Size Handlers v7

• status: complete
• version: 7.x
• follows from: Disconnections and Reconnections

Size-Handlers

Size-handlers are fired when a change in the size of the player list takes place. There are three types of size-handlers:

• minPlayers: fired when a player disconnects.

• maxPlayers: fired when a player connects or reconnects.

• exactPlayers: fired when a player connects/disconnects/reconnects. Important: it cannot be defined if either minPlayers or maxPlayers is set.

Syntax

All the size-handlers follow the same syntax. Their value can be a number|string (the threshold), or an array containing up to three elements ordered as follows:

1. threshold: an integer for the desired min/max/exact number of connected players. Wildcards accepted:

   • @: the current number of players in the player list (minimum 1),
   • *: any change in the number of players will trigger the threshold callback.

2. threshold_cb: a callback executed when the specified the number of connected players is larger or smaller than the threshold (e.g., less than minPlayers, or more than maxPlayers, or different from exactPlayers) for a period of time longer than a timeout (see below).

3. recovery_cb: a callback executed after that threshold_cb timeout was initiated, but the number of connected players returned correct again in time. If this function is executed, then threshold_cb is not executed and vice versa.

Example

Size-handler are generally defined in the logic and they may be added to individual step properties or to the whole game.

    // In logic.js

    let opts = [
        // Game must have at least 4 players.
        4,

        // If less than 4 player after timeout, go to the questionnaire step.
        // Note: in current stable branch 7.3.0, this function incorrectly receives
        // a game msg, and the player object is available under the property data.
        // Fixed in master.
        function(player) {
            node.game.gotoStep('questionnaire');
        },

        // If the game was temporarily less than 4 players and
        // then it returned to 4 players before the timeout expired.
        // Note: in current stable branch 7.3.0, this function incorrectly receives
        // a game msg, and the player object is available under the property data.
        // Fixed in master.
        function(player) {
            // Mark reconnection in time (optional).
            player.reconnectedInTime = true;
        }
    ];

    // Size-handler for all steps in the game.
    stager.setDefaultProperty('minPlayers', opts);

    // Or size-handler for a specific step.
    stager.extendStep('mystep', {
        minPlayers: opts
    });

Default behavior when a size handler is set.

When a min|max|exact threshold is hit, the following steps are taken:

1. The game is paused (default: for 30 seconds).

2. A message is displayed informing all connected clients of the situation.

3. If the correct number of players is not restored in time, the game is resumed normally.

4. Otherwise, if a threshold_cb was defined, it is executed. Here, the game developer could terminate the game, replace the player with a bot or do nothing.

5. If the correct number of connected players is restored after threshold_cb is executed once, then the recovery_cb is executed (if one is defined).

Customize default behavior

It is possible to customize the default waiting time, and text displayed while the game is paused in file game/game.settings.js by defining the following variables:

• WAIT_TIME: The amount of seconds to wait for a player to reconnect. Default 30.

• WAIT_TIME_TEXT: The text to display when on screen to the other players.

Override size-handler behavior

The following step properties determine the behavior of all size handlers:

• onWrongNumOfPlayers: callback executed when the number of players is not correct: pauses the game, alert connected players, and start the timer for the threshold callback.

• onCorrectNumOfPlayers: callback executed when the number of players is correct again: resumes the game, alert connected players, clear the threshold timer, executes the recovery callback.

Sources

• GameRoom code for onWrongNumOfPlayers and onCorrectPlayerNum step properties.

Next

• PushManager

Go Back to

• Home