Channel Configuration v7 - nodeGame/nodegame GitHub Wiki

NodeGame supports multiple games at the same time, each one executed in a separate channel.

Channels are named after the game, so if, for instance, your game's name is myexperiment, clients can join it at the address:

http://localhost:8080/myexperiment/

(assuming the server runs on port 8080)

The following configuration files are available for your channel:

  • channel.settings.js
  • channel.secret.js
  • channel.credentials.js

File: channel.settings.js

The channel/channel.settings.js file allows you to configure the channel to a very low level of detail (however, the default options usually are fine for most users).

Each channel is divided into two internal servers: 'player' server and 'admin' server. Each server is reachable through a different "endpoint," that is a socket.io address specified as a parameter to the node.connect method.

The player and admin servers grant different privileges to connected clients. For instance, admins can directly control the status of the game, pausing and resuming, while players can simply send and receive game messages.

Main parameters

playerServer and adminServer

The player and admin servers can be configured individually using a configuration object for the properties playerServer and adminServer. All properties not specified in these objects are shared across both servers.

The property endpoint contains the endpoint of each server. However, if this option is omitted, the default endpoints are: the name of the channel (for player server), and the name of channel followed by "/admin" (for admin server). For instance, if your channel is named "foo", the default endpoints are:

  • player server: "/foo"
  • admin server: "/foo/admin"

If the endpoint is the only difference between the two servers, the playerServer and adminServer properties can be reduced to strings containing the name of the endpoints.

sioQuery

The sioQuery (SocketIo Query) is particularly important. It controls "channel query parameters", which are extra parameters passed along the url of the nodeGame server. For example, if the url to join an experiment is:

http://myserver.com/mygame/

then query parameters would be attached to the end as follows:

http://myserver.com/mygame/?clientType=autoplay&startingRoom=Room1

There are two channel parameters that can be set:

  • clientType: sets the client type that will be assigned the connecting client.

  • startingRoom: sets the initial room where the client will be placed. If not specified, clients are placed first in the requirement room, and then moved into a waiting room.

File Example

An example of configuration object follows in which the player and admin servers share all the options, but the endpoint.

