Skip to content


Subversion checkout URL

You can clone with
Download ZIP
JavaScript port of GbxRemote to communicate with ManiaPlanet / TrackMania servers with Node.js.
Tag: v0.1.4

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


JavaScript (node.js) port of GbxRemote by Nadeo, which is built on Incutio XML-RPC Library.

Used to communicate with ManiaPlanet servers.

Note: The API may, or may not change!


npm install gbxremote

To Use

Look in /examples/ for all examples.

The following examples expects that var gbxremote = require('gbxremote').


To connect to a server, use var client = gbxremote.createClient(port, [host], [callback]);

Examples of ways to connect to the server:

// Connect with port only
var client = gbxremote.createClient(5000);

// Connect with port and hostname
var client = gbxremote.createClient(5000, 'localhost');

// Connect with port and ip
var client = gbxremote.createClient(5000, '');

// Connect with port only, and a callback
var client = gbxremote.createClient(5000, function(err) {
    // This callback is called both on connect and on error so we should check it.
    if (err) {
        console.error('Could not connect to server:', err);
    } else {
        console.log('Connection to server was successfull! Ready to send queries..');

// Connect with port, ip and a callback
var client = gbxremote.createClient(5000, '', function(err) {
    // Callback...


Queries are sent to the server by calling client.query(method, [params], [callback]);

Queries before the connect event has been emitted will be queued and sent on connect!

See the full list of methods.

var client = gbxremote.createClient(5000);

client.on('connect', function() {

    // GetVersion does not take any params.
    client.query('GetVersion', function(err, res) {
        if (err) {
            console.error('Error when querying server:', err);
        } else {
            console.log('Server version:', res.join(', '));

    // GetPlayerInfo takes 2 parameters, 1 optional.
    // GetPlayerInfo(string login, [int compatibility])
    client.query('GetPlayerInfo', ['minigod'], function(err, res) {
        if (err) {
            console.error('Error getting player info:', err);
        } else {
            console.log('Player info:');




Event: connect()

Emitted when connection to the server is successfull.
Ready to receive queries!

var client = gbxremote.createClient(5000);

client.on('connect', function() {
    console.log('Connection successfull! Lets do some queries!');
    client.query('GetVersion', function(err, res) {
        if (err)

If there is a problem connecting, the 'connect' event will not be emitted, the 'error' event will be emitted with the exception.

Event: error(err)

Emitted when:

  • Socket errors (host is not listening on that port, loose connection, etc.)
  • Handshake fails (host is listening on that port, but its not a ManiaPlanet (GbxRemote 2) server)
var client = gbxremote.createClient(80);

client.on('error', function(err) {
    console.error('Connection failed: ' + err);

Event: callback(method, params)

After sending EnableCallbacks(true) to the server, it will send you callbacks when stuff happend on the server.

  • ManiaPlanet.ServerStart
  • ManiaPlanet.ServerStop
  • ManiaPlanet.PlayerConnect
  • ManiaPlanet.PlayerChat

See the full list of callbacks

var client = gbxremote.createClient(5000);

client.on('connect', function() {
    client.query('SetApiVersion', ['2012-06-19']);
    client.query('EnableCallbacks', [true]);

client.on('callback', function(method, params) {
    console.log("Callback from server: %s - %d params", method, params.length);

    // This would be the typical place to have a switch statement. Please dont do that. Use the events, as shown below.

Event: <method>(params)

Callbacks will also emit separate events for each method. It's hard to explain. Learn from example:

var client = gbxremote.createClient(5000);

client.on('connect', function() {
    // Before enabling callbacks, make sure you set the latest API.
    client.query('SetApiVersion', ['2012-06-19']);
    client.query('EnableCallbacks', [true]);

// ManiaPlanet.PlayerConnect(string Login, bool IsSpectator);
client.on('ManiaPlanet.PlayerConnect', function(params) {
    console.log('%s just joined as a %s', params[0], params[1] ? 'spectator' : 'player');

// ManiaPlanet.PlayerDisconnect(string Login); 
client.on('ManiaPlanet.PlayerDisconnect', function(params) {
    console.log('%s left the server', params[0]);

These events can basically take over the big switch statements that is normal in todays server controllers.

Event: close(had_error)

Emitted once the socket is fully closed. The argument had_error is a boolean which says if the socket was closed due to a transmission error.

var client = gbxremote.createClient(5000);

client.on('connect', function() {
    // Connected...

    // Do stuff?

    // Disconnect

client.on('close', function(had_error) {
    console.log('Connection to the server has been closed');


This section does not currently apply, because tests are not being maintained atm
Note: Tests have not been changed since fork, hence will not pass.

TODO: Fix tests - Figure out how to do it with travis (and in general), since we need a running ManiaPlanet server to run tests - and we need to know exactly what the server will return.


XML-RPC must be precise so there are an extensive set of test cases in the test directory. Vows is the testing framework and Travis CI is used for Continuous Integration.

To run the test suite:

make test

If submitting a bug fix, please update the appropriate test file too.

The License (MIT)

Released under the MIT license. See the LICENSE file for the complete wording.

Something went wrong with that request. Please try again.