@indiegems/gem-web-sdk 9.1.4 → 10.0.0

package/dist/sdk.d.ts

@@ -157,6 +157,11 @@ type AffixSelection = {
     "pool": AffixPoolRef;
     "respect_groups"?: boolean;
 };
+type BackfillPolicy = "fill_existing_first" | "prefer_new_match";
+type BackfillSettings = {
+    "enabled": boolean;
+    "policy"?: BackfillPolicy;
+};
 type Boundary = {
     "boundary"?: string;
     "reset_time"?: string;
@@ -230,11 +235,20 @@ type LevelDefinition = {
     "rewards"?: RecipeOperation[];
     "threshold": number;
 };
+type MatchmakingSettings = {
+    "backfill"?: null | BackfillSettings;
+    "cluster_stagger_seconds"?: number;
+    "enabled": boolean;
+    "fill_window_seconds"?: number;
+    "strategy"?: MatchmakingStrategy;
+    "ticket_expiry_seconds"?: number | null;
+};
+type MatchmakingStrategy = "fifo";
 type OrderBySpec = {
     "column": RunValueColumn;
     "direction": SortDirection;
 };
-type OrderSource$1 = "real_money_purchase" | "real_money_refund" | "full_game_purchase" | "full_game_refund" | "platform_purchase" | "reward" | "admin" | "system" | "promo" | "game_consume" | "play" | "recipe" | "transfer" | "platform_funded_game_inventory_purchase" | "earning_reset";
+type OrderSource$1 = "real_money_purchase" | "real_money_refund" | "full_game_purchase" | "full_game_refund" | "platform_purchase" | "reward" | "admin" | "system" | "promo" | "game_consume" | "play" | "recipe" | "transfer" | "platform_funded_game_inventory_purchase" | "earning_reset" | "test_account_provision" | "developer_grant";
 type OverflowBehavior$1 = "fail" | "clamp" | "allow";
 type PityEffect = "guarantee_tier" | {
     "weight_boost": {
@@ -452,6 +466,7 @@ type SnapshotGameRoomTemplate = {
     "id": string;
     "idle_timeout_seconds"?: number | null;
     "match_type": string;
+    "matchmaking"?: null | MatchmakingSettings;
     "max_match_duration_seconds"?: number | null;
     "max_players": number;
     "min_players": number;
@@ -523,6 +538,7 @@ type SnapshotProgression = {
     "display_name"?: string | null;
     "icon_url"?: string | null;
     "id": string;
+    "localized"?: Record<string, unknown>;
     "progression_type": string;
     "slug"?: string | null;
     "sort_order": number;
@@ -560,6 +576,7 @@ type SnapshotRewardedPlacement = {
     "grants": SnapshotRewardGrant[];
     "max_held"?: number | null;
     "max_per_day"?: number | null;
+    "min_watch_secs"?: number | null;
     "placement": string;
     "reward_class": string;
     "without_ads": string;
@@ -1524,26 +1541,6 @@ interface ClusterTarget {
     readonly id: string;
     readonly pressure: string;
 }
-type RoomArgScalar = string | number | boolean;
-type RoomArgValue$1 = RoomArgScalar | readonly RoomArgScalar[];
-type RoomArgs = Readonly<Record<string, RoomArgValue$1>>;
-type RoomArgType$1 = "string" | "int" | "float" | "bool" | (string & {});
-interface RoomArgEntry {
-    readonly name: string;
-    readonly type: RoomArgType$1;
-    readonly list: boolean;
-    readonly required: boolean;
-    readonly mutable: boolean;
-    readonly fixed?: RoomArgValue$1;
-    readonly default?: RoomArgValue$1;
-    readonly description?: string;
-    readonly allowed?: readonly RoomArgScalar[];
-    readonly min?: number;
-    readonly max?: number;
-    readonly minItems?: number;
-    readonly maxItems?: number;
-    readonly maxLength?: number;
-}
 type DedicatedServerFailure = "timeout" | "aborted" | "allocation_failed" | "no_server_ready" | "start_rate_limited" | "p2p_unavailable" | "unsupported_protocol" | "credential_expired" | "credential_reused" | "join_rate_limited" | "signaling_unavailable" | "signaling_failed" | "offer_refused" | "invalid_sdp" | "media_refused" | "connection_failed" | "join_refused" | "match_ended" | "misconfigured";
 declare class DedicatedServerError extends Error {
     readonly reason: DedicatedServerFailure;
@@ -1652,6 +1649,26 @@ interface TransportAdvert {
 declare function readTemplateTransports(value: unknown): readonly TransportKind[] | null;
 declare function readTransportAdvert(settings: unknown, forMatch?: string): TransportAdvert | null;
 declare function webTransportAvailable(): boolean;
+type RoomArgScalar = string | number | boolean;
+type RoomArgValue$1 = RoomArgScalar | readonly RoomArgScalar[];
+type RoomArgs = Readonly<Record<string, RoomArgValue$1>>;
+type RoomArgType$1 = "string" | "int" | "float" | "bool" | (string & {});
+interface RoomArgEntry {
+    readonly name: string;
+    readonly type: RoomArgType$1;
+    readonly list: boolean;
+    readonly required: boolean;
+    readonly mutable: boolean;
+    readonly fixed?: RoomArgValue$1;
+    readonly default?: RoomArgValue$1;
+    readonly description?: string;
+    readonly allowed?: readonly RoomArgScalar[];
+    readonly min?: number;
+    readonly max?: number;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly maxLength?: number;
+}
 type RoomStatus = "open" | "in_game" | "closed" | (string & {});
 type MatchConnectionState = "disconnected" | "connecting" | "connected" | "suspended";
 type MatchSessionPhase = "none" | "starting" | "ready" | "connected" | "suspended" | "ended" | (string & {});
@@ -1749,6 +1766,38 @@ interface RoomOperationError {
     readonly message: string;
     readonly retryable: boolean;
 }
+interface QueueForMatchOptions {
+    readonly templateSlugs: readonly string[];
+    readonly partyId?: string;
+    readonly signal?: AbortSignal;
+}
+type MatchTicketStatus = "queued" | "matched" | "expired" | "cancelled" | "failed" | "lost" | "unavailable";
+type MatchTicketOutcome = {
+    readonly status: "matched";
+    readonly room: Room;
+} | {
+    readonly status: "expired";
+    readonly reason: string;
+} | {
+    readonly status: "cancelled";
+    readonly reason: string;
+} | {
+    readonly status: "failed";
+    readonly reason: string;
+} | {
+    readonly status: "lost";
+} | {
+    readonly status: "unavailable";
+};
+interface MatchTicket {
+    readonly id: string;
+    readonly status: MatchTicketStatus;
+    readonly partySize: number;
+    readonly queuedAt: number;
+    readonly expiresAt: number;
+    readonly outcome: Promise<MatchTicketOutcome>;
+    cancel(): Promise<MatchTicketOutcome>;
+}
 interface CreateRoomOptions {
     readonly name: string;
     readonly maxPlayers?: number;
@@ -1891,6 +1940,7 @@ interface RoomManager {
     join(roomId: string, options?: JoinRoomOptions): Promise<Room>;
     joinByCode(code: string, options?: JoinRoomOptions): Promise<Room>;
     quickJoin(options: QuickJoinOptions): Promise<Room>;
+    queueForMatch(options: QueueForMatchOptions): Promise<MatchTicket>;
     list(options?: ListRoomsOptions): Promise<RoomPage>;
     myRooms(signal?: AbortSignal): Promise<readonly RoomSummary[]>;
     leave(options?: {
@@ -1916,6 +1966,7 @@ interface RoomManager {
     }): Promise<void>;
     readonly gameId: string | null;
     readonly currentRoom: Room | null;
+    readonly currentTicket: MatchTicket | null;
     readonly currentMatch: ReadyMatch | null;
     readonly matchConnectionState: MatchConnectionState;
     readonly matchSession: MatchSession;

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v9.1.4, 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` v10.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.
 
@@ -14668,6 +14668,58 @@ session — [RoomManager.leaveAll](#roommanager-leaveall) is what clears those.
 
 **Returns.** The room joined or created.
 
+<a id="roommanager-queueformatch"></a>
+
+## RoomManager.queueForMatch
+
+```ts
+queueForMatch(options: QueueForMatchOptions): Promise<MatchTicket>
+```
+
+Queue for a match with other players, and get a ticket to wait on.
+
+FOR A MODE THAT NEEDS A FULL LOBBY BEFORE IT STARTS. The platform holds the
+player in a queue until it has enough players for one of the templates you
+named, then makes the room, seats everyone and starts the match — nobody
+hosts and nobody presses start. For a drop-in mode, where a player should
+be in a room at once and others join around them, use
+[RoomManager.quickJoin](#roommanager-quickjoin) instead.
+
+This call answers as soon as the player is queued. What happens next is on
+the ticket: await [MatchTicket.outcome](#matchticket-outcome), and when it says `matched`
+this manager is already in the room — `joined` has fired and the match
+events follow as for any other room.
+
+A PLAYER MAY QUEUE FROM INSIDE A ROOM — a hub, or a social lobby they wait
+in. When the ticket is matched the manager moves to the match's room:
+`currentRoom` becomes it and `joined` fires. The seat in the room they
+queued from is kept on the platform, not given up, so when the match is
+over `join()` with that room's id puts them back in it. If the tab closes
+before they go back, the SDK leaves both rooms.
+
+What it does refuse is a second thing in flight: while a ticket waits,
+`create`, `join`, `joinByCode`, `quickJoin` and another `queueForMatch`
+refuse until it ends or is cancelled.
+
+CLOSING THE TAB CANCELS THE TICKET. The SDK sends the cancel as the page
+goes away, so a player who left is not matched into a lobby they will
+never arrive in.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `QueueForMatchOptions` | The templates the player accepts. |
+
+**Returns.** The ticket, still `queued` unless a lobby was waiting for exactly
+this player.
+
+**Throws.** `GemApiError` when the platform refuses the ticket. Two refusals
+are worth their own branch, by [GemApiError.code](#gemapierror-code):
+`already_queued` — this player, or someone in their party, is already
+on a ticket, possibly in another tab or another game — and
+`matchmaking_unavailable`, which means matchmaking is turned off or not
+answering. Tell the player; do not loop on it, and do not quietly
+substitute `quickJoin`, which puts them in a different kind of room.
+
 <a id="roommanager-list"></a>
 
 ## RoomManager.list
@@ -15002,6 +15054,20 @@ The room this player is in, or `null`. Kept fresh for you.
 Read it whenever you render the lobby rather than caching it — the manager
 updates it as players join, ready up and leave, and emits events as it does.
 
+<a id="roommanager-currentticket"></a>
+
+## RoomManager.currentTicket
+
+```ts
+readonly currentTicket: MatchTicket | null
+```
+
+The matchmaking ticket this player is waiting on, or `null`.
+
+Set from the moment [RoomManager.queueForMatch](#roommanager-queueformatch) answers until the
+ticket ends — so it is `null` again by the time a matched ticket's room is
+[RoomManager.currentRoom](#roommanager-currentroom).
+
 <a id="roommanager-currentmatch"></a>
 
 ## RoomManager.currentMatch
@@ -15212,6 +15278,220 @@ Stop polling and drop every listener.
 Call this when tearing your game down. It does not leave the room — use
 [RoomManager.leave](#roommanager-leave) or `gem.exit()` for that.
 
+<a id="queueformatchoptions"></a>
+
+## QueueForMatchOptions
+
+```ts
+interface QueueForMatchOptions
+```
+
+What you pass to `gem.rooms.queueForMatch(...)`.
+
+NAME EVERY MODE THE PLAYER WILL ACCEPT. The ticket waits for all of them at
+once and is matched under whichever fills first, so "any mode" is one ticket
+naming several templates rather than several tickets — a player can only be
+on one.
+
+```js
+const ticket = await gem.rooms.queueForMatch({ templateSlugs: ['duel', 'brawl'] });
+```
+
+**Guides.** [rooms-and-matches](../rooms-and-matches.md)
+
+<a id="queueformatchoptions-templateslugs"></a>
+
+## QueueForMatchOptions.templateSlugs
+
+```ts
+readonly templateSlugs: readonly string[]
+```
+
+The room templates this player accepts, by slug — one to eight of them.
+
+EVERY ONE MUST HAVE MATCHMAKING TURNED ON in your game config. A template
+without it refuses the whole ticket rather than being skipped, so a typo
+is an error you see and not a mode nobody is ever matched into.
+
+<a id="queueformatchoptions-partyid"></a>
+
+## QueueForMatchOptions.partyId
+
+```ts
+readonly partyId?: string
+```
+
+A party to queue as one unit. Normally omit it — the SDK brings the
+player's party along when they lead one, exactly as a room call does.
+
+A party is seated together or not at all. If it gains or loses a member
+while it waits, the ticket ends `cancelled` with reason `party_changed`.
+
+<a id="queueformatchoptions-signal"></a>
+
+## QueueForMatchOptions.signal
+
+```ts
+readonly signal?: AbortSignal
+```
+
+Cancel the request that creates the ticket.
+
+Only that request. Once you hold a ticket, [MatchTicket.cancel](#matchticket-cancel) is
+what takes the player out of the queue.
+
+<a id="matchticketstatus"></a>
+
+## MatchTicketStatus
+
+```ts
+type MatchTicketStatus = "queued" | "matched" | "expired" | "cancelled" | "failed" | "lost" | "unavailable"
+```
+
+Where a ticket is: `queued` while it waits, and anything else for good.
+
+- `matched` — the player is seated and the match is starting.
+- `expired` — it waited too long, or stopped being kept alive.
+- `cancelled` — the player backed out, or their party changed.
+- `failed` — the platform formed a match and could not start it, repeatedly.
+- `lost` — the platform no longer has the ticket. Queue again.
+- `unavailable` — matchmaking is turned off or not answering.
+
+<a id="matchticketoutcome"></a>
+
+## MatchTicketOutcome
+
+```ts
+type MatchTicketOutcome = { status: "matched"; room: Room } | { status: "expired"; reason: string } | { status: "cancelled"; reason: string } | { status: "failed"; reason: string } | { status: "lost" } | { status: "unavailable" }
+```
+
+How a ticket ended. Branch on `status`.
+
+ONLY `matched` CARRIES A ROOM, and by the time you see it the SDK is already
+in that room: `gem.rooms.currentRoom` is it, `joined` has fired, and the
+match events follow as they do for any other room.
+
+Every other ending leaves the player in no room and on no ticket, free to
+queue again. None of them is retried for you, and nothing falls back to
+`quickJoin` — a game that wants either does it on purpose.
+
+`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.
+
+<a id="matchticket"></a>
+
+## MatchTicket
+
+```ts
+interface MatchTicket
+```
+
+A place in the matchmaking queue — what `gem.rooms.queueForMatch(...)`
+answers with.
+
+You do not keep it alive; the SDK does, for as long as it waits. What you do
+with it is wait for [MatchTicket.outcome](#matchticket-outcome), and offer the player a
+button that calls [MatchTicket.cancel](#matchticket-cancel).
+
+```js
+const ticket = await gem.rooms.queueForMatch({ templateSlugs: ['duel'] });
+showSearching({ onCancel: () => ticket.cancel() });
+
+const outcome = await ticket.outcome;
+if (outcome.status === 'matched') enterMatch(outcome.room);
+else backToMenu(outcome.status);
+```
+
+**Guides.** [rooms-and-matches](../rooms-and-matches.md)
+
+<a id="matchticket-id"></a>
+
+## MatchTicket.id
+
+```ts
+readonly id: string
+```
+
+The ticket's id. For logs and bug reports; nothing you call takes it.
+
+<a id="matchticket-status"></a>
+
+## MatchTicket.status
+
+```ts
+readonly status: MatchTicketStatus
+```
+
+Where the ticket is right now. Changes once, from `queued` to how it ended.
+
+<a id="matchticket-partysize"></a>
+
+## MatchTicket.partySize
+
+```ts
+readonly partySize: number
+```
+
+How many players the ticket seats: 1, or the size of the party.
+
+<a id="matchticket-queuedat"></a>
+
+## MatchTicket.queuedAt
+
+```ts
+readonly queuedAt: number
+```
+
+When the ticket joined the queue, in Unix seconds.
+
+<a id="matchticket-expiresat"></a>
+
+## MatchTicket.expiresAt
+
+```ts
+readonly expiresAt: number
+```
+
+When the ticket gives up if it is still waiting, in Unix seconds. Good for
+a countdown; the platform decides the length, per template.
+
+<a id="matchticket-outcome"></a>
+
+## MatchTicket.outcome
+
+```ts
+readonly outcome: Promise<MatchTicketOutcome>
+```
+
+How the ticket ends. Settles exactly once, and RESOLVES for every ending
+the platform reports — matched, expired, cancelled and the rest are
+outcomes to branch on, not errors to catch.
+
+It rejects in one case only: the ticket was matched and the SDK could not
+read the room it was seated in. The player holds a seat then, so
+`gem.rooms.myRooms()` shows the room and `gem.rooms.join(id)` enters it.
+
+<a id="matchticket-cancel"></a>
+
+## MatchTicket.cancel
+
+```ts
+cancel(): Promise<MatchTicketOutcome>
+```
+
+Take the player — and their party — out of the queue.
+
+A CANCEL CAN LOSE THE RACE, and then the answer is `matched`. A ticket the
+platform has already seated is never undone, so read the outcome this
+returns rather than assuming: when it says `matched` the player is in a
+room, and backing out is `gem.rooms.leave()`.
+
+Safe to call more than once, and after the ticket has ended.
+
+**Returns.** The same promise as [MatchTicket.outcome](#matchticket-outcome).
+
 <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` v9.1.4, 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` v10.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.