@indiegems/gem-web-sdk 10.2.0 → 10.3.1

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "10.2.0"
+    "version": "10.3.1"
   },
   "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",
@@ -5582,7 +6152,7 @@
           "group": "platform",
           "signature": "interface RewardCue",
           "documented": true,
-          "summary": "A platform-currency reward on its way to the arcade's wallet — what\n`gem.cueReward` takes.",
+          "summary": "A platform-currency reward on its way to the arcade — in the Gem Arcade, a\nflight into the Gem button at the top-left of your frame — what\n`gem.cueReward` takes.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -5598,7 +6168,7 @@
           "group": "platform",
           "signature": "currencySlug: string",
           "documented": true,
-          "summary": "The platform currency's slug, as `gem.platform.currencies.get()` lists it —\n`GEMS` or `ARCADE_TICKETS`. It decides which total in the arcade's wallet\nthe payout flies into.",
+          "summary": "The platform currency's slug, as `gem.platform.currencies.get()` lists it —\n`GEMS` or `ARCADE_TICKETS`. It decides what flies — gems or tickets — and\nwhich of the player's totals the payout moves.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -5630,7 +6200,7 @@
           "group": "platform",
           "signature": "origin?: { x: number; y: number }",
           "documented": true,
-          "summary": "Where the flight starts, in CSS px of YOUR viewport: the centre of the\ncurrency's icon (or hero) your screen draws beside the reward — the gem\nfor Gems, the ticket for Tickets. Measure that element's own box, not a\nrow or panel around it. Leave it out and the arcade animates at its wallet\nalone.",
+          "summary": "Where the flight starts, in CSS px of YOUR viewport: the centre of the\ncurrency's icon (or hero) your screen draws beside the reward — the gem\nfor Gems, the ticket for Tickets. Measure that element's own box, not a\nrow or panel around it. Leave it out and the Gem Arcade flies the payout\nfrom the middle of your frame once the platform confirms it.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -5914,7 +6484,7 @@
           "group": "frame",
           "signature": "cueReward(cue: RewardCue): boolean",
           "documented": true,
