Multiplayer rooms
For games. Rooms are real-time sessions over one WebSocket: quick match, private rooms with a 6-letter code, a public lobby, message relay, shared room state, per-player state, host migration and reconnection. No server code to write.
Join a room#
// resolves when a room is ready
const room = await kumo.rooms.quickMatch('duel');
// or
const room = await kumo.rooms.create('duel', { private: true });
// e.g. "K7QM3X"
showCode(room.code);
// the other player:
// room id or code, case-insensitive
const room = await kumo.rooms.join('k7qm3x');| Method | Notes |
|---|---|
rooms.quickMatch(mode) | joins the fullest open public room of that mode, or waits in a queue until minPlayers are ready (or fillTimeoutSeconds pass) |
rooms.cancelMatch() | stop waiting (the pending quickMatch rejects with match_cancelled) |
rooms.create(mode, opts) | private, maxPlayers, metadata (≤ 2 KB, shown in the lobby), custom code, hostOnlyState |
rooms.join(idOrCode) | room_not_found, room_full, room_locked |
rooms.list(mode?) | open public rooms for a lobby, most players first |
rooms.warmUp() | connect and sign in now, before any room call; resolves true / false, never throws |
Connect before the button is pressed#
Call kumo.rooms.warmUp() when the online button appears (title or menu screen). It loads the rooms code, opens the
connection and signs in while the player reads the menu, so pressing the button only waits for the room reply.
showMenu();
void kumo.rooms.warmUp();room.timings shows where the wait went: connectMs (connecting, ~0 after warmUp()), replyMs (the room reply)
and attachMs (the room's own connection, opened after the reply; the room is usable before it). Right after joining,
attachMs is null and attach is 'pending'; room.on('timings', (t) => …) fires once it is settled
(attach: 'attached', 'failed' or 'none').
Modes come from config. A project without modes gets a built-in default mode (2–8 players) so two browser tabs
can meet before you write any config:
{ "multiplayer": { "modes": [
{ "key": "duel", "minPlayers": 2, "maxPlayers": 2, "fillTimeoutSeconds": 20 },
{ "key": "party", "minPlayers": 1, "maxPlayers": 8, "fillTimeoutSeconds": 0 }
] } }Talk#
// to everyone else (fire-and-forget, ordered)
room.send('move', { x, y });
room.send('hit', { dmg: 3 }, { to: [targetId] }); // to specific players
room.on('message', ({ from, type, data }) => { … });
// shared state: everyone (you too) gets 'stateChanged'
await room.setState({ round: 2 });
await room.setMyState({ ready: true, skin: 'red' }); // your player state: 'playerStateChanged'
// current shared state
room.state;
// [{ id, displayName, connected, joinedAt, state }]
room.players;State patches are applied in the same order on every client (a null value deletes a key), so all clients agree.
Use send for high-frequency data (positions), state for things late joiners must see (scores, seats, settings).
Host#
room.hostId / room.isHost: the earliest-joined connected player. If the host leaves or drops, the next player
becomes host immediately (hostChanged), and a returning player never takes it back. Use the host for authority:
simulate on the host and broadcast snapshots. With hostOnlyState: true, only the host can setState.
room.lock() (host only) stops new players from joining a match in progress.
The room is not closed when the host goes — it lives while anyone is in it. If only the host's tab ran the match, the new
host carries on from room.state or ends the match with a plain message; never leave the others on a frozen screen.
Events#
| Event | Payload |
|---|---|
message | { from, type, data } |
playerJoined / playerLeft | player / { playerId, reason: 'left' | 'timeout' } |
playerDisconnected | { playerId, reason: 'closed' | 'lost' } — within seconds; their seat is kept while they come back. closed = they closed or reloaded the tab, lost = their connection dropped or went silent (in peer-to-peer rooms also when only the direct link broke) |
playerReconnected | { playerId } — back in their seat |
stateChanged | { patch, state, by, version } |
playerStateChanged | { playerId, patch, state } |
hostChanged | { hostId, previousHostId } |
reconnecting / resumed | your own connection dropped / came back (state refreshed from a snapshot) |
closed | { reason } — left, seat_expired, connection_lost, replaced, shutdown, unauthorized |
kumo.rooms.on('connection', state => …) reports connecting, open, reconnecting, closed.
Reconnects and page reloads#
The SDK reconnects automatically with backoff; the server keeps your seat for 20 seconds. After a page reload the
Room object is gone but the seat is not:
// { roomId, mode, code, expiresInMs } or null
const held = await kumo.rooms.fetchHeldRoom();
// back in, state restored from a snapshot
if (held) room = await kumo.rooms.rejoin();On page load, kumo.rooms.rejoinIfReloaded() does this for you, but only for the same tab, the same player, while the
seat is kept — so a guest who came by invite link gets back after a reload just like the host, and a second tab of the
same player never takes over the match. It returns the Room or null, never throws, and does not even connect on a
normal page load:
const room = await kumo.rooms.rejoinIfReloaded();
if (room) resumeMatch(room); else showMenu();When a tab closes or navigates away, the SDK tells the server (pagehide): the others get playerDisconnected with
reason closed at once, the seat is kept about 10 seconds (a reload comes back in that time), then playerLeft with
reason left. A mode with a longer seatHoldSeconds keeps its own time.
Or just start something new — create, join or quickMatch release the old seat as a normal leave.
Peer-to-peer mode#
By default every message goes through KUMODeck's servers. A mode with "transport": "p2p" instead sends game
messages directly between players over WebRTC. KUMODeck still does the tedious parts: matchmaking, room codes,
joining and leaving, choosing the host, relaying the WebRTC handshake, and handing out short-lived TURN relay
credentials. Your code does not change:
{ "key": "coop", "minPlayers": 2, "maxPlayers": 4, "transport": "p2p", "p2p": { "maxPlayers": 4, "relay": "fallback" } }const room = await kumo.rooms.quickMatch('coop');
// 'p2p'
room.transport;
// unordered, no retransmit: good for positions
room.send('pos', { x, y }, { reliable: false });
room.on('peer', ({ playerId, state, relayed }) => { … }); // connecting | connected | failed | closed
// [{ playerId, state, relayed }]
room.peers;The SDK connects everyone to everyone (a mesh), uses the TURN relay as p2p.relay says (below), and keeps
shared state working when the host leaves: the server picks the next host (same rule as above), which continues
from its copy of the state, and unconfirmed setState calls are resent to it.
Warning — no referee. In peer-to-peer rooms the host's browser decides the shared state, and a modified client can send anything. Use the default server transport for competitive, prize or paid matches.
Warning — IP addresses. A direct WebRTC connection shows each player's IP address (roughly where they live) to the others. Choose with
p2p.relay:
p2p.relay | What happens | Gives up |
|---|---|---|
always | every message goes through the TURN relay; only the relay's address is visible; connects wherever the relay is reachable | relay traffic is billed by the amount sent |
fallback | direct first; the relay only when a direct connection fails | players see each other's IP address when direct |
never | direct only; never any relay cost | players who cannot reach each other directly fail to connect (peer event state: 'failed') |
Which to pick, and the price per match of each way, is in Play online together: the
multiplayer Skill asks the creator once and picks it.
| Players | 2–8 per mesh (p2p.maxPlayers, default 4 — every player uploads to every other player). A full mesh refuses joins with p2p_room_full (details.max) |
| Cost | relay traffic is billed at cost as turn_egress_bytes (no markup); signaling is tiny |
| Errors | webrtc_unavailable (no WebRTC in this environment), turn_unavailable (a relay is required but not available), setState rejects with timeout if the host cannot be reached |
| Size | no limit (peer-to-peer traffic never goes through KUMO's servers). The SDK splits large messages and states. A game that wants limits sets them with kumo.rooms.setP2POptions({ maxMessageBytes, maxStateBytes, maxPlayerStateBytes }); going over gives payload_too_large / state_too_large (with details.limit). One received message is capped at 64 MiB by default (maxReceiveBytes, to protect the device from a modified client) |
| Timing | setP2POptions also takes connectTimeoutMs (default 10 s), disconnectGraceMs (5 s), maxRestarts (3), offerWaitMs (5 s) and stateTimeoutMs (15 s); they apply to voice connections too |
| State | it disappears when everyone leaves |
To try it, open the game in two different browsers (or one normal and one private window), quick match the same
p2p mode, and check room.peers shows connected in both.
Limits#
Room size and size limits are being raised. Passing one gives the number in the error's message or details.limit (do not copy numbers into your game). Why each exists and the way around it: Limits.
| Limit | Value |
|---|---|
| Messages | 30/s per connection (burst 60) by default, up to 240/s per mode (limits.messagesPerSecond); excess is dropped with a warning event |
| Message size | 16 KB by default, up to 1 MB per mode (limits.maxMessageBytes; payload_too_large with details.limit) |
| Shared state | 64 KB total by default, up to 1 MB; player state 8 KB each, up to 64 KB (limits.maxStateBytes / limits.maxPlayerStateBytes). Shared state plus all player states stay under 1.75 MB |
| Seat kept after a drop | 20 seconds by default, up to 1 hour (limits.seatHoldSeconds) |
| Players per room | up to 1,000 (per mode). One room handles about 1,000 messages a second: keep players × messages per second around 1,000 |
| Idle socket | closed after 10 minutes outside any room by default (multiplayer.idleTimeoutSeconds; reconnects on the next call) |
room.limits has the room's actual limits (maxMessageBytes, maxStateBytes, maxPlayerStateBytes, messagesPerSecond,
seatHoldMs in milliseconds; null on an older server) — read them there instead of hard-coding numbers.
One browser profile = one player: a second tab replaces the first tab's connection. To test multiplayer on one
machine, give each tab its own storage (the templates use ?player=2).
Note Rooms relay and synchronise; they do not run your game logic on the server. Competitive games should be host-authoritative (see
examples/sky-duel), or check every move on the server with your own Functions (a Durable Object per match: thefunctions-d1Skill has one to copy).