Client API v7

• status: NEEDS UPDATES
• version: 7.x

The Client API exports the node object, which is essentially the same in Node.js and in the browser.

API Overview

• node.game
  Controls and executes all the stages and steps of the game being played.
• node.widgets
  Creates and manages the widgets.
• node.window (browser only)
  Manages the user interface. Browser alias: W.
• node.timer
  Creates new timers and random events.
• node.msg
  The msg generator to create custom game messages.
• node.events
  Registers and executes event listeners.
• node.socket
  Handles the connection with the server.
• node.player (may change in future versions)
  Contains information about the client.
• node.conf
  Contains the configuration values used by setup functions.
• node.JSUS
  Collection of helper functions from the JSUS package including: randomization and sorting, Latin squares, parsing, manipulating objects and arrays, etc. Browser alias: J.

Connecting to a server

• node.connect(channel, conf)
  Connects to the specified channel endpoint. It accepts extra configuration options for the socket. If no parameter is specified, it will try to guess the name of the channel based on the uri of the page.

Examples

// Connect to the ultimatum endpoint (leading slash needed).
node.connect('/ultimatum');

Emitting and catching events locally

• node.on('KEY', callback, label)
  Registers an event-listener callback that will be executed each time the event 'KEY' is emitted. The label parameter is optional and can be used to remove the event listener directly with node.off.

• node.once('KEY', callback)
  Registers an event-listener callback that will be executed only the first time the event 'KEY' is emitted.

• node.emit('KEY', params)
  Synchronously executes all registered listeners for the event 'KEY'; accepts any number of additional parameters.

• node.emitAsync('KEY', params)
  Asynchronous version of node.emit.

• node.off('KEY', listener)
  Removes all listeners for the event 'KEY', or just the specified listener. The parameter listener can be

  • A reference to the function registered with node.on,
  • The name of the function (may fail on older browsers),
  • The label associated to the listener, if any is specified with node.on.

Important! The emit method by itself does NOT send data to other players or the server. However, emitting particular types of events locally triggers other event listeners that in turn send the data to the server or other players. Here is a list of existing events.

Examples

Registers a new event local event listener that increments a local variable with the value received by the emitting function; the current value of the local variable is returned back to the emitting function.

var localData = 1;
node.on('INCREMENT_DATA', function(increment) {
    // Update a local variable.
    localData += increment;
    // Return a value to the emit function.
    return localData;
});

node.emit('INCREMENT_DATA', 1); // returns 2.

In case there are more than one event listeners registered, they are executed in the order they are registered. The return values are returned inside an array.

var localData = 1;
node.on('INCREMENT_DATA', function(increment) {
    // Update a local variable.
    localData += increment;
    // Return a value to the emit function.
    return localData;
});
node.once('INCREMENT_DATA', function(increment) {
    // Update a local variable.
    localData += data;
    // Return a value to the emit function.
    return localData;
});

// First emit.
// Triggers two event listeners, and removes the one registered with node.once
// The return value of each triggered event listener is returned in an array.
node.emit('INCREMENT_DATA', 1); // returns [2, 3].

// Second emit.
Triggers only one event listener and returns one value.
node.emit('INCREMENT_DATA', 1); // returns 4.

Sending events between clients

• node.say('KEY', receiver, payload)
  Emits an event 'KEY' on a remote node object (receiver). Can send an optional payload along with the event.
• node.set('KEY', value, to)
  Saves a key-value pair into the memory of the node object of the logic of the game room. Optionally, the pair can be stored in another node object.
• node.get('KEY', callback, receiver, params, timeout)
  Emits the event 'KEY' on a remote node object (receiver); register a local event handler that will be executed when return value from the remote invocation is received.
• node.on.data('KEY', callback)
  Registers an event handler callback that will be executed when an incoming DATA message with the specified 'KEY' label is received.

When a node instance receives an incoming game message, the event in.[say|get|set].[target] is fired with the incoming message as input parameter.

Examples

