Relay Room

The built-in RelayRoom provides a lightweight relay for simple multiplayer use cases where you only need to track connected clients.

Features:

Broadcasts client messages to everyone else.
Minimal backend state (no authoritative validation).
Ideal for quick prototypes or frontend-driven validation.

The source-code for RelayRoom is available here. Consider implementing your own version with backend validations when needed.

Server

server.ts

import { defineServer, defineRoom, RelayRoom } from "colyseus";
 
//
// Expose your relayed room.
//
const server = defineServer({
  rooms: {
    your_relayed_room: defineRoom(RelayRoom, {
      maxClients: 4,
      allowReconnectionTime: 120
    })
  }
})

Client

See how to register callbacks for players joining, leaving, sending and receiving messages from the relayed room.

Connecting into the room

client.ts

import { Client } from "@colyseus/sdk";
 
const client = new Client("http://localhost:2567");
 
//
// Join the relayed room.
//
const relay = await client.joinOrCreate("your_relayed_room", {
  name: "This is my name!"
});

Registering callbacks when players join and leave

client.ts

//
// Detect when a player joined the room.
//
relay.state.players.onAdd((player, sessionId) => {
  if (relay.sessionId === sessionId) {
    console.log("It's me!", player.name);
 
  } else {
    console.log("It's an opponent", player.name, sessionId);
  }
})
 
//
// Detect when a player left the room.
//
relay.state.players.onRemove((player, sessionId) => {
  console.log("Opponent left!", player, sessionId);
})
 
//
// Detect when the connectivity of a player has changed.
// (only available if you provided `allowReconnection: true` in the backend)
//
relay.state.players.onChange((player, sessionId) => {
  if (player.connected) {
    console.log("Opponent has reconnected!", player, sessionId);
 
  } else {
    console.log("Opponent has disconnected!", player, sessionId);
  }
})

Sending and receiving messages

client.ts

//
// By sending a message, all other clients will receive it under the same name.
// Messages are only sent to other connected clients, never the current one.
//
relay.send("fire", {
  x: 100,
  y: 200
});
 
//
// Register a callback for messages you're interested in from other clients.
//
relay.onMessage("fire", ([sessionId, message]) => {
 
  //
  // The `sessionId` from who sent the message
  //
  console.log(sessionId, "sent a message!");
 
  //
  // The actual message sent by the other client
  //
  console.log("fire at", message);
});

Queue Room State Synchronization