@indiegems/gem-web-sdk 10.1.1 → 10.2.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "10.1.1"
+    "version": "10.2.0"
   },
   "entries": [
     {
@@ -6034,6 +6034,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemFrame.requestAvatarPicker",
+          "name": "requestAvatarPicker",
+          "anchor": "gemframe-requestavatarpicker",
+          "group": "frame",
+          "signature": "requestAvatarPicker(): boolean",
+          "documented": true,
+          "summary": "Ask the arcade to open its own avatar picker over your game. Nothing comes\nback: a changed portrait arrives as a new `gem.player`, through `onPlayer`.\n\nPrefer `gem.openAvatarPicker`, which documents what a game does with the\nchange.",
+          "deprecated": null,
+          "params": [],
+          "returns": "whether the message left the frame — `false` before the bridge is\n  up, for an arcade that has no avatar picker here, and past this frame's\n  own limit of six a minute.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemFrame.requestVibrate",
           "name": "requestVibrate",
@@ -6190,7 +6206,7 @@
           "group": "friends",
           "signature": "readonly avatarIconId?: string",
           "documented": true,
-          "summary": "The id of the player's portrait item, when they have one.",
+          "summary": "The id of the player's portrait item, when they have one — what a game\nthat draws Arcade avatars keys its own model on. On `gem.player` it\nchanges when the player wears another portrait, and `onPlayer` runs again;\nsee `gem.openAvatarPicker`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -7960,7 +7976,7 @@
           "group": "player",
           "signature": "readonly avatarIconId?: string",
           "documented": true,
-          "summary": "The id of the player's portrait item, when they have one.",
+          "summary": "The id of the player's portrait item, when they have one — what a game\nthat draws Arcade avatars keys its own model on. On `gem.player` it\nchanges when the player wears another portrait, and `onPlayer` runs again;\nsee `gem.openAvatarPicker`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9030,6 +9046,38 @@
             }
           ]
         },