// Sending the _DATA_ message previously created to 'receiver'.
node.say('myData', 'receiver', [ 0, 1, 2, 3 ]);

// 'receiver' node instance handle the incoming _DATA_ message
node.on('in.say.DATA', function(msg) {
   if (msg.text === 'myData') {
       // Do something with the data.
       console.log(msg.data); // [ 0, 1, 2, 3 ]
   }
});

Alternatively, it is possible to use the shortcuts to send and receive game messages.

// Sending the _DATA_ message previously created to 'receiver'.
node.say('myData', 'receiver', [ 0, 1, 2, 3 ]);

// 'receiver' node instance handle the incoming _DATA_ message
node.on.data('myData', function(msg) {
   // Do something with the data.
   console.log(msg.data); // [ 0, 1, 2, 3 ]
});

It is also possible to execute remote procedure calls on remote node instances.

// On remote instance register an handler for "get.myData" events.
node.on('get.myData', function(msg) {
    return [ 0, 1, 2, 3 ];
});

// Sending a  _get.DATA_ message to 'receiver',
// and handling the response message.
node.get('myData', 'receiver', function(response) {
    // Do something with response.
    console.log(response); // [ 0, 1, 2, 3 ]
});

Aliases

• node.alias('myalias', event, modifier)
  Creates a shortcut for registering event handlers for specific events. The alias will be available under node.on.myalias (for example, node.on.data is an alias for both 'in.say.DATA' and 'in.set.DATA' messages).

Setting up a node instance

• node.registerSetup('feature', func)
  Register a setup function available under node.setup.feature. All setup functions can be invoked remotely sending a SETUP message.
• node.setup('feature', conf)
  Calls a setup function locally with the required configuration. All return values are stored under node.conf.

For the all configuration options accepted by node.setup refer to the configuration guide.

After invoking node.setup, all settings are stored in the node.conf object.

Controlling the Console Output

The amount of text logged to console is controlled by the parameter node.verbosity. The parameter can be set directly, via node.setup.verbosity(level), or remotely via node.remoteSetup('verbosity', level). The verbosity parameter is a number usually between -1 and 100.

The level can be encoded as a string compatible with winston.js levels.

ALWAYS: -Number.MAX_VALUE,
error: -1,
warn: 0,
info: 1,
silly: 10,
debug: 100,
NEVER: Number.MAX_VALUE

The method node.log(text, level) prints to console only log messages with a level higher or equal to the node.verbosity. Other shortcut methods are available to log messages with a pre-defined log level.

node.log(text, level, prefix);
node.info(text, prefix);
node.warn(text, prefix);
node.error(text, prefix);

// The prefix is added automatically.
// to the log message. By default the prefix includes
// the node.nodename variable and the error level.

Admin Commands

Some commands are available only to node clients with higher privileges. They allow to setup, and execute commands on remote node instances.

• node.remoteSetup(feature, to)
  can setup remotely any of the features that node.setup() locally. Keep in mind that some features might be locked when a game is running.
• node.remoteCommand(command, to, options)
  Executes a game command on a remote client. Available game commands are:
  • 'start'
  • 'pause'
  • 'resume'
  • 'stop'
  • 'restart'
  • 'step'
  • 'push_step'
  • 'goto_step'
  • 'clear_buffer'
  • 'erase_buffer'
• node.remoteAlert(command, to)
  Displays an alert message in the screen of the remote client. If the client is a bot, the message will be printed to console.
• node.redirect(url, who)
  redirects a remote client to the specified URL. If the client is a bot the message will be ignored.

Loading the API

In the browser:

// Add socket.io for communication.
<script src="/socket.io/socket.io.js"></script>
// Load the full library.
<script src="/javascript/nodegame-full.js" charset="utf-8"></script>

In Node.js:

const ngc  = require('nodegame-client');
let node = ngc.getClient();

Additional Client API pages

• Stager API
• Matcher API
• Client API
• Game API
• Timer API
• Window API