Create a quick game whereby players simply move squares along the x-axis. I know, it's boring, but it keeps things simple and to the point. For a more thorough demonstration of how GarageServer.IO works, look at the example included in the source code.

Server

1. Create instance of GarageServer.IO - pass in a Socket.IO instance and GarageServer.IO options.

var garageServer = require('garageserver.io'),

var server = garageServer.createGarageServer(sockets, 
    {
        interpolation: true,
        clientSidePrediction: true,
        worldState: { width: '400px', height: '400px'; }
    });

2. Start GarageServer.IO instance prior to starting physics loop. This starts the clock that is used for broadcasting state and storing state history.

server.start();

3. Inside physics loop, process inputs for players, process entites and update states. Note that state is an object literal effectively offering up any grab bag of properties that pertain to your game's state.

var players = server.getPlayers(),
    entities = server.getEntities();

players.forEach(function (player) {
    var newState = {};
    if (!player.state.x) {
       player.state.x = 0;
    }
    for (i = 0; i < player.inputs.length; i ++) {
        if (player.inputs[i].input === 'left') {
            newState.x = player.state.x - (50 * deltaTime);
        } else if (inputs[i].input === 'right') {
            newState.x = player.state.x + (50 * deltaTime);
        }
    }
    server.updatePlayerState(player.id, newState);
});
entities.forEach(function (entity) {
    // Calculate new state from entity.state and send GarageServer.IO new state
    server.updateEntityState(entity.id, newState);
});

Client

1. Initialize GarageServer.IO.

