@indiegems/gem-web-sdk 9.1.4 → 10.1.0

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.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/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "9.1.4"
+    "version": "10.1.0"
   },
   "entries": [
     {
@@ -7630,7 +7630,7 @@
           "group": "start",
           "signature": "readonly onPrefs?: (prefs: GemPrefs) => void",
           "documented": true,
-          "summary": "The player's accessibility and locale preferences arrived, or changed.\n\n**A game that animates owes this a handler.** Reduced motion is the\nplayer's own account setting, and honouring it is on the platform's release\nchecklist.\n\n**`muted` is honoured for you** — the SDK silences your audio itself (see\n`manageAudio`). If your game has its own mute control, set it from `muted`\nhere so the two agree, and see [Gem.reportMuted](api-reference-game.md#gem-reportmuted) for the other\ndirection.",
+          "summary": "The player's accessibility and locale preferences arrived, or changed.\n\n**A game that animates owes this a handler.** Reduced motion is the\nplayer's own account setting, and honouring it is on the platform's release\nchecklist.\n\n**`muted` is honoured for you** — the SDK silences your audio itself (see\n`manageAudio`). If your game has its own mute control, set it from `muted`\nhere so the two agree, and see [Gem.reportMuted](api-reference-game.md#gem-reportmuted) for the other\ndirection.\n\n**`recommended` changing is advice changing.** Apply it only to a setting\nthe player has not chosen in your game; never overwrite their own choice\nwith it.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8008,7 +8008,7 @@
           "group": "player",
           "signature": "interface GemPrefs",
           "documented": true,
-          "summary": "The player's arcade-level preferences, which your game is expected to honour.\n\nReached as `gem.prefs`. These are the player's settings for the whole arcade,\nnot for your game — respecting them is part of what a game must do.\n\nThey can change mid-session, so read them when you need them rather than\ncaching at boot.",
+          "summary": "The player's arcade-level preferences, which your game is expected to honour.\n\nReached as `gem.prefs`. These are the player's settings for the whole arcade,\nnot for your game — respecting them is part of what a game must do.\n\nThey can change mid-session, so read them when you need them rather than\ncaching at boot.\n\n`recommended` is the exception: the player's Arcade-wide defaults, which\nyour game may start its own settings from or ignore — never a reason to\noverwrite a choice the player made in your game.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8086,6 +8086,123 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemPrefs.recommended",
+          "name": "recommended",
+          "anchor": "gemprefs-recommended",
+          "group": "player",
+          "signature": "readonly recommended: GemRecommendedSettings | null",
+          "documented": true,
+          "summary": "The player's Arcade-wide defaults for this device — a volume, battery\nsaver, a keyboard layout, the gamepad's confirm button and vibration — or\n`null` when the Arcade did not send them.\n\n**Recommendations only; the player's own choice in your game wins.** Start\na setting from here while the player has made no choice of their own for\nit, and never overwrite one they made because this changed:\n\n```js\nconst saved = gem.deviceSettings.current ?? {};\nconst volume = saved.volume ?? gem.prefs?.recommended?.volume ?? 100;\n```\n\nUnlike `muted` and `reducedMotion`, nothing here is applied for you, and\nnothing obliges you to use it. See the guide's \"Game settings\" section.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings",
+          "name": "GemRecommendedSettings",
+          "anchor": "gemrecommendedsettings",
+          "group": "player",
+          "signature": "interface GemRecommendedSettings",
+          "documented": true,
+          "summary": "The player's Arcade-wide defaults for this device, as `gem.prefs.recommended`.\n\nThe player sets these once in the Arcade's Settings, and every game that\nreads them starts in the right place. They are advice: a game may ignore\nthem, and a choice the player made in your game always beats them.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "what-a-game-must-do",
+              "anchor": null
+            }
+          ]
+        },
+        {
+          "id": "GemRecommendedSettings.volume",
+          "name": "volume",
+          "anchor": "gemrecommendedsettings-volume",
+          "group": "player",
+          "signature": "readonly volume: number",
+          "documented": true,
+          "summary": "The volume the player wants, as a percentage from 0 to 100. A level, not a\nmute — `gem.prefs.muted` is the mute.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.batterySaver",
+          "name": "batterySaver",
+          "anchor": "gemrecommendedsettings-batterysaver",
+          "group": "player",
+          "signature": "readonly batterySaver: boolean",
+          "documented": true,
+          "summary": "The player asked games to save power on this device: a lower frame rate,\nfewer effects, a lower resolution.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.keyboardLayout",
+          "name": "keyboardLayout",
+          "anchor": "gemrecommendedsettings-keyboardlayout",
+          "group": "player",
+          "signature": "readonly keyboardLayout: \"wasd\" | \"arrows\"",
+          "documented": true,
+          "summary": "Which keys the player expects to move with: `'wasd'` or `'arrows'`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.gamepadConfirm",
+          "name": "gamepadConfirm",
+          "anchor": "gemrecommendedsettings-gamepadconfirm",
+          "group": "player",
+          "signature": "readonly gamepadConfirm: \"south\" | \"east\"",
+          "documented": true,
+          "summary": "Which gamepad face button the player expects to confirm with, by position:\n`'south'` (the bottom button, A on an Xbox controller) or `'east'` (the\nright one, B on an Xbox controller). The other one goes back.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.vibration",
+          "name": "vibration",
+          "anchor": "gemrecommendedsettings-vibration",
+          "group": "player",
+          "signature": "readonly vibration: boolean",
+          "documented": true,
+          "summary": "Whether the player wants vibration and controller rumble.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemCohort",
           "name": "GemCohort",
@@ -8487,7 +8604,7 @@
           "group": "frame",
           "signature": "readonly onSettings?: () => void",
           "documented": true,
-          "summary": "Open your settings screen. Give this and the arcade's menu gains a\nSettings entry that calls it; leave it out and there is no such entry.",
+          "summary": "Open your settings screen. Another embedder may show a Settings entry that\ncalls it, but **the Gem Arcade no longer does**: draw a settings button of\nyour own, always (top-right is the recommendation). Passing this is still\naccepted and harmless.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9271,7 +9388,7 @@
           "group": "start",
           "signature": "setMenu(menu: GameMenu): boolean",
           "documented": true,
-          "summary": "Put your settings, and up to four entries of your own, in the arcade's\nmenu. The arcade keeps one menu button over your game, in the top-right\ncorner: it is how a player leaves, mutes, goes fullscreen and reports a\nproblem — and, once you call this, how they open **your** settings.\n\n```js\nconst inArcadeMenu = gem.setMenu({\n  onSettings: () => settingsScreen.open(),\n  items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],\n});\nownSettingsButton.hidden = inArcadeMenu;\n```\n\n**Do not draw a settings button of your own while this returns `true`** —\nthe arcade's menu is the one place a player looks, in every game. Draw\nyour own only when it returns `false` once the bridge has settled\n(`await gem.awaitBridge()`): an embedder with no menu, or no embedder at\nall. The top-left corner is yours, for a back or home button that moves\naround inside your game.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last, so call it again when the entries change — a new\nlanguage, a screen with different options. `gem.setMenu({})` takes\neverything of yours back out. The arcade's own entries are not yours to\nchange, and Return to the Arcade is always among them.\n\n**The arcade pauses your game while its menu is open** (`onPause`), and\nresumes it before a handler of yours runs. A handler opens a screen; it\nshould not assume the game was paused by you.",
+          "summary": "Put up to four entries of your own in the arcade's menu. The arcade keeps\none menu button over your game: it is how a player leaves, mutes, goes\nfullscreen, reports a problem and changes their Arcade-wide settings.\n\n```js\ngem.setMenu({\n  items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],\n});\n```\n\n**Your settings are not in it: draw your own settings button, always** —\ntop-right is the recommendation. `onSettings` is still accepted, and\nanother embedder may show an entry for it, but the Gem Arcade no longer\nshows a Settings entry, so a game whose settings open only from there has\nnone a player can reach.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last, so call it again when the entries change — a new\nlanguage, a screen with different options. `gem.setMenu({})` takes\neverything of yours back out. The arcade's own entries are not yours to\nchange, and Return to the Arcade is always among them.\n\n**The arcade pauses your game while its menu is open** (`onPause`), and\nresumes it before a handler of yours runs. A handler opens a screen; it\nshould not assume the game was paused by you.",
           "deprecated": null,
           "params": [
             {
@@ -16350,6 +16467,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "RoomManager.queueForMatch",
+          "name": "queueForMatch",
+          "anchor": "roommanager-queueformatch",
+          "group": "rooms",
+          "signature": "queueForMatch(options: QueueForMatchOptions): Promise<MatchTicket>",
+          "documented": true,
+          "summary": "Queue for a match with other players, and get a ticket to wait on.\n\nFOR A MODE THAT NEEDS A FULL LOBBY BEFORE IT STARTS. The platform holds the\nplayer in a queue until it has enough players for one of the templates you\nnamed, then makes the room, seats everyone and starts the match — nobody\nhosts and nobody presses start. For a drop-in mode, where a player should\nbe in a room at once and others join around them, use\n[RoomManager.quickJoin](api-reference-game.md#roommanager-quickjoin) instead.\n\nThis call answers as soon as the player is queued. What happens next is on\nthe ticket: await [MatchTicket.outcome](api-reference-game.md#matchticket-outcome), and when it says `matched`\nthis manager is already in the room — `joined` has fired and the match\nevents follow as for any other room.\n\nA PLAYER MAY QUEUE FROM INSIDE A ROOM — a hub, or a social lobby they wait\nin. When the ticket is matched the manager moves to the match's room:\n`currentRoom` becomes it and `joined` fires. The seat in the room they\nqueued from is kept on the platform, not given up, so when the match is\nover `join()` with that room's id puts them back in it. If the tab closes\nbefore they go back, the SDK leaves both rooms.\n\nWhat it does refuse is a second thing in flight: while a ticket waits,\n`create`, `join`, `joinByCode`, `quickJoin` and another `queueForMatch`\nrefuse until it ends or is cancelled.\n\nCLOSING THE TAB CANCELS THE TICKET. The SDK sends the cancel as the page\ngoes away, so a player who left is not matched into a lobby they will\nnever arrive in.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "options",
+              "type": "QueueForMatchOptions",
+              "optional": false,
+              "summary": "The templates the player accepts."
+            }
+          ],
+          "returns": "The ticket, still `queued` unless a lobby was waiting for exactly\nthis player.",
+          "throws": "`GemApiError` when the platform refuses the ticket. Two refusals\nare worth their own branch, by [GemApiError.code](api-reference-game.md#gemapierror-code):\n`already_queued` — this player, or someone in their party, is already\non a ticket, possibly in another tab or another game — and\n`matchmaking_unavailable`, which means matchmaking is turned off or not\nanswering. Tell the player; do not loop on it, and do not quietly\nsubstitute `quickJoin`, which puts them in a different kind of room.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "RoomManager.list",
           "name": "list",
@@ -16790,6 +16930,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "RoomManager.currentTicket",
+          "name": "currentTicket",
+          "anchor": "roommanager-currentticket",
+          "group": "rooms",
+          "signature": "readonly currentTicket: MatchTicket | null",
+          "documented": true,
+          "summary": "The matchmaking ticket this player is waiting on, or `null`.\n\nSet from the moment [RoomManager.queueForMatch](api-reference-game.md#roommanager-queueformatch) answers until the\nticket ends — so it is `null` again by the time a matched ticket's room is\n[RoomManager.currentRoom](api-reference-game.md#roommanager-currentroom).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "RoomManager.currentMatch",
           "name": "currentMatch",
@@ -17083,6 +17239,240 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "QueueForMatchOptions",
+          "name": "QueueForMatchOptions",
+          "anchor": "queueformatchoptions",
+          "group": "rooms",
+          "signature": "interface QueueForMatchOptions",
+          "documented": true,
+          "summary": "What you pass to `gem.rooms.queueForMatch(...)`.\n\nNAME EVERY MODE THE PLAYER WILL ACCEPT. The ticket waits for all of them at\nonce and is matched under whichever fills first, so \"any mode\" is one ticket\nnaming several templates rather than several tickets — a player can only be\non one.\n\n```js\nconst ticket = await gem.rooms.queueForMatch({ templateSlugs: ['duel', 'brawl'] });\n```",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "rooms-and-matches",
+              "anchor": null
+            }
+          ]
+        },
+        {
+          "id": "QueueForMatchOptions.templateSlugs",
+          "name": "templateSlugs",
+          "anchor": "queueformatchoptions-templateslugs",
+          "group": "rooms",
+          "signature": "readonly templateSlugs: readonly string[]",
+          "documented": true,
+          "summary": "The room templates this player accepts, by slug — one to eight of them.\n\nEVERY ONE MUST HAVE MATCHMAKING TURNED ON in your game config. A template\nwithout it refuses the whole ticket rather than being skipped, so a typo\nis an error you see and not a mode nobody is ever matched into.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "QueueForMatchOptions.partyId",
+          "name": "partyId",
+          "anchor": "queueformatchoptions-partyid",
+          "group": "rooms",
+          "signature": "readonly partyId?: string",
+          "documented": true,
+          "summary": "A party to queue as one unit. Normally omit it — the SDK brings the\nplayer's party along when they lead one, exactly as a room call does.\n\nA party is seated together or not at all. If it gains or loses a member\nwhile it waits, the ticket ends `cancelled` with reason `party_changed`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "QueueForMatchOptions.signal",
+          "name": "signal",
+          "anchor": "queueformatchoptions-signal",
+          "group": "rooms",
+          "signature": "readonly signal?: AbortSignal",
+          "documented": true,
+          "summary": "Cancel the request that creates the ticket.\n\nOnly that request. Once you hold a ticket, [MatchTicket.cancel](api-reference-game.md#matchticket-cancel) is\nwhat takes the player out of the queue.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchTicketStatus",
+          "name": "MatchTicketStatus",
+          "anchor": "matchticketstatus",
+          "group": "rooms",
+          "signature": "type MatchTicketStatus = \"queued\" | \"matched\" | \"expired\" | \"cancelled\" | \"failed\" | \"lost\" | \"unavailable\"",
+          "documented": true,
+          "summary": "Where a ticket is: `queued` while it waits, and anything else for good.\n\n- `matched` — the player is seated and the match is starting.\n- `expired` — it waited too long, or stopped being kept alive.\n- `cancelled` — the player backed out, or their party changed.\n- `failed` — the platform formed a match and could not start it, repeatedly.\n- `lost` — the platform no longer has the ticket. Queue again.\n- `unavailable` — matchmaking is turned off or not answering.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchTicketOutcome",
+          "name": "MatchTicketOutcome",
+          "anchor": "matchticketoutcome",
+          "group": "rooms",
+          "signature": "type MatchTicketOutcome = { status: \"matched\"; room: Room } | { status: \"expired\"; reason: string } | { status: \"cancelled\"; reason: string } | { status: \"failed\"; reason: string } | { status: \"lost\" } | { status: \"unavailable\" }",
+          "documented": true,
+          "summary": "How a ticket ended. Branch on `status`.\n\nONLY `matched` CARRIES A ROOM, and by the time you see it the SDK is already\nin that room: `gem.rooms.currentRoom` is it, `joined` has fired, and the\nmatch events follow as they do for any other room.\n\nEvery other ending leaves the player in no room and on no ticket, free to\nqueue again. None of them is retried for you, and nothing falls back to\n`quickJoin` — a game that wants either does it on purpose.\n\n`reason` says why, where the platform gave one: `timed_out` or\n`heartbeat_lapsed` for `expired`, `requested` or `party_changed` for\n`cancelled`, `handoff_failed` for `failed`. Treat a value you do not\nrecognise as the status alone.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchTicket",
+          "name": "MatchTicket",
+          "anchor": "matchticket",
+          "group": "rooms",
+          "signature": "interface MatchTicket",
+          "documented": true,
+          "summary": "A place in the matchmaking queue — what `gem.rooms.queueForMatch(...)`\nanswers with.\n\nYou do not keep it alive; the SDK does, for as long as it waits. What you do\nwith it is wait for [MatchTicket.outcome](api-reference-game.md#matchticket-outcome), and offer the player a\nbutton that calls [MatchTicket.cancel](api-reference-game.md#matchticket-cancel).\n\n```js\nconst ticket = await gem.rooms.queueForMatch({ templateSlugs: ['duel'] });\nshowSearching({ onCancel: () => ticket.cancel() });\n\nconst outcome = await ticket.outcome;\nif (outcome.status === 'matched') enterMatch(outcome.room);\nelse backToMenu(outcome.status);\n```",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "rooms-and-matches",
+              "anchor": null
+            }
+          ]
+        },
+        {
+          "id": "MatchTicket.id",
+          "name": "id",
+          "anchor": "matchticket-id",
+          "group": "rooms",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "The ticket's id. For logs and bug reports; nothing you call takes it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchTicket.status",
+          "name": "status",
+          "anchor": "matchticket-status",
+          "group": "rooms",
+          "signature": "readonly status: MatchTicketStatus",
+          "documented": true,
+          "summary": "Where the ticket is right now. Changes once, from `queued` to how it ended.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchTicket.partySize",
+          "name": "partySize",
+          "anchor": "matchticket-partysize",
+          "group": "rooms",
+          "signature": "readonly partySize: number",
+          "documented": true,
+          "summary": "How many players the ticket seats: 1, or the size of the party.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchTicket.queuedAt",
+          "name": "queuedAt",
+          "anchor": "matchticket-queuedat",
+          "group": "rooms",
+          "signature": "readonly queuedAt: number",
+          "documented": true,
+          "summary": "When the ticket joined the queue, in Unix seconds.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchTicket.expiresAt",
+          "name": "expiresAt",
+          "anchor": "matchticket-expiresat",
+          "group": "rooms",
+          "signature": "readonly expiresAt: number",
+          "documented": true,
+          "summary": "When the ticket gives up if it is still waiting, in Unix seconds. Good for\na countdown; the platform decides the length, per template.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchTicket.outcome",
+          "name": "outcome",
+          "anchor": "matchticket-outcome",
+          "group": "rooms",
+          "signature": "readonly outcome: Promise<MatchTicketOutcome>",
+          "documented": true,
+          "summary": "How the ticket ends. Settles exactly once, and RESOLVES for every ending\nthe platform reports — matched, expired, cancelled and the rest are\noutcomes to branch on, not errors to catch.\n\nIt rejects in one case only: the ticket was matched and the SDK could not\nread the room it was seated in. The player holds a seat then, so\n`gem.rooms.myRooms()` shows the room and `gem.rooms.join(id)` enters it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchTicket.cancel",
+          "name": "cancel",
+          "anchor": "matchticket-cancel",
+          "group": "rooms",
+          "signature": "cancel(): Promise<MatchTicketOutcome>",
+          "documented": true,
+          "summary": "Take the player — and their party — out of the queue.\n\nA CANCEL CAN LOSE THE RACE, and then the answer is `matched`. A ticket the\nplatform has already seated is never undone, so read the outcome this\nreturns rather than assuming: when it says `matched` the player is in a\nroom, and backing out is `gem.rooms.leave()`.\n\nSafe to call more than once, and after the ticket has ended.",
+          "deprecated": null,
+          "params": [],
+          "returns": "The same promise as [MatchTicket.outcome](api-reference-game.md#matchticket-outcome).",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "RoomStatus",
           "name": "RoomStatus",

package/docs/changelog.md

@@ -16,6 +16,32 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 10.1.0
+
+Upgrading from 10.0.0. Impact: required.
+
+### Rebuild
+
+- The host-side method for sending preferences now accepts an optional recommended object with the five default settings. Existing calls remain valid, so recompiling is enough. Pass the new field only if your test host should simulate the Arcade's recommended defaults.
+
+### New capability
+
+- GemPrefs now carries an optional recommended field holding the player's Arcade-wide defaults as advice: volume from 0 to 100, battery saver, keyboard layout (wasd or arrows), gamepad confirm button (south or east) and vibration. It is null when the Arcade does not send it. Changes arrive through the existing preferences callback, and the latest value is always available on the current preferences. Use these values as starting points when the player has no saved choice in your game, and never overwrite a choice the player made in your own settings. Muted, reduced motion and frame stats stay where they were.
+- A new GemRecommendedSettings type describes the recommended defaults object. You can use it to type your own code that reads or stores the recommended values. The object is frozen, so copy values into your own settings rather than modifying it.
+
+## 10.0.0
+
+Upgrading from 9.1.4. Impact: required.
+
+### Rebuild
+
+- The OrderSource type now accepts two more values, test_account_provision and developer_grant. Recompile your game. If your code handles order sources in an exhaustive switch or a lookup table typed by OrderSource, add handling for both new values, or the build may fail to compile.
+
+### New capability
+
+- A game can now put a player in a matchmaking queue for a mode that needs a formed lobby. Call RoomManager.queueForMatch with the template slugs you want. It returns a MatchTicket whose outcome settles once and whose cancel method leaves the queue. When the platform finds a match it creates the room, seats everyone and starts the match, and you follow it with the same code you use for any joined room. Options are described by QueueForMatchOptions. Ticket endings are described by MatchTicketOutcome, and the waiting state by MatchTicketStatus. RoomManager.currentTicket exposes the ticket the player is waiting on. The SDK keeps the ticket alive by itself, cancels it when the tab closes, and lets a player queue from inside a room. After a match the player leaves the room they queued from when the tab closes.
+- The lower-level rooms API now has createTicket, heartbeatTicket and cancelTicket calls for working with matchmaking tickets directly. Most games should use RoomManager.queueForMatch, which sends the heartbeats and cancellation for you.
+
 ## 9.1.4
 
 Upgrading from 9.1.3. Impact: none.