KUMODeck

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');
MethodNotes
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#

EventPayload
message{ from, type, data }
playerJoined / playerLeftplayer / { 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 / resumedyour 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.relayWhat happensGives up
alwaysevery message goes through the TURN relay; only the relay's address is visible; connects wherever the relay is reachablerelay traffic is billed by the amount sent
fallbackdirect first; the relay only when a direct connection failsplayers see each other's IP address when direct
neverdirect only; never any relay costplayers 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.

Players2–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)
Costrelay traffic is billed at cost as turn_egress_bytes (no markup); signaling is tiny
Errorswebrtc_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
Sizeno 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)
TimingsetP2POptions also takes connectTimeoutMs (default 10 s), disconnectGraceMs (5 s), maxRestarts (3), offerWaitMs (5 s) and stateTimeoutMs (15 s); they apply to voice connections too
Stateit 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.

LimitValue
Messages30/s per connection (burst 60) by default, up to 240/s per mode (limits.messagesPerSecond); excess is dropped with a warning event
Message size16 KB by default, up to 1 MB per mode (limits.maxMessageBytes; payload_too_large with details.limit)
Shared state64 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 drop20 seconds by default, up to 1 hour (limits.seatHoldSeconds)
Players per roomup to 1,000 (per mode). One room handles about 1,000 messages a second: keep players × messages per second around 1,000
Idle socketclosed 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: the functions-d1 Skill has one to copy).