@indiegems/gem-web-sdk 10.1.0 → 10.2.0

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

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-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.
+Generated from `@indiegems/gem-web-sdk/sdk` v10.2.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.
 
@@ -2244,6 +2244,38 @@ not have to keep reaching back to the host object.
 These are also the ids bound into every call `api` makes, which is why a
 bundle never types a game id and cannot name another game's.
 
+<a id="matchbackfillstate"></a>
+
+## MatchBackfillState
+
+```ts
+interface MatchBackfillState
+```
+
+Whether this match is being topped up from the matchmaking queue, as the
+platform now has it.
+
+<a id="matchplayerreport"></a>
+
+## MatchPlayerReport
+
+```ts
+interface MatchPlayerReport
+```
+
+What your server says about one player of its match, for
+[GemServer.match](#gemserver-match)'s `reportPlayers`.
+
+<a id="matchplayerreportresult"></a>
+
+## MatchPlayerReportResult
+
+```ts
+interface MatchPlayerReportResult
+```
+
+What a report did for one player, in the order you reported them.
+
 <a id="gemserveroptions"></a>
 
 ## GemServerOptions
@@ -3004,6 +3036,72 @@ The room this match came from, when there is one.
 CHECK IT BEFORE USING IT. It is absent on older platform images, which is
 also why [GemServer.room](#gemserver-room) can be absent — the two go together.
 
+<a id="matchplayerreport-playerid"></a>
+
+## MatchPlayerReport.playerId
+
+```ts
+readonly playerId: string
+```
+
+The player. Take it from `join()`, `leave()` or the room, never from a client.
+
+<a id="matchplayerreport-state"></a>
+
+## MatchPlayerReport.state
+
+```ts
+readonly state: "connected" | "no_show" | "left"
+```
+
+- `connected` — the player has connected to this server.
+- `no_show` — the player was given a seat and never connected.
+- `left` — the player was in the match and is gone FOR GOOD.
+
+The last two remove the player from the room, which frees the seat.
+
+<a id="matchplayerreportresult-playerid"></a>
+
+## MatchPlayerReportResult.playerId
+
+```ts
+readonly playerId: string
+```
+
+The player this result is for.
+
+<a id="matchplayerreportresult-outcome"></a>
+
+## MatchPlayerReportResult.outcome
+
+```ts
+readonly outcome: "recorded" | "removed" | "not_a_member" | string & object
+```
+
+- `recorded` — `connected` was noted.
+- `removed` — the player was taken out of the room.
+- `not_a_member` — the player is not in this match's room; nothing changed.
+
+<a id="matchbackfillstate-open"></a>
+
+## MatchBackfillState.open
+
+```ts
+readonly open: boolean
+```
+
+Whether the match is taking players from the queue.
+
+<a id="matchbackfillstate-seats"></a>
+
+## MatchBackfillState.seats
+
+```ts
+readonly seats: number | null
+```
+
+The most players still wanted, or `null` for every open seat.
+
 <a id="gemserver-identity"></a>
 
 ## GemServer.identity
@@ -3047,7 +3145,7 @@ See [ServerApi](#serverapi).
 ## GemServer.match
 
 ```ts
-readonly match: { end: null }
+readonly match: { end: null; setBackfill: null; reportPlayers: null }
 ```
 
 Ending the match.
@@ -3082,6 +3180,77 @@ Tell the platform this match is finished.
 **Throws.** When the platform image running this server predates
   `host.endMatch`, so the match cannot be ended from here.
 
+<a id="gemserver-match-setbackfill"></a>
+
+## GemServer.match.setBackfill
+
+```ts
+setBackfill(options: { open: boolean; seats?: number }, signal?: AbortSignal): Promise<MatchBackfillState>
+```
+
+Stop, or restart, the platform topping this match up from the
+matchmaking queue.
+
+A match the platform matchmade from a room type with backfill turned on
+takes waiting players into its open seats from the moment it starts.
+This is how your server takes control of that: close it once joining
+late no longer makes sense — the last round, a boss fight — and open it
+again if it does.
+
+Closing removes nobody, and a player already on the way in still
+arrives. The setting lasts for the match.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `{ open: boolean; seats?: number }` | `open` — whether to take players. `seats` — with
+  `open: true`, the most players still wanted; it counts down as seats
+  fill. Omit it for every open seat. |
+| `signal` | `AbortSignal` | Cancels the request. |
+
+**Throws.** A `GemApiError` with code `backfill_not_enabled` when this match
+  is not one the platform tops up: its room type has no backfill, or the
+  room was not matchmade.
+
+```js
+// Nobody new once the final round starts.
+await gem.match.setBackfill({ open: false });
+```
+
+<a id="gemserver-match-reportplayers"></a>
+
+## GemServer.match.reportPlayers
+
+```ts
+reportPlayers(reports: readonly MatchPlayerReport[], signal?: AbortSignal): Promise<MatchPlayerReportResult[]>
+```
+
+Tell the platform which players have connected, never arrived, or left.
+
+`no_show` and `left` REMOVE THE PLAYER FROM THE ROOM, which frees the
+seat — for the queue, when the match is being topped up. Report `left`
+only for a player who is gone for good: reconnecting does not put a
+removed player back, they have to join again.
+
+YOU DO NOT REPORT `connected` YOURSELF in a bundle built with
+[defineServer](#defineserver): it reports each player as they join. That report is
+what gives a seat the platform filled from the queue a time limit — a
+player who is seated and never connects is removed, and the seat goes to
+the next one waiting.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `reports` | `readonly MatchPlayerReport[]` | 1 to 32 players. |
+| `signal` | `AbortSignal` | Cancels the request. |
+
+**Returns.** One result per report, in the same order.
+
+```js
+leave(playerId) {
+  // This game does not let a player back in once they quit.
+  void gem.match.reportPlayers([{ playerId, state: 'left' }]);
+}
+```
+
 <a id="gemserver-analytics"></a>
 
 ## GemServer.analytics
@@ -3629,7 +3798,7 @@ Disconnect a player. `reason` is shown to them and recorded in the logs.
 ## GemServerHost.endMatch
 
 ```ts
-endMatch(): Promise<"ok" | "already_ended" | "refused" | "failed" | string & object>
+endMatch(): Promise<string & object | "ok" | "already_ended" | "refused" | "failed">
 ```
 
 Ask the platform half to end this match, with the allocation's own proof.
@@ -4070,7 +4239,7 @@ See [ServerApi](#serverapi).
 ## GemMatchServer.match
 
 ```ts
-readonly match: { end: null }
+readonly match: { end: null; setBackfill: null; reportPlayers: null }
 ```
 
 Ending the match.
@@ -4105,6 +4274,77 @@ Tell the platform this match is finished.
 **Throws.** When the platform image running this server predates
   `host.endMatch`, so the match cannot be ended from here.
 
+<a id="gemmatchserver-match-setbackfill"></a>
+
+## GemMatchServer.match.setBackfill
+
+```ts
+setBackfill(options: { open: boolean; seats?: number }, signal?: AbortSignal): Promise<MatchBackfillState>
+```
+
+Stop, or restart, the platform topping this match up from the
+matchmaking queue.
+
+A match the platform matchmade from a room type with backfill turned on
+takes waiting players into its open seats from the moment it starts.
+This is how your server takes control of that: close it once joining
+late no longer makes sense — the last round, a boss fight — and open it
+again if it does.
+
+Closing removes nobody, and a player already on the way in still
+arrives. The setting lasts for the match.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `{ open: boolean; seats?: number }` | `open` — whether to take players. `seats` — with
+  `open: true`, the most players still wanted; it counts down as seats
+  fill. Omit it for every open seat. |
+| `signal` | `AbortSignal` | Cancels the request. |
+
+**Throws.** A `GemApiError` with code `backfill_not_enabled` when this match
+  is not one the platform tops up: its room type has no backfill, or the
+  room was not matchmade.
+
+```js
+// Nobody new once the final round starts.
+await gem.match.setBackfill({ open: false });
+```
+
+<a id="gemmatchserver-match-reportplayers"></a>
+
+## GemMatchServer.match.reportPlayers
+
+```ts
+reportPlayers(reports: readonly MatchPlayerReport[], signal?: AbortSignal): Promise<MatchPlayerReportResult[]>
+```
+
+Tell the platform which players have connected, never arrived, or left.
+
+`no_show` and `left` REMOVE THE PLAYER FROM THE ROOM, which frees the
+seat — for the queue, when the match is being topped up. Report `left`
+only for a player who is gone for good: reconnecting does not put a
+removed player back, they have to join again.
+
+YOU DO NOT REPORT `connected` YOURSELF in a bundle built with
+[defineServer](#defineserver): it reports each player as they join. That report is
+what gives a seat the platform filled from the queue a time limit — a
+player who is seated and never connects is removed, and the seat goes to
+the next one waiting.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `reports` | `readonly MatchPlayerReport[]` | 1 to 32 players. |
+| `signal` | `AbortSignal` | Cancels the request. |
+
+**Returns.** One result per report, in the same order.
+
+```js
+leave(playerId) {
+  // This game does not let a player back in once they quit.
+  void gem.match.reportPlayers([{ playerId, state: 'left' }]);
+}
+```
+
 <a id="gemmatchserver-analytics"></a>
 
 ## GemMatchServer.analytics