@indiegems/gem-web-sdk 10.2.0 → 10.3.0

package/docs/changelog.md

@@ -16,6 +16,22 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 10.3.0
+
+Upgrading from 10.2.0. Impact: required.
+
+### Rebuild
+
+- The set of messages a frame sends to the Arcade has grown by one controls declaration message, so the message list and the FrameMessage union changed. Recompiling is enough. If your code switches exhaustively over frame message types, add a case for the new one.
+- GemCapability gained a controls value. Recompiling is enough. If you map every capability to something exhaustively, add an entry for it.
+- The recommended settings inside the preferences gained four optional fields for look sensitivity, gamepad look sensitivity, look inversion and touch movement. Recompiling is enough. The touch movement value appears as a plain string in the received preferences, while the host-side sendPrefs accepts only floating or fixed, so treat unknown values as the default.
+
+### New capability
+
+- Your game can now declare which control choices it offers by using Gem.controls, which is a ControlsApi, or GemFrame.declareControls. You describe the choices with GemControlChoice entries inside a GemControlsDeclaration. Declaring them lets the Arcade show the matching camera and controls settings for your game. Check that the new controls capability is available before declaring.
+- The SDK now provides camera look input. GemLook delivers GemLookDelta values, configured with GemLookOptions and scaled by a GemLookSpeed. GemLookBase gives the base look speed. Use these instead of your own look scaling so that the player's sensitivity choices apply to your game.
+- The player's recommended settings now carry four optional fields: lookSensitivity, gamepadLookSensitivity, invertLookY and touchMovement. Read them to start with the player's preferred look sensitivity, look inversion and touch movement style. They may be absent, so keep your own defaults for when they are not provided.
+
 ## 10.2.0
 
 Upgrading from 10.1.1. Impact: required.

package/docs/getting-started.md

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

package/docs/manifest.json

@@ -33,8 +33,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "d7178e17c79418dc26cb685c667eb998b0d09dca6b1b2760268812c6af466151",
-      "updated": "2026-10-11T16:47:39Z"
+      "sha256": "daae6b71cecc9761bc1e3ed5603c5d8f366e0533ce4ecc6d6c57f546efe1a292",
+      "updated": "2026-10-11T18:22:44Z"
     },
     {
       "file": "cross-promotion.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "5758f3a68307af4650e6af3e74cba48e7110dd9c405aefa33b4eaa1c73b3f85a",
-      "updated": "2026-10-11T16:47:39Z"
+      "sha256": "fd566ed7d7f0b1b2b9bea823de5455d2ee9a66072e7303df1bc5c12c1acddcbe",
+      "updated": "2026-10-11T18:22:44Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -123,8 +123,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "a0e995c9a4f05515f39c5958918bd38bccb53e1c20bf13959f81d7694aa72ef0",
-      "updated": "2026-10-11T16:47:39Z"
+      "sha256": "c6935f10ba645e8a9d3fd48c10f313324bfdbca6fcbd273dfade6579dcfd32e8",
+      "updated": "2026-10-11T18:22:44Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -148,8 +148,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "2ef43f70b16f0004e6b82178a2b370b84e68b87754e50a649cf78164177244f0",
-      "updated": "2026-10-11T16:21:27Z"
+      "sha256": "44fa07b8f379181cfac9a89c8fa672946d0e4aaeefe1fd3386cc3565abcb3c95",
+      "updated": "2026-10-11T17:59:34Z"
     }
   ]
 }

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v10.2.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v10.2.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v10.3.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v10.3.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/what-a-game-must-do.md

@@ -939,6 +939,16 @@ same push as `muted` and `reducedMotion`, and again whenever the player changes
 | `keyboardLayout` | `'wasd'` / `'arrows'` | Which keys move by default.                                                                                  |
 | `gamepadConfirm` | `'south'` / `'east'`  | Which face button confirms, by position: the bottom one (A on an Xbox controller) or the right one (B). The other one goes back. |
 | `vibration`      | `true` / `false`      | Your vibration toggle's starting state ([if your game vibrates](#if-your-game-vibrates)).                    |