+        {
+          "id": "Gem.avatarPickerAvailable",
+          "name": "avatarPickerAvailable",
+          "anchor": "gem-avatarpickeravailable",
+          "group": "start",
+          "signature": "readonly avatarPickerAvailable: boolean",
+          "documented": true,
+          "summary": "Whether the arcade will open its avatar picker for [Gem.openAvatarPicker](api-reference-game.md#gem-openavatarpicker)\nhere. Decide from it whether to show your own \"Change avatar\" button, and\nread it again in the click handler — it is read live.\n\n`false` outside the arcade, before the bridge is up, after the session\nends, and under an embedder that has no avatar picker.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Gem.openAvatarPicker",
+          "name": "openAvatarPicker",
+          "anchor": "gem-openavatarpicker",
+          "group": "start",
+          "signature": "openAvatarPicker(): boolean",
+          "documented": true,
+          "summary": "Open the arcade's avatar picker over your game, so the player can change\nthe Arcade avatar they wear without leaving it. For a game that draws\nArcade avatars — whole characters the player owns as Arcade items — put a\n\"Change avatar\" button in your own UI and call this from it:\n\n```js\nchangeAvatar.hidden = !gem.avatarPickerAvailable;\nchangeAvatar.onclick = () => {\n  if (!gem.openAvatarPicker()) changeAvatar.hidden = true;\n};\n```\n\n**The change arrives as a new player, not as an answer.** Nothing comes\nback from this call. When the player picks a different avatar, the arcade\npauses your game while the picker is open, then sends the player again —\nyour `onPlayer` callback runs and [Gem.player](api-reference-game.md#gem-player) holds the new\n[PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) — and resumes it. Redraw from\n`onPlayer`, which also runs when the player changes their avatar from the\narcade's own menu without your game asking. A player who closes the picker\nunchanged produces nothing at all.\n\n**Your server learns it only when it reads the room again.** A\nserver-authoritative game reads each member's `avatar_icon_id` from the\nroom read (`GET /v1/games/{game_id}/game-rooms/{game_room_id}`, or\n`gem.room.get()` on a dedicated server); nothing tells the server the\nplayer changed. So when `onPlayer` brings a different `avatarIconId`, have\nyour client tell your server, and have the server re-read the room — never\ntrust the id the client sends.",
+          "deprecated": null,
+          "params": [],
+          "returns": "`true` when the arcade was asked; `false` when it was not and\n  never will be for this call — outside the arcade, before the bridge is\n  up, under an embedder with no avatar picker, or past six asks a minute.\n  It never throws and never waits.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.vibration",
           "name": "vibration",
@@ -10625,7 +10673,7 @@
           "group": "player",
           "signature": "readonly avatarIconId?: string",
           "documented": true,
-          "summary": "The id of the player's portrait item, when they have one.",
+          "summary": "The id of the player's portrait item, when they have one — what a game\nthat draws Arcade avatars keys its own model on. On `gem.player` it\nchanges when the player wears another portrait, and `onPlayer` runs again;\nsee `gem.openAvatarPicker`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -13397,7 +13445,7 @@
           "group": "leaderboards",
           "signature": "readonly avatarIconId?: string",
           "documented": true,
-          "summary": "The id of the player's portrait item, when they have one.",
+          "summary": "The id of the player's portrait item, when they have one — what a game\nthat draws Arcade avatars keys its own model on. On `gem.player` it\nchanges when the player wears another portrait, and `onPlayer` runs again;\nsee `gem.openAvatarPicker`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -15160,7 +15208,7 @@
           "group": "profiles",
           "signature": "readonly avatarIconId?: string",
           "documented": true,
-          "summary": "The id of the player's portrait item, when they have one.",
+          "summary": "The id of the player's portrait item, when they have one — what a game\nthat draws Arcade avatars keys its own model on. On `gem.player` it\nchanges when the player wears another portrait, and `onPlayer` runs again;\nsee `gem.openAvatarPicker`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -17976,7 +18024,7 @@
           "group": "rooms",
           "signature": "readonly avatarIconId?: string",
           "documented": true,
-          "summary": "The id of the player's portrait item, when they have one.",
+          "summary": "The id of the player's portrait item, when they have one — what a game\nthat draws Arcade avatars keys its own model on. On `gem.player` it\nchanges when the player wears another portrait, and `onPlayer` runs again;\nsee `gem.openAvatarPicker`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -19058,7 +19106,7 @@
           "group": "showcase",
           "signature": "readonly avatarIconId?: string",
           "documented": true,
-          "summary": "The id of the player's portrait item, when they have one.",
+          "summary": "The id of the player's portrait item, when they have one — what a game\nthat draws Arcade avatars keys its own model on. On `gem.player` it\nchanges when the player wears another portrait, and `onPlayer` runs again;\nsee `gem.openAvatarPicker`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -21744,6 +21792,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "MatchBackfillState",
+          "name": "MatchBackfillState",
+          "anchor": "matchbackfillstate",
+          "group": "match",
+          "signature": "interface MatchBackfillState",
+          "documented": true,
+          "summary": "Whether this match is being topped up from the matchmaking queue, as the\nplatform now has it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchPlayerReport",
+          "name": "MatchPlayerReport",
+          "anchor": "matchplayerreport",
+          "group": "match",
+          "signature": "interface MatchPlayerReport",
+          "documented": true,
+          "summary": "What your server says about one player of its match, for\n[GemServer.match](api-reference-server.md#gemserver-match)'s `reportPlayers`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchPlayerReportResult",
+          "name": "MatchPlayerReportResult",
+          "anchor": "matchplayerreportresult",
+          "group": "match",
+          "signature": "interface MatchPlayerReportResult",
+          "documented": true,
+          "summary": "What a report did for one player, in the order you reported them.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemServerOptions",
           "name": "GemServerOptions",
@@ -22535,6 +22631,102 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "MatchPlayerReport.playerId",
+          "name": "playerId",
+          "anchor": "matchplayerreport-playerid",
+          "group": "match",
+          "signature": "readonly playerId: string",
+          "documented": true,
+          "summary": "The player. Take it from `join()`, `leave()` or the room, never from a client.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchPlayerReport.state",
+          "name": "state",
+          "anchor": "matchplayerreport-state",
+          "group": "match",
+          "signature": "readonly state: \"connected\" | \"no_show\" | \"left\"",
+          "documented": true,
+          "summary": "- `connected` — the player has connected to this server.\n- `no_show` — the player was given a seat and never connected.\n- `left` — the player was in the match and is gone FOR GOOD.\n\nThe last two remove the player from the room, which frees the seat.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchPlayerReportResult.playerId",
+          "name": "playerId",
+          "anchor": "matchplayerreportresult-playerid",
+          "group": "match",
+          "signature": "readonly playerId: string",
+          "documented": true,
+          "summary": "The player this result is for.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchPlayerReportResult.outcome",
+          "name": "outcome",
+          "anchor": "matchplayerreportresult-outcome",
+          "group": "match",
+          "signature": "readonly outcome: \"recorded\" | \"removed\" | \"not_a_member\" | string & object",
+          "documented": true,
+          "summary": "- `recorded` — `connected` was noted.\n- `removed` — the player was taken out of the room.\n- `not_a_member` — the player is not in this match's room; nothing changed.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchBackfillState.open",
+          "name": "open",
+          "anchor": "matchbackfillstate-open",
+          "group": "match",
+          "signature": "readonly open: boolean",
+          "documented": true,
+          "summary": "Whether the match is taking players from the queue.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "MatchBackfillState.seats",
+          "name": "seats",
+          "anchor": "matchbackfillstate-seats",
+          "group": "match",
+          "signature": "readonly seats: number | null",
+          "documented": true,
+          "summary": "The most players still wanted, or `null` for every open seat.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemServer.identity",
           "name": "identity",
@@ -22588,7 +22780,7 @@
           "name": "match",
           "anchor": "gemserver-match",
           "group": "api",
-          "signature": "readonly match: { end: null }",
+          "signature": "readonly match: { end: null; setBackfill: null; reportPlayers: null }",
           "documented": true,
           "summary": "Ending the match.\n\n`end()` is HOW A SERVER-AUTHORITATIVE GAME FINISHES. It tells the platform\nthe match is over; the platform then tells the runtime, and your server\nwinds down through its ordinary shutdown. You do not stop the process\nyourself.\n\nIt always means THIS match — the id is already known, so there is nothing to\npass and no way to end someone else's.\n\nThe platform half makes the request, not your process: it holds the proof\nthat this server is the one allocated to the match, which the platform\nrequires. On a platform image too old to offer that, `end()` throws rather\nthan sending a request without the proof.",
           "deprecated": null,
@@ -22622,6 +22814,64 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemServer.match.setBackfill",
+          "name": "setBackfill",
+          "anchor": "gemserver-match-setbackfill",
+          "group": "api",
+          "signature": "setBackfill(options: { open: boolean; seats?: number }, signal?: AbortSignal): Promise<MatchBackfillState>",
+          "documented": true,
+          "summary": "Stop, or restart, the platform topping this match up from the\nmatchmaking queue.\n\nA match the platform matchmade from a room type with backfill turned on\ntakes waiting players into its open seats from the moment it starts.\nThis is how your server takes control of that: close it once joining\nlate no longer makes sense — the last round, a boss fight — and open it\nagain if it does.\n\nClosing removes nobody, and a player already on the way in still\narrives. The setting lasts for the match.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "options",
+              "type": "{ open: boolean; seats?: number }",
+              "optional": false,
+              "summary": "`open` — whether to take players. `seats` — with\n  `open: true`, the most players still wanted; it counts down as seats\n  fill. Omit it for every open seat."
+            },
+            {
+              "name": "signal",
+              "type": "AbortSignal",
+              "optional": true,
+              "summary": "Cancels the request."
+            }
+          ],
+          "returns": null,
+          "throws": "A `GemApiError` with code `backfill_not_enabled` when this match\n  is not one the platform tops up: its room type has no backfill, or the\n  room was not matchmade.",
+          "example": "```js\n// Nobody new once the final round starts.\nawait gem.match.setBackfill({ open: false });\n```",
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemServer.match.reportPlayers",
+          "name": "reportPlayers",
+          "anchor": "gemserver-match-reportplayers",
+          "group": "api",
+          "signature": "reportPlayers(reports: readonly MatchPlayerReport[], signal?: AbortSignal): Promise<MatchPlayerReportResult[]>",
+          "documented": true,
+          "summary": "Tell the platform which players have connected, never arrived, or left.\n\n`no_show` and `left` REMOVE THE PLAYER FROM THE ROOM, which frees the\nseat — for the queue, when the match is being topped up. Report `left`\nonly for a player who is gone for good: reconnecting does not put a\nremoved player back, they have to join again.\n\nYOU DO NOT REPORT `connected` YOURSELF in a bundle built with\n[defineServer](api-reference-server.md#defineserver): it reports each player as they join. That report is\nwhat gives a seat the platform filled from the queue a time limit — a\nplayer who is seated and never connects is removed, and the seat goes to\nthe next one waiting.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "reports",
+              "type": "readonly MatchPlayerReport[]",
+              "optional": false,
+              "summary": "1 to 32 players."
+            },
+            {
+              "name": "signal",
+              "type": "AbortSignal",
+              "optional": true,
+              "summary": "Cancels the request."
+            }
+          ],
+          "returns": "One result per report, in the same order.",
+          "throws": null,
+          "example": "```js\nleave(playerId) {\n  // This game does not let a player back in once they quit.\n  void gem.match.reportPlayers([{ playerId, state: 'left' }]);\n}\n```",
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemServer.analytics",
           "name": "analytics",
