@idosgames/mcp 0.1.35 → 0.1.37

package/registry/skills/multiplayer-realtime.json

@@ -1,7 +1,7 @@
 {
   "name": "multiplayer-realtime",
   "description": "Build realtime peer-to-peer multiplayer in a game on the iDosGames TypeScript SDK via client.multiplayer (MultiplayerService): create, join, list and close rooms, relay WebRTC offers/answers and ICE candidates, poll for signal/chat/presence envelopes, in-room chat, ready/lobby state, host handover (claimHost), kick/ban; plus the ready WebRTC transport RealtimeSession from @idosgames/core/realtime. It is a signaling and room relay, not a gameplay or economy module. Use this whenever the user wants realtime rooms or lobbies, WebRTC signaling, peer-to-peer setup, in-room chat or ready-check UIs, or touches client.multiplayer, MultiplayerService, RoomSnapshotResponse, RealtimeEnvelope or RealtimeSession — even without naming the module. In an app with the base (lobby) a game does NOT open rooms: it registers in ctx.multiplayer (registerGame) and takes the room in start(room) — read the first section.",
-  "content": "---\nname: multiplayer-realtime\ndescription: >-\n  Build realtime peer-to-peer multiplayer in a game on the iDosGames\n  TypeScript SDK via client.multiplayer (MultiplayerService): create, join,\n  list and close rooms, relay WebRTC offers/answers and ICE candidates, poll for\n  signal/chat/presence envelopes, in-room chat, ready/lobby state, host\n  handover (claimHost), kick/ban; plus the ready WebRTC transport\n  RealtimeSession from @idosgames/core/realtime. It is a signaling and room\n  relay, not a gameplay or economy module. Use this whenever the user wants\n  realtime rooms or lobbies, WebRTC signaling, peer-to-peer setup, in-room chat\n  or ready-check UIs, or touches client.multiplayer, MultiplayerService,\n  RoomSnapshotResponse, RealtimeEnvelope or RealtimeSession — even without\n  naming the module. In an app with the base (lobby) a game does NOT open rooms:\n  it registers in ctx.multiplayer (registerGame) and takes the room in\n  start(room) — read the first section.\n---\n\n# Multiplayer realtime signaling (iDosGames TS SDK)\n\nMultiplayer is a **realtime WebRTC signaling relay**, not a gameplay or\neconomy module. It gives you room lifecycle (create/join/leave/list/close) and\na message relay for two things peer-to-peer games need: SDP offer/answer + ICE\ncandidate exchange (so browsers/clients can establish a direct WebRTC\nconnection), and optional server-relayed chat/presence. The actual game state\nsync between players happens over the WebRTC connection you establish\nyourself — this module only gets players into the same room and helps them\nfind each other.\n\n**No currency/item coupling, no per-player cache mirror.** Unlike every other\nmodule in this SDK, no Multiplayer action ever returns a `ResourceOperation`\nor writes to `client.data.user.state` — there is nothing to mirror into a\nlocal player-state cache. Room state itself is ephemeral (Redis, TTL-based, no\nMongo document), so the SDK surface here is pure transport + event-emission:\ncall a method, get a response, emit an event, done. There is no\n`user:multiplayerUpdated` event and no `client.data.user.state.Multiplayer` —\ndon't look for either. The one piece of _config_ this module does expose —\n`MultiplayerDefinitions` (feature switch, topology/chat defaults, room-size\ncap, TTL, payload limits, ICE servers) — rides in on the title's public\nconfig bundle rather than a dedicated fetch call; see\n[Reading limits from config](#reading-limits-from-config).\n\nThis skill is for **using** the production `MultiplayerService`, not for\nporting or extending it. **Don't hand-roll WebRTC** on top of it: the SDK ships\n`RealtimeSession` (`@idosgames/core/realtime`, see\n[Recommended: RealtimeSession](#recommended-realtimesession)) which owns the\n`RTCPeerConnection`s, the poll loop and the signaling etiquette the backend\nexpects. The raw methods below are for lobby UI and for the rare custom\ntransport. Server rejections (room full, wrong join\ncode, not the owner, payload too large) are backend rules — surface them,\ndon't try to pre-validate every one of them client-side.\n\n## A game in an app with the base: `ctx.multiplayer` — do NOT open rooms yourself\n\nIn a project built on the base (lobby) the ROOMS belong to the multiplayer system (the `multiplayer`\nmodule): the list of rooms, \"Create a room\", joining by invite, members, \"Ready\", chat — and the\n`RealtimeSession`, opened already in the lobby. A game never calls `createRoom`/`joinRoom`/\n`RealtimeSession.create|join`; it declares how it plays online and TAKES the room:\n\n```ts\n// module.ts, in setup()\nctx.multiplayer.registerGame({\n  mode: \"my-game\", // the game's route id — the room's game\n  topology: \"Host\", // \"Host\" (star) | \"Mesh\"\n  chatMode: \"P2P\", // the game has its own chat; \"ServerRelay\" = the lobby's chat\n  maxPlayers: 8,\n  joinInProgress: true, // a player may join a running game (your late-joiner path)\n  settings: [\n    // the host picks them in \"Create a room\"\n    {\n      id: \"mode\",\n      label: \"Mode\",\n      kind: \"choice\",\n      default: \"coop\",\n      options: [\n        { value: \"coop\", label: \"Co-op\" },\n        { value: \"pvp\", label: \"PvP\" },\n      ],\n    },\n    { id: \"cheats\", label: \"Cheats for all\", kind: \"toggle\", default: false },\n  ],\n  // Called on EVERY member's device after the app switched to the game's mode (the host first).\n  start: async (room) => {\n    const game = await whenGameMounted(); // the scene may mount on this very switch\n    game.playOnline(room.session, {\n      host: room.isHost && !room.lateJoin, // opens its world for the others\n      settings: room.settings, // { mode: \"coop\", cheats: false }\n      leave: room.leave, // leave through the lobby, never session.leave()\n    });\n  },\n});\n```\n\n- The lobby then draws \"With friends\" next to the game's \"Play\" (its rooms), and the rooms screen\n  offers the game in \"Create a room\". A game's own \"Play with friends\" button:\n  `ctx.features.open(\"multiplayer\", { mode: \"my-game\", create: true })` — from inside the game it\n  switches to the lobby by itself.\n- Show that button only while `ctx.features.get(\"multiplayer\")?.available` — without the system the\n  game is single-player, nothing else changes.\n- Leave with `room.leave()`: the lobby owns the room and forgets it together with the session.\n- Messages on the session are yours from `start` on; the lobby's own start message goes out before\n  any of yours on the ordered channel and never reaches the game.\n- Reference implementation: `modules/voxelcraft` (`module.ts` → `registerGame`, `net/NetGame.ts` →\n  `NetGame.fromRoom`, `main.ts` → `Game.acceptRoom`).\n\nEverything below — `client.multiplayer` and `RealtimeSession` directly — is for an app WITHOUT the\nbase, or for writing the rooms system itself.\n\n## Mental model\n\n1. One player **creates a room** (picks topology/chat mode/visibility/max\n   players, optionally a join code); others **join** by room id (+ join code\n   if private). **A player can only be in one room at a time** — creating or\n   joining while already in a live room fails; leave first.\n2. Each member **polls** the room on a cursor (`LastSeq`) to receive a stream\n   of envelopes: other members' signals, chat, presence changes\n   (join/leave/host-migration), and room-closed notices. Polling is also the\n   heartbeat — it's what keeps your presence and the room's Redis TTL alive.\n3. To establish a direct connection, members exchange SDP offer/answer and ICE\n   candidates by calling **`sendSignal`** — the server just relays the\n   `payload` string to a specific `targetUserID`; it never inspects or\n   validates WebRTC semantics.\n4. Optional **`sendChat`** (only meaningful when the room's `ChatMode` is\n   `ServerRelay` — under `P2P` chat should go over your own DataChannel\n   instead) and **`setMemberState`** (ready flags + a free-form string map)\n   round out lobby UX.\n5. Someone **leaves**, or the owner/host **closes** the room; on host\n   departure the server may migrate to a `NewHostUserID` if members remain.\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst mp = client.multiplayer; // the MultiplayerService\n```\n\nEvery method requires an authenticated session. Without one they return\n`{ ok: false, reason: \"unauthorized\" }` — they do not throw. There is one\n`client` per player; don't share it across sessions.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>`: a discriminated union that is\neither `{ ok: true, data }` or `{ ok: false, reason, error }`. Always branch on\n`result.ok` before touching `result.data`. `reason` is one of `\"client\"` (bad\nlocal args — missing room id/name/target/kind), `\"unauthorized\"`,\n`\"throttled\"` (fired the same endpoint again inside the transport's throttle\nwindow), `\"connection\"` (transient, offer Retry), `\"validation\"`\n(response/schema drift), or `\"server\"` (the backend rejected it — `error`\ncarries a human-readable reason; see the verbatim strings below).\n\n| Method                                                  | Purpose                                                                                                                                                                                                            | `data` on success                          |\n| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |\n| `createRoom(roomName, options?)`                        | Create a room; caller becomes owner/host.                                                                                                                                                                          | `RoomSnapshotResponse`                     |\n| `joinRoom(roomID, joinCode?)`                           | Join an existing room.                                                                                                                                                                                             | `RoomSnapshotResponse`                     |\n| `leaveRoom(roomID, { successorUserID?, keepalive? }?)`  | Leave a room (may trigger host migration or close it if empty). A leaving host may name the successor; `keepalive` lets the request outlive the page (`pagehide`).                                                 | `LeaveRoomResponse`                        |\n| `listRooms(page?, pageSize?)`                           | Page through public rooms (default `page=0, pageSize=20`, server caps `pageSize` at 50).                                                                                                                           | `RoomsPageResponse`                        |\n| `getRoom(roomID)`                                       | Fetch a fresh snapshot of one room.                                                                                                                                                                                | `RoomSnapshotResponse`                     |\n| `closeRoom(roomID)`                                     | Owner/host-only: force-close a room.                                                                                                                                                                               | `LeaveRoomResponse`                        |\n| `poll(roomID, lastSeq)`                                 | Long-poll cursor: get every envelope with `Seq > lastSeq`.                                                                                                                                                         | `PollResponse`                             |\n| `sendSignal(roomID, targetUserID, signalKind, payload)` | Relay an SDP offer/answer/ICE candidate to one member.                                                                                                                                                             | `PublishResponse`                          |\n| `sendChat(roomID, chatText)`                            | Server-relayed chat message (only when `ChatMode: ServerRelay`).                                                                                                                                                   | `PublishResponse`                          |\n| `setMemberState(roomID, ready?, memberState?)`          | Publish this member's ready flag / free-form lobby state.                                                                                                                                                          | `PublishResponse`                          |\n| `claimHost(roomID)`                                     | Take the host role from a host that stopped polling (silent longer than `MemberTimeoutMs`). The silent host is evicted; `PlayerLeft` (Kind `\"timeout\"`) + `HostChanged` go to everyone. Exactly one claimant wins. | `RoomSnapshotResponse`                     |\n| `kickMember(roomID, targetUserID, ban?)`                | Owner/host-only: remove a member (`PlayerLeft`, Kind `\"kicked\"`); `ban` also puts them on the room's ban list (survives host changes, dies with the room). Their TURN credentials are revoked.                     | `KickMemberResponse` (`Removed`, `Banned`) |\n| `unbanMember(roomID, targetUserID)`                     | Owner/host-only: take a player off the ban list.                                                                                                                                                                   | `UnbanMemberResponse` (`WasBanned`)        |\n\n`createRoom`'s `options`: `{ topology?: MultiplayerTopology (\"Mesh\"|\"Host\"),\nchatMode?: MultiplayerChatMode (\"ServerRelay\"|\"P2P\"), maxPlayers?: number,\nvisibility?: RoomVisibility (\"Public\"|\"Private\"), joinCode?: string }`. Any\nfield you omit falls back to the title's configured defaults\n(`MultiplayerDefinitions.DefaultTopology`/`DefaultChatMode`), and an override\nis only honored if the title allows it\n(`AllowCreatorTopologyOverride`/`AllowCreatorChatOverride`) — otherwise the\ncall fails server-side with `\"Topology override is not allowed for this\ntitle.\"` / `\"Chat mode override is not allowed for this title.\"`.\n`maxPlayers` is clamped down to the title's `MaxPlayersPerRoom` hard cap; you\ncan only ask for _fewer_, never more.\n\n`closeRoom` succeeds for either the room's `OwnerUserID` **or** its current\n`HostUserID` (these can diverge after a host migration) — anyone else gets\n`\"Only the room owner or host can close the room.\"`.\n\nEvery method still emits its event on success even though nothing is cached —\nevents are your only hook here, there's no cache to read afterward.\n\n### Server error strings (verbatim)\n\nThese are exact `error` text from the backend (`RoomService.cs` /\n`SignalingService.cs`) — match on substrings if you need to branch, but the\nsafe default is just to display `result.error` as-is:\n\n- `\"Multiplayer is disabled for this title.\"` — title-wide kill switch is off.\n- `\"You are already in room {roomId}. Leave it first.\"` — one-active-room rule,\n  on both `createRoom` and `joinRoom`.\n- `\"RoomID is required.\"` / `\"TargetUserID is required.\"` / `\"SignalKind is\nrequired.\"` — same validation the SDK does client-side; you'll only see\n  these from a raw/bypassed call.\n- `\"Invalid or missing join code.\"` — private room join code mismatch.\n- `\"Room not found.\"` — unknown room id, or a **private** room you aren't a\n  member of (privacy is enforced by returning the same not-found error, not a\n  distinct \"forbidden\").\n- `\"Room is closed.\"` / `\"Room is full.\"` — join-time rejections.\n- `\"Only the room owner or host can close the room.\"`\n- `\"You were removed from this room.\"` — `joinRoom` by a banned player.\n- `\"The host is still active.\"` — `claimHost` while the host still polls\n  (retry later; only a host silent for `MemberTimeoutMs` can be replaced).\n- `\"Only the room owner or host can remove players.\"` / `\"Cannot kick\nyourself.\"` / `\"Cannot remove the host.\"` / `\"Cannot remove the room owner.\"`\n  — `kickMember` / `unbanMember`.\n- `\"Room no longer exists.\"` / `\"You are not a member of this room.\"` — from\n  `poll`, `sendSignal`, `sendChat`, `setMemberState` once you've dropped out of\n  the member hash (TTL expiry, or someone else removed you).\n- `\"Target user is not in this room.\"` — `sendSignal` to a non-member.\n- `\"Cannot signal yourself.\"`\n- `` `Signal payload exceeds {N} bytes.` `` — `MaxSignalPayloadBytes` (default 16384) exceeded.\n- `` `Chat text exceeds {N} characters.` `` — `MaxChatTextLength` (default 500)\n  exceeded.\n- `\"Chat is peer-to-peer in this room; send it over the DataChannel.\"` —\n  called `sendChat` while `ChatMode` is `P2P`.\n- `\"Corrupted member record.\"` — internal deserialization failure on\n  `setMemberState`; treat as transient/report.\n\n## Reading limits from config\n\nThere's no `getMultiplayerDefinitions()` call — `MultiplayerDefinitions`\ntravels as part of the title's public config bundle, not a per-module\ndefinitions fetch. It's populated by `client.title.getTitlePublicConfiguration()`\n(or already present after login, since the bootstrap `ClientState` includes\nthe title config):\n\n```ts\nimport type { MultiplayerDefinitions } from \"@idosgames/core\";\n\nawait client.title.getTitlePublicConfiguration(); // if not already loaded\nconst cfg = client.data.config.titlePublicConfiguration?.Multiplayer as\n  MultiplayerDefinitions | undefined;\n\ncfg?.MaxPlayersPerRoom; // hard cap enforced server-side\ncfg?.MaxChatTextLength;\ncfg?.MaxSignalPayloadBytes;\ncfg?.HeartbeatIntervalMs; // recommended poll cadence, not enforced\ncfg?.MemberTimeoutMs; // client-side presumed-offline threshold\n```\n\nRead it for building config-driven UI (create-room forms that pre-fill/clamp\n`maxPlayers`, a chat box that disables itself when `ChatMode` will be `P2P`,\netc.) — the server enforces the real limits regardless of what you show.\n\n## Events\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn. There is no\ncoarse `user:*Updated`/`user:anyUpdated` companion for any of these — they\ndon't touch the shared cache.\n\n- `multiplayer:roomCreated` → `RoomSnapshotResponse`\n- `multiplayer:roomJoined` → `RoomSnapshotResponse`\n- `multiplayer:roomLeft` → `LeaveRoomResponse`\n- `multiplayer:roomsListed` → `RoomsPageResponse`\n- `multiplayer:roomLoaded` → `RoomSnapshotResponse`\n- `multiplayer:roomClosed` → `LeaveRoomResponse`\n- `multiplayer:polled` → `PollResponse`\n- `multiplayer:signalSent` → `PublishResponse`\n- `multiplayer:chatSent` → `PublishResponse`\n- `multiplayer:memberStateSet` → `PublishResponse`\n- `multiplayer:hostClaimed` → `RoomSnapshotResponse`\n- `multiplayer:memberKicked` → `KickMemberResponse`\n- `multiplayer:memberUnbanned` → `UnbanMemberResponse`\n\n```ts\nconst off = client.on(\"multiplayer:roomClosed\", (r) => {\n  if (r.Closed) navigateToLobbyList();\n});\n// later: off();\n```\n\nFor the full shape of `RoomSnapshotResponse`, `RealtimeEnvelope`,\n`RoomMemberView`, and `MultiplayerDefinitions`, see\n[references/data-model.md](references/data-model.md).\n\n## Recommended: RealtimeSession\n\n`@idosgames/core/realtime` is the WebRTC transport on top of this module. Use it\ninstead of writing the offer/answer/ICE dance yourself:\n\n```ts\nimport { RealtimeSession } from \"@idosgames/core/realtime\";\n\nconst res = await RealtimeSession.create(client, \"My world\", {\n  topology: \"Host\", // star: guests link to the host only\n  visibility: \"Public\",\n  maxPlayers: 8,\n});\n// guests: await RealtimeSession.join(client, roomID, joinCode?)\nif (!res.ok) return showError(res.error);\nconst session = res.data;\n\nsession.on(\"peerOpen\", ({ peerId }) => sendWorldSnapshot(peerId));\nsession.on(\"message\", ({ from, channel, data }) => handle(from, channel, data));\nsession.on(\"hostChanged\", ({ hostId }) => {\n  if (hostId === session.selfId) becomeHost();\n});\nsession.on(\"removed\", ({ reason }) => backToMenu(reason)); // kicked / banned\nsession.on(\"roomClosed\", () => backToMenu(\"closed\"));\n\nsession.send(peerId, \"rel\", bytes); // ordered + reliable, fragmented into 16 KB frames\nsession.broadcast(\"fast\", poseBytes); // unordered, no retransmits: positions etc.\n```\n\nWhat it does for you:\n\n- **Two DataChannels per link**: `rel` (ordered, reliable; large messages are\n  fragmented) and `fast` (unordered, `maxRetransmits: 0`). `send` returns\n  `false` when the link is not open, a `fast` message is too big, or `rel` is\n  backed up — drop or retry, don't queue forever.\n- **Cheap polling**: 1 s only while something is being set up, then the host\n  polls every 2.5 s (to see newcomers) and everyone else every 20 s (just to\n  stay a member). Signals go through a single-flight, per-peer batched outbox,\n  and descriptions carry their ICE candidates — about one `SendSignal` per\n  side per connection.\n- **Liveness**: own keepalive on `fast` (a silent peer is closed after ~6 s),\n  RTT via `linkStats(peerId)` (measured every ~5 s even under load),\n  reconnect with back-off.\n- **Host handover**: the host calls `setSuccessor(userId)`; `leave()` (and\n  page close — a `keepalive` request on `pagehide`) passes it to the server.\n  If the host tab dies instead, the successor calls `session.claimHost()`\n  once the host has been silent for the title's `MemberTimeoutMs`.\n  `setExtraPeers([...])` keeps standby links (e.g. every guest to the\n  successor) so the handover does not wait for signaling.\n- **Moderation**: `session.kick(userId, ban?)`, `session.unban(userId)`. After\n  a successful kick the host sends the kicked player a \"check your membership\"\n  notice over the link; that player polls at once and gets `removed` within\n  about a round trip. The notice is only a hint — the SERVER confirms the\n  removal, so a forged notice costs one extra poll and nothing else.\n- **TURN**: `IceServers` of the snapshot are used as is. When the engine has\n  Cloudflare TURN configured (env `CLOUDFLARE_TURN_KEY_ID` / `CLOUDFLARE_TURN_API_TOKEN` on the\n  engine — not title config) members get short-lived TURN credentials in the\n  snapshot; otherwise STUN only.\n\nA full game built on it: `modules/voxelcraft/src/net/` (NetGame — dimension\nowners, replicas, host migration with a shadow copy of the world).\n\n## Recipes\n\n### Create or join a room\n\n```ts\nconst created = await client.multiplayer.createRoom(\"Match 42\", {\n  topology: \"Mesh\",\n  chatMode: \"ServerRelay\",\n  maxPlayers: 4,\n  visibility: \"Private\",\n  joinCode: \"AB12\",\n});\nif (!created.ok) return showError(created.error);\nconst { RoomID, Seq, IceServers, Members } = created.data;\n\n// another player:\nconst joined = await client.multiplayer.joinRoom(RoomID, \"AB12\");\nif (!joined.ok) return showError(joined.error); // e.g. wrong code, room full\n```\n\n`IceServers` on the snapshot is the STUN/TURN config for your `RTCPeerConnection`\n— pass it straight through (if the title has none configured, the backend\nfalls back to public STUN servers, so this array is never empty). TURN\ncredentials, when the engine has Cloudflare TURN configured, are included only\nfor room members and expire after ~12 h — never put a static TURN login into\nthe title's public config.\n`Seq` is your starting poll cursor. Remember the one-active-room rule: a\nsecond `createRoom`/`joinRoom` call while already in a room fails with\n`\"You are already in room {roomId}. Leave it first.\"` — call `leaveRoom` (or\ncheck your own app state) before switching rooms.\n\n### The polling loop (signals, chat, presence)\n\nPoll is a cursor-based long-poll: pass the last `Seq` you've seen, get back\neverything newer, and each response's `MaxSeq` becomes your next cursor. Each\npoll call also renews your presence heartbeat and the room's TTL server-side\n— an idle client that stops polling will eventually look disconnected to\nothers and the room itself can expire.\n\n```ts\nlet lastSeq = created.data.Seq ?? 0;\nlet polling = true;\n\nasync function pollLoop(roomID: string) {\n  while (polling) {\n    const res = await client.multiplayer.poll(roomID, lastSeq);\n    if (!res.ok) {\n      if (res.reason === \"connection\") continue; // transient, retry\n      break; // unauthorized/server error (\"Room no longer exists.\", etc) — stop and surface it\n    }\n    for (const env of res.data.Envelopes ?? []) {\n      switch (env.Type) {\n        case \"Signal\":\n          // env.Kind: \"offer\" | \"answer\" | \"candidate\"; env.FromUserID, env.Payload\n          handleSignal(env.FromUserID, env.Kind, env.Payload);\n          break;\n        case \"Chat\":\n          appendChatMessage(env.FromUserID, env.Payload);\n          break;\n        case \"PlayerJoined\":\n        case \"PlayerLeft\":\n        case \"MemberState\":\n          refreshRoomMembers(roomID);\n          break;\n        case \"HostChanged\":\n          break; // env.Payload / a follow-up getRoom() carries new host\n        case \"RoomClosed\":\n          polling = false;\n          break;\n      }\n    }\n    lastSeq = res.data.MaxSeq ?? lastSeq;\n  }\n}\n```\n\nThere's no push/websocket transport here — polling cadence is your call. The\ntitle's `MultiplayerDefinitions.HeartbeatIntervalMs` (default 1000ms) is a\n_recommended_ interval only, not enforced — poll too fast and you risk\n`reason: \"throttled\"` at the transport layer; too slow and signaling feels\nlaggy, and other members' `LastSeenMs` will look stale to you. Use the\nrecommended interval as your default; back off on `\"connection\"` errors\nrather than hot-looping.\n\n### Exchange a WebRTC offer/answer\n\n```ts\n// caller side, after creating an RTCPeerConnection and an offer:\nconst offer = await pc.createOffer();\nawait pc.setLocalDescription(offer);\nawait client.multiplayer.sendSignal(\n  roomID,\n  targetUserID,\n  \"offer\",\n  JSON.stringify(offer),\n);\n\n// callee side, from the poll loop's \"Signal\"/\"offer\" case:\nconst offer = JSON.parse(env.Payload);\nawait pc.setRemoteDescription(offer);\nconst answer = await pc.createAnswer();\nawait pc.setLocalDescription(answer);\nawait client.multiplayer.sendSignal(\n  roomID,\n  env.FromUserID,\n  \"answer\",\n  JSON.stringify(answer),\n);\n\n// both sides, as ICE candidates trickle in:\npc.onicecandidate = (e) => {\n  if (e.candidate) {\n    client.multiplayer.sendSignal(\n      roomID,\n      targetUserID,\n      \"candidate\",\n      JSON.stringify(e.candidate),\n    );\n  }\n};\n```\n\n`signalKind` is a free-form string (`\"offer\"`/`\"answer\"`/`\"candidate\"` by\nconvention) and `payload` is an opaque string — the server relays both without\ninspecting them, so encoding is entirely up to you (JSON-stringify is the\nobvious choice). Keep the serialized payload under the title's\n`MaxSignalPayloadBytes` (default 16384) — an oversized payload is rejected\nwith `` `Signal payload exceeds {N} bytes.` `` before it's ever relayed, and\nyou can't signal yourself (`\"Cannot signal yourself.\"`) or a user who isn't\ncurrently a room member (`\"Target user is not in this room.\"`).\n\n### Lobby ready-check and leaving\n\n```ts\nawait client.multiplayer.setMemberState(roomID, true, { loadout: \"red\" });\n// other members see this via a \"MemberState\" envelope on their next poll,\n// then re-fetch with getRoom(roomID) to read updated Members[].Ready/State.\n\nconst left = await client.multiplayer.leaveRoom(roomID);\nif (left.ok && left.data.Closed) {\n  // room was empty/owner left with no migration target — it's gone\n} else if (left.ok && left.data.NewHostUserID) {\n  // host migrated; that member is now authoritative for Host topology\n}\n```\n\n## Gotchas\n\n- **Nothing here touches `client.data.user.state`.** Don't look for a cached\n  room state or resource balances changing — read everything from method\n  responses and poll envelopes, and keep your own local room/member state in\n  your app layer. The one thing that _is_ cached is the title-wide\n  `MultiplayerDefinitions` config, and only after you fetch the title config\n  (see [Reading limits from config](#reading-limits-from-config)).\n- **One room per player, enforced server-side.** `createRoom` and `joinRoom`\n  both reject with `\"You are already in room {roomId}. Leave it first.\"` if\n  you're already a live member elsewhere — there's no implicit \"leave old,\n  join new.\"\n- **Room state is ephemeral.** No persistent document backs a room — it's\n  Redis, TTL-based (`RoomTtlSeconds`, default 3600s, renewed on every\n  interaction including `poll`). A room can disappear if nobody interacts\n  with it; don't assume a `RoomID` is valid indefinitely. A title may also\n  set a hard lifetime (`MaxRoomLifetimeSeconds`, counted from creation, NOT\n  renewed by activity): when it passes, members receive `RoomClosed` with\n  `Kind: \"expired\"` mid-game — save progress and offer \"new room\".\n- **`sendChat` only works under `ChatMode: ServerRelay`.** Under `P2P` chat\n  mode, send chat over your own WebRTC DataChannel instead — calling\n  `sendChat` in `P2P` mode fails with `\"Chat is peer-to-peer in this room;\nsend it over the DataChannel.\"` (check the room snapshot's `ChatMode`\n  before wiring a chat send button to it).\n- **`closeRoom` works for the owner or the current host, not just the\n  original creator.** After a host migration the new host can also close the\n  room; anyone else gets `\"Only the room owner or host can close the room.\"`.\n  Regular non-host, non-owner members only have `leaveRoom` (which itself may\n  close the room if it empties out).\n- **Private rooms 404 instead of 403.** `getRoom`/`poll`/etc. on a private\n  room you're not a member of returns the same `\"Room not found.\"` as a\n  genuinely unknown id — the backend doesn't leak room existence to\n  non-members.\n- **No automatic eviction — except via `claimHost`.** `RoomMemberView.LastSeenMs`\n  is a last-heartbeat timestamp for clients to compare against\n  `MultiplayerDefinitions.MemberTimeoutMs` themselves (e.g. to gray out a\n  presumed-disconnected member). The server never evicts a stale member on\n  its own; the one exception is `claimHost`, which removes a HOST that has\n  been silent longer than `MemberTimeoutMs` and hands the role to the caller.\n- **Poll cadence is uncapped by the SDK — you own the rate.** There's no\n  built-in backoff or interval; hitting the same endpoint faster than the\n  transport's throttle window returns `reason: \"throttled\"` rather than\n  duplicating work. `HeartbeatIntervalMs` is the title's _recommended_\n  interval, not an enforced one. Design your loop's interval deliberately\n  rather than polling in a tight `while(true)`.\n- **`Payload`/`signalKind` are opaque strings.** The server does not validate\n  WebRTC SDP/ICE structure — malformed payloads only fail on the _receiving_\n  client when it tries to parse/apply them, not at the relay. It does,\n  however, enforce a byte-size ceiling (`MaxSignalPayloadBytes`) before\n  relaying at all.\n- **Guard against double-submit** on room actions (create/join/close): each\n  call is a distinct request, so two separate calls are two real operations\n  server-side (e.g. two `createRoom` calls can both succeed as two different\n  rooms if the first response is slow). Disable the control while a call is\n  in flight.\n\n## Full reference\n\n[references/data-model.md](references/data-model.md) — full shape of\n`RoomSnapshotResponse`, `RoomMemberView`, `RealtimeEnvelope`/`EnvelopeType`,\n`MultiplayerDefinitions`, and the request/action surface, plus the room\nlifecycle state machine (Open → Closed, host migration, TTL expiry). Read it\nwhen building richer room/lobby UI or wiring up the poll loop's envelope\nhandling in detail.\n",
+  "content": "---\nname: multiplayer-realtime\ndescription: >-\n  Build realtime peer-to-peer multiplayer in a game on the iDosGames\n  TypeScript SDK via client.multiplayer (MultiplayerService): create, join,\n  list and close rooms, relay WebRTC offers/answers and ICE candidates, poll for\n  signal/chat/presence envelopes, in-room chat, ready/lobby state, host\n  handover (claimHost), kick/ban; plus the ready WebRTC transport\n  RealtimeSession from @idosgames/core/realtime. It is a signaling and room\n  relay, not a gameplay or economy module. Use this whenever the user wants\n  realtime rooms or lobbies, WebRTC signaling, peer-to-peer setup, in-room chat\n  or ready-check UIs, or touches client.multiplayer, MultiplayerService,\n  RoomSnapshotResponse, RealtimeEnvelope or RealtimeSession — even without\n  naming the module. In an app with the base (lobby) a game does NOT open rooms:\n  it registers in ctx.multiplayer (registerGame) and takes the room in\n  start(room) — read the first section.\n---\n\n# Multiplayer realtime signaling (iDosGames TS SDK)\n\nMultiplayer is a **realtime WebRTC signaling relay**, not a gameplay or\neconomy module. It gives you room lifecycle (create/join/leave/list/close) and\na message relay for two things peer-to-peer games need: SDP offer/answer + ICE\ncandidate exchange (so browsers/clients can establish a direct WebRTC\nconnection), and optional server-relayed chat/presence. The actual game state\nsync between players happens over the WebRTC connection you establish\nyourself — this module only gets players into the same room and helps them\nfind each other.\n\n**No currency/item coupling, no per-player cache mirror.** Unlike every other\nmodule in this SDK, no Multiplayer action ever returns a `ResourceOperation`\nor writes to `client.data.user.state` — there is nothing to mirror into a\nlocal player-state cache. Room state itself is ephemeral (Redis, TTL-based, no\nMongo document), so the SDK surface here is pure transport + event-emission:\ncall a method, get a response, emit an event, done. There is no\n`user:multiplayerUpdated` event and no `client.data.user.state.Multiplayer` —\ndon't look for either. The one piece of _config_ this module does expose —\n`MultiplayerDefinitions` (feature switch, topology/chat defaults, room-size\ncap, TTL, payload limits, ICE servers) — rides in on the title's public\nconfig bundle rather than a dedicated fetch call; see\n[Reading limits from config](#reading-limits-from-config).\n\nThis skill is for **using** the production `MultiplayerService`, not for\nporting or extending it. **Don't hand-roll WebRTC** on top of it: the SDK ships\n`RealtimeSession` (`@idosgames/core/realtime`, see\n[Recommended: RealtimeSession](#recommended-realtimesession)) which owns the\n`RTCPeerConnection`s, the poll loop and the signaling etiquette the backend\nexpects. The raw methods below are for lobby UI and for the rare custom\ntransport. Server rejections (room full, wrong join\ncode, not the owner, payload too large) are backend rules — surface them,\ndon't try to pre-validate every one of them client-side.\n\n## A game in an app with the base: `ctx.multiplayer` — do NOT open rooms yourself\n\nIn a project built on the base (lobby) the ROOMS belong to the multiplayer system (the `multiplayer`\nmodule): the list of rooms, \"Create a room\", joining by invite, members, \"Ready\", chat — and the\n`RealtimeSession`, opened already in the lobby. A game never calls `createRoom`/`joinRoom`/\n`RealtimeSession.create|join`; it declares how it plays online and TAKES the room:\n\n```ts\n// module.ts, in setup()\nctx.multiplayer.registerGame({\n  mode: \"my-game\", // the game's route id — the room's game\n  topology: \"Host\", // \"Host\" (star) | \"Mesh\"\n  chatMode: \"P2P\", // the game has its own chat; \"ServerRelay\" = the lobby's chat\n  maxPlayers: 8,\n  joinInProgress: true, // a player may join a running game (your late-joiner path)\n  settings: [\n    // the host picks them in \"Create a room\"\n    {\n      id: \"mode\",\n      label: \"Mode\",\n      kind: \"choice\",\n      default: \"coop\",\n      options: [\n        { value: \"coop\", label: \"Co-op\" },\n        { value: \"pvp\", label: \"PvP\" },\n      ],\n    },\n    { id: \"cheats\", label: \"Cheats for all\", kind: \"toggle\", default: false },\n  ],\n  // Called on EVERY member's device after the app switched to the game's mode (the host first).\n  start: async (room) => {\n    const game = await whenGameMounted(); // the scene may mount on this very switch\n    game.playOnline(room.session, {\n      host: room.isHost && !room.lateJoin, // opens its world for the others\n      settings: room.settings, // { mode: \"coop\", cheats: false }\n      leave: room.leave, // leave through the lobby, never session.leave()\n    });\n  },\n});\n```\n\n- The lobby then draws \"With friends\" next to the game's \"Play\" (its rooms), and the rooms screen\n  offers the game in \"Create a room\". A game's own \"Play with friends\" button:\n  `ctx.features.open(\"multiplayer\", { mode: \"my-game\", create: true })` — from inside the game it\n  switches to the lobby by itself.\n- Show that button only while `ctx.features.get(\"multiplayer\")?.available` — without the system the\n  game is single-player, nothing else changes.\n- Leave with `room.leave()`: the lobby owns the room and forgets it together with the session.\n- Messages on the session are yours from `start` on; the lobby's own start message goes out before\n  any of yours on the ordered channel and never reaches the game.\n- Reference implementation: `modules/voxelcraft` (`module.ts` → `registerGame`, `net/NetGame.ts` →\n  `NetGame.fromRoom`, `main.ts` → `Game.acceptRoom`).\n\n### Voice chat — already there, do NOT build your own\n\nA room has voice chat unless the title (`Multiplayer.VoiceEnabled`) or the room's creator turned it\noff. The rooms system owns it completely: the mic modes (off / push-to-talk on `V` / open mic), the\nmic button over the running game, every member's mute and volume, the \"Conversations may be\nrecorded\" notice. Never call `getUserMedia` or add audio tracks yourself. A game only READS\n`room.voice` (a `VoiceController`, or `null` — no voice in this room) for its own touches:\n\n```ts\nstart: (room) => {\n  const voice = room.voice;\n  if (!voice) return;\n  // A \"talking\" marker over a player's avatar.\n  voice.on(\"change\", () => avatars.forEach((a) => a.setTalking(voice.isSpeaking(a.userId))));\n  // Proximity voice: quieter with distance (0–2, 1 = as is). Call on your own tick.\n  for (const p of players) voice.setPeerVolume(p.userId, Math.max(0, 1 - dist(me, p) / 30));\n},\n```\n\n- `voice.isSpeaking(id)` / `voice.speaking()` / `voice.level(id)` (RMS 0–1); `on(\"levels\")` each tick.\n- In a `Host` room every pair is linked for voice, but those guest↔guest links carry NO game data:\n  `session.openPeers()` / `broadcast` / `send` still see the star — the game protocol is unchanged.\n\nEverything below — `client.multiplayer` and `RealtimeSession` directly — is for an app WITHOUT the\nbase, or for writing the rooms system itself.\n\n## Mental model\n\n1. One player **creates a room** (picks topology/chat mode/visibility/max\n   players, optionally a join code); others **join** by room id (+ join code\n   if private). **A player can only be in one room at a time** — creating or\n   joining while already in a live room fails; leave first.\n2. Each member **polls** the room on a cursor (`LastSeq`) to receive a stream\n   of envelopes: other members' signals, chat, presence changes\n   (join/leave/host-migration), and room-closed notices. Polling is also the\n   heartbeat — it's what keeps your presence and the room's Redis TTL alive.\n3. To establish a direct connection, members exchange SDP offer/answer and ICE\n   candidates by calling **`sendSignal`** — the server just relays the\n   `payload` string to a specific `targetUserID`; it never inspects or\n   validates WebRTC semantics.\n4. Optional **`sendChat`** (only meaningful when the room's `ChatMode` is\n   `ServerRelay` — under `P2P` chat should go over your own DataChannel\n   instead) and **`setMemberState`** (ready flags + a free-form string map)\n   round out lobby UX.\n5. Someone **leaves**, or the owner/host **closes** the room; on host\n   departure the server may migrate to a `NewHostUserID` if members remain.\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst mp = client.multiplayer; // the MultiplayerService\n```\n\nEvery method requires an authenticated session. Without one they return\n`{ ok: false, reason: \"unauthorized\" }` — they do not throw. There is one\n`client` per player; don't share it across sessions.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>`: a discriminated union that is\neither `{ ok: true, data }` or `{ ok: false, reason, error }`. Always branch on\n`result.ok` before touching `result.data`. `reason` is one of `\"client\"` (bad\nlocal args — missing room id/name/target/kind), `\"unauthorized\"`,\n`\"throttled\"` (fired the same endpoint again inside the transport's throttle\nwindow), `\"connection\"` (transient, offer Retry), `\"validation\"`\n(response/schema drift), or `\"server\"` (the backend rejected it — `error`\ncarries a human-readable reason; see the verbatim strings below).\n\n| Method                                                  | Purpose                                                                                                                                                                                                            | `data` on success                          |\n| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |\n| `createRoom(roomName, options?)`                        | Create a room; caller becomes owner/host.                                                                                                                                                                          | `RoomSnapshotResponse`                     |\n| `joinRoom(roomID, joinCode?)`                           | Join an existing room.                                                                                                                                                                                             | `RoomSnapshotResponse`                     |\n| `leaveRoom(roomID, { successorUserID?, keepalive? }?)`  | Leave a room (may trigger host migration or close it if empty). A leaving host may name the successor; `keepalive` lets the request outlive the page (`pagehide`).                                                 | `LeaveRoomResponse`                        |\n| `listRooms(page?, pageSize?)`                           | Page through public rooms (default `page=0, pageSize=20`, server caps `pageSize` at 50).                                                                                                                           | `RoomsPageResponse`                        |\n| `getRoom(roomID)`                                       | Fetch a fresh snapshot of one room.                                                                                                                                                                                | `RoomSnapshotResponse`                     |\n| `closeRoom(roomID)`                                     | Owner/host-only: force-close a room.                                                                                                                                                                               | `LeaveRoomResponse`                        |\n| `poll(roomID, lastSeq)`                                 | Long-poll cursor: get every envelope with `Seq > lastSeq`.                                                                                                                                                         | `PollResponse`                             |\n| `sendSignal(roomID, targetUserID, signalKind, payload)` | Relay an SDP offer/answer/ICE candidate to one member.                                                                                                                                                             | `PublishResponse`                          |\n| `sendChat(roomID, chatText)`                            | Server-relayed chat message (only when `ChatMode: ServerRelay`).                                                                                                                                                   | `PublishResponse`                          |\n| `setMemberState(roomID, ready?, memberState?)`          | Publish this member's ready flag / free-form lobby state.                                                                                                                                                          | `PublishResponse`                          |\n| `claimHost(roomID)`                                     | Take the host role from a host that stopped polling (silent longer than `MemberTimeoutMs`). The silent host is evicted; `PlayerLeft` (Kind `\"timeout\"`) + `HostChanged` go to everyone. Exactly one claimant wins. | `RoomSnapshotResponse`                     |\n| `kickMember(roomID, targetUserID, ban?)`                | Owner/host-only: remove a member (`PlayerLeft`, Kind `\"kicked\"`); `ban` also puts them on the room's ban list (survives host changes, dies with the room). Their TURN credentials are revoked.                     | `KickMemberResponse` (`Removed`, `Banned`) |\n| `unbanMember(roomID, targetUserID)`                     | Owner/host-only: take a player off the ban list.                                                                                                                                                                   | `UnbanMemberResponse` (`WasBanned`)        |\n\n`createRoom`'s `options`: `{ topology?: MultiplayerTopology (\"Mesh\"|\"Host\"),\nchatMode?: MultiplayerChatMode (\"ServerRelay\"|\"P2P\"), maxPlayers?: number,\nvisibility?: RoomVisibility (\"Public\"|\"Private\"), joinCode?: string }`. Any\nfield you omit falls back to the title's configured defaults\n(`MultiplayerDefinitions.DefaultTopology`/`DefaultChatMode`), and an override\nis only honored if the title allows it\n(`AllowCreatorTopologyOverride`/`AllowCreatorChatOverride`) — otherwise the\ncall fails server-side with `\"Topology override is not allowed for this\ntitle.\"` / `\"Chat mode override is not allowed for this title.\"`.\n`maxPlayers` is clamped down to the title's `MaxPlayersPerRoom` hard cap; you\ncan only ask for _fewer_, never more.\n\n`closeRoom` succeeds for either the room's `OwnerUserID` **or** its current\n`HostUserID` (these can diverge after a host migration) — anyone else gets\n`\"Only the room owner or host can close the room.\"`.\n\nEvery method still emits its event on success even though nothing is cached —\nevents are your only hook here, there's no cache to read afterward.\n\n### Server error strings (verbatim)\n\nThese are exact `error` text from the backend (`RoomService.cs` /\n`SignalingService.cs`) — match on substrings if you need to branch, but the\nsafe default is just to display `result.error` as-is:\n\n- `\"Multiplayer is disabled for this title.\"` — title-wide kill switch is off.\n- `\"You are already in room {roomId}. Leave it first.\"` — one-active-room rule,\n  on both `createRoom` and `joinRoom`.\n- `\"RoomID is required.\"` / `\"TargetUserID is required.\"` / `\"SignalKind is\nrequired.\"` — same validation the SDK does client-side; you'll only see\n  these from a raw/bypassed call.\n- `\"Invalid or missing join code.\"` — private room join code mismatch.\n- `\"Room not found.\"` — unknown room id, or a **private** room you aren't a\n  member of (privacy is enforced by returning the same not-found error, not a\n  distinct \"forbidden\").\n- `\"Room is closed.\"` / `\"Room is full.\"` — join-time rejections.\n- `\"Only the room owner or host can close the room.\"`\n- `\"You were removed from this room.\"` — `joinRoom` by a banned player.\n- `\"The host is still active.\"` — `claimHost` while the host still polls\n  (retry later; only a host silent for `MemberTimeoutMs` can be replaced).\n- `\"Only the room owner or host can remove players.\"` / `\"Cannot kick\nyourself.\"` / `\"Cannot remove the host.\"` / `\"Cannot remove the room owner.\"`\n  — `kickMember` / `unbanMember`.\n- `\"Room no longer exists.\"` / `\"You are not a member of this room.\"` — from\n  `poll`, `sendSignal`, `sendChat`, `setMemberState` once you've dropped out of\n  the member hash (TTL expiry, or someone else removed you).\n- `\"Target user is not in this room.\"` — `sendSignal` to a non-member.\n- `\"Cannot signal yourself.\"`\n- `` `Signal payload exceeds {N} bytes.` `` — `MaxSignalPayloadBytes` (default 16384) exceeded.\n- `` `Chat text exceeds {N} characters.` `` — `MaxChatTextLength` (default 500)\n  exceeded.\n- `\"Chat is peer-to-peer in this room; send it over the DataChannel.\"` —\n  called `sendChat` while `ChatMode` is `P2P`.\n- `\"Corrupted member record.\"` — internal deserialization failure on\n  `setMemberState`; treat as transient/report.\n\n## Reading limits from config\n\nThere's no `getMultiplayerDefinitions()` call — `MultiplayerDefinitions`\ntravels as part of the title's public config bundle, not a per-module\ndefinitions fetch. It's populated by `client.title.getTitlePublicConfiguration()`\n(or already present after login, since the bootstrap `ClientState` includes\nthe title config):\n\n```ts\nimport type { MultiplayerDefinitions } from \"@idosgames/core\";\n\nawait client.title.getTitlePublicConfiguration(); // if not already loaded\nconst cfg = client.data.config.titlePublicConfiguration?.Multiplayer as\n  MultiplayerDefinitions | undefined;\n\ncfg?.MaxPlayersPerRoom; // hard cap enforced server-side\ncfg?.MaxChatTextLength;\ncfg?.MaxSignalPayloadBytes;\ncfg?.HeartbeatIntervalMs; // recommended poll cadence, not enforced\ncfg?.MemberTimeoutMs; // client-side presumed-offline threshold\n```\n\nRead it for building config-driven UI (create-room forms that pre-fill/clamp\n`maxPlayers`, a chat box that disables itself when `ChatMode` will be `P2P`,\netc.) — the server enforces the real limits regardless of what you show.\n\n## Events\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn. There is no\ncoarse `user:*Updated`/`user:anyUpdated` companion for any of these — they\ndon't touch the shared cache.\n\n- `multiplayer:roomCreated` → `RoomSnapshotResponse`\n- `multiplayer:roomJoined` → `RoomSnapshotResponse`\n- `multiplayer:roomLeft` → `LeaveRoomResponse`\n- `multiplayer:roomsListed` → `RoomsPageResponse`\n- `multiplayer:roomLoaded` → `RoomSnapshotResponse`\n- `multiplayer:roomClosed` → `LeaveRoomResponse`\n- `multiplayer:polled` → `PollResponse`\n- `multiplayer:signalSent` → `PublishResponse`\n- `multiplayer:chatSent` → `PublishResponse`\n- `multiplayer:memberStateSet` → `PublishResponse`\n- `multiplayer:hostClaimed` → `RoomSnapshotResponse`\n- `multiplayer:memberKicked` → `KickMemberResponse`\n- `multiplayer:memberUnbanned` → `UnbanMemberResponse`\n\n```ts\nconst off = client.on(\"multiplayer:roomClosed\", (r) => {\n  if (r.Closed) navigateToLobbyList();\n});\n// later: off();\n```\n\nFor the full shape of `RoomSnapshotResponse`, `RealtimeEnvelope`,\n`RoomMemberView`, and `MultiplayerDefinitions`, see\n[references/data-model.md](references/data-model.md).\n\n## Recommended: RealtimeSession\n\n`@idosgames/core/realtime` is the WebRTC transport on top of this module. Use it\ninstead of writing the offer/answer/ICE dance yourself:\n\n```ts\nimport { RealtimeSession } from \"@idosgames/core/realtime\";\n\nconst res = await RealtimeSession.create(client, \"My world\", {\n  topology: \"Host\", // star: guests link to the host only\n  visibility: \"Public\",\n  maxPlayers: 8,\n});\n// guests: await RealtimeSession.join(client, roomID, joinCode?)\nif (!res.ok) return showError(res.error);\nconst session = res.data;\n\nsession.on(\"peerOpen\", ({ peerId }) => sendWorldSnapshot(peerId));\nsession.on(\"message\", ({ from, channel, data }) => handle(from, channel, data));\nsession.on(\"hostChanged\", ({ hostId }) => {\n  if (hostId === session.selfId) becomeHost();\n});\nsession.on(\"removed\", ({ reason }) => backToMenu(reason)); // kicked / banned\nsession.on(\"roomClosed\", () => backToMenu(\"closed\"));\n\nsession.send(peerId, \"rel\", bytes); // ordered + reliable, fragmented into 16 KB frames\nsession.broadcast(\"fast\", poseBytes); // unordered, no retransmits: positions etc.\n```\n\nWhat it does for you:\n\n- **Two DataChannels per link**: `rel` (ordered, reliable; large messages are\n  fragmented) and `fast` (unordered, `maxRetransmits: 0`). `send` returns\n  `false` when the link is not open, a `fast` message is too big, or `rel` is\n  backed up — drop or retry, don't queue forever.\n- **Cheap polling**: 1 s only while something is being set up, then the host\n  polls every 2.5 s (to see newcomers) and everyone else every 20 s (just to\n  stay a member). Signals go through a single-flight, per-peer batched outbox,\n  and descriptions carry their ICE candidates — about one `SendSignal` per\n  side per connection.\n- **Liveness**: own keepalive on `fast` (a silent peer is closed after ~6 s),\n  RTT via `linkStats(peerId)` (measured every ~5 s even under load),\n  reconnect with back-off.\n- **Host handover**: the host calls `setSuccessor(userId)`; `leave()` (and\n  page close — a `keepalive` request on `pagehide`) passes it to the server.\n  If the host tab dies instead, the successor calls `session.claimHost()`\n  once the host has been silent for the title's `MemberTimeoutMs`.\n  `setExtraPeers([...])` keeps standby links (e.g. every guest to the\n  successor) so the handover does not wait for signaling.\n- **Moderation**: `session.kick(userId, ban?)`, `session.unban(userId)`. After\n  a successful kick the host sends the kicked player a \"check your membership\"\n  notice over the link; that player polls at once and gets `removed` within\n  about a round trip. The notice is only a hint — the SERVER confirms the\n  removal, so a forged notice costs one extra poll and nothing else.\n- **TURN**: `IceServers` of the snapshot are used as is. When the engine has\n  Cloudflare TURN configured (env `CLOUDFLARE_TURN_KEY_ID` / `CLOUDFLARE_TURN_API_TOKEN` on the\n  engine — not title config) members get short-lived TURN credentials in the\n  snapshot; otherwise STUN only.\n\nA full game built on it: `modules/voxelcraft/src/net/` (NetGame — dimension\nowners, replicas, host migration with a shadow copy of the world).\n\n## Recipes\n\n### Create or join a room\n\n```ts\nconst created = await client.multiplayer.createRoom(\"Match 42\", {\n  topology: \"Mesh\",\n  chatMode: \"ServerRelay\",\n  maxPlayers: 4,\n  visibility: \"Private\",\n  joinCode: \"AB12\",\n});\nif (!created.ok) return showError(created.error);\nconst { RoomID, Seq, IceServers, Members } = created.data;\n\n// another player:\nconst joined = await client.multiplayer.joinRoom(RoomID, \"AB12\");\nif (!joined.ok) return showError(joined.error); // e.g. wrong code, room full\n```\n\n`IceServers` on the snapshot is the STUN/TURN config for your `RTCPeerConnection`\n— pass it straight through (if the title has none configured, the backend\nfalls back to public STUN servers, so this array is never empty). TURN\ncredentials, when the engine has Cloudflare TURN configured, are included only\nfor room members and expire after ~12 h — never put a static TURN login into\nthe title's public config.\n`Seq` is your starting poll cursor. Remember the one-active-room rule: a\nsecond `createRoom`/`joinRoom` call while already in a room fails with\n`\"You are already in room {roomId}. Leave it first.\"` — call `leaveRoom` (or\ncheck your own app state) before switching rooms.\n\n### The polling loop (signals, chat, presence)\n\nPoll is a cursor-based long-poll: pass the last `Seq` you've seen, get back\neverything newer, and each response's `MaxSeq` becomes your next cursor. Each\npoll call also renews your presence heartbeat and the room's TTL server-side\n— an idle client that stops polling will eventually look disconnected to\nothers and the room itself can expire.\n\n```ts\nlet lastSeq = created.data.Seq ?? 0;\nlet polling = true;\n\nasync function pollLoop(roomID: string) {\n  while (polling) {\n    const res = await client.multiplayer.poll(roomID, lastSeq);\n    if (!res.ok) {\n      if (res.reason === \"connection\") continue; // transient, retry\n      break; // unauthorized/server error (\"Room no longer exists.\", etc) — stop and surface it\n    }\n    for (const env of res.data.Envelopes ?? []) {\n      switch (env.Type) {\n        case \"Signal\":\n          // env.Kind: \"offer\" | \"answer\" | \"candidate\"; env.FromUserID, env.Payload\n          handleSignal(env.FromUserID, env.Kind, env.Payload);\n          break;\n        case \"Chat\":\n          appendChatMessage(env.FromUserID, env.Payload);\n          break;\n        case \"PlayerJoined\":\n        case \"PlayerLeft\":\n        case \"MemberState\":\n          refreshRoomMembers(roomID);\n          break;\n        case \"HostChanged\":\n          break; // env.Payload / a follow-up getRoom() carries new host\n        case \"RoomClosed\":\n          polling = false;\n          break;\n      }\n    }\n    lastSeq = res.data.MaxSeq ?? lastSeq;\n  }\n}\n```\n\nThere's no push/websocket transport here — polling cadence is your call. The\ntitle's `MultiplayerDefinitions.HeartbeatIntervalMs` (default 1000ms) is a\n_recommended_ interval only, not enforced — poll too fast and you risk\n`reason: \"throttled\"` at the transport layer; too slow and signaling feels\nlaggy, and other members' `LastSeenMs` will look stale to you. Use the\nrecommended interval as your default; back off on `\"connection\"` errors\nrather than hot-looping.\n\n### Exchange a WebRTC offer/answer\n\n```ts\n// caller side, after creating an RTCPeerConnection and an offer:\nconst offer = await pc.createOffer();\nawait pc.setLocalDescription(offer);\nawait client.multiplayer.sendSignal(\n  roomID,\n  targetUserID,\n  \"offer\",\n  JSON.stringify(offer),\n);\n\n// callee side, from the poll loop's \"Signal\"/\"offer\" case:\nconst offer = JSON.parse(env.Payload);\nawait pc.setRemoteDescription(offer);\nconst answer = await pc.createAnswer();\nawait pc.setLocalDescription(answer);\nawait client.multiplayer.sendSignal(\n  roomID,\n  env.FromUserID,\n  \"answer\",\n  JSON.stringify(answer),\n);\n\n// both sides, as ICE candidates trickle in:\npc.onicecandidate = (e) => {\n  if (e.candidate) {\n    client.multiplayer.sendSignal(\n      roomID,\n      targetUserID,\n      \"candidate\",\n      JSON.stringify(e.candidate),\n    );\n  }\n};\n```\n\n`signalKind` is a free-form string (`\"offer\"`/`\"answer\"`/`\"candidate\"` by\nconvention) and `payload` is an opaque string — the server relays both without\ninspecting them, so encoding is entirely up to you (JSON-stringify is the\nobvious choice). Keep the serialized payload under the title's\n`MaxSignalPayloadBytes` (default 16384) — an oversized payload is rejected\nwith `` `Signal payload exceeds {N} bytes.` `` before it's ever relayed, and\nyou can't signal yourself (`\"Cannot signal yourself.\"`) or a user who isn't\ncurrently a room member (`\"Target user is not in this room.\"`).\n\n### Lobby ready-check and leaving\n\n```ts\nawait client.multiplayer.setMemberState(roomID, true, { loadout: \"red\" });\n// other members see this via a \"MemberState\" envelope on their next poll,\n// then re-fetch with getRoom(roomID) to read updated Members[].Ready/State.\n\nconst left = await client.multiplayer.leaveRoom(roomID);\nif (left.ok && left.data.Closed) {\n  // room was empty/owner left with no migration target — it's gone\n} else if (left.ok && left.data.NewHostUserID) {\n  // host migrated; that member is now authoritative for Host topology\n}\n```\n\n## Gotchas\n\n- **Nothing here touches `client.data.user.state`.** Don't look for a cached\n  room state or resource balances changing — read everything from method\n  responses and poll envelopes, and keep your own local room/member state in\n  your app layer. The one thing that _is_ cached is the title-wide\n  `MultiplayerDefinitions` config, and only after you fetch the title config\n  (see [Reading limits from config](#reading-limits-from-config)).\n- **One room per player, enforced server-side.** `createRoom` and `joinRoom`\n  both reject with `\"You are already in room {roomId}. Leave it first.\"` if\n  you're already a live member elsewhere — there's no implicit \"leave old,\n  join new.\"\n- **Room state is ephemeral.** No persistent document backs a room — it's\n  Redis, TTL-based (`RoomTtlSeconds`, default 3600s, renewed on every\n  interaction including `poll`). A room can disappear if nobody interacts\n  with it; don't assume a `RoomID` is valid indefinitely. A title may also\n  set a hard lifetime (`MaxRoomLifetimeSeconds`, counted from creation, NOT\n  renewed by activity): when it passes, members receive `RoomClosed` with\n  `Kind: \"expired\"` mid-game — save progress and offer \"new room\".\n- **`sendChat` only works under `ChatMode: ServerRelay`.** Under `P2P` chat\n  mode, send chat over your own WebRTC DataChannel instead — calling\n  `sendChat` in `P2P` mode fails with `\"Chat is peer-to-peer in this room;\nsend it over the DataChannel.\"` (check the room snapshot's `ChatMode`\n  before wiring a chat send button to it).\n- **`closeRoom` works for the owner or the current host, not just the\n  original creator.** After a host migration the new host can also close the\n  room; anyone else gets `\"Only the room owner or host can close the room.\"`.\n  Regular non-host, non-owner members only have `leaveRoom` (which itself may\n  close the room if it empties out).\n- **Private rooms 404 instead of 403.** `getRoom`/`poll`/etc. on a private\n  room you're not a member of returns the same `\"Room not found.\"` as a\n  genuinely unknown id — the backend doesn't leak room existence to\n  non-members.\n- **No automatic eviction — except via `claimHost`.** `RoomMemberView.LastSeenMs`\n  is a last-heartbeat timestamp for clients to compare against\n  `MultiplayerDefinitions.MemberTimeoutMs` themselves (e.g. to gray out a\n  presumed-disconnected member). The server never evicts a stale member on\n  its own; the one exception is `claimHost`, which removes a HOST that has\n  been silent longer than `MemberTimeoutMs` and hands the role to the caller.\n- **Poll cadence is uncapped by the SDK — you own the rate.** There's no\n  built-in backoff or interval; hitting the same endpoint faster than the\n  transport's throttle window returns `reason: \"throttled\"` rather than\n  duplicating work. `HeartbeatIntervalMs` is the title's _recommended_\n  interval, not an enforced one. Design your loop's interval deliberately\n  rather than polling in a tight `while(true)`.\n- **`Payload`/`signalKind` are opaque strings.** The server does not validate\n  WebRTC SDP/ICE structure — malformed payloads only fail on the _receiving_\n  client when it tries to parse/apply them, not at the relay. It does,\n  however, enforce a byte-size ceiling (`MaxSignalPayloadBytes`) before\n  relaying at all.\n- **Guard against double-submit** on room actions (create/join/close): each\n  call is a distinct request, so two separate calls are two real operations\n  server-side (e.g. two `createRoom` calls can both succeed as two different\n  rooms if the first response is slow). Disable the control while a call is\n  in flight.\n\n## Full reference\n\n[references/data-model.md](references/data-model.md) — full shape of\n`RoomSnapshotResponse`, `RoomMemberView`, `RealtimeEnvelope`/`EnvelopeType`,\n`MultiplayerDefinitions`, and the request/action surface, plus the room\nlifecycle state machine (Open → Closed, host migration, TTL expiry). Read it\nwhen building richer room/lobby UI or wiring up the poll loop's envelope\nhandling in detail.\n",
   "references": [
     {
       "path": "data-model.md",