Game API v7

• status: complete
• version: 7.x

The Game API controls the flow of the game. It is a subset of the Client API and it is accessible through the object node.game. The most common methods and properties are described below.

Game properties

• memory
  Where the game results are saved. It is a special instance of the NDDB database. For more information see the Memory-Database page or the NDDB home page.
• playerList | pl
  The list of players currently connected. For more information see Player-List page.
• timer
  The default game timer containing how much time is left in current step.
• settings
  The object containing the current treatment's settings (in remote clients).
• plot
  The object containing the game sequence.
• pushManager
  The object responsible for making the game keep up with its timer. For more information see the push-manager page
• sizeManager
  The object responsible for taking actions when the number of connected players changes. For more information see the page on how to handle disconnections.

Game methods

Fetching properties of the game sequence

• Game.getProperty(property, nf)

  Returns the requested step property from the game plot.

  • property {string} The name of the property.

  • nf {mixed} Optional. The return value in case the requested property is not found. Default: null.

  Returns {mixed} The value of the requested step property.

• Game.getCurrentStepObj()

  Returns the object representing the current game step. The returning object includes all the properties, such as: id, cb, timer, etc.

  Returns {object} The game-step as defined in the stager.

• Game.getRound(mod)

  Returns the current/remaining/past/total round number in current stage.

  • mod {string} Optional. Modifies the return value.

    • 'current': current round number (default)
    • 'total': total number of rounds
    • 'remaining': number of rounds remaining (excluding current round)
    • 'past': number of rounds already past (excluding current round)

  Returns {number|null} The requested information, or null if the number of rounds is not known (e.g. if the stage is a loop).

Get current/previous/next game-stage

• Game.getCurrentGameStage()

  Return the GameStage that is currently being executed. The return value is a reference to node.player.stage.

  Returns {GameStage} The stage currently played.

• Game.getPreviousStep(delta, opts)

  Returns the game-stage played delta steps ago.

  • delta {number} Optional. The number of past steps. Default 1.

  • opts {bolean|object } Optional. A configuration object accepting the following options:

    • acrossStages: if FALSE, if the previous step belongs to another stage, it returns NULL. Default: TRUE.
    • acrossRounds: if FALSE, if the previous step belongs to another round, it returns NULL. Default: TRUE.
    • noZeroStep: if TRUE, replaces return value 0.0.0 with NULL. Default: FALSE.
    • execLoops If TRUE, loop and doLoop conditional functions are executed to determine the previous step. If FALSE, if a loop or doLoop is found, it returns NULL. Note! This option is evaluated only if no step is found in the cache. Default: TRUE.

  Note: for backward compatibility, if this parameter is a boolean, it will be treated as option execLoops.

  Returns {GameStage|null} The game-stage played delta steps ago, null if an error occurred (e.g., a loop stage), or stage 0.0.0 for all deltas > steppable steps (i.e., previous of 0.0.0 is 0.0.0).

• Game.getNextStep(delta)

  Returns the game-stage that will be played in delta steps.

  • delta {number } Optional. The number of future steps. Default 1.

  Returns {GameStage|null} The game-stage that will be played in delta future steps, or null if none is found, or if the game sequence contains a loop in between.

• Game.compareCurrentStep(step)

  Returns the relative order of a step with the current step.

  • step {GameStage|string} The step to compare.

  Returns {number} 0 if comparing step is the same as current step, -1 if current step is before comparing step, 1 if current step is after comparing step.

Identify game steps/stages

• Game.getStageId(stage)

  Returns the id of current stage, or of another user-specified stage.

  • stage {object} Optional. A GameStage object. Default: current game stage.

  Returns {string|null} The id of (current) stage, or NULL if not found.

• Game.getStepId(stage)

  Returns the id of current step, or of another user-specified stage.

  • stage {object} Optional. A GameStage object. Default: current game stage.

  Returns {string|null} The id of (current) step, or NULL if not found.

• Game.isStage(stage, compareStage)

  Returns TRUE if current stage matches input parameter (steps and rounds are not considered).

  • stage {string|GameStage|number} The name of the stage, its ordinal position in the game sequence, or its object representation. If string, the object is resolved with GamePlot.normalizeGameStage.

  • compareStage {GameStage}: Optional. The stage to compare against. Default: current game stage.

  Returns {boolean} TRUE if stage matches input parameter.

  Example:

  // Check if current stage is the 'ultimatum' stage.
  node.game.isStage('ultimatum');
  // Check if a given stage is the 'ultimatum' stage.
  node.game.isStage('ultimatum', { stage: 2, step: 1, round: 3 });

• Game.isStep(step, compareStage)

  Returns TRUE if current step matches input parameter (rounds are not considered).

  • step {string|GameStage|number} The name of the stage, its ordinal position in the game sequence, or its object representation. If string, the object is resolved with GamePlot.normalizeGameStage.

  • compareStage {GameStage} Optional. The stage to compare against. Default: current game stage.

  Returns {boolean} TRUE if stage matches input parameter

  Example:

  // Check if current step in current stage is the 'results' step.
  node.game.isStep('results');
  // Check if a given stage is the 'results' step.
  node.game.isStep('results', { stage: 2, step: 1, round: 3 });

• Game.isRound(round)

  Returns TRUE if current step matches input parameter.

  • round {GameStage|number} The round number or its object representation. If object, it is resolved with GamePlot.normalizeGameStage.

  Returns {boolean} TRUE if stage matches input parameter

  Example:

  // Check if game is currently in round 3.
  node.game.isRound(3);
  // Check if game is currently in round 3.
  node.game.isRound({ stage: 2, step: 1, round: 3 });

• Game.isWidgetStep

  Returns TRUE if current step is a widget step.

  Returns {boolean} TRUE if current step is a widget step.

Altering the game flow

• Game.pause()

  Pauses the game. Returns TRUE if the game is paused.

• Game.resume(param)

  Resumes the game from pause.

  • param {string} Optional. A parameter to pass along the emitted events RESUMING and RESUMED.

• Game.stop()

  Stops the current game. Clears timers, event handlers, local memory, and window frame (if any). Does not clear node.env variables and any node.player extra property.

  GameStage is set to 0.0.0 and server is notified.

Checking the state of the game

• Game.isReady()

  Returns TRUE if a game is set and interactive.

  A game is ready unless a stage or step is currently being loaded or DONE procedure has been started, i.e. between the stage levels: PLAYING and GETTING_DONE.

  If a game is paused, it is also NOT ready.

• Game.isPaused()

  Returns TRUE, if game is paused.

• Game.isGameover()

  Returns TRUE, if gameover was called and state level set.

  Returns {boolean} TRUE if is game over.

• Game.isStoppable()

  Returns TRUE, if Game.stop can be called.

  Returns {boolean} TRUE if the game can be stopped.

• Game.isPausable()

  Returns TRUE, if Game.pause can be called.

  Returns {boolean} TRUE if the game can be paused.

• Game.isResumable()

  Returns TRUE, if Game.resume can be called.

  Returns {boolean} TRUE if the game can be resumed.

• Game.isSteppable()

  Returns TRUE, if Game.step and Game.gotoStep can be called.

  Returns {boolean} TRUE if the game can be stepped.

Sources

• Game.js