The GameRoom template — add a multiplayer room

cli tutorial Intermediate ⏱ 6 min vgai 0.1.0

Prerequisites: Colyseus rooms

What you'll learn

• Read the GameRoom template's Colyseus Schema state
• Know how a room is registered (name → handler)
• Point an example at a room with the manifest's server.room

What you'll build: A terminal tour of the GameRoom template — the generic multiplayer starting point.

GameRoom is the generic multiplayer room the template ships as a starting point — a small arena with players and collectible orbs. The shipped arena example uses its own room (arena_room), but GameRoom is the one you copy when adding multiplayer to your own game. This is a terminal tour of it (real captured output below).

The GameRoom template — add a multiplayer room

# transcript pending capture — run: node site/media/capture-cli.mjs

Terminal — The GameRoom template — add a multiplayer room · captured by site/media/capture-cli.mjs

Steps

1. The room is its Schema state. game-room.ts defines PlayerSchema (sessionId, name, color, x/y/z, score), OrbSchema (id, x, z), and GameState (maps of players + orbs). With @colyseus/schema, the server mutates state directly and Colyseus delta-encodes and syncs it to every client — new joiners get the full state automatically. Clients only send a position message (onMessage); everything else is server-authoritative state. onJoin/onLeave add and remove players.

2. Register it, then opt in. rooms.ts registers two rooms — { name: 'game_room', handler: GameRoom } and { name: 'arena_room', handler: ArenaRoom }. An example points at a room by declaring "server": {"room": "..."} in its folder’s vgai.game.json (the shipped third-person-arena example uses arena_room); set "room": "game_room" to use this one.

Adding your own room

Copy game-room.ts, rename the class, define your Schema state, and add { name: 'my_room', handler: MyRoom } to rooms.ts. On the client, connect with the Colyseus Callbacks API (Callbacks.get(room) + onAdd/onChange/onRemove) and read live schema properties in onChange — don’t destructure schema fields into copies. The shipped third-person-arena example is a worked client reference.

Recap

New functionality

• Read the GameRoom Schema state (players + orbs)
• Saw the room registered and how an example opts in

New concepts & skills

• a Colyseus room IS its @colyseus/schema state — server mutates, deltas sync automatically
• clients send minimal input (position); the server is authoritative
• rooms.ts maps a name → handler; an example selects it via its manifest's server.room

Next lesson → Colyseus rooms (reference)

See also

• Colyseus rooms (reference) · Multiplayer Developer pathway