@indiegems/gem-web-sdk 11.1.2 → 12.0.0

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v11.1.2, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v12.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -3832,8 +3832,10 @@ the callback instead.
 
 - `ready` — a usable token is held.
 - `pending` — no token yet, or one is being fetched.
-- `degraded` — the last attempt failed but another may succeed. Keep playing;
-  a retry is worthwhile.
+- `degraded` — the last attempt failed but another may succeed, and the SDK
+  makes it on its own: once any wait the platform named has passed, or
+  otherwise at growing intervals of up to a minute. Keep playing. `ready`
+  follows when an attempt succeeds, with no call of yours needed to cause it.
 - `lost` — terminal for this session. Signing back in is the only way
   forward, and retrying will not produce one.
 
@@ -15307,6 +15309,36 @@ room. A double fire — the push and the reconcile landing together, or the
 event arriving just as the player presses your own button — costs one
 redundant request and never a second seat.
 
+<a id="roomeventmap-partyqueued"></a>
+
+## RoomEventMap.partyQueued
+
+```ts
+partyQueued: [PartyTicket]
+```
+
+This player's party is queued for a match: its leader called
+`queueForMatch`, and this player is on that ticket.
+
+The ticket is a view — show a searching screen from it, and await its
+`outcome` to take the screen down. It has no `cancel()`: the ticket is
+the leader's.
+
+```js
+gem.rooms.on('partyQueued', async (ticket) => {
+  showSearching({ canCancel: false });
+  const outcome = await ticket.outcome;
+  if (outcome.status !== 'matched') backToMenu(outcome.status);
+});
+```
+
+When the outcome is `matched` the room arrives as `seated`, as it does
+for any seat this player's party was given.
+
+NOT RAISED FOR THE PLAYER WHO QUEUED — they hold the ticket itself — and
+not raised at all under an arcade page that does not relay ticket
+events. See [PartyTicket](#partyticket).
+
 <a id="roomeventmap-listed"></a>
 
 ## RoomEventMap.listed
@@ -16125,6 +16157,25 @@ Set from the moment [RoomManager.queueForMatch](#roommanager-queueformatch) answ
 ticket ends — so it is `null` again by the time a matched ticket's room is
 [RoomManager.currentRoom](#roommanager-currentroom).
 
+<a id="roommanager-partyticket"></a>
+
+## RoomManager.partyTicket
+
+```ts
+readonly partyTicket: PartyTicket | null
+```
+
+The matchmaking ticket this player's PARTY is waiting on, or `null` — a
+ticket this game did not create, which it can show and cannot cancel.
+
+Set when the arcade page reports that the party's leader queued, and
+`null` again once that ticket ends. Never set beside
+[RoomManager.currentTicket](#roommanager-currentticket): the player who queued holds that one.
+The `partyQueued` event is raised when this is set.
+
+Always `null` under a page that does not relay ticket events. See
+[PartyTicket](#partyticket).
+
 <a id="roommanager-currentmatch"></a>
 
 ## RoomManager.currentMatch
@@ -16549,6 +16600,143 @@ Safe to call more than once, and after the ticket has ended.
 
 **Returns.** The same promise as [MatchTicket.outcome](#matchticket-outcome).
 
+<a id="partyticketstatus"></a>
+
+## PartyTicketStatus
+
+```ts
+type PartyTicketStatus = "queued" | "matched" | "expired" | "cancelled" | "failed" | "lost"
+```
+
+Where a party's ticket is, as far as this player's game has been told:
+`queued` while it waits, and anything else for good.
+
+- `matched` — the party is seated and the match is starting. The room arrives
+  as a `seated` event.
+- `expired` — it waited too long, or its owner's game stopped keeping it alive.
+- `cancelled` — the leader backed out, or the party changed.
+- `failed` — the platform formed a match and could not start it, repeatedly.
+- `lost` — nothing more was heard about it by the time it must have ended.
+
+<a id="partyticketoutcome"></a>
+
+## PartyTicketOutcome
+
+```ts
+type PartyTicketOutcome = { status: "matched" } | { status: "expired"; reason: string } | { status: "cancelled"; reason: string } | { status: "failed"; reason: string } | { status: "lost" }
+```
+
+How a party's ticket ended. Branch on `status`.
+
+`matched` CARRIES NO ROOM. The room is reported the way a party's seat always
+is — the `seated` event — and that is where a game joins it. The SDK looks
+for the seat the moment it hears `matched`.
+
+`reason` says why, where the platform gave one: `timed_out` or
+`heartbeat_lapsed` for `expired`, `requested` or `party_changed` for
+`cancelled`, `handoff_failed` for `failed`. Treat a value you do not
+recognise as the status alone.
+
+`lost` is the SDK's own ending, not the platform's: the ticket's lifetime
+ran out and no ending was heard. Whatever happened, the party is not
+waiting any more.
+
+<a id="partyticket"></a>
+
+## PartyTicket
+
+```ts
+interface PartyTicket
+```
+
+The matchmaking ticket this player's party is waiting on — a ticket this
+game did not create. What `gem.rooms.partyTicket` holds, and what the
+`partyQueued` event hands you.
+
+READ-ONLY, ON PURPOSE. There is no `cancel()`: a party is one ticket and it
+is its leader's to cancel. A player who wants out leaves the party, which
+ends the ticket for everyone.
+
+```js
+gem.rooms.on('partyQueued', async (ticket) => {
+  showSearching({ canCancel: false });
+  const outcome = await ticket.outcome;
+  if (outcome.status !== 'matched') backToMenu(outcome.status);
+  // `matched`: your `seated` handler has the room.
+});
+```
+
+ONLY WHERE THE ARCADE PAGE RELAYS IT. Under a page that does not, there is
+no party ticket and no `partyQueued`, and a member is carried into the match
+by `seated` with no lead-up. Build the searching screen as an extra, never
+as a step the match depends on.
+
+**Guides.** [rooms-and-matches](../rooms-and-matches.md)
+
+<a id="partyticket-id"></a>
+
+## PartyTicket.id
+
+```ts
+readonly id: string
+```
+
+The ticket's id. For logs and bug reports; nothing you call takes it.
+
+<a id="partyticket-status"></a>
+
+## PartyTicket.status
+
+```ts
+readonly status: PartyTicketStatus
+```
+
+Where the ticket is, as far as this game has been told. Changes once, from
+`queued` to how it ended.
+
+<a id="partyticket-partysize"></a>
+
+## PartyTicket.partySize
+
+```ts
+readonly partySize: number
+```
+
+How many players the ticket seats: the size of the party. 0 when the page
+did not say.
+
+<a id="partyticket-queuedat"></a>
+
+## PartyTicket.queuedAt
+
+```ts
+readonly queuedAt: number
+```
+
+When the ticket joined the queue, in Unix seconds. 0 when the page did not
+say.
+
+<a id="partyticket-expiresat"></a>
+
+## PartyTicket.expiresAt
+
+```ts
+readonly expiresAt: number
+```
+
+When the ticket gives up if it is still waiting, in Unix seconds. Good for
+a countdown. 0 when the page did not say.
+
+<a id="partyticket-outcome"></a>
+
+## PartyTicket.outcome
+
+```ts
+readonly outcome: Promise<PartyTicketOutcome>
+```
+
+How the ticket ends. Settles exactly once and never rejects.
+
 <a id="roomstatus"></a>
 
 ## RoomStatus

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v11.1.2, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v12.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -766,8 +766,10 @@ the callback instead.
 
 - `ready` — a usable token is held.
 - `pending` — no token yet, or one is being fetched.
-- `degraded` — the last attempt failed but another may succeed. Keep playing;
-  a retry is worthwhile.
+- `degraded` — the last attempt failed but another may succeed, and the SDK
+  makes it on its own: once any wait the platform named has passed, or
+  otherwise at growing intervals of up to a minute. Keep playing. `ready`
+  follows when an attempt succeeds, with no call of yours needed to cause it.
 - `lost` — terminal for this session. Signing back in is the only way
   forward, and retrying will not produce one.