@@ -23340,7 +23590,7 @@
           "name": "endMatch",
           "anchor": "gemserverhost-endmatch",
           "group": "host",
-          "signature": "endMatch(): Promise<\"ok\" | \"already_ended\" | \"refused\" | \"failed\" | string & object>",
+          "signature": "endMatch(): Promise<string & object | \"ok\" | \"already_ended\" | \"refused\" | \"failed\">",
           "documented": true,
           "summary": "Ask the platform half to end this match, with the allocation's own proof.\n\nMAY BE ABSENT on older platform images. `gem.match.end()` is this call —\nthe request carries the allocation nonce, which never enters the bundle\nprocess — and refuses on an image that does not offer it. You rarely call\nthis yourself.\n\nResolves with what the platform half did: `ok`, `already_ended` (this\nmatch was already over, or you asked twice), `refused` (the allocation was\nnot ready yet) or `failed` (the platform could not be reached).",
           "deprecated": null,
@@ -23930,7 +24180,7 @@
           "name": "match",
           "anchor": "gemmatchserver-match",
           "group": "start",
-          "signature": "readonly match: { end: null }",
+          "signature": "readonly match: { end: null; setBackfill: null; reportPlayers: null }",
           "documented": true,
           "summary": "Ending the match.\n\n`end()` is HOW A SERVER-AUTHORITATIVE GAME FINISHES. It tells the platform\nthe match is over; the platform then tells the runtime, and your server\nwinds down through its ordinary shutdown. You do not stop the process\nyourself.\n\nIt always means THIS match — the id is already known, so there is nothing to\npass and no way to end someone else's.\n\nThe platform half makes the request, not your process: it holds the proof\nthat this server is the one allocated to the match, which the platform\nrequires. On a platform image too old to offer that, `end()` throws rather\nthan sending a request without the proof.",
           "deprecated": null,
