Size Handlers v7 - nodeGame/nodegame GitHub Wiki
- status: complete
- version: 7.x
- follows from: Disconnections and Reconnections
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
ormaxPlayers
is set.
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:
-
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.
-
-
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).
-
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.
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
});
When a min|max|exact threshold is hit, the following steps are taken:
-
The game is paused (default: for 30 seconds).
-
A message is displayed informing all connected clients of the situation.
-
If the correct number of players is not restored in time, the game is resumed normally.
-
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.
-
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).
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.
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.
- GameRoom code for onWrongNumOfPlayers and onCorrectPlayerNum step properties.