Skip to content

Room API (Server-side)

Considering that you already set up your server, now it's time to register room handlers, and start accepting connections from your users.

You'll define room handlers creating classes that extends from Room.

import http from "http";
import { Room, Client } from "colyseus";

export class MyRoom extends Room {
    // When room is initialized
    onCreate (options: any) { }

    // Authorize client based on provided options before WebSocket handshake is complete
    onAuth (client: Client, options: any, request: http.IncomingMessage) { }

    // When client successfully join the room
    onJoin (client: Client, options: any, auth: any) { }

    // When a client sends a message
    onMessage (client: Client, message: any) { }

    // When a client leaves the room
    onLeave (client: Client, consented: boolean) { }

    // Cleanup callback, called after there are no more clients in the room. (see `autoDispose`)
    onDispose () { }
}

const colyseus = require('colyseus');

export class MyRoom extends colyseus.Room {
    // When room is initialized
    onCreate (options) { }

    // Authorize client based on provided options before WebSocket handshake is complete
    onAuth (client, options, request) { }

    // When client successfully join the room
    onJoin (client, options, auth) { }

    // When a client sends a message
    onMessage (client, message) { }

    // When a client leaves the room
    onLeave (client, consented) { }

    // Cleanup callback, called after there are no more clients in the room. (see `autoDispose`)
    onDispose () { }
}

Abstract methods

Room handlers can implement all these methods.

onCreate (options)

Is called once when room is initialized. You may specify custom initialization options when registering the room handler.

Tip

The options will contain the merged values you specified on Server#define() + the options provided by client.joinOrCreate() or client.create()

onAuth (client, options, request)

Can be used to verify authenticity of the client that's joining the room.

If left non-implemented it returns true, allowing any client to connect.

See Authentication API section.

Getting player's IP address

You can use the request variable to retrieve the user IP address, http headers, and more. E.g.: request.headers['x-forwarded-for'] || request.connection.remoteAddress

onJoin (client, options, auth?)

Parameters:

Is called when client successfully join the room, after requestJoin and onAuth has been succeeded.

onMessage (client, data)

Is called when a client sends a message to the server. Here's where you'll process client actions to update the room's state.

Example:

onMessage (client, data) {
    let player = this.playersByClientId.get(client);

    if (data.command === "left") {
        player.x -= 1;

    } else if (data.command === "right") {
        player.x += 1;
    }
}

onLeave (client, consented)

Is called when a client leave the room. If the disconnection was initiated by the client, the consented parameter will be true, otherwise, it will be false.

You can define this function as async. See graceful shutdown

onDispose ()

Cleanup callback, called after there are no more clients in the room.

You can define this function as async. See graceful shutdown

Public properties

roomId: string

A unique, auto-generated, 9-character-long id of the room.

roomName: string

The name of the room you provided as first argument for gameServer.define().

state: T

The state instance you provided to setState().

clients: WebSocket[]

The array of connected clients. See Web-Socket Client.

maxClients: number

Maximum number of clients allowed to connect into the room. When room reaches this limit, it is locked automatically. Unless the room was explicitly locked by you via lock() method, the room will be unlocked as soon as a client disconnects from it.

patchRate: number

Frequency to send the room state to connected clients, in milliseconds. Default is 50ms (20fps)

autoDispose: boolean

Automatically dispose the room when last client disconnect. Default is true

locked: boolean (read-only)

This property will change on these situations:

  • The maximum number of allowed clients has been reached (maxClients)
  • You manually locked, or unlocked the room using lock() or unlock().

clock: ClockTimer

A ClockTimer instance, used for timing events.

presence: Presence

The presence instance. Check Presence API for more details.

Public methods

Room handlers have these methods available.

setState (object)

Set the new room state instance. See State Handling for more details on the state object. It's highly recommended to use the new Schema Serializer to handle your state.

Warning

Do not call this method for updates in the room state. The binary patch algorithm is re-set every time you call it.

Tip

You usually will call this method only once during onCreate() in your room handler.

setSimulationInterval (callback[, milliseconds=16.6])

(Optional) Set a simulation interval that can change the state of the game. The simulation interval is your game loop. Default simulation interval: 16.6ms (60fps)