GarageServerIO.initializeGarageServer('http://insertmygameurlhere.com', {
    onReady: function () {
        // Call your game loop
    },
    onUpdatePlayerPrediction: function (state, inputs, deltaTime) {
        var newState = {};
        if (!player.state.x) {
        player.state.x = 0;
        }
        for (i = 0; i < player.inputs.length; i ++) {
            if (player.inputs[i].input === 'left') {
                newState.x = player.state.x - (50 * deltaTime);
            } else if (inputs[i].input === 'right') {
                newState.x = player.state.x + (50 * deltaTime);
            }
        }
        return newState;
    },
    onInterpolation: function (previousState, targetState, amount) {
        return { x: (previousState.x + amount * (targetState.x - previousState.x)) };
    },
    onWorldState: function (state) {
        document.getElementById('gameCanvas').style.width = state.width;
        document.getElementById('gameCanvas').style.height = state.height;
    }
};

2. Inside physics loop, capture and send input via GarageServer.IO.

GarageServerIO.addInput(myInput);

3. Inside render loop, extract player and entity states.

var playerStates = GarageServerIO.getPlayerStates(),
    entityStates = GarageServerIO.getEntityStates();  
    playerStates.forEach(function (player) {
        ctxCanvas.fillRect(player.state.x, 0, 5, 5);
    });
    entityStates.forEach(function (entity) {
        ctxCanvas.fillRect(entity.state.x, 0, 5, 5);
    });

API

Client

initializeGarageServer

GarageServerIO.initializeGarageServer(path, options)

Establish connection to GarageServer.IO on the server via Socket.IO and register events.
path string
The URL that points to where GarageServer.IO is running at on the server.
options object literal
Configure the different options, events, callbacks that you would like to consume on the client.

Client Options

options.onPlayerConnect(callback)

Once the client has made a connection to the server, this event will fire.
callback function
Function to be invoked upon event firing.

options.onPlayerDisconnect(callback)

If client disconnects from the server, this event will fire.
callback function
Function to be invoked upon event firing.

options.onPlayerReconnect(callback)

If client disconnects and reconnects to the server, this event will fire.
callback function
Function to be invoked upon event firing.

options.onPlayerUpdate(callback(state))

Event fired each time state has been received to the client for a player.
callback function
Function to be invoked upon event firing.
state object literal
Object containing all of the properties pertaining to a player for your game - x, y, z, time, etc., whatever you want to add to it.

options.onEntityUpdate(callback(state))

Event fired each time state has been received to the client for an entity.
callback function
Function to be invoked upon event firing.

state object literal
Object containing all of the properties pertaining to an entity for your game - x, y, z, time, etc., whatever you want to add to it.

options.onPlayerRemove(callback(id))

Event fired when a player has been removed from GarageServer.IO.
callback function
Function to be invoked upon event firing.

id string
Id of the player who has been removed from GarageServer.IO.

options.onEntityRemove(callback(id))

Event fired when an entity has been removed from GarageServer.IO.
callback function
Function to be invoked upon event firing.

id string
Id of the entity who has been removed from GarageServer.IO.

options.onEvent(callback(data))

Event fired for custom event calling.
callback function
Function to be invoked upon event firing.

data object literal
Object containing all of the properties pertaining to a custom event for your game - a, b, c, etc., whatever you want to add to it.

options.onWorldState(callback(state))

Event fired once world state has been received to the client from the server.
callback function
Function to be invoked upon event firing.

state object literal
Object containing all of the properties pertaining to world state for your game - f, u, n, etc., whatever you want to add to it.

options.onPing(callback(pingDelay))

Event fired upon receiving ping delay on the client - determined by the 'pingInterval' option from the server.
callback function
Function to be invoked upon event firing.

pingDelay number
The current ping in milliseconds.

options.onUpdatePlayerPrediction(callback(state, inputs, deltaTime) : newState)

If using client side prediction, this callback should return the new state based on the current state, inputs to be processed, and the delta time.
Returns: object literal

callback function
Function to be invoked upon event firing.

state object literal
The current state of the player.

inputs array
List of all the inputs to be processed.

deltaTime number
The amount, in milliseconds, between physics processing.

options.onInterpolation(callback(previousState, targetState, amount) : newState)

If using interpolation, this callback should return the new state, based on the previous state, target state, and percent between.
Returns: object literal

callback function
Function to be invoked upon event firing.

previousState object literal
Object containing all of the properties pertaining to a player for your game - x, y, z, time, etc., whatever you want to add to it.

targetState object literal
Object containing all of the properties pertaining to a player for your game - x, y, z, time, etc., whatever you want to add to it.

amount number
The "rough" percentage between frames to be used in conjuction with interpolation - client side smoothing is considered during the calculation of this number.

options.onReady(callback)

Event fired once client has succesfully connected to the server and received the world state.
callback function
Function to be invoked upon event firing.

options.logging

Enables console logging of all the events occuring within the GarageServer.IO client.
logging boolean

addInput

GarageServerIO.addInput(input)

Notify the server of client inputs. These will be used to determine state from the physics processing.
input object literal
This can be anything as it pertains to your game - 1, 'left', 'right', etc., whatever you want to make it.

getPlayerStates

GarageServerIO.getPlayerStates() : [, {id, state}]

Returns a list of current player states from the most recent broadcast depending on interpolation settings.
Returns: array

id string
The id of the player.
state object literal
Object containing all properties pertaining to an entity state in your game.

getEntityStates

GarageServerIO.getEntityStates() : [, {id, state}]

Returns a list of current entity states from the most recent broadcast depending on interpolation settings.
Returns: array

id string
The id of the entity.
state object literal
Object containing all properties pertaining to an entity state in your game.

getId

GarageServerIO.getId() : playerid

Gets the id of the client's player.
Returns: string

playerid string
Id of the client's player.

sendServerEvent

GarageServerIO.sendServerEvent(data)

Send a custom event to the server.
data object literal
Object containing all properties pertaining to the custom event.

Server

createGarageServer

require('garageserver.io').createGarageServer(io, options) : GarageServerIO

Returns a new instance of GarageServer.IO, registers Socket.IO events and instantiates an instance of a game that handles the broadcasting of state.
io Socket.IO instance

options object literal
Configure the different options, events, callbacks that you would like to consume on the server.

Server Options

options.stateInterval

number
The amount, in milliseconds, that state is broadcasted to clients.

options.logging

boolean
Enable console logging of all the events occuring within the GarageServer.IO server.

options.clientSidePrediction

boolean
Enables client side prediction and callback on the client.

options.interpolation

boolean
Enables interpolation and callback on the client.

options.interpolationDelay

number
The amount, in milliseconds, that state is rendered to the client behind actual server time.

options.smoothingFactor

number

options.pingInterval

number
The amount, in milliseconds, that a ping is made to the server to test for latency.

options.maxUpdateBuffer

number
The maximum amount of broadcasted state updates to store on the client for each player and entity.

options.maxHistorySecondBuffer

number
The amount, in milliseconds, that a ping is made to the server to test for latency.

options.worldState

object literal
Object containing all of the properties pertaining to world state for your game - f, u, n, etc., whatever you want to add to it.

options.onPlayerConnect(callback(socket))

Event fired when a player connects to the server.
callback function
Function to be invoked upon event firing.
socket Socket

options.onPlayerInput(callback(socket, input))

callback function
Function to be invoked upon event firing.
socket Socket

input object literal

options.onPlayerDisconnect(callback(socket))

callback function
Function to be invoked upon event firing.
socket Socket

options.onPing(callback(socket, data))

callback function
Function to be invoked upon event firing.
socket Socket

`data` number
The client start time when the ping was initiated.

options.onEvent(callback(data))

callback function
Function to be invoked upon event firing.
data object literal
Object containing all properties pertaining to the custom event.

start

GarageServerIO.start()

Starts the server time and broadcast loop.

stop

GarageServerIO.stop()

Stops the server time and broadcast loop.

getPlayers

GarageServerIO.getPlayers() : [, {id, state, [, inputs], [, {states, executionTimes}]}]

Returns: array

id string

state object literal

inputs array of object literals

stateHistory array of object literals

getEntities

GarageServerIO.getEntities() : [,{id, state, [, {state, executionTime }]}]

Returns: array

id string

state object literal

stateHistory array of object literals

updatePlayerState

GarageServerIO.updatePlayerState(id, state)

id string

state object literal

updateEntityState

GarageServerIO.updateEntityState(id, state)

id string

state object literal

addEntity

GarageServerIO.addEntity(id)

id string

removeEntity

GarageServerIO.removeEntity(id)

id string

sendPlayerEvent

GarageServerIO.sendPlayerEvent(id, data)

id string

data object literal

sendPlayersEvent

GarageServerIO.sendPlayersEvent(data)

data object literal

License

MIT License

README.md

GarageServer.IO

Features

Quick Start

Server

Client

API

Client

initializeGarageServer

Client Options

addInput

getPlayerStates

getEntityStates

getId

sendServerEvent

Server

createGarageServer

Server Options

object literal Object containing all of the properties pertaining to world state for your game - f, u, n, etc., whatever you want to add to it.

data number The client start time when the ping was initiated.

start

stop

getPlayers

getEntities

updatePlayerState

updateEntityState

addEntity

removeEntity

sendPlayerEvent

sendPlayersEvent

License

object literal
Object containing all of the properties pertaining to world state for your game - f, u, n, etc., whatever you want to add to it.

`data` number
The client start time when the ping was initiated.