Client Types v7

• status: complete
• version: 7.x
• follows from: Game-Sequence

Overview

Client types implement the game sequence. Each client type can be different depending on what its purpose is (player, bot, or logic).

Two client types are mandatory: player and logic.

• player type: is assigned to participants connecting to the experiment with a browser. It has the purpose to load the pages of the game, to handle users' interaction with the screen (e.g., the movement of the mouse, or the click on a button) and to exchange messages with the server.

• logic type: is executed on the server and controls the flow of operations of a game room, such as creating sub-groups, accessing external datasets, handling player disconnections, etc.

Other optional client types can be defined, for example to create automated players (bots), used to interact with human participants, or to test the correct functioning of the experiment.

Implementation

Each client type is defined in a separate file inside the game/client_types/ directory. So, for example:

• the player client type is defined in: game/client_types/player.js,
• the logic client type is defined in: game/client_types/logic.js.

Client types are constructed by adding step properties to the "empty" stages and steps created in the game sequence and available through the stager.

Defining a client type

Each client type is wrapped in a function definition:

module.exports = function(treatmentName, settings, stager, setup, gameRoom) {

    // Client type code here.
};

where the input parameters mean:

• treatmentName: the name of the treatment (chosen by the waiting room)
• settings: the game variables associated with the chosen treatment (as in game.settings.js)
• stager: a stager object initialized with the sequence from game.stages
• setup: the nodeGame setup (as in game.setup.js)
• gameRoom: a reference to the game room object

Adding step properties

The task of the game developer is to add step properties for all the steps defined in the game sequence.

Step properties are variables that are read by the nodeGame engine when the game reaches a given step. They are divided in two groups:

• default: the nodeGame engine reads them and automatically executes some routines; for instance, frame property contains the name of the html page to load (will learn more about these later).
• user-defined: the specific design of the game requires them; more info below.

For this purpose, the following methods of the Stager API are available:

• stager.extendStep: adds a property to a step,
• stager.extendStage: adds a property to a stage,
• stager.setDefaultProperty: adds a property for the whole game,
• stager.setOnInit: adds a function executed before the game starts,
• stager.setOnGameover: adds a function executed after the game ends.

For instance:

stager.extendStep('instructions', {
    coins: settings.COINS
});

adds a game variable into the "instructions" step. Notice that variable is coming from the settings object, which is received in input by the client type function.

Step properties inheritance

Generally, properties defined at higher levels are available to all lower levels:

• If a property is defined at the level of the game, it is inherited by all stages and steps.

• If a property is defined at the level of a stage, it is inherited by all steps contained within that stage.

• If a property is defined at the level of a step, it is valid only within that step.

A lower level can, however, overwrite higher-level properties.

Examples

Game-Level Properties.

// Methods that define step properties valid throughout a whole game:

// Sets the default step-rule function that never steps forward (wait rule).
stager.setDefaultStepRule(function() { return false; } );

// Sets a default property (see also stager.setDefaultProperties).
stager.setDefaultProperty('timer', 30000);

Stage-Level Properties

// Stage with id stage2 overwrite the 'timer' property and defines
// a new 'minPlayer' property for all nested steps.
stager.extendStage('stage2', {
    // Steps in stage2 have double the time.
    timer: 6000,
    // New property.
    minPlayers: [ 4, function() { console.log('Not enough players!') } ]
});

Step-Level Properties

// Step with id step_3 belongs to stage stage2.
// It overwrites both and minPlayers properties with other values.
stager.extendStep('step_3'{
    cb: function() { console.log('I am the third step of stage2.'); },
    minPlayers: undefined,
    timer: 3000
});

Next

Default Step Properties

See Also

• The full Stager API