Skip to content

Room API (Client-side)

Methods

listen (path: string, callback: Function)

Listen to room state changes from the room handler.

Use this method to synchronize the room state from the server with the clients.

Examples

Listening to map data structures

import { DataChange } from "colyseus.js";
// ...

room.listen("players/:id", (change: DataChange) => {
  if (change.operation === "add") {
    console.log("new player added to the state");
    console.log("player id:", change.path.id);
    console.log("player data:", change.value);

  } else if (change.operation === "remove") {
    console.log("player has been removed from the state");
    console.log("player id:", change.path.id);
  }
});
using Colyseus;
// ...

room.Listen("players/:id", OnPlayerChange);

void OnPlayerChange (DataChange change)
{
  if (change.operation == "add") {
    Debug.Log ("new player added to the state");
    Debug.Log (change.path["id"]);
    Debug.Log (change.value);

  } else if (change.operation == "remove") {
    Debug.Log ("player has been removed from the state");
    Debug.Log (change.path["id"]);
  }
});
room:listen("players/:id", function(change)
  if (change.operation == "add") then
    print("new player added to the state")
    print(change.path["id"])
    print(change.value)

  elseif (change.operation == "remove") then
    print("player has been removed from the state")
    print(change.path["id"])
  end
end)

Listening to attribute changes of deep data structures

import { DataChange } from "colyseus.js";
// ...

room.listen("players/:id/:attribute", (change: DataChange) => {
  console.log(change.operation); // => "add" | "remove" | "replace"
  console.log(change.path.attribute, "has been changed");
  console.log(change.path.id);
  console.log(change.value);
});
using Colyseus;
// ...

room.Listen("players/:id/:attribute", OnPlayerAttributeChange);

void OnPlayerAttributeChange (DataChange change)
{
  Debug.Log (change.operation); // => "add" | "remove" | "replace"
  Debug.Log (change.path["attribute"] + "has been changed");
  Debug.Log (change.path["id"]);
  Debug.Log (change.value);
});
room:listen("players/:id/:attribute", function()
  print(change.operation) // => "add" | "remove" | "replace"
  print(change.path["attribute"] + "has been changed")
  print(change.path["id"])
  print(change.value)
end)

Tip

See State synchronization for more examples on how to use the listen method.

send (data)

Send message to the room handler.

room.send({ move: "left" });
room.Send(new { move = "left" });
room:send({ move = "left" })

Use Room#onMessage() from the server-side to read the message.

leave ()

Disconnect from the room.

room.leave();
room.Leave();
room:leave()

Tip

Use Room#onLeave() to handle the disconnection from the server-side.

removeAllListeners()

Remove all event and data listeners.

Properties

id: string

The unique idenfitier of the room. You can share this id with other clients in order to allow them to connect directly to this room.

// get `roomId` from the query string
let roomId = location.href.match(/roomId=([a-zA-Z0-9\-_]+)/)[1];

// connect the client directly into a specific room id
let room = client.join(roomId);

Warning

If you're looking for the unique identifier of the client, use client.id instead.

sessionId: string

Unique session identifier.

This property matches the client.sessionId from the server-side.

name: string

Name of the room handler. Ex: "battle".

state: any

The current room's state. This variable is always synched with the latest state from the server-side. To listen for updates on the whole state, see onStateChange event.

Events

onStateChange

This event is triggered when the server updates its state.

room.onStateChange.addOnce(function(state) {
  console.log("this is the first room state!", state);
});

room.onStateChange.add(function(state) {
  console.log("the room state has been updated:", state);
});
room.OnStateChange += (object sender, RoomUpdateEventArgs e) => {
  if (e.isFirstState) {
    Debug.Log ("this is the first room state!");
  }

  Debug.Log ("the room state has been updated");
}
room:on("statechange", function(state)
  print("new state:", state)
end)

onMessage

This event is triggered when the server sends a message directly to the client.

room.onMessage.add(function(message) {
  console.log("server just sent this message:");
  console.log(message);
});
room.OnMessage += (object sender, MessageEventArgs e) => {
  Debug.Log ("server just sent this message:");
  Debug.Log(e.message);
}
room:on("message", function(message)
  print("server just sent this message:")
  print(message)
end)

Tip

To send a message from the server directly to the clients you'll need to use either room.send() or room.broadcast()

onJoin

This event is triggered when the client successfuly joins the room.

room.onJoin.add(function() {
  console.log("client joined successfully");
});
room.OnJoin += (object sender, EventArgs e) => {
  Debug.Log ("client joined successfully");
}
room:on("join", function()
  print("client joined successfully")
end)

onLeave

This event is triggered when the client leave the room.

room.onLeave.add(function() {
  console.log("client left the room");
});
room.OnLeave += (object sender, EventArgs e) => {
  Debug.Log ("client left the room");
}
room:on("leave", function()
  print("client left the room")
end)

onError

This event is triggered when some error occurs in the room handler.

room.onError.add(function(err) {
  console.log("oops, error ocurred:");
  console.log(err);
});
room.OnError += (object sender, EventArgs e) => {
  Debug.Log ("oops, error ocurred:");
  Debug.Log(e);
}
room:on("error", function()
  print("oops, error ocurred:")
  print(e)
end)