Core Concepts

┌─────────────────────────────────────────────────────────────┐
│                        ROOM LIFECYCLE                        │
└─────────────────────────────────────────────────────────────┘

  ┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
  │ onCreate │ ──> │  onJoin  │ ──> │ onLeave  │ ──> │ onDispose│
  └──────────┘     └──────────┘     └──────────┘     └──────────┘
       │                │                │                │
       │                │                │                │
       v                v                v                v
  Room created    Client joins     Client leaves    Room destroyed
  Initialize      Add to state     Remove from      Clean up
  state/logic     Send welcome     state            resources

class GameRoom extends Room {
    maxClients = 4;
    state = new GameState();
 
    onCreate(options) {
        this.setMetadata({ map: options.map });
    }
 
    onJoin(client) {
        this.state.players.set(client.sessionId, new Player());
 
        if (this.clients.length === this.maxClients) {
            this.lock(); // Prevent more joins
            this.startGame();
        }
    }
}

class LobbyRoom extends Room {
    state = new LobbyState();
 
    onCreate() {
        this.onMessage("ready", (client) => {
            const player = this.state.players.get(client.sessionId);
            player.isReady = true;
 
            if (this.allPlayersReady()) {
                this.broadcast("gameStarting");
                // Transfer players to game room
            }
        });
    }
}

onJoin(client, options) {
    if (options.spectator) {
        // Don't add to players, just let them watch
        this.state.spectators.push(client.sessionId);
    } else {
        this.state.players.set(client.sessionId, new Player());
    }
}

class WorldRoom extends Room {
    autoDispose = false; // Don't destroy when empty
 
    onCreate() {
        // Load world state from database
        this.loadWorldState();
    }
 
    onDispose() {
        // Save before shutting down
        this.saveWorldState();
    }
}

// To everyone
this.broadcast("announcement", { text: "Game starting!" });
 
// To everyone except one client
this.broadcast("playerAction", data, { except: client });

this.send(client, "privateMessage", { text: "You found a bonus!" });

this.state.players.get(sessionId).score += 10;
// All clients receive this update automatically

import { Schema, type, MapSchema } from "@colyseus/schema";
 
class Player extends Schema {
    @type("number") x: number = 0;
    @type("number") y: number = 0;
    @type("number") health: number = 100;
}
 
class GameState extends Schema {
    @type({ map: Player }) players = new MapSchema<Player>();
    @type("string") phase: string = "waiting";
}

// Listen when a player is added
callbacks.onAdd("players", (player, sessionId) => {
    console.log("Player joined:", sessionId);
 
    // Listen to this specific player's position changes
    callbacks.onChange(player, "x", (value) => {
        updatePlayerPosition(sessionId, value, player.y);
    });
});

// Broadcast to all clients
this.broadcast("gameEvent", { type: "explosion", x: 100, y: 200 });
 
// Send to a specific client
this.send(client, "privateNotification", { message: "You found a secret!" });

room.onMessage("gameEvent", (data) => {
    if (data.type === "explosion") {
        playExplosionEffect(data.x, data.y);
    }
});
 
room.onMessage("privateNotification", (data) => {
    showNotification(data.message);
});

1. Does this data need to be known by clients who join later?
   YES → Use State
   NO  → Consider Messages

2. Do clients need the current value, or just react to changes?
   CURRENT VALUE → Use State
   REACT TO EVENT → Messages work fine

3. Is this data used in game logic calculations?
   YES → Use State (server needs authoritative value)
   NO  → Messages may be sufficient

4. How often does this change?
   FREQUENTLY (every frame) → Use State with delta sync
   RARELY (events) → Messages are more explicit

// Bad: Position via messages
this.onMessage("move", (client, pos) => {
    this.broadcast("playerMoved", { id: client.sessionId, x: pos.x, y: pos.y });
});
 
// Good: Position in state
this.onMessage("move", (client, pos) => {
    const player = this.state.players.get(client.sessionId);
    player.x = pos.x;
    player.y = pos.y;
    // Automatically synced to all clients
});

// Bad: Chat in state (grows forever, unnecessary sync)
class GameState extends Schema {
    @type([ChatMessage]) chatHistory = new ArraySchema<ChatMessage>();
}
 
// Good: Chat via messages
this.onMessage("chat", (client, text) => {
    this.broadcast("chatMessage", {
        sender: client.sessionId,
        text
    });
});

// Bad: Sending health in both state AND message
target.health -= damage;
this.broadcast("damage", { targetId, newHealth: target.health, damage });
 
// Good: State handles the value, message just triggers the effect
target.health -= damage;
this.broadcast("damageEffect", { targetId, damage });
// Client reads current health from state

Client                    Matchmaker                   Room Instances
  |                           |                              |
  |--- joinOrCreate("game") ->|                              |
  |                           |--- Search for available ---->|
  |                           |<-- Found Room A -------------|
  |                           |--- Reserve seat ------------>|
  |<-- Connection details ----|                              |
  |                           |                              |
  |=============== WebSocket Connection to Room A ===========|

onCreate(options) {
    // Set metadata that clients can filter by
    this.setMetadata({
        mode: options.mode || "casual",
        map: options.map || "default",
        currentPlayers: 0
    });
}
 
onJoin(client) {
    // Update metadata as the room state changes
    this.setMetadata({ currentPlayers: this.clients.length });
}

// Only join rooms with mode="ranked" and map="arena"
const room = await client.joinOrCreate("battle", {
    mode: "ranked",
    map: "arena"
});

import { defineServer, defineRoom } from "colyseus";
import { BattleRoom } from "./BattleRoom";
 
const server = defineServer({
    rooms: {
        battle: defineRoom(BattleRoom, {
            // Only "mode" and "map" will be used for filtering
            // Other options are passed to onCreate but don't affect matching
            filterBy: ["mode", "map"]
        })
    }
});

// Get all available "battle" rooms
const rooms = await client.getAvailableRooms("battle");
 
rooms.forEach((room) => {
    console.log(room.roomId, room.metadata, room.clients);
});
 
// Join a specific room
const selectedRoom = rooms[0];
const room = await client.joinById(selectedRoom.roomId);

onJoin(client) {
    if (this.clients.length >= this.maxClients) {
        // Room is full, lock it
        this.lock();
    }
}
 
startGame() {
    // Lock the room when the game starts
    this.lock();
}

onCreate(options) {
    this.setMetadata({
        skillBracket: this.getSkillBracket(options.playerSkill)
    });
}
 
getSkillBracket(skill: number): string {
    if (skill < 1000) return "bronze";
    if (skill < 2000) return "silver";
    if (skill < 3000) return "gold";
    return "platinum";
}

const room = await client.joinOrCreate("ranked", {
    playerSkill: 1500  // Will match with "silver" bracket
});

onCreate(options) {
    if (options.private) {
        this.setPrivate(true);  // Won't appear in listings
    }
}

// Create a private room
const room = await client.create("game", { private: true });
const inviteCode = room.roomId;  // Share this with friends
 
// Friend joins using the code
const room = await client.joinById(inviteCode);