onCreate () {
    this.setSimulationInterval((deltaTime) => this.update(deltaTime));
}

update (deltaTime) {
    // implement your physics or world updates here!
    // this is a good place to update the room state
}

setPatchRate (milliseconds)

Set frequency the patched state should be sent to all clients. Default is 50ms (20fps)

setPrivate (bool)

Set the room listing as private (or revert to public, if false is provided).

Private rooms are not listed in the getAvailableRooms() method.

setMetadata (metadata)

Set metadata to this room. Each room instance may have metadata attached to it - the only purpose for attaching metadata is to differentiate one room from another when getting the list of available rooms from the client-side, to connect to it by its roomId, using client.getAvailableRooms().

// server-side
this.setMetadata({ friendlyFire: true });

Now that a room has metadata attached to it, the client-side can check which room has friendlyFire, for example, and connect directly to it via its roomId:

// client-side
client.getAvailableRooms("battle").then(rooms => {
  for (var i=0; i<rooms.length; i++) {
    if (room.metadata && room.metadata.friendlyFire) {
      //
      // join the room with `friendlyFire` by id:
      //
      var room = client.join(room.roomId);
      return;
    }
  }
});

Tip

See how to call getAvailableRooms() in other languages.

setSeatReservationTime (seconds)

Set the number of seconds a room can wait for a client to effectively join the room. You should consider how long your onAuth() will have to wait for setting a different seat reservation time. The default value is usually enough. (8 seconds)

send (client, message)

Send a message to a particular client. The message can be either a plain JavaScript object, or a Schema instance.

Sending a msgpack-encoded message:

This is the recommended way if you're using an interpreted language on the client-side, such as JavaScript or LUA.

this.send(client, { message: "Hello world!" });

Sending a schema-encoded message:

Sending schema-encoded messages is particularly useful for statically-typed languages such as C#.

class MyMessage extends Schema {
  @type("string") message: string;
}

const data = new MyMessage();
data.message = "Hello world!";
this.send(client, data);

Tip

See how to handle these messages on client-side.

broadcast (message, options?)

Send a message to all connected clients.

Available options are:

  • except: a Client instance not to send the message to
  • afterNextPatch: waits until next patch to broadcast the message

Broadcast examples

Broadcasting a message to all clients:

onMessage (client, message) {
    if (message === "action") {
        // broadcast a message to all clients
        this.broadcast("an action has been taken!");
    }
}

Broadcasting a message to all clients, except the sender.

onMessage (client, message) {
    if (message === "fire") {
        // sends "fire" event to every client, except the one who triggered it.
        this.broadcast("fire!", { except: client });
    }
}

Broadcasting a message to all clients, only after a change in the state has been applied:

onMessage (client, message) {
    if (message === "destroy") {
        // perform changes in your state!
        this.state.destroySomething();

        // this message will arrive only after new state has been applied
        this.broadcast("has been destroyed!", { afterNextPatch: true });
    }
}

Broadcasting a schema-encoded message:

class MyMessage extends Schema {
  @type("string") message: string;
}

// ...

onMessage (client, message) {
    if (message === "action") {
        const data = new MyMessage();
        data.message = "an action has been taken!";
        this.broadcast(data);
    }
}

Tip

See how to handle these onMessage() in the client-side.

lock ()

Locking the room will remove it from the pool of available rooms for new clients to connect to.

unlock ()

Unlocking the room returns it to the pool of available rooms for new clients to connect to.

allowReconnection (client, seconds)

Allow the specified client to reconnect into the room. Must be used inside onLeave() method.

async onLeave (client, consented: boolean) {
  // flag client as inactive for other users
  this.state.players[client.sessionId].connected = false;

  try {
    if (consented) {
        throw new Error("consented leave");
    }

    // allow disconnected client to reconnect into this room until 20 seconds
    await this.allowReconnection(client, 20);

    // client returned! let's re-activate it.
    this.state.players[client.sessionId].connected = true;

  } catch (e) {

    // 20 seconds expired. let's remove the client.
    delete this.state.players[client.sessionId];
  }
}

disconnect ()

Disconnect all clients, then dispose.