@@ -23964,6 +24214,64 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemMatchServer.match.setBackfill",
+          "name": "setBackfill",
+          "anchor": "gemmatchserver-match-setbackfill",
+          "group": "start",
+          "signature": "setBackfill(options: { open: boolean; seats?: number }, signal?: AbortSignal): Promise<MatchBackfillState>",
+          "documented": true,
+          "summary": "Stop, or restart, the platform topping this match up from the\nmatchmaking queue.\n\nA match the platform matchmade from a room type with backfill turned on\ntakes waiting players into its open seats from the moment it starts.\nThis is how your server takes control of that: close it once joining\nlate no longer makes sense — the last round, a boss fight — and open it\nagain if it does.\n\nClosing removes nobody, and a player already on the way in still\narrives. The setting lasts for the match.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "options",
+              "type": "{ open: boolean; seats?: number }",
+              "optional": false,
+              "summary": "`open` — whether to take players. `seats` — with\n  `open: true`, the most players still wanted; it counts down as seats\n  fill. Omit it for every open seat."
+            },
+            {
+              "name": "signal",
+              "type": "AbortSignal",
+              "optional": true,
+              "summary": "Cancels the request."
+            }
+          ],
+          "returns": null,
+          "throws": "A `GemApiError` with code `backfill_not_enabled` when this match\n  is not one the platform tops up: its room type has no backfill, or the\n  room was not matchmade.",
+          "example": "```js\n// Nobody new once the final round starts.\nawait gem.match.setBackfill({ open: false });\n```",
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemMatchServer.match.reportPlayers",
+          "name": "reportPlayers",
+          "anchor": "gemmatchserver-match-reportplayers",
+          "group": "start",
+          "signature": "reportPlayers(reports: readonly MatchPlayerReport[], signal?: AbortSignal): Promise<MatchPlayerReportResult[]>",
+          "documented": true,
+          "summary": "Tell the platform which players have connected, never arrived, or left.\n\n`no_show` and `left` REMOVE THE PLAYER FROM THE ROOM, which frees the\nseat — for the queue, when the match is being topped up. Report `left`\nonly for a player who is gone for good: reconnecting does not put a\nremoved player back, they have to join again.\n\nYOU DO NOT REPORT `connected` YOURSELF in a bundle built with\n[defineServer](api-reference-server.md#defineserver): it reports each player as they join. That report is\nwhat gives a seat the platform filled from the queue a time limit — a\nplayer who is seated and never connects is removed, and the seat goes to\nthe next one waiting.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "reports",
+              "type": "readonly MatchPlayerReport[]",
+              "optional": false,
+              "summary": "1 to 32 players."
+            },
+            {
+              "name": "signal",
+              "type": "AbortSignal",
+              "optional": true,
+              "summary": "Cancels the request."
+            }
+          ],
+          "returns": "One result per report, in the same order.",
+          "throws": null,
+          "example": "```js\nleave(playerId) {\n  // This game does not let a player back in once they quit.\n  void gem.match.reportPlayers([{ playerId, state: 'left' }]);\n}\n```",
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemMatchServer.analytics",
           "name": "analytics",

