@indiegems/gem-web-sdk 10.1.1 → 10.3.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.3.0"
   },
   "entries": [
     {
@@ -65,6 +65,10 @@
           "key": "vibration",
           "title": "Vibrating the device"
         },
+        {
+          "key": "controls",
+          "title": "Camera and look controls"
+        },
         {
           "key": "config",
           "title": "Your published config"
@@ -5385,6 +5389,572 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemLookSpeed",
+          "name": "GemLookSpeed",
+          "anchor": "gemlookspeed",
+          "group": "controls",
+          "signature": "interface GemLookSpeed",
+          "documented": true,
+          "summary": "A look speed per axis, in radians: per CSS px for a pointer, per second at\nfull tilt for a stick.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookSpeed.yaw",
+          "name": "yaw",
+          "anchor": "gemlookspeed-yaw",
+          "group": "controls",
+          "signature": "readonly yaw: number",
+          "documented": true,
+          "summary": "Across: radians of yaw.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookSpeed.pitch",
+          "name": "pitch",
+          "anchor": "gemlookspeed-pitch",
+          "group": "controls",
+          "signature": "readonly pitch: number",
+          "documented": true,
+          "summary": "Up/down: radians of pitch.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookBase",
+          "name": "GemLookBase",
+          "anchor": "gemlookbase",
+          "group": "controls",
+          "signature": "interface GemLookBase",
+          "documented": true,
+          "summary": "The shape of `gem.controls.LOOK_BASE`: Roblox's base look speeds and the\nstick and touch shaping constants `gem.controls.look()` applies.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookBase.touch",
+          "name": "touch",
+          "anchor": "gemlookbase-touch",
+          "group": "controls",
+          "signature": "readonly touch: GemLookSpeed",
+          "documented": true,
+          "summary": "Radians per CSS px, for touch and pen: 1° across, 0.66° up/down.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookBase.mouse",
+          "name": "mouse",
+          "anchor": "gemlookbase-mouse",
+          "group": "controls",
+          "signature": "readonly mouse: GemLookSpeed",
+          "documented": true,
+          "summary": "Radians per CSS px, for a mouse: 0.5° across, 0.385° up/down.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookBase.stick",
+          "name": "stick",
+          "anchor": "gemlookbase-stick",
+          "group": "controls",
+          "signature": "readonly stick: GemLookSpeed",
+          "documented": true,
+          "summary": "Radians per second at full tilt, for a gamepad stick: 240° across, 184.8° up/down.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookBase.stickDeadzone",
+          "name": "stickDeadzone",
+          "anchor": "gemlookbase-stickdeadzone",
+          "group": "controls",
+          "signature": "readonly stickDeadzone: number",
+          "documented": true,
+          "summary": "A stick axis below this magnitude turns nothing: 0.1.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookBase.stickCurve",
+          "name": "stickCurve",
+          "anchor": "gemlookbase-stickcurve",
+          "group": "controls",
+          "signature": "readonly stickCurve: number",
+          "documented": true,
+          "summary": "The stick curve's curvature `k` in `(e^(k·d) − 1) / (e^k − 1)`: 2.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookBase.touchPitchMin",
+          "name": "touchPitchMin",
+          "anchor": "gemlookbase-touchpitchmin",
+          "group": "controls",
+          "signature": "readonly touchPitchMin: number",
+          "documented": true,
+          "summary": "The least fraction of the pitch speed a touch drag keeps straight up or down: 0.25.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookOptions",
+          "name": "GemLookOptions",
+          "anchor": "gemlookoptions",
+          "group": "controls",
+          "signature": "interface GemLookOptions",
+          "documented": true,
+          "summary": "The game's own overrides for `gem.controls.look()` — what the player chose in\nYOUR settings screen. Each one wins over the Arcade's value; leave one out to\nfollow the Arcade.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookOptions.sensitivity",
+          "name": "sensitivity",
+          "anchor": "gemlookoptions-sensitivity",
+          "group": "controls",
+          "signature": "readonly sensitivity?: number",
+          "documented": true,
+          "summary": "The player's own look speed for touch, mouse and pen, as a multiplier\n(`1` = the base speed). Wins over `gem.prefs.recommended.lookSensitivity`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookOptions.gamepadSensitivity",
+          "name": "gamepadSensitivity",
+          "anchor": "gemlookoptions-gamepadsensitivity",
+          "group": "controls",
+          "signature": "readonly gamepadSensitivity?: number",
+          "documented": true,
+          "summary": "The player's own look speed for a gamepad stick, as a multiplier. Wins\nover `gem.prefs.recommended.gamepadLookSensitivity`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookOptions.invertY",
+          "name": "invertY",
+          "anchor": "gemlookoptions-inverty",
+          "group": "controls",
+          "signature": "readonly invertY?: boolean",
+          "documented": true,
+          "summary": "The player's own inverted up/down look. Wins over\n`gem.prefs.recommended.invertLookY`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookDelta",
+          "name": "GemLookDelta",
+          "anchor": "gemlookdelta",
+          "group": "controls",
+          "signature": "interface GemLookDelta",
+          "documented": true,
+          "summary": "A turn to apply to your camera, in radians to ADD: `yaw` positive turns\nright (clockwise seen from above), `pitch` positive looks up.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookDelta.yaw",
+          "name": "yaw",
+          "anchor": "gemlookdelta-yaw",
+          "group": "controls",
+          "signature": "readonly yaw: number",
+          "documented": true,
+          "summary": "Radians to add to the camera's yaw; positive turns right.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLookDelta.pitch",
+          "name": "pitch",
+          "anchor": "gemlookdelta-pitch",
+          "group": "controls",
+          "signature": "readonly pitch: number",
+          "documented": true,
+          "summary": "Radians to add to the camera's pitch; positive looks up.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLook",
+          "name": "GemLook",
+          "anchor": "gemlook",
+          "group": "controls",
+          "signature": "interface GemLook",
+          "documented": true,
+          "summary": "The look helper `gem.controls.look()` returns. Pure math: it listens to\nnothing and moves no camera — feed it the deltas your input code already\nhas and add what it returns to your camera's yaw and pitch, then clamp the\npitch as you always do.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLook.fromPointer",
+          "name": "fromPointer",
+          "anchor": "gemlook-frompointer",
+          "group": "controls",
+          "signature": "fromPointer(dx: number, dy: number, pointerType: string, pitch?: number): GemLookDelta",
+          "documented": true,
+          "summary": "A pointer move — a touch drag, a mouse move (under pointer lock,\n`movementX` / `movementY`) or a pen — turned into a look turn.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "dx",
+              "type": "number",
+              "optional": false,
+              "summary": "The move across, in CSS px, right positive."
+            },
+            {
+              "name": "dy",
+              "type": "number",
+              "optional": false,
+              "summary": "The move down the screen, in CSS px, DOWN positive (as\n  `PointerEvent` reports it). Dragging up looks up."
+            },
+            {
+              "name": "pointerType",
+              "type": "string",
+              "optional": false,
+              "summary": "The event's `pointerType`: `'touch'` and `'pen'` take\n  the touch speeds, anything else the mouse speeds."
+            },
+            {
+              "name": "pitch",
+              "type": "number",
+              "optional": true,
+              "summary": "The camera's current pitch in radians (0 = the horizon,\n  positive = looking up), for the touch slowdown near straight up or\n  down. Leave it out to skip the slowdown."
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLook.fromStick",
+          "name": "fromStick",
+          "anchor": "gemlook-fromstick",
+          "group": "controls",
+          "signature": "fromStick(x: number, y: number, dt: number): GemLookDelta",
+          "documented": true,
+          "summary": "A right stick turned into a look turn over one frame.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "x",
+              "type": "number",
+              "optional": false,
+              "summary": "The stick's horizontal axis as the Gamepad API reports it,\n  −1..1, right positive."
+            },
+            {
+              "name": "y",
+              "type": "number",
+              "optional": false,
+              "summary": "The stick's vertical axis as the Gamepad API reports it, −1..1,\n  DOWN positive. Pushing up looks up."
+            },
+            {
+              "name": "dt",
+              "type": "number",
+              "optional": false,
+              "summary": "The frame's duration in seconds."
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemLook.set",
+          "name": "set",
+          "anchor": "gemlook-set",
+          "group": "controls",
+          "signature": "set(options: GemLookOptions): void",
+          "documented": true,
+          "summary": "Change your game's overrides — call it when the player changes a setting\nin your settings screen. Each key you pass replaces that override; a key\npassed as `undefined` removes it, so that input follows the Arcade again;\na key you leave out is unchanged.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "options",
+              "type": "GemLookOptions",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": "TypeError when a sensitivity is not a finite number above 0, or\n  `invertY` is not a boolean.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ControlsApi",
+          "name": "ControlsApi",
+          "anchor": "controlsapi",
+          "group": "controls",
+          "signature": "interface ControlsApi",
+          "documented": true,
+          "summary": "`gem.controls` — the player's camera and controls settings: tell the Arcade\nwhich ones your game leaves to the player, and turn look input into a camera\nturn at the player's sensitivity.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "what-a-game-must-do",
+              "anchor": null
+            }
+          ]
+        },
+        {
+          "id": "ControlsApi.declare",
+          "name": "declare",
+          "anchor": "controlsapi-declare",
+          "group": "controls",
+          "signature": "declare(uses: GemControlsDeclaration): boolean",
+          "documented": true,
+          "summary": "Tell the Arcade which of the player's camera and controls settings your\ngame uses, and for each one who decides it: `'player'` — you apply the\nArcade's value from `gem.prefs.recommended` (or the player's own choice\nin your settings, which wins) — or `'game'` — you decide it yourself, and\nthe Arcade's Settings shows that row as \"Set by this game\". Leave out a\nsetting your game does not use.\n\n```js\ngem.controls.declare({\n  lookSensitivity: 'player',\n  gamepadLookSensitivity: 'player',\n  invertLookY: 'player',\n  touchMovement: 'game', // this game always uses a fixed stick\n});\n```\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. The SDK holds it and sends it again after every\nreconnect, so call it once at boot, and again only when the answer\nchanges. Any other key or value is dropped.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "uses",
+              "type": "GemControlsDeclaration",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "`true` when the Arcade was told now; `false` before the bridge is\n  up (the declaration is held and sent when it connects), outside the\n  Arcade, and under an embedder that does not show these settings. Never\n  throws.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ControlsApi.look",
+          "name": "look",
+          "anchor": "controlsapi-look",
+          "group": "controls",
+          "signature": "look(options?: GemLookOptions): GemLook",
+          "documented": true,
+          "summary": "Make a look helper: Roblox's camera-input math at the player's look\nsensitivity and invert. Make one and keep it.\n\n```js\nconst look = gem.controls.look();\n// A mouse under pointer lock; for touch, pass the change in clientX/clientY.\ncanvas.addEventListener('pointermove', (e) => {\n  if (document.pointerLockElement !== canvas) return;\n  const t = look.fromPointer(e.movementX, e.movementY, e.pointerType, camera.pitch);\n  camera.yaw += t.yaw;\n  camera.pitch = clamp(camera.pitch + t.pitch, -1.4, 1.4);\n});\n```\n\nThe sensitivity and invert are read **live** on every call: the Arcade's\n`gem.prefs.recommended` values, unless `options` (or a later\n[GemLook.set](api-reference-game.md#gemlook-set)) gives your game's own, which win.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "options",
+              "type": "GemLookOptions",
+              "optional": true,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": "TypeError when an option is malformed, as [GemLook.set](api-reference-game.md#gemlook-set).",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ControlsApi.LOOK_BASE",
+          "name": "LOOK_BASE",
+          "anchor": "controlsapi-look_base",
+          "group": "controls",
+          "signature": "readonly LOOK_BASE: GemLookBase",
+          "documented": true,
+          "summary": "The base speeds `look` applies at 1×, in radians. Frozen.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemControlChoice",
+          "name": "GemControlChoice",
+          "anchor": "gemcontrolchoice",
+          "group": "controls",
+          "signature": "type GemControlChoice = \"player\" | \"game\"",
+          "documented": true,
+          "summary": "Who decides one camera or controls setting: `'player'` — your game applies\nthe Arcade's value, or the player's own in-game choice, which wins — or\n`'game'` — your game decides it itself, and the Arcade's Settings shows the\nrow as \"Set by this game\".",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemControlsDeclaration",
+          "name": "GemControlsDeclaration",
+          "anchor": "gemcontrolsdeclaration",
+          "group": "controls",
+          "signature": "interface GemControlsDeclaration",
+          "documented": true,
+          "summary": "What `gem.controls.declare` takes: for each of the player's camera and\ncontrols settings your game uses, who decides it. Leave a setting out when\nyour game does not use it at all — the Arcade then says \"This game doesn't\nuse this\" beside that row.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemControlsDeclaration.lookSensitivity",
+          "name": "lookSensitivity",
+          "anchor": "gemcontrolsdeclaration-looksensitivity",
+          "group": "controls",
+          "signature": "readonly lookSensitivity?: GemControlChoice",
+          "documented": true,
+          "summary": "Look speed for touch, mouse and pen — `gem.prefs.recommended.lookSensitivity`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemControlsDeclaration.gamepadLookSensitivity",
+          "name": "gamepadLookSensitivity",
+          "anchor": "gemcontrolsdeclaration-gamepadlooksensitivity",
+          "group": "controls",
+          "signature": "readonly gamepadLookSensitivity?: GemControlChoice",
+          "documented": true,
+          "summary": "Look speed for a gamepad stick — `gem.prefs.recommended.gamepadLookSensitivity`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemControlsDeclaration.invertLookY",
+          "name": "invertLookY",
+          "anchor": "gemcontrolsdeclaration-invertlooky",
+          "group": "controls",
+          "signature": "readonly invertLookY?: GemControlChoice",
+          "documented": true,
+          "summary": "Inverted up/down look — `gem.prefs.recommended.invertLookY`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemControlsDeclaration.touchMovement",
+          "name": "touchMovement",
+          "anchor": "gemcontrolsdeclaration-touchmovement",
+          "group": "controls",
+          "signature": "readonly touchMovement?: GemControlChoice",
+          "documented": true,
+          "summary": "The touch movement thumbstick, floating or fixed — `gem.prefs.recommended.touchMovement`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "DEVICE_SETTINGS_MAX_BYTES",
           "name": "DEVICE_SETTINGS_MAX_BYTES",
@@ -5982,6 +6552,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemFrame.declareControls",
+          "name": "declareControls",
+          "anchor": "gemframe-declarecontrols",
+          "group": "frame",
+          "signature": "declareControls(uses: GemControlsDeclaration): boolean",
+          "documented": true,
+          "summary": "Tell the arcade which of the player's camera and controls settings your\ngame leaves to the player and which it decides itself — the whole answer\neach time, the latest one winning.\n\nPrefer `gem.controls.declare`, which holds the declaration across a\nreconnect. This one sends only while connected, and only to an arcade\nthat shows these settings.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "uses",
+              "type": "GemControlsDeclaration",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "whether the message left the frame — `false` before the bridge is\n  up, for an arcade that does not show these settings, and past this\n  frame's own limit.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemFrame.setMenu",
           "name": "setMenu",
@@ -6034,6 +6627,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 +6799,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 +8569,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,
@@ -8093,7 +8702,7 @@
           "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.",
+          "summary": "The player's Arcade-wide defaults for this device — a volume, battery\nsaver, a keyboard layout, the gamepad's confirm button, vibration, and the\ncamera and controls settings (look sensitivity, gamepad look sensitivity,\ninvert look, touch movement) — or `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,
@@ -8203,6 +8812,70 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemRecommendedSettings.lookSensitivity",
+          "name": "lookSensitivity",
+          "anchor": "gemrecommendedsettings-looksensitivity",
+          "group": "player",
+          "signature": "readonly lookSensitivity: number",
+          "documented": true,
+          "summary": "The player's look speed for touch, mouse and pen, as a percentage of the\nbase speeds: `100` is 1×, from `20` (0.2×) to `400` (4×). `100` when the\nArcade did not say. `gem.controls.look()` applies it for you.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.gamepadLookSensitivity",
+          "name": "gamepadLookSensitivity",
+          "anchor": "gemrecommendedsettings-gamepadlooksensitivity",
+          "group": "player",
+          "signature": "readonly gamepadLookSensitivity: number",
+          "documented": true,
+          "summary": "The player's look speed for a gamepad stick, as a percentage: `100` is 1×,\nfrom `20` to `400`. `100` when the Arcade did not say.\n`gem.controls.look()` applies it for you.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.invertLookY",
+          "name": "invertLookY",
+          "anchor": "gemrecommendedsettings-invertlooky",
+          "group": "player",
+          "signature": "readonly invertLookY: boolean",
+          "documented": true,
+          "summary": "Whether the player wants up/down look inverted: pushing up or dragging up\nlooks down. Flips pitch only, never yaw. `false` when the Arcade did not\nsay. `gem.controls.look()` applies it for you.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.touchMovement",
+          "name": "touchMovement",
+          "anchor": "gemrecommendedsettings-touchmovement",
+          "group": "player",
+          "signature": "readonly touchMovement: \"floating\" | \"fixed\"",
+          "documented": true,
+          "summary": "On a touch screen, the movement thumbstick the player wants: `'floating'`\nappears where the thumb lands, `'fixed'` stays in one place. `'floating'`\nwhen the Arcade did not say. Your game draws the stick.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemCohort",
           "name": "GemCohort",
@@ -9030,6 +9703,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",
@@ -9051,6 +9756,22 @@
             }
           ]
         },
+        {
+          "id": "Gem.controls",
+          "name": "controls",
+          "anchor": "gem-controls",
+          "group": "start",
+          "signature": "readonly controls: ControlsApi",
+          "documented": true,
+          "summary": "The player's camera and controls settings — look sensitivity, gamepad look\nsensitivity, invert look and touch movement, which arrive in\n`gem.prefs.recommended`. Two things to do with them:\n\n```js\n// 1. Tell the Arcade which ones your game leaves to the player.\ngem.controls.declare({ lookSensitivity: 'player', invertLookY: 'player' });\n\n// 2. Turn look input into a camera turn at the player's sensitivity.\nconst look = gem.controls.look();\n// dx, dy: the pointer's move in CSS px since the last event.\nconst t = look.fromPointer(dx, dy, e.pointerType, camera.pitch);\ncamera.yaw += t.yaw;\ncamera.pitch += t.pitch;\n```\n\nSee the guide's \"Camera and look controls\" section.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.analytics",
           "name": "analytics",
@@ -10625,7 +11346,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 +14118,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 +15881,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 +18697,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 +19779,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 +22465,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 +23304,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 +23453,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 +23487,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 +24263,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 +24853,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 +24887,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",