-          "summary": "Tell the arcade a platform-currency reward is on its way, so its wallet can\nshow it landing — a pending state now and, once the platform confirms the\ngrant, the currency flying from `origin` into the wallet.\n\nPrefer `gem.cueReward`, which says what the arcade does with it. This one\nsends only while connected, and only to an arcade that draws a wallet.",
+          "summary": "Tell the arcade a platform-currency reward is on its way, so it can show it\nlanding — in the Gem Arcade, the currency flying from `origin` into the Gem\nbutton, the total moving once the platform confirms the grant.\n\nPrefer `gem.cueReward`, which says what the arcade does with it. This one\nsends only while connected, and only to an arcade that draws a wallet.",
           "deprecated": null,
           "params": [
             {
@@ -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",
@@ -8109,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,
@@ -8219,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",
@@ -8412,7 +9069,7 @@
           "group": "player",
           "signature": "readonly reserved: readonly GemReservedArea[]",
           "documented": true,
-          "summary": "Rectangles of your frame the arcade's own controls cover — its menu button\nin the top-right corner, and the wallets in the middle of the top row while they are shown (see\n`setWalletVisible`). Keep essential UI and touch targets out of them. Empty\nwhen the arcade covers nothing.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends.",
+          "summary": "Rectangles of your frame the arcade's own controls cover — in the Gem\nArcade, its Gem button in the top-left corner, and the frame-rate readout\nbeside it while the player shows it; an embedder that draws wallets over\nyour game adds theirs (see `setWalletVisible`). Keep essential UI and touch\ntargets out of them. Empty when the arcade covers nothing.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8524,7 +9181,7 @@
           "group": "platform",
           "signature": "readonly only?: readonly string[]",
           "documented": true,
-          "summary": "While shown, show ONLY these: platform currency slugs as\n`gem.platform.currencies.get()` lists them (`GEMS`, `ARCADE_TICKETS`),\nmatched exactly, and the literal `'score'` for the achievement score. Only\nfor a screen about one currency, such as a ticket store; leave it out and\nevery wallet shows, which is always safe. The Gem Arcade ignores it and\nshows every wallet while shown.",
+          "summary": "While shown, show ONLY these: platform currency slugs as\n`gem.platform.currencies.get()` lists them (`GEMS`, `ARCADE_TICKETS`),\nmatched exactly, and the literal `'score'` for the achievement score. Only\nfor a screen about one currency, such as a ticket store; leave it out and\nevery wallet shows, which is always safe. The Gem Arcade draws no wallet\nover a game, so it has nothing to narrow and ignores it.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9099,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",
@@ -9384,7 +10057,7 @@
           "group": "start",
           "signature": "cueReward(cue: RewardCue): boolean",
           "documented": true,
-          "summary": "Tell the arcade a platform-currency reward is on its way, so its **wallet\nshows it landing**: a pending state right away and, once the platform\nconfirms the grant, the currency flying from `origin` into the wallet with\na bounce as the total moves.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the ticket\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Tickets alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
+          "summary": "Tell the arcade a platform-currency reward is on its way, so it **shows it\nlanding**: in the Gem Arcade the currency flies from `origin` into the Gem\nbutton at the top-left of your frame, which pops as each mark lands, and\nthe player's total moves once the platform confirms the grant. The Gem\nArcade draws no wallet over your game: the player sees their Gems and\nTickets in the Gem menu. A payout you do not cue still flies, from the\nmiddle of your frame, so cue the ones the player earns on screen.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the ticket\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Tickets alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
           "deprecated": null,
           "params": [
             {
@@ -9407,7 +10080,7 @@
           "group": "start",
           "signature": "setWalletVisible(visible: boolean, options?: WalletVisibleOptions): boolean",
           "documented": true,
-          "summary": "Show or hide the player's wallets — Gems, Tickets, the achievement score —\nthat an embedder draws over your game.\n\n**Shown unless you hide them.** Call nothing and the Gem Arcade shows\nevery wallet the whole time, during play too. A game that wants the top\nrow for gameplay hides them while it plays and shows them again on its\nmenus (the Gem Arcade honours this again since 2026-10-08, on a phone,\nwhere the wallets sit over your game; where they sit beside the frame it\nchanges nothing).\n\n```js\nlevel.onStart = () => gem.setWalletVisible(false);\nmenu.onOpen = () => gem.setWalletVisible(true);\n```\n\nThe Gem Arcade does NOT act on `only`: a shown wallet there is every\nwallet. Another embedder may honour it.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. While hidden, the arcade still pops a wallet up for a\nmoment when something happens to it — a reward you cued, a spend, a\nlanding — and your state never cancels that. Shown wallets cover the\nmiddle of your frame's top row, each arriving as a rectangle in\n`gem.viewport.reserved`; hiding them gives that space back. A wallet the\narcade pops up for a moment floats over your game and moves nothing.\n\n**Never draw a platform balance yourself**, and never show a pending state\nfor one: the arcade takes every figure from the platform. If this returns\n`false`, do nothing in its place.",
+          "summary": "Show or hide the player's wallets — Gems, Tickets, the achievement score —\nthat an embedder draws over your game.\n\n**The Gem Arcade draws no wallet over a game** (since 2026-10-11): the\nplayer sees their balances in the Gem menu, and payouts fly into the Gem\nbutton. So under the Gem Arcade this changes nothing on screen — it is\naccepted and harmless, and a game that already calls it keeps working.\nCall it for an embedder that does draw wallets over your game: hide them\nwhile you play, show them on your menus.\n\n```js\nlevel.onStart = () => gem.setWalletVisible(false);\nmenu.onOpen = () => gem.setWalletVisible(true);\n```\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. Where an embedder draws wallets, shown ones arrive as\nrectangles in `gem.viewport.reserved` and hiding them gives that space\nback; the Gem Arcade sends none for wallets. `only` narrows what shows,\nwhere an embedder honours it; the Gem Arcade does not.\n\n**Never draw a platform balance yourself**, and never show a pending state\nfor one: the arcade takes every figure from the platform. If this returns\n`false`, do nothing in its place.",
           "deprecated": null,
           "params": [
             {