package/docs/changelog.md

@@ -16,6 +16,22 @@ 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.2.0
+
+Upgrading from 10.1.1. Impact: required.
+
+### Rebuild
+
+- The match object on the server types now has two more methods, setBackfill and reportPlayers, besides end. Recompile your server. If you wrote your own implementation or test double of the server or match server types, add the two new methods or it will no longer type-check.
+- The list of frame-to-parent message names, the frame message type and the capability type each gained a new member for the avatar picker. Recompile. If your code switches exhaustively over any of them, or checks that every member is handled, add a case for the new avatar picker member.
+- The order source type gained two new values, one for test account provisioning and one for developer grants, and each progression state entry in a paginated response may now carry an optional completion threshold. Recompile. If you switch exhaustively over order sources, handle the new values.
+
+### New capability
+
+- Games running inside the Arcade can now read the player's current Arcade avatar from GemPlayer.avatarIconId. It is only set when the value is a valid identifier, and the Arcade sends the player again whenever the worn avatar changes, so listen for player updates rather than reading it once. Games can also ask the Arcade to open its avatar picker. Check Gem.avatarPickerAvailable first, then call Gem.openAvatarPicker. It returns false outside the Arcade, before the connection is ready, when the Arcade does not offer the picker, or when you call it too often, and it never throws or waits. Nothing answers the request directly; the outcome is an updated player.
+- If your code hosts a game frame, you can now pass the avatar identifier when sending player information and handle the avatar picker request through the new host callback and option. Incoming picker requests have a new message type with its own validator. Without a handler, the request is refused.
+- Dedicated game servers can now control matchmaking backfill. Call setBackfill to stop or restart the platform topping up a running match from the matchmaking queue, optionally with a seat count, and it returns the resulting backfill state. Call reportPlayers to tell the platform whether each player has connected, never showed up, or left. The last two remove the player from the room. The server SDK also reports each joining player as connected on its own, which gives a seat filled from the queue a time limit. If the platform does not offer these routes, it stops trying for that match after one refused call. The matching low-level server API operations and request and response types are available too.
+
 ## 10.1.1
 
 Upgrading from 10.1.0. Impact: none.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "10.1.1"
