@indiegems/gem-web-sdk 9.1.4 → 10.1.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;
@@ -1973,6 +2024,13 @@ interface GemPrefs$1 {
     readonly muted: boolean;
     readonly showFrameStats?: boolean;
     readonly locale: string;
+    readonly recommended?: {
+        volume: number;
+        batterySaver: boolean;
+        keyboardLayout: "wasd" | "arrows";
+        gamepadConfirm: "south" | "east";
+        vibration: boolean;
+    };
 }
 interface GemCohorts$1 {
     readonly gem: typeof PROTOCOL;
@@ -4385,6 +4443,14 @@ interface GemPrefs {
     readonly muted: boolean;
     readonly showFrameStats: boolean;
     readonly locale: string;
+    readonly recommended: GemRecommendedSettings | null;
+}
+interface GemRecommendedSettings {
+    readonly volume: number;
+    readonly batterySaver: boolean;
+    readonly keyboardLayout: "wasd" | "arrows";
+    readonly gamepadConfirm: "south" | "east";
+    readonly vibration: boolean;
 }
 interface GemCohort {
     readonly experimentId: string;
@@ -4487,4 +4553,4 @@ interface ExitAnalytics {
 }
 declare function leaveAndExit(rooms: ExitRooms, bridge: ExitBridge | null, reason?: string, analytics?: ExitAnalytics): Promise<void>;
 declare function createGem(options?: GemOptions): Gem;
-export { ARCADE_EMBEDDERS, type AccountApi, type AdFormat, type AdOutcome, type AdOutcomeKind, type AdRequest, type AdsApi, AnalyticsApi, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection$1 as AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Base64String, type BootMark, type BootTimeline, type BroadcastOptions, type BytesResponse, CONDITIONAL_HEADERS, type Challenge, type ChallengeWindow, ChallengesApi, type ClientOptions, type Clock, type ConditionalRequestHeaders, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, DEVICE_SETTINGS_MAX_BYTES, DedicatedServerError, type DedicatedServerFailure, type DedicatedServerSession, type DevToolsOpener, type DeviceSettings, type DeviceSettingsApi, type DeviceSettingsPutOutcome, type DirectPurchaseRequest, type DirectPurchaseResult, type EarnAllowance, type EarnAllowanceEvent, type EarnAllowancePeriod, type EarnAllowanceReadOptions, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, type EntityType$1 as EntityType, type ExitAnalytics, type ExitBridge, type ExitRooms, type FrameState, type Friend, type FriendChallenge, FriendChallengeError, type FriendChallengeErrorCode, type FriendChallengeOutcome, type FriendChallengeOutcomeKind, type FriendChallengeRequest, type FriendChallengesPage, FriendsApi, type FriendsPage, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, FunctionsApi, type GameApi, type GameConfig, type GameMenu, type GameMenuItem, type GameServerLink, type Gem, GemApiError, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemDevTools, type GemErrorReason, GemFrame, GemFunctionError, type GemIdentity, type GemInsets, type GemMatchApi, type GemMatchServer, type GemMatchServerModule, type GemOptions, type GemPlayer, type GemPrefs, type GemReservedArea, GemSaveError, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type GemTerminationNotice, GemUnframedError, type GemViewport, type GetLeaderboardOptions, type HostTokenSource, type HostTokenSourceOptions, type JoinWelcome, type Leaderboard, type LeaderboardEntry, type LeaderboardPeriod, LeaderboardsApi, type ListChallengesOptions, type ListFriendChallengesOptions, type ListFriendsOptions, MAX_PERIODS_BACK, type MatchConnectOptions, type MatchConnection, type MatchHosting, type MatchHostingMode, type MatchServeOptions, type MatchTransport, type MessageMeta, type MultiTransportSession, PLATFORM_EVENTS, type PeriodOptions, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, PlatformEarnAllowanceApi, type PlatformEventName, type PlayerBadge$1 as PlayerBadge, type PlayerBoost, type PlayerBoostMultiplier, type PlayerIdentity, type PlayerProfile, PlayerText, type ProfileCallOptions, type ProfileShowcaseEntry$1 as ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, PurchaseRefusal, type PurchaseRefusalCode, type PurchaseRequest, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RecipeAvailability, type RecipeLock, type RequestOptions, type RewardCue, type RewardedStatus, type RoomArgValue, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerApi, type ServerBundleHost, type ServerTokenGrant, type SessionEndReason, type ShareApi, type ShareRequest, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SnapshotCurrency, type SnapshotItem, type TokenGrant, type Transport, type TransportAdvert, type TransportKind, TransportRefusal, type TransportRequest, type TransportResponse, UNRELIABLE_CHANNEL_LABEL, type VersionedGetOptions, type VersionedResponse, type VibrationApi, type WalletVisibleOptions, asPlayerText, createBootTimeline, createGem, createGemServer, createHostTokenSource, createMatchServer, defineServer, leaveAndExit, mapIdentity, markOnResolve, platformIconUrl, presentJoinCredential, readTemplateTransports, readTransportAdvert, reportOnResolve, systemClock, text, toBase64, webTransportAvailable };
+export { ARCADE_EMBEDDERS, type AccountApi, type AdFormat, type AdOutcome, type AdOutcomeKind, type AdRequest, type AdsApi, AnalyticsApi, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection$1 as AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Base64String, type BootMark, type BootTimeline, type BroadcastOptions, type BytesResponse, CONDITIONAL_HEADERS, type Challenge, type ChallengeWindow, ChallengesApi, type ClientOptions, type Clock, type ConditionalRequestHeaders, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, DEVICE_SETTINGS_MAX_BYTES, DedicatedServerError, type DedicatedServerFailure, type DedicatedServerSession, type DevToolsOpener, type DeviceSettings, type DeviceSettingsApi, type DeviceSettingsPutOutcome, type DirectPurchaseRequest, type DirectPurchaseResult, type EarnAllowance, type EarnAllowanceEvent, type EarnAllowancePeriod, type EarnAllowanceReadOptions, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, type EntityType$1 as EntityType, type ExitAnalytics, type ExitBridge, type ExitRooms, type FrameState, type Friend, type FriendChallenge, FriendChallengeError, type FriendChallengeErrorCode, type FriendChallengeOutcome, type FriendChallengeOutcomeKind, type FriendChallengeRequest, type FriendChallengesPage, FriendsApi, type FriendsPage, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, FunctionsApi, type GameApi, type GameConfig, type GameMenu, type GameMenuItem, type GameServerLink, type Gem, GemApiError, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemDevTools, type GemErrorReason, GemFrame, GemFunctionError, type GemIdentity, type GemInsets, type GemMatchApi, type GemMatchServer, type GemMatchServerModule, type GemOptions, type GemPlayer, type GemPrefs, type GemRecommendedSettings, type GemReservedArea, GemSaveError, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type GemTerminationNotice, GemUnframedError, type GemViewport, type GetLeaderboardOptions, type HostTokenSource, type HostTokenSourceOptions, type JoinWelcome, type Leaderboard, type LeaderboardEntry, type LeaderboardPeriod, LeaderboardsApi, type ListChallengesOptions, type ListFriendChallengesOptions, type ListFriendsOptions, MAX_PERIODS_BACK, type MatchConnectOptions, type MatchConnection, type MatchHosting, type MatchHostingMode, type MatchServeOptions, type MatchTransport, type MessageMeta, type MultiTransportSession, PLATFORM_EVENTS, type PeriodOptions, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, PlatformEarnAllowanceApi, type PlatformEventName, type PlayerBadge$1 as PlayerBadge, type PlayerBoost, type PlayerBoostMultiplier, type PlayerIdentity, type PlayerProfile, PlayerText, type ProfileCallOptions, type ProfileShowcaseEntry$1 as ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, PurchaseRefusal, type PurchaseRefusalCode, type PurchaseRequest, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RecipeAvailability, type RecipeLock, type RequestOptions, type RewardCue, type RewardedStatus, type RoomArgValue, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerApi, type ServerBundleHost, type ServerTokenGrant, type SessionEndReason, type ShareApi, type ShareRequest, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SnapshotCurrency, type SnapshotItem, type TokenGrant, type Transport, type TransportAdvert, type TransportKind, TransportRefusal, type TransportRequest, type TransportResponse, UNRELIABLE_CHANNEL_LABEL, type VersionedGetOptions, type VersionedResponse, type VibrationApi, type WalletVisibleOptions, asPlayerText, createBootTimeline, createGem, createGemServer, createHostTokenSource, createMatchServer, defineServer, leaveAndExit, mapIdentity, markOnResolve, platformIconUrl, presentJoinCredential, readTemplateTransports, readTransportAdvert, reportOnResolve, systemClock, text, toBase64, webTransportAvailable };

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.1.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.
 
@@ -6733,6 +6733,10 @@ checklist.
 here so the two agree, and see [Gem.reportMuted](#gem-reportmuted) for the other
 direction.
 
+**`recommended` changing is advice changing.** Apply it only to a setting
+the player has not chosen in your game; never overwrite their own choice
+with it.
+
 <a id="gemoptions-oncohorts"></a>
 
 ## GemOptions.onCohorts
@@ -7175,6 +7179,10 @@ not for your game — respecting them is part of what a game must do.
 They can change mid-session, so read them when you need them rather than
 caching at boot.
 
+`recommended` is the exception: the player's Arcade-wide defaults, which
+your game may start its own settings from or ignore — never a reason to
+overwrite a choice the player made in your game.
+
 **Guides.** [what-a-game-must-do](../what-a-game-must-do.md)
 
 <a id="gemprefs-reducedmotion"></a>
@@ -7227,6 +7235,100 @@ Use it to pick your game's language, and pass it to
 [text.compare](#text-compare) when sorting names — that call has no other way to
 learn a locale.
 
+<a id="gemprefs-recommended"></a>
+
+## GemPrefs.recommended
+
+```ts
+readonly recommended: GemRecommendedSettings | null
+```
+
+The player's Arcade-wide defaults for this device — a volume, battery
+saver, a keyboard layout, the gamepad's confirm button and vibration — or
+`null` when the Arcade did not send them.
+
+**Recommendations only; the player's own choice in your game wins.** Start
+a setting from here while the player has made no choice of their own for
+it, and never overwrite one they made because this changed:
+
+```js
+const saved = gem.deviceSettings.current ?? {};
+const volume = saved.volume ?? gem.prefs?.recommended?.volume ?? 100;
+```
+
+Unlike `muted` and `reducedMotion`, nothing here is applied for you, and
+nothing obliges you to use it. See the guide's "Game settings" section.
+
+<a id="gemrecommendedsettings"></a>
+
+## GemRecommendedSettings
+
+```ts
+interface GemRecommendedSettings
+```
+
+The player's Arcade-wide defaults for this device, as `gem.prefs.recommended`.
+
+The player sets these once in the Arcade's Settings, and every game that
+reads them starts in the right place. They are advice: a game may ignore
+them, and a choice the player made in your game always beats them.
+
+**Guides.** [what-a-game-must-do](../what-a-game-must-do.md)
+
+<a id="gemrecommendedsettings-volume"></a>
+
+## GemRecommendedSettings.volume
+
+```ts
+readonly volume: number
+```
+
+The volume the player wants, as a percentage from 0 to 100. A level, not a
+mute — `gem.prefs.muted` is the mute.
+
+<a id="gemrecommendedsettings-batterysaver"></a>
+
+## GemRecommendedSettings.batterySaver
+
+```ts
+readonly batterySaver: boolean
+```
+
+The player asked games to save power on this device: a lower frame rate,
+fewer effects, a lower resolution.
+
+<a id="gemrecommendedsettings-keyboardlayout"></a>
+
+## GemRecommendedSettings.keyboardLayout
+
+```ts
+readonly keyboardLayout: "wasd" | "arrows"
+```
+
+Which keys the player expects to move with: `'wasd'` or `'arrows'`.
+
+<a id="gemrecommendedsettings-gamepadconfirm"></a>
+
+## GemRecommendedSettings.gamepadConfirm
+
+```ts
+readonly gamepadConfirm: "south" | "east"
+```
+
+Which gamepad face button the player expects to confirm with, by position:
+`'south'` (the bottom button, A on an Xbox controller) or `'east'` (the
+right one, B on an Xbox controller). The other one goes back.
+
+<a id="gemrecommendedsettings-vibration"></a>
+
+## GemRecommendedSettings.vibration
+
+```ts
+readonly vibration: boolean
+```
+
+Whether the player wants vibration and controller rumble.
+
 <a id="gemcohort"></a>
 
 ## GemCohort
@@ -7536,8 +7638,10 @@ What your game adds to the arcade's menu — see `gem.setMenu`.
 readonly onSettings?: () => void
 ```
 
-Open your settings screen. Give this and the arcade's menu gains a
-Settings entry that calls it; leave it out and there is no such entry.
+Open your settings screen. Another embedder may show a Settings entry that
+calls it, but **the Gem Arcade no longer does**: draw a settings button of
+your own, always (top-right is the recommendation). Passing this is still
+accepted and harmless.
 
 <a id="gamemenu-items"></a>
 
@@ -8484,25 +8588,21 @@ for one: the arcade takes every figure from the platform. If this returns
 setMenu(menu: GameMenu): boolean
 ```
 
-Put your settings, and up to four entries of your own, in the arcade's
-menu. The arcade keeps one menu button over your game, in the top-right
-corner: it is how a player leaves, mutes, goes fullscreen and reports a
-problem — and, once you call this, how they open **your** settings.
+Put up to four entries of your own in the arcade's menu. The arcade keeps
+one menu button over your game: it is how a player leaves, mutes, goes
+fullscreen, reports a problem and changes their Arcade-wide settings.
 
 ```js
-const inArcadeMenu = gem.setMenu({
-  onSettings: () => settingsScreen.open(),
+gem.setMenu({
   items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],
 });
-ownSettingsButton.hidden = inArcadeMenu;
 ```
 
-**Do not draw a settings button of your own while this returns `true`** —
-the arcade's menu is the one place a player looks, in every game. Draw
-your own only when it returns `false` once the bridge has settled
-(`await gem.awaitBridge()`): an embedder with no menu, or no embedder at
-all. The top-left corner is yours, for a back or home button that moves
-around inside your game.
+**Your settings are not in it: draw your own settings button, always** —
+top-right is the recommendation. `onSettings` is still accepted, and
+another embedder may show an entry for it, but the Gem Arcade no longer
+shows a Settings entry, so a game whose settings open only from there has
+none a player can reach.
 
 **It is screen state, not a toggle.** Each call is the whole answer and
 replaces the last, so call it again when the entries change — a new
@@ -14668,6 +14768,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 +15154,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 +15378,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