+| `lookSensitivity` | `20` to `400`        | Look speed for touch, mouse and pen, as a percentage of the base speeds: `100` is 1×.                        |
+| `gamepadLookSensitivity` | `20` to `400` | Look speed for a gamepad stick, as a percentage: `100` is 1×.                                                |
+| `invertLookY`    | `true` / `false`      | Up/down look inverted: pushing up or dragging up looks down. Pitch only, never yaw.                          |
+| `touchMovement`  | `'floating'` / `'fixed'` | On a touch screen, a movement stick that appears where the thumb lands, or one fixed in place.            |
+
+The last four are the camera and controls settings: see
+[camera and look controls](#camera-and-look-controls) for telling the Arcade which of them your game
+uses, and for `gem.controls.look()`, which applies the two sensitivities and the invert for you. An
+older Arcade sends `recommended` without them; the SDK then fills each with its default (`100`,
+`100`, `false`, `'floating'`), so whenever `recommended` is not `null` all nine fields are there.
 
 **They are recommendations, and the player's own choice in your game always wins:**
 
@@ -955,7 +965,10 @@ same push as `muted` and `reducedMotion`, and again whenever the player changes
   `keyboardLayout`.
 
 ```js
-const DEFAULTS = { volume: 100, batterySaver: false, keyboardLayout: 'wasd', gamepadConfirm: 'south', vibration: true };
+const DEFAULTS = {
+  volume: 100, batterySaver: false, keyboardLayout: 'wasd', gamepadConfirm: 'south', vibration: true,
+  lookSensitivity: 100, gamepadLookSensitivity: 100, invertLookY: false, touchMovement: 'floating',
+};
 let chosen = {}; // ONLY what the player picked in your settings screen
 
 // The player's choice, then the Arcade's recommendation, then your own default.
@@ -985,6 +998,94 @@ player's choices are kept between sessions.
 ([sound](#sound-your-own-mute-control-and-the-arcades)), and `reducedMotion` is the player's
 accessibility setting, which your game honours.
 
+## Camera and look controls
+
+If your game turns a camera — a drag on a phone, a mouse under pointer lock, a gamepad's right
+stick — the player has four settings for it in the Arcade, per device, the way Roblox players do:
+**look sensitivity**, **gamepad look sensitivity**, **invert look up/down** and **touch movement**
+(a floating or a fixed thumbstick). They reach you in `gem.prefs.recommended`
+([the table above](#start-from-the-players-arcade-wide-defaults-gemprefsrecommended)). Two calls
+make them work.
+
+**1. Declare which ones your game uses — `gem.controls.declare`.** For each setting, `'player'`
+means you apply the Arcade's value (or the player's own choice in your settings, which still wins);
+`'game'` means your game decides it, and the Arcade's Settings shows that row as "Set by this game";
+leave out a setting your game does not use, and the Arcade says so beside it. Call it once at boot:
+
+```js
+gem.controls.declare({
+  lookSensitivity: 'player',
+  gamepadLookSensitivity: 'player',
+  invertLookY: 'player',
+  touchMovement: 'game', // this game always draws a fixed stick
+});
+```
+
+It is screen state, like [`gem.setWalletVisible`](#the-arcades-wallet-shown-unless-you-hide-it-never-drawn):
+each call is the whole answer, the latest wins, and the SDK holds it and sends it again after a
+reconnect. It returns `false` before the bridge is up (it is held and sent on connect) and under an
+embedder that does not show these settings; it never throws. A key or a value other than these is
+dropped.
+
+**2. Turn look input into a camera turn — `gem.controls.look()`.** It is pure math: it listens to
+nothing and moves no camera. Give it the deltas your input code already has; it returns radians to
+**add**, `yaw` positive turning right and `pitch` positive looking up, at Roblox's base speeds
+(`gem.controls.LOOK_BASE`: touch 1° across and 0.66° up/down per CSS px, mouse 0.5° and 0.385°,
+a stick 240° and 184.8° a second at full tilt), times the player's sensitivity, with the invert
+applied. It also does what is easy to get wrong: the stick's deadzone (0.1) and curve, dragging up
+to look up, and on touch a slower pitch as the camera nears straight up or down.
+
+```js
+import * as THREE from 'three';
+
+const camera = new THREE.PerspectiveCamera(70, innerWidth / innerHeight, 0.1, 500);
+camera.rotation.order = 'YXZ'; // yaw, then pitch
+let yaw = 0;
+let pitch = 0;
+const look = gem.controls.look(); // make one, keep it
+
+function turn({ yaw: dYaw, pitch: dPitch }) {
+  yaw -= dYaw; // three.js: a positive rotation.y turns LEFT, so subtract to turn right
+  pitch = THREE.MathUtils.clamp(pitch + dPitch, -1.45, 1.45); // your clamp, as always
+  camera.rotation.set(pitch, yaw, 0);
+}
+
+// Touch and pen: the change since the last event. A mouse: movementX/Y under pointer lock.
+let last = null;
+canvas.addEventListener('pointerdown', (e) => { last = { x: e.clientX, y: e.clientY }; });
+canvas.addEventListener('pointerup', () => { last = null; });
+canvas.addEventListener('pointermove', (e) => {
+  if (e.pointerType === 'mouse') {
+    if (document.pointerLockElement === canvas) turn(look.fromPointer(e.movementX, e.movementY, 'mouse'));
+    return;
+  }
+  if (!last) return;
+  turn(look.fromPointer(e.clientX - last.x, e.clientY - last.y, e.pointerType, pitch));
+  last = { x: e.clientX, y: e.clientY };
+});
+
+// The right stick, once per frame.
+function frame(dt) {
+  const pad = navigator.getGamepads().find(Boolean);
+  if (pad) turn(look.fromStick(pad.axes[2], pad.axes[3], dt));
+}
+```
+
+- **Read live.** The sensitivities and the invert are read from `gem.prefs.recommended` on every
+  call, so a change the player makes in the Arcade's Settings mid-game applies on the next move.
+  Do not copy them into variables at boot.
+- **The player's choice in your game wins.** If your settings screen has its own look speed or
+  invert, pass it — `gem.controls.look({ sensitivity: 1.5, invertY: true })`, or later
+  `look.set({ sensitivity: 1.5 })` — and that input stops following the Arcade.
+  `look.set({ sensitivity: undefined })` hands it back. `sensitivity` and `gamepadSensitivity` are
+  multipliers (`1` is the base speed); the Arcade's percentages are divided by 100 for you.
+- **Pass `pitch` for touch**, the camera's current pitch in radians (0 at the horizon, positive
+  looking up), or the slowdown near vertical is skipped. A mouse and a stick are never slowed.
+- **`touchMovement` is yours to draw.** The SDK has no thumbstick: read
+  `gem.prefs.recommended?.touchMovement` and draw a floating or a fixed one, or declare
+  `touchMovement: 'game'` if your game only has one kind.
+- **No camera, no call.** A game with no camera to turn declares nothing and never calls `look`.
+
 ## The Arcade's menu
 
 The Arcade keeps one menu button over every game, on every device. Its menu is how a player leaves

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "10.2.0",
+  "version": "10.3.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -811,10 +811,18 @@
             "A game may ignore it entirely.",
             "",
             "OPTIONAL because it is additive: a parent that predates it sends the",
-            "fields above without it, and the SDK reports `null`. All five fields",
-            "come together or the object is absent -- a parent that keeps only some",
-            "of them fills the rest from the defaults below rather than sending a",
-            "partial object.",
+            "fields above without it, and the SDK reports `null`. The first five",
+            "fields come together or the object is absent -- a parent that keeps",
+            "only some of them fills the rest from the defaults below rather than",
+            "sending a partial object.",
+            "",
+            "THE CAMERA AND CONTROLS FOUR ARE OPTIONAL INSIDE IT (owner decision",
+            "2026-10-11): `lookSensitivity`, `gamepadLookSensitivity`, `invertLookY`",
+            "and `touchMovement`, Roblox's per-device camera settings. A parent built",
+            "against an older SDK sends the object without them, and the SDK fills",
+            "each missing one with its default (100, 100, false, `floating`), so on",
+            "the game side all four are present whenever the object is. A game says",
+            "which of them it leaves to the player with `gem.controlsDeclare`.",
             "",
             "`muted`, `reducedMotion` and `showFrameStats` stay where they are, at",
             "the top of this message, and keep their meaning: they are the Arcade's",
@@ -829,8 +837,8 @@
             "WIDENING AN ENUM HERE IS NOT FREE. The generated validator refuses the",
             "WHOLE message on any field it rejects, so a value an older frame does",
             "not know would cost it `muted` and `reducedMotion` as well. A new",
-            "keyboard layout or confirm button needs a capability the frame",
-            "advertises before a parent may send it."
+            "keyboard layout, confirm button or touch-movement mode needs a",
+            "capability the frame advertises before a parent may send it."
           ],
           "fields": {
             "volume": {
@@ -856,6 +864,42 @@
             "vibration": {
               "kind": "boolean",
               "$comment": "Whether the player wants vibration and controller rumble. Default true."
+            },
+            "lookSensitivity": {
+              "kind": "int",
+              "min": 20,
+              "max": 400,
+              "optional": true,
+              "$comment": "Look speed for touch, mouse and pen, as a percentage of the base speeds (Roblox's MouseSensitivity): 100 is 1x, 20..400. Default 100 when absent. The Arcade's slider has eleven positions (20, 36, 52, 68, 84, 100, 160, 220, 280, 340, 400) but any integer in range is valid."
+            },
+            "gamepadLookSensitivity": {
+              "kind": "int",
+              "min": 20,
+              "max": 400,
+              "optional": true,
+              "$comment": "Look speed for a gamepad stick, as a percentage of the base speed (Roblox's GamepadCameraSensitivity): 100 is 1x, 20..400. Default 100 when absent."
+            },
+            "invertLookY": {
+              "kind": "boolean",
+              "optional": true,
+              "$comment": "Up/down look inverted: pushing up or dragging up looks DOWN (Roblox's CameraYInverted). Flips pitch only, never yaw. Default false when absent."
+            },
+            "touchMovement": {
+              "kind": "string",
+              "maxLength": 16,
+              "format": "code",
+              "optional": true,
+              "$comment": [
+                "On a touch screen, the movement thumbstick: `floating` appears where",
+                "the thumb lands (Roblox's Dynamic Thumbstick), `fixed` stays in one",
+                "place (Roblox's Thumbstick). Stored on every device, meaningful on",
+                "touch. Default `floating` when absent.",
+                "",
+                "A CODE, NOT AN ENUM, so the vocabulary can grow without costing an",
+                "older frame the whole message (see WIDENING above): a parent sends",
+                "only `floating` or `fixed` today, and the SDK maps any other value to",
+                "the default, `floating`, so a game only ever sees those two."
+              ]
             }
           }
         }
@@ -2511,6 +2555,83 @@
       "rateLimit": { "perMinute": 60 }
     },
 
+    {
+      "type": "gem.controlsDeclare",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Which of the player's camera and controls settings this game leaves to",
+        "the player and which it decides itself — Roblox's UserChoice versus",
+        "`StarterPlayer.Dev*`, declared at runtime (owner decision 2026-10-11).",
+        "The settings are the four camera and controls fields of",
+        "`gem.prefs.recommended`; the parent's Settings panel shows each row",
+        "according to this.",
+        "",
+        "  'player'  the game applies the Arcade's value (or the player's own",
+        "            in-game choice, which wins); a normal row",
+        "  'game'    the game decides this itself; the parent shows the row",
+        "            disabled, \"Set by this game\"",
+        "  absent    the game does not use this setting at all",
+        "",
+        "SCREEN STATE, NOT A TOGGLE, like `gem.walletDisplay`. Each message is the",
+        "whole answer and the latest one wins; nothing accumulates. The SDK holds",
+        "the latest declaration and re-sends it after every handshake, deduped per",
+        "connection, so a parent that reconnects never shows a stale panel. With no",
+        "message at all, the parent treats every setting as unused by this game.",
+        "A declaration is per game session: the parent forgets it when the game is",
+        "left.",
+        "",
+        "EACH VALUE IS A CODE, NOT AN ENUM, and an unknown KEY is ignored, so the",
+        "vocabulary can grow without an older parent refusing the whole message:",
+        "the SDK drops any key or value it does not know before sending, and a",
+        "parent ignores any it does not know on receipt — treating that setting",
+        "as absent.",
+        "",
+        "A PRESENTATION REQUEST ONLY. Not an authorization control: it changes",
+        "which rows of the parent's own panel are editable, and nothing the game",
+        "receives.",
+        "",
+        "Gated by `controls`: sent only to a parent that advertised it."
+      ],
+      "fields": {
+        "uses": {
+          "kind": "object",
+          "$comment": "One optional entry per setting, each `player` or `game`. An empty object is a valid declaration: the game uses none of them.",
+          "fields": {
+            "lookSensitivity": {
+              "kind": "string",
+              "maxLength": 16,
+              "format": "code",
+              "optional": true,
+              "$comment": "`player` or `game` for `gem.prefs.recommended.lookSensitivity`."
+            },
+            "gamepadLookSensitivity": {
+              "kind": "string",
+              "maxLength": 16,
+              "format": "code",
+              "optional": true,
+              "$comment": "`player` or `game` for `gem.prefs.recommended.gamepadLookSensitivity`."
+            },
+            "invertLookY": {
+              "kind": "string",
+              "maxLength": 16,
+              "format": "code",
+              "optional": true,
+              "$comment": "`player` or `game` for `gem.prefs.recommended.invertLookY`."
+            },
+            "touchMovement": {
+              "kind": "string",
+              "maxLength": 16,
+              "format": "code",
+              "optional": true,
+              "$comment": "`player` or `game` for `gem.prefs.recommended.touchMovement`."
+            }
+          }
+        }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
+
     {
       "type": "gem.menu",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -218,6 +218,12 @@
         "gem.menu",
         "gem.menuSelect"
       ]
+    },
+    "controls": {
+      "implemented": true,
+      "gates": [
+        "gem.controlsDeclare"
+      ]
     }
   }
 }