module.exports = {

    /**
    * ## enabled (boolean) Optional
    *
    * If TRUE, the channel is loaded by nodeGame
    *
    * Default: TRUE.
    */
    enabled: true,

   /**
     * ## name (string) Optional
     *
     * The name of the channel
     *
     * Default: the name of the game, as found in the package.json file.
     */
    name: 'channelName',

    /**
     * ## alias (string|array) Optional
     *
     * Alternative name/s for the channel
     *
     * By default, if 'gameName' is the name of the channel, files will
     * be served from the address: `http://myserver/gameName/`.
     * Here you can add aliases to enable urls like: `http://myserver/alias/`.
     *
     * Important! `node.connect()` in `public/js/index.js` still needs
     * to use the real channel name, so you might need to pass it explicitly:
     * `node.connect('/gameName').
     */
    alias: [ 'alias1', 'alias2' ],

    /**
     * ## playerServer (object|string) Optional
     *
     * Set of custom options applying only to player server
     *
     * If string, it will be interpreted as the name of the server
     * endpoint for socket.io player connections.
     *
     * If object, the endpoint must be specified in the _endpoint_ property.
     *
     * Default: name-of-the-channel
     */
    playerServer: 'channelName',

    /**
     * ## adminServer (object|string) Optional
     *
     * Set of custom options applying only to admin server
     *
     * If string, it will be interpreted as the name of the server
     * endpoint for socket.io admin connections.
     *
     * If object, the endpoint must be specified in the _endpoint_ property.
     *
     * Default: name-of-the-channel/admin
     */
    adminServer: 'channelName/admin',

    /**
     * ## getFromAdmins (boolean) Optional
     *
     * If TRUE, players can invoke GET commands on admins
     *
     * Default: FALSE
     */
    getFromAdmins: true,

    /**
     * ## accessDeniedUrl (string) Optional
     *
     * Unauthorized clients will be redirected here.
     *
     * Default: "/pages/accessdenied.htm"
     */
    // accessDeniedUrl: 'unauth.htm',

    /**
     * ## notify (object) Optional
     *
     * Configuration options controlling what events are notified to players
     *
     * Default: player actions are notified to admins only.
     */
    notify: {

        // When a player connects / disconnects.
        onConnect: false,

        // When a player changes a stage / step.
        onStageUpdate: false,

        // When the 'LOADED' stageLevel is fired (useful to sync players)
        onStageLoadedUpdate: false,

        // When any change of stageLevel happens (e.g. INIT, CALLBACK_EXECUTED)
        // Notice: generates a lot of overhead of messages.
        onStageLevelUpdate: false,

    },

    /**
     * ## enableReconnections (boolean) Optional
     *
     * If TRUE, only one TAB per browser will be allowed
     *
     * Default: FALSE
     */
    enableReconnections: true,

    /**
     * ### sameStepReconnectionOnly (boolean) Optional
     *
     * If TRUE, only reconnections in the same game step are allowed.
     *
     * Default: FALSE
     */
    sameStepReconnectionOnly: false,

    /**
     * ### disposeFailedReconnections (boolean) Optional
     *
     * If TRUE, failed reconnections are disposed
     *
     * If FALSE, failed reconnections are treated as a new connection.
     *
     * A reconnection can fail for the following reasones:
     *
     * - Parameter `enabledReconnections` is FALSE.
     * - Parameter `sameStepReconnectionOnly` is TRUE, and the
     *      client's stage and the logic's stage are different.
     * - The room in which the client was at the moment of
     *      disconnection cannot be located.
     * - Any other error.
     *
     * Default: FALSE
     */
    disposeFailedReconnections: false,

    /**
     * ### cacheMaxAge (number) Optional
     *
     * The duration in ms of the browser cache for public/ resources
     *
     * Default: 0 (no cache)
     */
    cacheMaxAge: 360000,

    /**
     * ### sioQuery (boolean) Optional
     *
     * If TRUE, clients connecting via Socket.io can set own parameters
     *
     * Available parameters:
     *
     *  - clientType: sets the client type
     *  - startingRoom: sets the room in which the client will be placed first
     *
     * It is recommended to disable sioQuery in production
     *
     * Default: TRUE
     */
    sioQuery: false,

    /**
    * ### defaultChannel (boolean) Optional
    *
    * If TRUE, the game is served from / (instead of /gamename/)
    *
    * The route `/gamename` will be disabled, while aliases,
    * if defined, will continue to work if not shadowed by any public path.
    *
    * Important! Socket.io connection must be established
    * with the right endpoint (i.e., node.connect("/channelName").
    * Check the public/index.htm file or public/js/index.js file for the
    * connect statement.
    *
    * Important! Other games might not be reachable any more.
    *
    * @deprecated. Use option --default at startup
    *
    * Default: false
     */
    defaultChannel: false,

    /**
     * ### noAuthCookie (boolean) Optional
     *
     * If TRUE, a cookie is set even with authorization disabled
     *
     * Opening multiple browser tabs will cause a disconnection in other ones.
     *
     * Default: false
     */
    noAuthCookie: false,

    /**
     * ### roomOwnDataDir (boolean) Optional
     *
     * If TRUE, each new room in the channel has an own data dir named after it
     *
     * Default: true
     */
    roomOwnDataDir: true,

    /**
     * ### roomCounter (number) Optional
     *
     * If set, room counter is initialized to this value
     *
     * If undefined, room counter self-initialize to the next available id,
     * starting from 1, as found in the data folder of the game.
     *
     * Default: undefined
     */
    // roomCounter: 100,

    /**
     * ### roomCounterPadChars (0 <= number <= 12) Optional
     *
     * If set, leading 0 are added to the room counter to reach desired length
     *
     * For example, if `roomCounterChars` is equal to 6 and
     * the current roomCounter value is 123, then room name is: '000123'.
     *
     * Default: 6
     */
    // roomCounterPadChars: 6    
};

File: channel.secret.js

Contains a secret string to sign all json web tokens. For example:

module.exports = function(settings, done) {
    return 'this is a secret';
};

This file is used only if authorization is enabled.

File: channel.credentials.js

Contains user name and password to access the monitor interface. For example:

module.exports = function(settings, done) {
    return {
        user: 'admin',
        pwd: 'password'
    };    
};

The url to enter the monitor interface is:

http://localhost:8080/yourgame/monitor/auth/admin/password

This file is used only if authorization is enabled.

Next

Go Back to

⚠️ **GitHub.com Fallback** ⚠️