@indiegems/gem-web-sdk 9.1.4 → 10.0.0

package/docs/rooms-and-matches.md

@@ -746,16 +746,140 @@ for it would find it, and the room would still be briefly the wrong size — a v
 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.
 
+## 5c. Queueing for a match: tickets
+
+`quickJoin()` puts a player in a room at once and lets the room fill around them. That is right for a
+drop-in mode and wrong for one that must not start short — a duel, a team mode — because the first
+player in sits alone in a lobby, and a match is sized by who is there when it starts.
+
+`queueForMatch()` is the other way in. The player waits in a queue; when the platform has enough
+players for one of the templates the ticket named, it makes the room, seats every one of them and
+starts the match. Nobody hosts, and nobody calls `startMatch()`.
+
+```js
+const ticket = await gem.rooms.queueForMatch({ templateSlugs: ['duel', 'brawl'] });
+showSearching({ expiresAt: ticket.expiresAt, onCancel: () => ticket.cancel() });
+
+const outcome = await ticket.outcome;
+if (outcome.status === 'matched') enterMatch(outcome.room);
+else backToMenu(outcome.status);
+```
+
+**A template has to opt in.** A room template is queueable when its `matchmaking` block says
+`enabled: true`; a ticket naming one that does not is refused whole, **400
+`matchmaking_not_enabled`**. `fill_window_seconds` in that block is how long a queue holds out for
+`max_players` before it accepts `min_players`. The block cannot be combined with `auto_start_host`.
+
+**A ticket names every mode the player accepts**, one to eight templates, and is matched under
+whichever fills first. That is one ticket, not several: a player can be on one ticket at a time, across
+every game.
+
+### What the SDK does while the ticket waits
+
+- **It keeps the ticket alive.** A ticket nobody heartbeats is expired by the platform, so that a
+  player who closed the tab does not hold a place in a lobby. The interval is the platform's setting
+  and arrives on the ticket; the SDK reads it from there and a game never sends a heartbeat.
+- **The heartbeat is also how it learns the answer.** Each one returns the ticket as it stands, so a
+  match is noticed within one interval even when nothing crosses the bridge.
+- **A relayed push makes it ask at once.** The match's own start is relayed like any room event (§3),
+  and one that arrives about a room the manager is not in, while a ticket waits, is treated as a cue:
+  the ticket is read immediately, and once more a second later if it still says `queued` — the
+  platform sends the push a moment before it marks the ticket. So on a page that relays, a match is
+  noticed in about the time the push takes, not at the next heartbeat. A tab returning to the
+  foreground is the same cue. Like every relay it is a hint: nothing is entered on its strength.
+- **It refuses a second thing in flight.** While a ticket waits, `create`, `join`, `joinByCode`,
+  `quickJoin` and another `queueForMatch` are refused locally.
+- **It cancels the ticket when the tab closes.** See below.
+- **It raises no `seated` for the ticket's own room.** The owner is told by the outcome. Party
+  members, who hold no ticket, are told by `seated` as they are for any room their leader enters.
+
+### Queueing from inside a room
+
+A player sitting in a hub or a social lobby can queue without leaving it. The ticket takes no seat
+while it waits, and `gem.rooms.currentRoom` stays the room they are in.
+
+When the ticket is matched, **the manager moves and the seat stays**. `currentRoom` becomes the
+match's room and `joined` fires for it. The room the player queued from is not left: no leave is
+sent, no `left` is raised, and the platform still counts them as a member there. When the match is
+over, `gem.rooms.leave()` then `gem.rooms.join(hub.id)` puts them back — `join()` on a room a player
+already holds a seat in answers with the room.
+
+Keep the hub's id if you want that return trip: `currentRoom` is the match's room now, and the
+manager does not hand the old one back.
+
+**A tab closed before the player goes back leaves both rooms.** The SDK remembers the room a matched
+ticket moved it out of, and on `pagehide` sends a keepalive leave for it as well as for the room it
+is in. Otherwise the hub seat would outlive the page with nothing tracking it, and the player's next
+session would start already inside a room. Once the player is back in the hub, it is the tracked
+room again and the ordinary leave covers it.
+
+### When the tab closes
+
+**The ticket is cancelled as the page goes away.** On `pagehide` the SDK sends the cancel as a
+keepalive request, which the browser delivers after the document is gone, and settles the ticket
+`cancelled`. Without it a closed tab's ticket would stay matchable until the platform noticed nobody
+was keeping it alive, and a match formed in that window seats a player who is not there.
+
+This also happens when the page is put in the back/forward cache. A frozen page keeps nothing alive,
+so the player cannot come back to the same ticket; they come back to one that reads `cancelled` and
+queue again.
+
+The platform's own timeout is still there for a tab that crashed or lost its network, where no
+request can be sent. It is the fallback, not the mechanism.
+
+### How a ticket ends
+
+`ticket.outcome` settles once, and **resolves** for every ending the platform reports — these are
+outcomes to branch on, not errors to catch:
+
+| `status` | `reason` | What happened | Queue again? |
+| --- | --- | --- | --- |
+| `matched` | — | Seated, and the match is starting. `gem.rooms.currentRoom` is `outcome.room`, `joined` has fired, and the match events follow as for any room. | — |
+| `expired` | `timed_out` | Nobody to play with before the ticket's expiry. | on a fresh press |
+| `expired` | `heartbeat_lapsed` | The tab was throttled or offline too long to keep it alive. | on a fresh press |
+| `cancelled` | `requested` | `ticket.cancel()`. | — |
+| `cancelled` | `party_changed` | The party gained or lost a member while it waited. | once the party is settled |
+| `failed` | `handoff_failed` | A match formed and could not be started, several times over. | later; this is the platform's fault |
+| `lost` | — | The platform no longer has the ticket. Queues are held in memory and a restart loses them. | yes |
+| `unavailable` | — | Matchmaking is turned off, or stopped answering for longer than a ticket survives. | not in a loop |
+
+`lost` and `unavailable` are the SDK's own conclusions. A heartbeat answered "no such ticket" ends
+the wait as `lost` at once. Three heartbeats in a row that got no usable answer end it too — as
+`unavailable` when the platform said matchmaking is off, `lost` otherwise — and the SDK sends one
+cancel on its way out, in case the requests arrived and only the answers were lost.
+
+It **rejects** in one case: the ticket was matched and the room it was seated in could not be read. The
+seat stands, so `myRooms()` shows the room and `join(id)` enters it.
+
+**`cancel()` can lose the race.** A ticket the platform has already seated is never undone, so
+`cancel()` resolves the ticket's real outcome, and that may be `matched`. Backing out from there is
+`gem.rooms.leave()`.
+
+### The refusals when queueing
+
+`queueForMatch()` itself rejects with `GemApiError` when no ticket was made. Branch on `code`:
+
+| Code | Meaning |
+| --- | --- |
+| `already_queued` (409) | This player, or someone in their party, is already on a ticket — another tab, or another game. |
+| `matchmaking_not_enabled` (400) | A named template has no enabled `matchmaking` block. A config fault, not a player one. |
+| `matchmaking_unavailable` (503) | Matchmaking is turned off for the whole platform, or its store is not answering. |
+
+⚠️ **Nothing falls back to quick-join, and a game should not either.** Not on
+`matchmaking_unavailable`, not on `expired`. Quick-join puts the player in a different kind of room —
+alone, in a mode that was queued for precisely because it needs a lobby. Tell the player matchmaking is
+unavailable and leave the button where it is.
+
 ## 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.
+**Out:** matching by anything but arrival order. `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.
+`queueForMatch()` (§5c) waits for a full lobby, oldest ticket first. There is no ranked system and no
+skill rating, 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:

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v9.1.4/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v9.1.4/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v10.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v10.0.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "9.1.4",
+  "version": "10.0.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",