API

Server/host API

The server API describes how to create a game server.

var host = new lobby.Host(lobbyUrl, port):

• lobbyUrl is the full web address of the lobby server to register the game with (i.e. 'http://lobby-flack.dotcloud.com').
• port is the local port to listen for incoming connections on. Note, this be ignored when WebRTC PeerConnections are implemented.

host.updateInfo(details):

• Updates the game information with the supplied dictionary. This can be called whenever there is an update to the current game state. You only have to pass the fields which have updated when calling this function (i.e. host.updateInfo({status: 'started'});). Recognized fields are:
  • gameId: Used to identify other connectable instances of the same game (i.e. 'lobby-chess').
  • name: A friendly name for the game type (i.e. 'Lobby Chess').
  • description: A textual description of a particular game instance (i.e. 'Expert 2v2').
  • status: The current state of the game. Currently recognized values include:
    • 'awaiting_players': The game is waiting for more players before starting.
    • 'started': The game is currently running.
  • accepting: True if the game is accepting players.
  • observable: True if the game is accepting observers.
  • password: True if the game requires a password to connect (not yet implemented).
  • players: A list of the current players in the game (i.e. ['Rob', 'Kevin']).
  • url: A URL at which this game's code can be downloaded (i.e. 'http://www.dynprojects.com/games/chess/').

var client = host.createLocalClient():

• Creates a local client connection allowing the host of the game to play as a connected client.

host.disconnect():

• Disconnects all connected clients and stops listening for new game connections.

host.disconnect(clientIndex):

• Disconnects the specified client.

host.send(clientIndex, message):

• JSON encodes the message object and sends the resulting string to the client identified by clientIndex.

var url = host.getGameUrl():

• Returns a URL which can be shared to allow others to connect to this game instance, or an empty string if this is not possible.

Events

host.addEventListener('ready', function(serverAddress)):

• This is dispatched when the server is listening on the incoming port for game clients.

host.addEventListener('connection', function(clientIndex)):

• Dispatched when a client connects to the server. The clientIndex will correspond to this connected client until they disconnect as the client list is a sparse array of client indices.

host.addEventListener('message', function(clientIndex, message)):

• Called when a message is received from the client identified by clientIndex. The message is a Javascript object (i.e. {type: 'message', text: 'Hello'}).

host.addEventListener('disconnection', function(clientIndex)):

• Called when a client disconnects, giving the clientIndex of the now disconnected client.

host.addEventListener('update', function(updatedInformation)):

• Called when the game information is updated by the lobby. This will for example inform the server if it is found to be publicly visible when updatedInformation.visibility == 'public'.

Client API

The client API is mostly a subset of the server API.

var client = new lobby.Client(gameInfo):

• Creates a new client and attempts to connect to the game described by the gameInfo object.

var client = new lobby.Client(gameInfo, overrideUrl):

• Same as above, but uses the overrideUrl address to connect to the server instead of the address described by gameInfo. This is used for lobby.Host.createLocalClient.

client.send(message):

• JSON encodes and sends the message object to the game server.

client.disconnect():

• Disconnects from the game server.

var url = client.getGameUrl():

• Returns a URL which can be shared to allow others to connect to the game or an empty string if this is not possible.

Events

client.addEventListener('connected', function()):

• Called when the client connection is established.

client.addEventListener('message', function(message)):

• Called when a message is received from the server. The message is a Javascript object.

client.addEventListener('disconnected', function()):

• Called when the client has been disconnected from the server for any means (i.e. an error, asked to disconnect, etc).