@indiegems/gem-web-sdk 10.2.0 → 10.3.0

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.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",
@@ -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",
@@ -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",