Skip to content

Room API (Client-side)

Methods

listen (path: string, callback: Function, immediate?: boolean)

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
room.listen("players/:id", (change) => {
  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)
room.listen("players/:id", function (change) {
  if (change.operation === "add") {
    trace("new player added to the state");
    trace("player id:" + change.path.id);
    trace("player data:" + Std.string(change.value));

  } else if (change.operation === "remove") {
    trace("player has been removed from the state");
    trace("player id:" + change.path.id);
  }
});
Listening to attribute changes of deep data structures
room.listen("players/:id/:attribute", (change) => {
  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)
room.listen("players/:id/:attribute", function(change) {
  trace(change.operation); // => "add" | "remove" | "replace"
  trace(change.path.attribute + " has been changed");
  trace(change.path.id);
  trace(Std.string(change.value));
});

Initial state / Listening to incoming AND existing data in the state

The callbacks will be triggered for each incoming change in the state after the moment of registration. To listen also for existing data on the state, make sure to pass true on the immediate argument.

room.listen("players/:id", (change) => {
  // ...
}, true); // immediate
using Colyseus;
// ...

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

void OnPlayerChange (DataChange change)
{
  // ...
});
room:listen("players/:id", function(change)
  -- ...
end, true) -- immediate
room.listen("players/:id", function (change) {
  // ...
}, true); // immediate

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" })
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()
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)
room.onStateChange = function(state) {
  trace("new state:" + Std.string(state));
};

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)
room.onMessage = function(message) {
  trace("server just sent this message:");
  trace(Std.string(message));
};

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)
room.onJoin = function () {
  trace("client joined successfully");
};

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)
room.onLeave = function () {
  trace("client left the room");
};

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)
room.onError = function(err) {
  trace("oops, error ocurred:");
  trace(err);
};