Stager API Advanced v7

Stager API: Advanced Commands

• status: complete
• version: 7.x

Stage Aliases

The same stage can be played again later in the sequence if you define an "alias". In the following snippet, we are going to play stage "game" twice, using the 'AS' keyword to define the "game2" alias.

stager.next('game');
stager.next('something_in_betwen');
// Now add an alias.
stager.next('game AS game2');

Important! All steps of the aliased stage need to be added before the alias, see this issue.

Specifying a stage object directly

It is possible to specify the stage and its steps in one command. For example:

stager.stage({
    id: 'mystage',
    steps: [ 'step1', 'step2', 'step3' ]
});

adds a new stage with id mystage containing steps step1, step2, step3 into the sequence. The stage id must be unique. Any step that is not found in the stager is automatically created with a default callback.

Blocks and Positions

To have a finer control on the game sequence, it is possible to specify the positions that stages and steps are allowed to take (0-indexed).

When a position is specified the order in which stages and steps are inserted might lose importance.

Step positions

stager.stage('stage_1');

// * means take any available position.
stager.step('step_1', '*');
stager.step('step_2', '1');
stager.step('step_3', '*');

defines a sequence of one stage with three steps, one of which is fixed in position 1 (positions are zero-indexed), and the other two can assume a variable position.

When the game runs it will follow a variable game sequence which will alternate between two possibilities:

• step_1, step_2, step_3,
• step_3, step_2, step_1.

Stage positions

Positions can be specified for stages as well, and the position parameter is always the last one. Position can be specified as an expression which will be evaluated.

// Place stage 1 after position 0.
stager.stage('stage_1', '>0');

stager.step('step_1', '*');
stager.step('step_2', '1');
stager.step('step_3', '*');

// When no position is specified, the order
// of insertion into the sequence counts.
stager.stage('stage_2');

stager.repeatStage('stage_3', 2, '*');

leads to one of the two sequences:

• stage_3, stage_2, step_1, step_2, step_3,
• stage_3, stage_2, step_3, step_2, step_1 (note the steps 1 and 3 are switched).

Blocks

Blocks group together stages or steps and define the scope within which the position parameter applies. For example:

// Place block of stages with id "first_block" at any position > 0.
stager.stageBlock('first_block', '>0');

stager.stage('stage_1')

    // This step can at any position within stage 1.
    .step('step_1', '*')

    // This block of steps must be at position 0 within stage 1.
    // Notice that blocks can optionally be given an id (first param).
    .stepBlock('Step Block 1', '0')

        .step('step_2');
        .step('step_3');

    // This block of steps must be at position 1.
    .stepBlock('Step Block 2', '1')

        .step('step_4');
        .step('step_5');

// Place this block of stages with ID "anywhere" anywhere in the sequence.
stager.stageBlock('anywhere', '*');

// Place at position 0 or 1.
stager.stage('stage_2', '0..1');

stager.stage('stage_3', '2');

    .step('step_3_1', '*');
    .step('step_3_2', '*');

stager.stage('stage_4', '*');

would create the sequence (among others):

• stage_4, stage_2, step_3_2, step_3_1, step_1_2, step_1_3, step_1_4, step_1_5, step_1_1.

Setting the Game Plot on Clients

The stager's state can be directly used to setup local or remote clients. When the game-sequence is passed onto clients is named Game Plot.

var state2 = stager2.getState();

// Setups locally the game-plot.
node.setup('plot', state2);

// Setups remotely the game-plot on client 'client'.
node.remoteSetup('plot', 'client', state2);

The game-plot will be used at run-time to execute the game as defined by the stager.

The setup of the game-plot can be done automatically when a client enters a new game room if the plot is exported by one of the game-paths defined in the game.settings.js file. For details, refer to the User Guide.

Create a Stager Object

Load the nodegame-client library and request a new stager instance.

var ngc = require('nodegame-client');
var stager = ngc.getStager();

Stager State

After all the stages have been added, and the sequence created, it is possible to fetch the stager state with stager.getState(). The state can be passed directly to the constructor of a new Stager object, to create a copy that can be extended.

var state = stager.getState();

// Variable state contains the stages, the steps,
// and the sequence, as previously defined.

var stager2 = ngc.getStager(state);

// Extend stager2 as needed.

Flexible Execution Mode (Experimental)

In the standard execution mode, the sequence of all the stages of a game must be completely defined before the game starts.

However, it is also possible to decide the next stage of the game dynamically at run-time. This way the actual sequence played can depend on players's actions. This is called the flexible execution mode.

• registerGeneralNext(func): Sets general callback for next stage decision. Available only when nodegame is executed in flexible mode. The callback given here is used to determine the next stage.
• registerNext(id, func): Registers a step-decider callback for a specific stage. The function overrides the general callback for the specific stage, and determines the next stage. Available only when nodegame is executed in flexible mode.

The next functions must return the id of the next stage to be executed or 'NODEGAME_GAMEOVER' in case the game is over.