@indiegems/gem-web-sdk 7.3.1 → 7.4.1

package/docs/rooms-and-matches.md

@@ -0,0 +1,779 @@
+# Rooms and the match lifecycle — the browser half
+
+How a browser game gets from "the player pressed Play" to "everyone in this room is on the same
+server". It mirrors the platform's own room manager deliberately and closely: a developer or an agent
+carrying the engine's model should transfer with no friction, and where the web cannot look like the
+engine this document says why.
+
+> **Which SHAPE of room you want is decided first, on
+> [`room-shapes.md`](room-shapes.md)** — a match, a hub players drift through, a custom lobby one
+> player owns, or an authoritative worker whose server runs no match at all. This page is the
+> mechanism underneath all four.
+
+> **This page is the SDK's model. The platform's own rules are
+> [`platform-rules.md`](platform-rules.md)** — what gem-api enforces underneath, none of which is
+> visible in a type signature. The one to carry into everything below: **a match is sized by who is in
+> the room the instant `startMatch()` is called**, never by the room's capacity. Two of eight seats
+> filled is a two-player match, and nothing tops it up.
+
+## 1. Rooms are a state machine that emits events
+
+The engine's signal list **is** the API, and it is reproduced here name for name, in this SDK's
+casing:
+
+| Engine signal                                                      | This SDK                                            |
+| ------------------------------------------------------------------ | --------------------------------------------------- |
+| `game_room_created` / `_joined` / `_left` / `_closed` / `_updated` | `created` `joined` `left` `closed` `updated`        |
+| `game_rooms_listed` / `my_game_rooms_listed`                       | `listed` `mineListed`                               |
+| `member_joined` / `member_left` / `kicked_from_game_room`          | `memberJoined` `memberLeft` `kicked`                |
+| `ready_changed` / `host_changed`                                   | `readyChanged` `hostChanged`                        |
+| `match_allocation_started` / `match_ready` / `match_failed`        | `matchAllocationStarted` `matchReady` `matchFailed` |
+| `version_update_available`                                         | `versionUpdateAvailable`                            |
+| `error(operation, code, message)`                                  | `error({ operation, code, message, … })`            |
+
+Three events have no engine counterpart.
+
+**`matchStartWaiting`** fires while the SDK is waiting for the platform to have a server to allocate
+at all. It is web-only because the wait is: the engine does not absorb a refused start, and this SDK
+does. §4.4 is the whole of it.
+
+**`matchAutoStartFailed`** tells the host the platform tried to start the room's match on its own and
+was refused, with the error code. No match exists, so by default the host's SDK starts it, and the
+event's `handled` says whether it did. §4.4 again.
+
+**`seated`** says this player holds a seat in a room this game never joined — the party case, and
+the only thing that reports it. Players who launch together arrive as room members who are already
+there, so a member's game is put in a room by the *leader's* call and has nothing of its own to
+learn from. It is **a fact, not a join**: nothing about the manager changes, `currentRoom` is
+untouched, and what to do about a seat is the game's. It fires on the relayed push, once when a game
+subscribes, and again whenever the tab returns to the foreground — and it costs nothing at all until
+something subscribes, because the watch behind it is what a subscription turns on.
+`p2p-and-parties.md` §7.4 is the flow.
+
+Two engine signals are deliberately absent, and each absence is a rule rather than an oversight:
+
+- **`game_room_invite_received`** — invites are Arcade surface. The line the platform draws
+  around the friend graph is: your game may read **who the player's accepted friends are** —
+  display identity only, via `gem.friends` ([`friends.md`](friends.md)) — and nothing else about
+  the graph crosses the frame. No presence, no pending requests, no invite events, no mutations.
+  An invite is something happening *in* the graph, so it is delivered and rendered where the
+  graph lives, on the Arcade. Derived questions also keep being answered where the data lives:
+  the friend view in [`leaderboards.md`](leaderboards.md) re-ranks a board server-side, and a
+  party crosses into a room as an opaque grouping.
+- **`ping_results_ready`** — the engine's measurement is a UDP echo, which a browser cannot perform.
+  A browser ranks regions by timing STUN probes instead, and that happens on the Arcade page rather
+  than in the frame: the game is handed the few clusters close enough to be acceptable, best first,
+  and never the table of results, because a round trip to every region is coarse geolocation plus a
+  network fingerprint. So there is a ranking on web, and no signal carrying it. See
+  `dedicated-server-flow.md` §5.
+
+Rooms are **not** promises with room-shaped return values. `create()` and `join()` do return the room
+they acted on, because the caller asked and deserves an answer — but every subsequent fact about that
+room arrives as an event, because every subsequent fact originates somewhere else: another member
+readying up, the host leaving, a server coming up in Frankfurt.
+
+## 2. What this kills
+
+Before this, `join()` took a `matchId` that nothing in the SDK could produce. Every game had to invent
+a side channel to carry it from the host to players **who were already in a room with them** — which
+is to say, every game had to rebuild the thing the room already is.
+
+The engine has no such problem and neither does this now. The host calls `startMatch()`; every member
+receives `matchAllocationStarted` the moment allocation begins and `matchReady` when it is up. Nobody
+passes an id around, and `dedicatedServer.connect()` takes no match id at all.
+
+`connect` and `join` have collapsed into one method for the same reason. The host-only/everyone-else
+split existed because `start_match` 403s a non-host — but the room knows who the host is, so
+`connect()` allocates when this player is the host and waits when they are not. That is a fact the
+game should never have had to carry.
+
+One fact remains that `dedicatedServer.connect()` and `p2p.connect()` still make the game carry:
+**which of the two flows this room's template chose**. `gem.match` removes that one too — `serve()`
+offers to run your server bundle wherever the template says the authority lives, and `connect()`
+resolves one link shape to it, dedicated or peer-hosted alike
+([`server-bundles.md` § The same bundle, hosted by a
+player](server-bundles.md#the-same-bundle-hosted-by-a-player)). The two lower flows stay public for
+games that want their specifics; `gem.match` is the surface to reach for first.
+
+**The first-call race is gone too.** Every room route is scoped by your game's id, and the id
+arrives with the first play token — moments after the handshake, but not at the instant your game
+starts. A room call made before it landed used to throw `misconfigured: the game id is not known
+yet`, which made a game whose first act was `quickJoin()` a race: green on a fast handshake, a
+refusal on a slow one, and nothing in the error naming the wait that would have fixed it. From SDK
+3.8.0 a room call made in that gap **waits for the token** — the same bounded wait
+`gem.awaitIdentity()` performs, with the same rejection if no token ever comes. `awaitIdentity()` is
+still how you read the ids yourself; it is no longer a gate you must pass before the first room call.
+On an older SDK, keep awaiting it first.
+
+## 3. Where the socket lives, and what crosses the bridge
+
+**The parent page holds the notification WebSocket.** It holds the player token, and
+`POST /v1/ws/ticket` accepts only player tokens — by design, and not something to widen. The frame
+never holds that socket and never holds a credential for it. That is a platform decision, settled and
+not being revisited.
+
+So room pushes reach the game the same way signaling is meant to: over the bridge, with the parent
+deciding what crosses.
+
+```
+notification socket ──▶ GemHost.relayRoomEvent(raw)  ──▶ gem.roomEvent ──▶ RoomManager
+                        (the allowlist)                   (the bridge)     (authoritative refresh)
+```
+
+### The allowlist is one allowlist
+
+`GemHost.relayRoomEvent` takes a raw socket frame and either sends a `gem.roomEvent` or returns
+`false`. It drops:
+
+- any `type` outside the five allowlisted room events — **an unrecognised type is a drop, not a
+  passthrough**, so friend requests, party invites, transfer receipts and purchase completions can
+  never reach a game by the parent forgetting to filter them;
+- any event for a different `game_id` than the token this host issued — pinned from the first
+  `sendToken`, so relaying cannot begin before the parent has said which game is running;
+- any event whose fields do not survive projection. Fields are **copied by name onto a fresh object**,
+  never spread, which is the same rule `sendToken` and `sendPlayer` already follow and for the same
+  reason: an API record passed through carries whatever else it happened to hold.
+
+**One more room push crosses, as a message of its own.** gem-api tells a room's host when it tried to
+start the match on its own and was refused — `game_room_auto_start_failed`, with the error code — and
+the parent relays it as `gem.autoStartFailedEvent`, the room id and the code and nothing else, to a
+frame that advertises `autoStartFailure`. It is not a sixth `gem.roomEvent` because an older frame
+refuses an enum value it does not know, and reports that to the game as a protocol error; an unknown
+message type it ignores. The game sees it as `matchAutoStartFailed` (§4.4).
+
+There is exactly one filtering point and this is it. The engine keeps a full match event in native
+code and hands its scripting layer an allowlisted subset, because native code can hold a secret
+from a sandboxed script. **The frame-side SDK cannot** — it shares a JavaScript realm with the game,
+so anything it holds the game can read. Reproducing the engine's strip _inside the frame_ would be
+theatre. The trust boundary that actually exists on web is parent↔frame, so that is where the strip
+lives, and it is the stronger placement: the parent decides before the bytes cross an origin, and the
+values it never sends cannot be read out of a closure.
+
+What the SDK hands the game from a match status response is still projected by an allowlist,
+and that is an **API contract** — the shape a game may depend on — not a confidentiality
+control. Said plainly here so nobody later mistakes it for one.
+
+The same reasoning decides where a member's _group_ is worked out, and it used to be decided the
+other way. A room roster once carried the platform's real party id, and this SDK read it, replaced it
+with a room-scoped label and dropped the original — a strip inside the frame, which is the thing the
+paragraph above calls theatre. It was the only option at the time and it was the weak version:
+the id still crossed into the game's realm on its way to being discarded. gem-api now issues the
+room-scoped marker itself and sends no party id at all, so there is nothing here to strip. **A value
+the frame never receives is one a game cannot read out of it** — which is what "no interior" means
+when you take it seriously rather than work around it.
+
+### Which room routes are v2
+
+That marker arrived with a second version of the routes that named a party, so this SDK calls both
+versions. The line is not arbitrary: `/v2` is every route that answers with a member roster, plus
+leave, whose v1 _request_ asked the caller to name a party. Everything else mentions a party in
+neither direction and was left where it was.
+
+| `/v2`                                                                            | `/v1`                                                  |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| create, join, join-by-code, quick-join, get, update, ready, transfer host, leave | list, my rooms, close, kick, start match, match status |
+
+The one place that costs something is **kick**. It never mentioned a party, so it was not versioned,
+and its response is therefore a v1 roster with no group markers in it — taking that as the room's new
+state would blank every member's group until the next poll. So the SDK discards what kick answers
+with and re-reads the room on `/v2`: one extra GET on a host action a player performs by hand,
+against a bug a player would see.
+
+### The relay is a hint, not the truth
+
+`gem.roomEvent` carries a room id, an optional match id, an optional room version, an optional
+failure reason and an optional platform. It carries **no room state**: no member list, no display
+names, no join code.
+
+That is exactly what the engine does — its push handler triggers an authoritative HTTP refresh
+rather than applying the push — and on web it pays twice over. The push crosses an origin boundary and
+would otherwise be a route by which a compromised parent writes the game's model of who is in the
+room. Instead the frame re-reads the room with its own game-scoped token and diffs, so the parent can
+make the frame _look_, and cannot make it _believe_.
+
+`version` is the debounce: a hint whose version the frame already holds is dropped without a request.
+That is the engine's ETag/`If-None-Match` behaviour expressed in the one field the push already
+carries.
+
+### One of the five is forwarded rather than re-read
+
+`version_stale` is **platform-scoped, not room-scoped**. It says a build line the room requires is
+ahead of one a member is running, and it adds no version and no match id. There is nothing to re-read
+behind it, so receiving one triggers no refresh, no poll retune and no change to any state this SDK
+holds. It is handed to the game as `versionUpdateAvailable` and that is all that happens.
+
+**Expect no `platform` on it.** A browser client joins as `web` and gem-api names that platform when
+it raises the push, and the bridge does not carry the value, so the field arrives empty. Nothing is
+lost: a browser game has one build line and this event is about that line whether or not it is named.
+Branch on the event, not on its payload.
+
+This mirrors the engine deliberately rather than approximately, because the alternative is a
+divergence a developer would hit rather than read about: the engine answers this event before its
+"is this for my current room" guard and emits a signal without triggering its refresh, so a native
+game observes a forwarded platform and nothing else. A web build should observe the same thing on the
+same push — which is also why the Arcade page does not act on it instead. What to do about a stale
+build (prompt, reload at a safe moment, carry on) is a decision only the game can make, and a
+platform layer that made it would be making it for every game.
+
+The platform is **validated at the parent and blanked when the bridge does not carry it**, which is
+again the engine's handling and for the engine's stated reason: the string arrives from a server push,
+so it is treated as untrusted rather than as a value the receiver can rely on. That is also what keeps
+the event alive for `web`, and for whatever gem-api adds next — the frame's validator is generated
+from a frozen schema, so a frame built before a value existed would reject the whole message and the
+game would be told nothing at all.
+
+### Why a browser game needs it at all
+
+This event was once deliberately absent here, and the argument for leaving it out was that a browser
+game is updated by the platform serving new bytes rather than by a player running an installer — so
+there is nothing to prompt. What that misses is that a tab which has been open a while is running
+bytes nobody is serving any more.
+
+gem-api raises this push by re-checking each member's stored version against the channel, scoped to
+the platform of the join that triggered it. A browser game reports `web`, which is the dimension it
+publishes into, so **every** verdict reaches it: a build you blacklisted, one that was never released
+on this channel, and one that aged out after you promoted a replacement. This push means the version
+this tab is running is no longer one the channel will serve, and the tab has been open since before
+that changed.
+
+Reloading is what fixes it, and only the game knows whether the player is between matches or mid-boss.
+Which is the whole argument for forwarding rather than acting.
+
+### What ages a version out, and the three levers the game's owner has
+
+The push above is the tail end of a lifecycle the _owner_ of the game drives, from a signed-in
+developer account rather than from the running game. None of it is reachable with the token the
+frame holds, and none of it is something the SDK can do for you — but a game's own error handling is
+written against its results, so it is worth knowing what they are before a player meets one.
+
+**Expiry — a new build starts a clock on the old one.** Assigning a version to a channel
+(`PUT /v1/games/{game_id}/packages/{platform}/channels/{channel}`) makes it the head and _dethrones_
+whatever was there. A dethroned version stays playable for that channel's expiry window and then
+fails as `expired`. The window defaults to **24 hours** and is set per game and channel with
+`GET` / `PUT /v1/games/{game_id}/channels/{channel}/version-policy`, body
+`{ "expiry_ttl_secs": <seconds> }` (minimum 1). **It is applied when the check runs rather than
+stamped in at the moment a version was dethroned**, so raising it during an incident immediately
+extends the remaining window of every already-dethroned build, and lowering it immediately shortens
+them. The same window decides how long an older _server_ build keeps serving its line, which is what
+the `expired` reason on `no_compatible_server` means.
+
+**Blacklist — the kill switch, and it is blunt on purpose.**
+`POST /v1/games/{game_id}/versions/{version}/blacklist` with a reason (1–500 characters), cleared
+with the matching `DELETE`. Two properties decide how you use it:
+
+- **It is channel-agnostic.** A blacklisted version is refused on dev, test _and_ release at once.
+  The only narrowing available is by platform, so there is no "block it on release, keep it on dev".
+- **It is not retroactive.** A match that has already allocated keeps running and nobody is kicked.
+  What changes is the _next_ check — including a reconnect, so a player already inside a running
+  match is bounced the moment their client next polls status, while members on a still-good version
+  carry on normally.
+
+**Rollback is re-assignment, not an undo.** `PUT` the previous good version back onto the channel:
+that clears its dethroned mark and makes it the head again immediately, however long ago it was
+superseded and whether or not it had already expired. There is no separate un-dethrone. A version
+that is _also_ blacklisted stays blocked even as head — clearing the blacklist is a second,
+independent step.
+
+**What the player's client actually gets** is a **409 `bad_version`**, carrying `details.reason`,
+the version that was rejected and the channel it was checked against. It fires at room create, join,
+quick-join, match start, reconnect and party version submission — so a player in a lobby meets it
+before they play and a player mid-match meets it on their next status poll. The four reasons are
+evaluated in a fixed order and mean different things:
+
+| `details.reason`  | What it means                                                                                                                                         |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `blacklisted`     | Somebody killed this version. Checked first, ahead of every case below                                                                                |
+| `unknown_version` | No such version was ever published for this game — a client reporting a version that does not exist                                                  |
+| `not_released`    | The version exists but carries no lifecycle row, which normally means a channel assignment landed without one. Re-assigning the same version fixes it |
+| `expired`         | It was dethroned longer ago than the channel's window allows                                                                                          |
+
+**All four reach a browser build**, and `unknown_version` is the one that used to be easiest to cause:
+it fires when the reported version is not one you uploaded for the `web` platform on the channel being
+played. The arcade now reports the version of the build it routed the player to, so a number typed into
+your source can no longer disagree with the number the build was published under — the one case that
+produced this reason for a game that had done nothing wrong. It still fires for a build deleted out
+from under a live session, and for a game still declaring its own version under an arcade too old to
+send one. The SDK reports the platform itself — see
+[`dedicated-server-flow.md`](dedicated-server-flow.md) §1 — so all four controls are live, where a
+client naming a dimension it publishes nothing in would sail past every one of them.
+
+### Polling is the floor, not the fallback
+
+The manager polls. Push makes it poll less — the interval relaxes when the parent has advertised the
+`rooms` capability and pushes are arriving, exactly as the engine drops to 60s when its push
+connection is up. A game running against a parent that never relays anything still works; it is just
+slower. A design where push is the only path has a silent failure mode, and the silent failure mode is
+"the lobby never updates".
+
+**The relaxation expires.** It lasts two relaxed intervals past the last push and then the base
+interval is back, so the relaxed one is a ceiling on how long this side goes without looking rather
+than a switch that turns looking off.
+
+🔴 **It used to be permanent.** The interval was chosen when a push arrived and re-armed unchanged
+forever after, so one push relaxed the poll to a minute for the rest of the room's life — and a relay
+that then stopped delivering was never noticed, because nothing was ever going to look sooner. A game
+waiting on a room change whose push was dropped sat through its entire matchmaking window without
+re-reading the room. A push is an optimisation; it is never the thing that licenses not looking.
+
+`startPolling(ms)` **pins** the interval. The cadence is then the game's, and no push moves it —
+which used to be untrue in the same way, and in the worse direction: a game that asked for a
+one-second poll was retuned to the relaxed default by the first push and never came back.
+
+## 4. Match connection state, and the four things that are load-bearing
+
+```
+DISCONNECTED ──startMatch/adopt──▶ CONNECTING ──ready──▶ CONNECTED
+     ▲                                  ▲                    │
+     └────────── failed / left ─────────┴── reconnect ── SUSPENDED ◀── the link dropped
+```
+
+`matchConnectionState` is this coarse view. Underneath it, `matchSession` carries the finer one —
+`none`, `starting`, `ready`, `connected`, `suspended`, `ended`, with the match id and, once it is
+over, the reason — and the events that move it (`matchEnded`, `matchSuspended`,
+`matchReconnecting`, `matchReconnected`). That whole contract, including play-again and what to show
+the player in each phase, is [match-session.md](match-session.md); this section covers the four
+properties of the connection itself.
+
+### 4.1 The late subscriber
+
+`matchReady` fires once, and a game that attaches its handler afterwards would wait forever. A
+promise-shaped API hides this; an event-shaped one exposes it, so the semantics are chosen out loud:
+
+**`matchReady` is retained and replayed.** A handler attached after the match came up is invoked with
+the retained match info on the next microtask, exactly once. `matchAllocationStarted`, `memberJoined`
+and the rest are **not** replayed — they are transitions, and a transition you missed is not a state
+you are in. The retained value is cleared when the match fails, when the room is left, and when a new
+allocation starts.
+
+Two other ways in exist for the same reason, because different games are written differently:
+`rooms.currentMatch` is the pull model (the engine's `get_last_match_event`), and `rooms.awaitMatch()`
+is the promise — it resolves immediately when a match is already ready, and is bounded, because this
+SDK ships no promise that can never settle.
+
+### 4.2 Reconnection is first-class, and by default it is the SDK's
+
+A backgrounded tab, a laptop lid, a train tunnel. `SUSPENDED` means "the link dropped and the
+platform has not said the match is over". Since the SDK's 4.0.0 release (2026-09-10) the way out
+is, by default, nothing you write: a connection from `gem.match.connect()` reconnects itself — six
+attempts, the wait doubling from half a second to eight, a read before the first attempt so a link
+that dropped because the match ended produces `matchEnded` and no attempt at all, and nothing while
+the page is hidden. The room raises `matchSuspended`, `matchReconnecting` per attempt and
+`matchReconnected` when the link is back; the connection's `onClose` fires only when the attempts
+run out, or when the platform ended the match.
+
+`reconnectToMatch()` is the manual takeover — calling it stops the policy's loop and forces an
+immediate status poll rather than waiting out the interval — and `gem.match.connect()` again on a
+suspended session does the same through the unified surface. `createGem({ autoReconnect: false })`
+turns the policy off, and a connection then closes on every drop. The policy, its knobs and what to
+show the player while it runs are [match-session.md](match-session.md) §4.
+
+The SDK does not guess when to suspend from browser events: `visibilitychange` fires when a player
+alt-tabs to read a wiki, and treating that as a disconnect would tear down live matches. What it does
+do is wire the one signal that is unambiguous — the transport closing without the game having
+closed it, which is what moves the session to `SUSPENDED`. A game that dials its own transport says
+the same thing with `notifyMatchDisconnected()`.
+
+### 4.3 Leaving is an explicit notification
+
+`notifyLeavingMatch()` posts `POST /v1/games/{game_id}/matches/{match_id}/leave`, best-effort and
+quiet, so the backend broadcasts the departure and the match authority evicts the peer immediately
+instead of waiting out an ICE recovery budget.
+
+**gem-api refuses that route for a dedicated match** with `match_not_p2p` — it is a P2P lifecycle
+route, which the engine's own comment says (`p2p_peer_left`). So on web the honest picture is: for a
+P2P match the notification is the mechanism; for a dedicated match the mechanism is the data channel
+closing, which the browser does on unload anyway, and leaving the room is what ends the allocation.
+The call is made in both cases and quiet-fails in one, which is what the engine does too.
+
+### 4.3a Tab close leaves the ROOM, and that is the part that matters
+
+`pagehide` fires two keepalive requests: **the room leave first**, then the match departure above.
+Neither is awaited — they are keepalive requests, which the browser has already undertaken to
+deliver, and awaiting inside an unload handler is how the second one never gets issued at all.
+
+🔴 **This used to send the match departure alone.** On this platform that route is a guaranteed 400
+(see 4.3), so the effect was a doomed round trip and a room membership that outlived the page every
+time. Measured on a live release channel, 2026-08-04: the arcade still showed the player as a member,
+and their next session met a quick-join **409** that locked them out of the game entirely — gem-api
+refuses to quick-join a player who is already in a room, so the leftover does not merely get handed
+back. The game that hit it wrote both halves of the recovery by hand.
+
+`keepalive` matters because a `fetch` issued during `pagehide` without it is cancelled by the browser
+— an unload notification that is not `keepalive` is a silent no-op wearing a feature's clothes. It is
+an ask rather than a contract, which is why the 409 recovery below still exists as a backstop.
+
+Nothing is sent when `pagehide` fires into the **bfcache** (`event.persisted`). The page may well come
+back to the same match, and leaving there evicts a player who did nothing but switch tabs.
+
+### 4.3b A membership that outlived its page
+
+`myRooms()` is the only thing that can see one: the leftover is the backend's, so the manager holds no
+room and `leave()` has nothing to act on. Two calls answer it:
+
+- **`leaveAll()`** leaves every room this player still holds, best-effort per room — one unleavable
+  room must not stop the others, since the refusal stands while any remain. Best-effort **per room**
+  is the whole of it: if the listing that finds those rooms fails, the call **rejects**. It does not
+  answer with an empty array, because that is also what a player holding nothing gets, and the two
+  want opposite handling. See the warning below before wiring it to a button.
+- **`quickJoin()` recovers on its own, by default.** A 409 clears the memberships and retries
+  **once**; any other refusal is not a membership problem, and a 409 that survives the clear means
+  something the manager does not model, so it is raised rather than looped on.
+  `createGem({ recoverStaleMembership: false })` turns this off for a game whose players are in
+  rooms on purpose — and the refusal that game then meets says so, naming `myRooms()` and
+  `leaveAll()` beside gem-api's own sentence, because "already in a game room" reads as nonsense to
+  a caller whose manager is in no room at all.
+
+**No game has to ask for this.** The recovery is the default and `leaveAll()` is the manual tool
+beside it, not a call a correct integration is obliged to make.
+
+**A party seat is not debris, and quick-join no longer treats it as such.** A party reaches a game
+as room members who are already there — the leader's single room call seats every member
+(`p2p-and-parties.md` §7) — so a member's game boots already in a room it never asked for. Its own
+`quickJoin()` for that template is neither refused nor answered with a second room: the platform
+reads `party_id` off the membership row and hands back the room the leader put them in. Debris
+keeps its 409. **Only the server can draw that line** — from inside the frame a party seat and a
+dead page's leftover are the same observation — which is why this is not something the recovery
+above was ever going to get right, and why it was fixed in the platform rather than here.
+
+⚠️ **So quick-join has three outcomes, not two: a room created, a room joined, and a room you were
+already a member of.** A game that assumes a fresh or newly-joined room — clearing per-match state
+on the strength of the call returning, say — is surprised by the third. `Room` reports `joined` for
+all three, and cannot do better: gem-api answers 200 and 201 through one route, so the client sees
+one body. Reporting `created` for half of them would be wrong half the time.
+
+A member's game is better off not asking at all. **`seated`** reports the seat as soon as it exists
+— on the relayed push, when the game subscribes, and whenever the tab returns to the foreground —
+so the handler can put the player straight into the leader's match with no start menu and no press,
+which quick-join can only do after the player has pressed something. §1 introduces the event and
+`p2p-and-parties.md` §7.4 is the flow, including the one thing a member still cannot do: leave.
+`leaveAll()` cannot clear a party seat, because only the leader may take a party out of a room.
+
+🔴 **This was once got wrong in a test fixture, which is how it was found.** gem-api answers 409
+`already_in_matching_room` when a player already holds a joinable room matching the template, and it
+answers it _before_ it looks for a candidate — but the fixture had no such guard, so its quick-join found
+the player's own leftover in the ordinary sweep, joined a room they were already in and answered
+**200**. Locally, that is a player silently returned to the dead room they never left, the recovery
+path never running against the fiction it was written for. The guard is modelled now, cluster and
+all: gem-api compares the template and the channel only, so a leftover in a cluster this quick-join
+did not list blocks a quick-join the candidate sweep would never have matched it to.
+
+### 4.4 There may be no server to start on, and `startMatch` waits
+
+**A start can be refused because no server is free.** The platform allocates a server when a match
+starts, and a start that arrives when none is available is answered **503**. That is a normal
+condition to design for, and the SDK absorbs it rather than handing it to the game.
+
+So `startMatch()` retries a 503 rather than handing it to the game, and the wait is
+`matchStartWaiting`:
+
+```ts
+rooms.on('matchStartWaiting', ({ attempt, elapsedMs, budgetMs, nextAttemptInMs }) => {
+  ui.showFindingServer({ elapsedMs, budgetMs }); // "Finding a server… 12s"
+});
+await rooms.startMatch();
+```
+
+It fires once per refusal, **before** `matchAllocationStarted` — which cannot fire yet, since there
+is no match id — and only for the host, since only the host allocates. A game that renders nothing
+here has a Start button that stalls for up to half a minute, which is a worse experience than the
+refusal it replaced.
+
+**The budget is 30 seconds, and the player is what sets it.** This is the one number here that is
+_not_ derived from the platform: a player who has pressed Start is watching a spinner, and thirty
+seconds is the ceiling on what they will tolerate.
+
+> 🔴 **It will give up on some starts that a longer budget would have caught.** That cost is
+> accepted deliberately, in exchange for not stalling the player. A game whose own players will wait
+> longer sets `retry: { budgetMs }`; the default is not going to grow to meet the platform.
+
+**The other two numbers are measured against the platform.** The gap between attempts is exponential
+from 1s and **capped at 20s**, because gem-api meters match starts at **ten per player per minute**
+and fails closed: a schedule that outran the limiter would manufacture the 429 it then had to handle.
+The cap holds the steady state to three requests a minute at any budget.
+
+The gap is **jittered** — half the nominal, plus a random share of the other half. The failure being
+absorbed is several clients starting matches on one fleet at the same instant, and an unjittered
+backoff re-synchronises exactly those callers into a second collision.
+
+`retry: { budgetMs }` sets the budget per call, on `startMatch()` and on `dedicatedServer.connect()`;
+`budgetMs: 0` stands the retry down and hands back gem-api's own error, for a game that would rather
+run its own loop. A budget that runs out raises `no_server_ready` — saying how long it waited and
+what the platform said last, and carrying that refusal as its `cause` — which is a different thing
+from any 4xx gem-api answers, and should be presented differently to a player.
+
+**Retrying is safe because of what the route guarantees, not because 503 sounds transient.** Starting
+a match is idempotent for a room — a repeat gets the match that is already running, never a second
+one — and a 503 is answered before any match is recorded at all. Waiting cannot leave a room with two
+matches.
+
+Two refusals are deliberately **not** retried, because waiting changes nothing: any 4xx about the
+request itself, and the 429 `too_many_concurrent_matches`, which gem-api's own documentation says
+clears only when one of this player's matches ends.
+
+**A cluster that keeps having no server is left, once.** A start runs in the room's own cluster, and
+two `capacity_unavailable` refusals in a row move it to the next cluster this player can play well
+in, where it keeps waiting inside the same budget. A start in a cluster the platform does not run —
+`invalid_cluster_target` — is not waited on either: the SDK starts once in this player's best other
+cluster. Both name a cluster, so both move the room there for its later matches, and neither runs on
+a `clusterTargetId` you passed yourself. `dedicated-server-flow.md` §5 has the whole rule.
+
+**A match the room was meant to start on its own can be refused too, and then the host's SDK starts
+it.** When a template starts the match as the room fills to `min_players`, nobody pressed Start and
+nobody is waiting on a call — so the refusal arrives as `matchAutoStartFailed`, to the host only, with
+the error code a manual start would have had. No match exists and the room stays open. By default
+the host's SDK then starts the match itself, running the recoveries above, and the event carries
+`handled: true`. What follows is what follows any start: `matchStartWaiting` while no server is free,
+`matchAllocationStarted` when one is, `error` if the start fails.
+
+It does that for `invalid_cluster_target` and `capacity_unavailable` only — the refusals a start from
+the host can get past. The others are about the build (a version no server accepts, an engine line
+no fleet serves, a server size not configured), and the same start would meet them again.
+
+**Once per room until a match begins in it, and never beside another start.** The start the SDK makes
+already carries every recovery it has, so a second one would be the same attempt against the same
+fleet. A later refusal in the same room comes to the game with `handled: false`; the platform itself
+tries the automatic start again whenever another player joins. A start already in flight — the host
+pressed Start, or `gem.match.connect()` is starting one — is left to finish, and the event says
+`handled: true`.
+
+A game that wants to decide passes `createGem({ retryAutoStart: false })`. The event then always says
+`handled: false`, nothing is started for you, and starting it yourself runs the same recoveries:
+
+```ts
+rooms.on('matchAutoStartFailed', () => rooms.startMatch());
+```
+
+**The SDK's 5.11.0 and 5.12.0 releases (2026-09-24) raised this event and started nothing.** A game
+written for them whose handler calls `startMatch()` straight away, as above, still works: the SDK
+sees that start and makes none of its own. A game whose handler holds the start back — for the host
+to press Start, or to decide by the code — needs `retryAutoStart: false`, or the SDK starts the match
+before the host has chosen.
+
+The event reaches a game only when the Arcade page relays it. Where it does not, a game sees nothing,
+and the room waits for a start that is not coming.
+
+#### A peer-to-peer room never waits, because nothing is being allocated
+
+gem-api answers **503** for two unrelated things: a fleet with no server to give, and a backend with
+no P2P configured. A P2P room that waited the second one out would spend the whole budget on a
+server that was never going to be allocated, because a P2P match allocates none.
+
+**The refusal says which it is.** The 503 carries an error code: `capacity_unavailable` when a fleet
+has nothing ready, and `p2p_unavailable` when the backend has no P2P. On `p2p_unavailable` the
+refusal is raised immediately as **`p2p_unavailable`**, carrying gem-api's sentence and its error as
+the `cause`. Nothing waits and nothing is rendered, because there is nothing to wait for.
+
+The two refusals were once byte-identical, and the SDK settled it by fetching the room's template
+and reading its `match_type` — a request on every refused start, plus the fail-open paths that made
+depending on it safe. gem-api separated the codes, so that lookup is gone and a refused start now
+costs nothing beyond the refusal.
+
+Two things about the shape of that, each load-bearing:
+
+- **Every other 503 keeps its wait.** The route documents `capacity_unavailable`,
+  `match_start_fence_expired`, `match_state_race`, `p2p_unavailable` and `service_unavailable`, and
+  reserves the right to add more; anything sitting between the game and the platform can answer with
+  no error body at all. So one code exactly short-circuits and everything else — including a
+  refusal carrying no code — waits as it always did. The cost of a wrong "keep waiting" is the wait
+  a P2P game had before any of this existed; the cost of a wrong "p2p" is a dedicated game that can
+  no longer wait for a server at all.
+- **`p2p_unavailable` is not retryable**, because the usual cause is a platform configuration and no
+  amount of asking changes one. Two rare fence races on the P2P branch answer 503 as well — they
+  carry their own codes, so they keep the retry they always had.
+
+A `match_type` of `none` needs nothing here: gem-api refuses `start_match` for it with **400**
+`match_type_not_supported`, which was never retried.
+
+### 4.5 The refusals from the dedicated-server flow are preserved
+
+Both findings that flow reported still hold and are still enforced:
+
+- **A match whose protocol is not `webrtc_dedicated` is refused, loudly.** `host` and `port` are
+  populated and advisory; dialling them would also make gem-api's lenient protocol read invisible from
+  both ends. See `dedicated-server-flow.md` §4.
+- **Signaling is a seam**, and where nothing is wired to carry an offer it throws naming what is
+  missing rather than hanging. Unchanged by this work: the reason it is a seam at all is the same
+  `POST /v1/ws/ticket` fact that puts the notification socket on the parent, so the shipped
+  implementation relays through the parent as P2P signaling does.
+
+### 4.6 Starting a match is bounded per player, and the bound refuses fail-closed
+
+**A player may only have so many matches running at once**, and a start beyond that is a **429
+`too_many_concurrent_matches`** — deliberately without naming the ceiling. The limiter in front of it
+fails **closed**, so a start it cannot meter is refused rather than allowed. Neither is a queue: this
+is a refusal to handle, not a wait to retry into, and the way out is for one of this player's own
+matches to end.
+
+## 5. Player-authored text
+
+`GameRoomMemberResponse` carries `display_name`, `discriminator` and `display_tag` for every member,
+and every one of them is **text another player typed**. Nothing scrubs them the way the platform
+scrubs the identity fields on `gem.player`, so treat them the way you would treat any untrusted
+input: escape them where they land, and never put them into a page as markup.
+
+What this SDK does about it, so it is hard to get wrong rather than merely documented: a member's
+`displayName` and `displayTag` arrive as `PlayerText`, not `string`, so
+`el.innerHTML = member.displayName` does not compile. `displayTag` is
+platform-composed but embeds the display name, so it is wrapped for the same reason `gem.player`'s
+is. The discriminator alone stays a plain string. A member also carries a portrait
+(`avatarIconUrl`) and `badges` — the identity fields every surface that shows a player carries;
+[Showing a player](what-a-game-must-do.md#showing-a-player-one-identity-on-every-surface) is how to render them. A member with an empty `playerId` is one whose identity the
+platform withholds from you; the seat still counts.
+
+Key member rows on `playerId`. Names are not identifiers.
+
+## 5a. Room args: how a room is configured
+
+A room's configuration is its **room args** — a flat object of typed values: strings, numbers,
+booleans, and homogeneous arrays of those. The shape is not invented per room. Your game's published
+config declares a schema on the room's template naming every entry, its type, its allowed values, its
+default, whether you fixed the value and whether it may change once the room exists; the room takes a
+**frozen copy of that schema** when it is created, so promoting a new config never moves the ground
+under a room that is already open.
+
+**The schema decides who may set what.** Whoever creates the room supplies the entries you left
+choosable, in the create request. Every room you read carries the resolved values and the room's own
+frozen schema on it — `room.roomArgs` and `room.roomArgsTemplate` — so a settings screen is rendered
+from what this room actually allows rather than from a copy of the config your build shipped with, and
+costs no request of its own. The host changes them with `rooms.update({ roomArgs })`.
+
+```ts
+// Configured at creation. A `required` entry has no fallback, so this is the
+// only moment it can be given one — and so is an entry your config marked
+// `mutable: false`, which is choosable here and locked for the room's life.
+const room = await gem.rooms.create({
+  name: 'Match 1',
+  templateSlug: 'skirmish',
+  roomArgs: { map: 'dust', rounds: 5 },
+});
+
+// A settings screen, drawn from the room's own schema rather than from yours.
+for (const entry of room.roomArgsTemplate ?? []) {
+  // `fixed` is the studio's and nobody may write it; `mutable: false` was
+  // settable at creation and is locked now. The rest are the host's to change
+  // while the room is open.
+  drawControl(entry, room.roomArgs?.[entry.name]);
+}
+
+await gem.rooms.update({ roomArgs: { ...room.roomArgs, rounds: 3 } });
+```
+
+**A write is a replacement, not a patch**, and the spread above is not decoration. The object you send
+is your complete intent for every entry you may choose: an optional one you leave out reverts to its
+default or to absence, and a required one has to be sent again. Leaving `roomArgs` out of an update
+altogether is the different thing — it changes nothing, so renaming a room does not quietly reset its
+configuration. Host only, and refused once a match is running (**409 `room_not_open`**) — the server
+was handed its snapshot at match start, and a later edit would be invisible to it.
+
+**Absent is not empty.** A room whose template declares no schema carries neither field, which is how
+you know there is no settings screen to draw; `roomArgs: {}` is a room that has a schema and is sitting
+at its defaults. Both fields are withheld from a player who is not a member, so a public room in a
+browser listing says nothing about how it was configured.
+
+**Every refusal names the entry it is about.** `unknown_room_arg` (a key your template does not
+declare), `room_arg_fixed` (a key the studio fixed), `missing_required_room_arg`, `invalid_room_arg` (a
+value outside the entry's type, bounds or allowed set) and, on a write, `room_arg_immutable` (a
+set-once entry handed a new value). All 400, and all of them refuse the whole call — nothing is
+partially applied and nothing is quietly dropped.
+
+⚠️ **`quickJoin` cannot configure a room**, and that is where a required entry bites. Its request
+carries no configuration in either direction — it may join a room somebody else already configured, and
+a room it creates takes your fixed values and defaults alone. So a template with a **required** entry
+cannot be quick-joined into existence: the call is refused, **400 `missing_required_room_arg`**,
+whether or not there was a room to join. Give every entry a default if your game quick-joins; make one
+required only if your rooms are created with `rooms.create()`.
+
+**Every member can read every value, including the ones you fixed.** Nothing whose safety depends on
+a player not knowing it belongs here; that is what a server holding authority is for.
+
+Both halves of a game read one published shape, **off the room itself, differing only in the token
+presented**. In the browser that is `room.roomArgs` under the player's own token — a **P2P
+listen-host** included, since it has no server to be handed anything. A dedicated bundle presents a
+game-server token instead, and the SDK's server entry pre-binds the room read to the bundle's own room
+as `server.room.get()` ([`server-bundles.md` § What your server reads at
+startup](server-bundles.md#what-your-server-reads-at-startup)). The push that bundle used to rely on,
+`host.roomArgs`, is deprecated but still delivered — [`server-bundles.md` §
+Room args](server-bundles.md#room-args). The dedicated-server runtime image is what delivers it,
+so how long it keeps arriving is that image's to say rather than this package's — [the
+deprecation policy](deprecation-policy.md#3-runtime-delivered-pushes-are-a-separate-question).
+
+The platform used to answer both halves from a `/room-args` sub-resource beside the room. That pair is
+deprecated in favour of the room's own read, which is why there is no `getRoomArgs` on the browser
+surface to call.
+
+⚠️ **`gameArgs` and `templateArgs` are gone.** The two opaque `key=value&key=value` strings a room and
+its template used to carry were removed from the platform, and a create or update still sending one is
+refused — **400 `game_args_removed`**, naming room args as the replacement. They are now gone from
+this SDK too: `Room.gameArgs`, `Room.templateArgs`, `CreateRoomOptions.gameArgs` and
+`UpdateRoomOptions.gameArgs` no longer exist, and the SDK no longer sends `game_args` on a create or
+an update.
+
+If you are upgrading, a `gameArgs` you were still passing was **breaking the call**, not merely
+being ignored — every create carrying one was refused outright. TypeScript callers now get a compile
+error naming the property, which is the loudest form this can take; a JavaScript caller's value is
+simply dropped before the request, which turns a refused create back into a working one.
+
+`settings` is a different thing and still works: free-form game-authored JSON on the room, capped at
+64 KB, which the platform stores and never inspects. Room args are the part it validates and the part
+a server receives. Neither is on the server browser's wire — `RoomSummary` is gem-api's narrower
+projection and omits `settings` along with `members` and `joinCode`. Room args ride a room's **own**
+read — this SDK reads them off the v2 route it already calls — and only for members and game
+servers; a non-member's read does not carry them.
+
+## 5b. The template decides the seats, and a create that asks for its own is refused
+
+⚠️ **A create cannot set a seat count.** The room's size comes from the template it names, and a
+request carrying one is refused — `400 max_players_not_settable`, with the value echoed back. A room
+created without naming a template seats 8. `quickJoin` never offered the option: its request has no
+seat field, and a body that invents one is refused before it looks for a room to join.
+
+**`CreateRoomOptions.maxPlayers` is deprecated and is not sent.** Setting it logs a warning naming the
+replacement, and the field is stripped before the request leaves — so a call site that still sets it
+creates a room of the template's size rather than failing outright. Delete it when you see the warning.
+It stays on the type deliberately: removing it would stop a TypeScript caller compiling, but it would
+leave a JavaScript one passing a field that vanishes without a word, which is the failure this whole
+rule exists to remove. It keeps working for the rest of `3.x`, and `4.0.0` is the earliest release
+that may take it off the type — [the deprecation
+policy](deprecation-policy.md#2-the-rule-for-the-packages-api-surface).
+
+**To size a room, resize it after it exists** — `update({ maxPlayers })`, host-only, refused below the
+room's current member count, and bounded 2–64 whatever the template allows. The seat count you want
+every room to have belongs in the template instead, where it costs no extra round trip and no window
+in which the room is briefly the wrong size.
+
+**The SDK does not create-then-patch for you**, and the omission is the decision. Folding it into
+`create()` would put a workaround for another service's shape inside this one, where nobody looking
+for it would find it, and the room would still be briefly the wrong size — a visible hazard replaced
+by a hidden one. The platform refuses the field outright, for this reason: a
+developer meets the rule locally rather than as a 400 in production.
+
+## 6. Scope
+
+**In:** rooms, membership, host, ready state, the match lifecycle, and the dedicated-server connect
+flow reshaped around them. P2P _allocation_ falls out of the same shape — `startMatch` is one route
+and a P2P match simply reports `ready` at once.
+
+**Out:** matchmaking beyond the engine's find-or-create. `quickJoin()` is exactly `quick_join`: join
+an open public room matching the template, in a cluster this player can play well in, or create one.
+There is no ranked
+system, no skill rating and no queue, and inventing one is not a small addition to this.
+
+**Elsewhere:** P2P _connection_ and parties. Both are
+[`p2p-and-parties.md`](p2p-and-parties.md). Three things surface here:
+
+- **A member's group, not their party.** `RoomMember.groupId` says who arrived together, as an opaque
+  label that is stable for the life of this room and unrelated to the label the same people carry in
+  any other room. It is gem-api's, read off the wire; it replaced a pass-through of the real
+  `party_id`, which is account-level and cross-game and therefore a social-graph key rather than a
+  room fact. See §7.3 of that document.
+- **`partyId` is normally omitted on create, join and quick-join.** The manager resolves the local
+  player's party through the parent and attaches it when this player leads one, which is what
+  the platform's room manager does. Passing one explicitly still works and overrides that. This is the
+  one direction a party id still travels, and it is the caller naming a party to act on rather than
+  the platform exporting one.
+- **`leave()` takes the group out by default.** The room call that brought the party in has a
+  counterpart, and gem-api will not let a member of a party that is in the room leave alone — it
+  answers 409 `party_member_cannot_leave_game_room`. So `leave()` states the intent
+  (`leave_as_group`) and the server resolves which party that was from the membership row; a player
+  who arrived alone is unaffected either way. `leave({ asGroup: false })` asks for exactly the solo
+  path, and therefore for that 409 when a party is in the room.