+  "@indiegems/gem-web-sdk": "10.2.0"
 }
 ```
 

package/docs/manifest.json

@@ -33,8 +33,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "7f4f97b99bd6c851c26ae076485a592d80e4736a5efc472dfac17100003d034a",
-      "updated": "2026-10-11T07:34:02Z"
+      "sha256": "d7178e17c79418dc26cb685c667eb998b0d09dca6b1b2760268812c6af466151",
+      "updated": "2026-10-11T16:47:39Z"
     },
     {
       "file": "cross-promotion.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "17f3b522b1b67a1b8d22667e1a282832c6389d08cdd8f833126f9dcf2b7114dd",
-      "updated": "2026-10-11T07:34:02Z"
+      "sha256": "5758f3a68307af4650e6af3e74cba48e7110dd9c405aefa33b4eaa1c73b3f85a",
+      "updated": "2026-10-11T16:47:39Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -113,8 +113,8 @@
     },
     {
       "file": "rooms-and-matches.md",
-      "sha256": "23540a20bdd8c8d058eb06d8ef11085ffd8eaaeeaadc93a807608b7c279e240c",
-      "updated": "2026-10-10T18:05:31Z"
+      "sha256": "be22367f8dc9147e815a14ddb417788fa6614720a0df4f9f01624bf4667877d3",
+      "updated": "2026-10-11T10:17:11Z"
     },
     {
       "file": "saving-player-progress.md",
@@ -123,8 +123,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "eabaca8643bb58c23b1d476ed9f6045b8b82bef43c897205c872e5884ac6660f",
-      "updated": "2026-10-11T07:34:02Z"
+      "sha256": "a0e995c9a4f05515f39c5958918bd38bccb53e1c20bf13959f81d7694aa72ef0",
+      "updated": "2026-10-11T16:47:39Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -148,8 +148,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "a339443ece37e5a5311a05ff946a081ac6e8557d29e2ab59b90832e4ad40fc5d",
-      "updated": "2026-10-10T20:42:00Z"
+      "sha256": "2ef43f70b16f0004e6b82178a2b370b84e68b87754e50a649cf78164177244f0",
+      "updated": "2026-10-11T16:21:27Z"
     }
   ]
 }

package/docs/rooms-and-matches.md

@@ -770,6 +770,13 @@ else backToMenu(outcome.status);
 `matchmaking_not_enabled`**. `fill_window_seconds` in that block is how long a queue holds out for
 `max_players` before it accepts `min_players`. The block cannot be combined with `auto_start_host`.
 
+**A running match can take late arrivals.** Add `backfill: { enabled: true }` to the template's
+`matchmaking` block (the template must also allow joining in progress) and a match the platform made
+is topped up from the queue: a ticket that arrives after the match started is seated in it when it
+has an open seat, instead of waiting for a whole new lobby. To the queueing player nothing is
+different — the ticket ends `matched`, in a room whose match is already running. The match's server
+decides how long that lasts; see [the server guide](server-bundles.md#topping-a-running-match-up-from-the-queue).
+
 **A ticket names every mode the player accepts**, one to eight templates, and is matched under
 whichever fills first. That is one ticket, not several: a player can be on one ticket at a time, across
 every game.

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v10.1.1/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v10.1.1/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v10.2.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v10.2.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 
@@ -769,6 +769,50 @@ publish is your code plus whatever of the SDK it reached. No API origin is baked
 that arrives on `host.apiBaseUrl` at runtime. (`/server` remains as the server-only door for a
 bundle that wants nothing of the browser half in its graph.)
 
+### Topping a running match up from the queue
+
+A match the platform matchmade from a room template with `matchmaking.backfill` turned on takes
+waiting players into its open seats from the moment it starts, and again whenever a seat frees. Your
+server does nothing to get that. Two calls let it take control:
+
+```js
+// Nobody new once the final round starts.
+await gem.match.setBackfill({ open: false });
+
+// Open again, for at most two more players.
+await gem.match.setBackfill({ open: true, seats: 2 });
+```
+
+- **Closing removes nobody**, and a player already on the way in still arrives.
+- **`seats` counts down** as seats fill and backfill stops at 0. Omit it for every open seat.
+- It rejects with `GemApiError.code === 'backfill_not_enabled'` on a match the platform is not
+  topping up: the room template has no backfill, or the room was not matchmade.
+
+```js
+leave(playerId) {
+  // This game does not let a player back in once they quit.
+  void gem.match.reportPlayers([{ playerId, state: 'left' }]);
+}
+```
+
+`gem.match.reportPlayers` tells the platform about players, one of three ways:
+
+| `state` | Meaning | Effect |
+| --- | --- | --- |
+| `connected` | the player has connected to your server | noted |
+| `no_show` | the player was given a seat and never connected | removed from the room; the seat is free |
+| `left` | the player was in the match and is gone for good | removed from the room; the seat is free |
+
+⚠️ **`left` is final.** A removed player is not put back by reconnecting; they have to join again.
+Do not report it from every `leave()` in a game where a dropped connection is expected to return.
+
+**You do not report `connected` yourself** in a bundle built with `defineServer`: the SDK reports
+each player as they join. That report is what gives a seat filled from the queue a time limit. Once
+your server has reported anyone connected, a player the platform seats afterwards has a limited
+time to connect too, and is removed if they do not — so a seat is not held by somebody who closed
+the tab on the way in. A bundle that drives the lifecycle by hand reports `connected` from its own
+`join`, or gets no time limit.
+
 ### What is not on the server surface, and why
 
 `gem.p2p`, `gem.dedicatedServer`, `gem.me`, `gem.characters` and `gem.gameConfig` are browser-only.