@indiegems/gem-web-sdk 10.1.1 → 10.3.0

package/docs/changelog.md

@@ -16,6 +16,38 @@ 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.
+
+### Rebuild
+
+- The match object on the server types now has two more methods, setBackfill and reportPlayers, besides end. Recompile your server. If you wrote your own implementation or test double of the server or match server types, add the two new methods or it will no longer type-check.
+- The list of frame-to-parent message names, the frame message type and the capability type each gained a new member for the avatar picker. Recompile. If your code switches exhaustively over any of them, or checks that every member is handled, add a case for the new avatar picker member.
+- The order source type gained two new values, one for test account provisioning and one for developer grants, and each progression state entry in a paginated response may now carry an optional completion threshold. Recompile. If you switch exhaustively over order sources, handle the new values.
+
+### New capability
+
+- Games running inside the Arcade can now read the player's current Arcade avatar from GemPlayer.avatarIconId. It is only set when the value is a valid identifier, and the Arcade sends the player again whenever the worn avatar changes, so listen for player updates rather than reading it once. Games can also ask the Arcade to open its avatar picker. Check Gem.avatarPickerAvailable first, then call Gem.openAvatarPicker. It returns false outside the Arcade, before the connection is ready, when the Arcade does not offer the picker, or when you call it too often, and it never throws or waits. Nothing answers the request directly; the outcome is an updated player.
+- If your code hosts a game frame, you can now pass the avatar identifier when sending player information and handle the avatar picker request through the new host callback and option. Incoming picker requests have a new message type with its own validator. Without a handler, the request is refused.
+- Dedicated game servers can now control matchmaking backfill. Call setBackfill to stop or restart the platform topping up a running match from the matchmaking queue, optionally with a seat count, and it returns the resulting backfill state. Call reportPlayers to tell the platform whether each player has connected, never showed up, or left. The last two remove the player from the room. The server SDK also reports each joining player as connected on its own, which gives a seat filled from the queue a time limit. If the platform does not offer these routes, it stops trying for that match after one refused call. The matching low-level server API operations and request and response types are available too.
+
 ## 10.1.1
 
 Upgrading from 10.1.0. Impact: none.

package/docs/getting-started.md

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

package/docs/manifest.json

@@ -33,8 +33,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "7f4f97b99bd6c851c26ae076485a592d80e4736a5efc472dfac17100003d034a",
-      "updated": "2026-10-11T07:34:02Z"
+      "sha256": "daae6b71cecc9761bc1e3ed5603c5d8f366e0533ce4ecc6d6c57f546efe1a292",
+      "updated": "2026-10-11T18:22:44Z"
     },
     {
       "file": "cross-promotion.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "17f3b522b1b67a1b8d22667e1a282832c6389d08cdd8f833126f9dcf2b7114dd",
-      "updated": "2026-10-11T07:34:02Z"
+      "sha256": "fd566ed7d7f0b1b2b9bea823de5455d2ee9a66072e7303df1bc5c12c1acddcbe",
+      "updated": "2026-10-11T18:22:44Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -113,8 +113,8 @@
     },
     {
       "file": "rooms-and-matches.md",
-      "sha256": "23540a20bdd8c8d058eb06d8ef11085ffd8eaaeeaadc93a807608b7c279e240c",
-      "updated": "2026-10-10T18:05:31Z"
+      "sha256": "be22367f8dc9147e815a14ddb417788fa6614720a0df4f9f01624bf4667877d3",
+      "updated": "2026-10-11T10:17:11Z"
     },
     {
       "file": "saving-player-progress.md",
@@ -123,8 +123,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "eabaca8643bb58c23b1d476ed9f6045b8b82bef43c897205c872e5884ac6660f",
-      "updated": "2026-10-11T07:34:02Z"
+      "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": "a339443ece37e5a5311a05ff946a081ac6e8557d29e2ab59b90832e4ad40fc5d",
-      "updated": "2026-10-10T20:42:00Z"
+      "sha256": "44fa07b8f379181cfac9a89c8fa672946d0e4aaeefe1fd3386cc3565abcb3c95",
+      "updated": "2026-10-11T17:59:34Z"
     }
   ]
 }

package/docs/rooms-and-matches.md

@@ -770,6 +770,13 @@ else backToMenu(outcome.status);
 `matchmaking_not_enabled`**. `fill_window_seconds` in that block is how long a queue holds out for
 `max_players` before it accepts `min_players`. The block cannot be combined with `auto_start_host`.
 
+**A running match can take late arrivals.** Add `backfill: { enabled: true }` to the template's
+`matchmaking` block (the template must also allow joining in progress) and a match the platform made
+is topped up from the queue: a ticket that arrives after the match started is seated in it when it
+has an open seat, instead of waiting for a whole new lobby. To the queueing player nothing is
+different — the ticket ends `matched`, in a room whose match is already running. The match's server
+decides how long that lasts; see [the server guide](server-bundles.md#topping-a-running-match-up-from-the-queue).
+
 **A ticket names every mode the player accepts**, one to eight templates, and is matched under
 whichever fills first. That is one ticket, not several: a player can be on one ticket at a time, across
 every game.

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.1.1/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v10.1.1/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
 ```
 
@@ -769,6 +769,50 @@ publish is your code plus whatever of the SDK it reached. No API origin is baked
 that arrives on `host.apiBaseUrl` at runtime. (`/server` remains as the server-only door for a
 bundle that wants nothing of the browser half in its graph.)
 
+### Topping a running match up from the queue
+
+A match the platform matchmade from a room template with `matchmaking.backfill` turned on takes
+waiting players into its open seats from the moment it starts, and again whenever a seat frees. Your
+server does nothing to get that. Two calls let it take control:
+
+```js
+// Nobody new once the final round starts.
+await gem.match.setBackfill({ open: false });
+
+// Open again, for at most two more players.
+await gem.match.setBackfill({ open: true, seats: 2 });
+```
+
+- **Closing removes nobody**, and a player already on the way in still arrives.
+- **`seats` counts down** as seats fill and backfill stops at 0. Omit it for every open seat.
+- It rejects with `GemApiError.code === 'backfill_not_enabled'` on a match the platform is not
+  topping up: the room template has no backfill, or the room was not matchmade.
+
+```js
+leave(playerId) {
+  // This game does not let a player back in once they quit.
+  void gem.match.reportPlayers([{ playerId, state: 'left' }]);
+}
+```
+
+`gem.match.reportPlayers` tells the platform about players, one of three ways:
+
+| `state` | Meaning | Effect |
+| --- | --- | --- |
+| `connected` | the player has connected to your server | noted |
+| `no_show` | the player was given a seat and never connected | removed from the room; the seat is free |
+| `left` | the player was in the match and is gone for good | removed from the room; the seat is free |
+
+⚠️ **`left` is final.** A removed player is not put back by reconnecting; they have to join again.
+Do not report it from every `leave()` in a game where a dropped connection is expected to return.
+
+**You do not report `connected` yourself** in a bundle built with `defineServer`: the SDK reports
+each player as they join. That report is what gives a seat filled from the queue a time limit. Once
+your server has reported anyone connected, a player the platform seats afterwards has a limited
+time to connect too, and is removed if they do not — so a seat is not held by somebody who closed
+the tab on the way in. A bundle that drives the lifecycle by hand reports `connected` from its own
+`join`, or gets no time limit.
+
 ### What is not on the server surface, and why
 
 `gem.p2p`, `gem.dedicatedServer`, `gem.me`, `gem.characters` and `gem.gameConfig` are browser-only.

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
@@ -1310,6 +1411,44 @@ your own page. It carries a day count and never a date, and nothing about what t
 This is a platform rule, not advice — see
 [platform rules §8](platform-rules.md#8-a-players-boost-is-for-display-never-a-gate).
 
+### Arcade avatars: the character the player wears, and changing it mid-game
+
+Some games draw **Arcade avatars**: whole characters the player owns as Arcade portrait items and
+wears as their Arcade portrait (store tag `arcade-avatars`). Such a game keys its own model on
+**`avatarIconId`**, the worn item's id — on `gem.player` for the signed-in player, as on every room
+member — rather than on the thumbnail.
+
+**Redraw from `onPlayer`, not from boot alone.** The Arcade sends the player again whenever the
+portrait they wear changes, including mid-game from the Arcade's own menu, without your game
+asking. `onPlayer` runs and `gem.player` holds the new value; a field missing from the new player
+is missing now.
+
+**A "Change avatar" button belongs in your own UI**, and `gem.openAvatarPicker()` opens the
+Arcade's picker from it. The Arcade pauses your game while the picker is open, saves the player's
+choice, sends the player again, and resumes you:
+
+```js
+const gem = createGem({ onPlayer: (p) => hero.wear(avatarOfItem(p.avatarIconId)) });
+
+changeAvatar.hidden = !gem.avatarPickerAvailable; // read it live
+changeAvatar.onclick = () => {
+  if (!gem.openAvatarPicker()) changeAvatar.hidden = true;
+};
+```
+
+- **`gem.avatarPickerAvailable`** says whether the Arcade will open its picker here. It is `false`
+  outside the Arcade, before the bridge is up, and under an embedder that has no picker.
+- **`gem.openAvatarPicker()`** returns `true` when the Arcade was asked and `false` when it was not
+  (the same cases, or more than six asks a minute). It never throws and never waits.
+- **Nothing answers it.** The outcome is the new player through `onPlayer`. A player who closes the
+  picker unchanged produces nothing, so never wait for an answer or poll `gem.player`.
+
+**Your server is not told.** A server-authoritative game reads each member's `avatar_icon_id` from
+the room read (`GET /v1/games/{game_id}/game-rooms/{game_room_id}`, or `gem.room.get()` on a
+dedicated server), and nothing pushes a change to it. So when `onPlayer` brings a different
+`avatarIconId`, have your client tell your server, and have the server **re-read the room** —
+never trust the id the client sends.
+
 ## Which backend — no longer yours, and what the override is for
 
 The Arcade names the API root on every `gem.token`, and the SDK sends there. Your game never types

package/package.json

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

package/schema/bridge.v1.json

@@ -547,7 +547,17 @@
         "",
         "ADDITIVE, so no `v` bump: every new field is optional (an older parent",
         "sends none of them and must still be accepted), and an older frame",
-        "ignores fields it does not know (rule 4)."
+        "ignores fields it does not know (rule 4).",
+        "",
+        "RE-SENT WHENEVER IT CHANGES, and always the whole message. The parent",
+        "sends it after the handshake, again whenever the identity changes (a",
+        "sign-in in place), and again whenever the WORN PORTRAIT changes — the",
+        "player picked another one in the parent's own avatar picker, whether a",
+        "game opened it (`gem.requestAvatarPicker`) or the player did, mid-game,",
+        "from the parent's menu. A frame replaces its whole copy with each one; a",
+        "field absent from the latest message is absent now. There is no other",
+        "signal that the portrait changed, and no reply to the request that",
+        "opened the picker: this message is the outcome."
       ],
       "fields": {
         "untrusted": {
@@ -586,6 +596,30 @@
           "optional": true,
           "$comment": "The portrait's THUMBNAIL (gem-api `avatar_icon_url`). Absent means no portrait; a parent never sends an empty string. Structurally validated only — https (or loopback), no userinfo, parsed rather than regex-matched. It is NOT origin-pinned: the validator is a pure function with no configuration, so it cannot know the CDN origin. An earlier version of this comment claimed a pin that the generated code did not emit — a documented control that did not exist. THE CONSUMER MUST PIN THE ORIGIN before putting this in an <img src> — the SDK's `platformIconUrl` does — or a hostile parent supplies a request-time beacon carrying the Referer."
         },
+        "avatarIconId": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": [
+            "The item-definition id of the portrait the player WEARS (gem-api",
+            "`avatar_icon_id`, a UUID) — the same id a game-room member's",
+            "`avatar_icon_id` carries, so a game that draws whole characters as",
+            "Arcade avatars (store tag `arcade-avatars`) can map it to its own",
+            "model rather than to the thumbnail.",
+            "",
+            "Platform-assigned, so it sits on the trusted side of the `untrusted`",
+            "split, beside `playerId` and the badges' `itemId`. Absent means no",
+            "portrait is worn, or an older parent; a parent never sends an empty",
+            "string. Sent with `avatarIconUrl` and describing the same item.",
+            "",
+            "BOUNDED HERE, SHAPE-CHECKED BY THE FRAME. The schema has no pattern",
+            "kind, and a format here would cost a frame the WHOLE message for one",
+            "bad id — its name and portrait with it. So the validator bounds the",
+            "length only, and the frame keeps the value only when it is a UUID",
+            "(`8-4-4-4-12` hex, either case), dropping anything else to absent,",
+            "the way it drops a non-digit `discriminator`."
+          ]
+        },
         "badges": {
           "kind": "array",
           "maxItems": 2,
@@ -777,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",
@@ -795,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": {
@@ -822,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."
+              ]
             }
           }
         }
@@ -2477,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",
@@ -2673,6 +2828,64 @@
       }
     },
 
+    {
+      "type": "gem.requestAvatarPicker",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask the arcade to open its own avatar picker over the game, so the",
+        "player can change the portrait they wear without leaving it — the",
+        "\"Change avatar\" button of a game that draws Arcade avatars. Gated by",
+        "the `avatarPicker` capability: sent only to a parent that advertised",
+        "it.",
+        "",
+        "WHY THE PARENT OPENS IT. Wearing a portrait is an account act: the",
+        "account surface refuses the game-scoped token by construction, and the",
+        "list of portraits a player owns is theirs, not the game's. So the game",
+        "ASKS, and the parent, which holds the account session, renders the",
+        "picker in its own chrome and saves the choice.",
+        "",
+        "NO FIELDS, AND NO REPLY. The game names nothing — not an item, not a",
+        "filter, not a line of text: which portraits are offered and what the",
+        "picker says are the parent's. And nothing answers this message. THE",
+        "OUTCOME IS A NEW `gem.player`: when the worn portrait changes, the",
+        "parent re-sends it with the new `avatarIconId` and `avatarIconUrl`, as",
+        "it does for a change the player makes from the parent's menu without",
+        "the game asking. A reply would be a second copy of an identity fact",
+        "(`gem.signInResult`'s argument), and the picker may stay open for as",
+        "long as the player browses, which no wait should be sized for. A",
+        "player who closes it unchanged produces nothing at all.",
+        "",
+        "WHAT THE PARENT OWES, none of which this schema can enforce:",
+        "",
+        "  ADVERTISE IT ONLY WHERE IT OPENS. `avatarPicker` is the game's cue to",
+        "  show its own Change avatar button, so a parent with no picker on this",
+        "  surface does not advertise it. A player who cannot wear a portrait",
+        "  yet (no account) is the parent's to explain in its own chrome.",
+        "",
+        "  PAUSE THE GAME while the picker is open (`gem.pause`) and lift it when",
+        "  the picker closes, returning focus to the frame. When the portrait",
+        "  changed, send `gem.player` BEFORE lifting the pause, so the game",
+        "  redraws before it runs again.",
+        "",
+        "  ONE AT A TIME. An ask arriving while the picker, or any other sheet",
+        "  that holds the stage, is open is dropped. A parent may also drop an",
+        "  ask that arrives without transient user activation in the frame, or",
+        "  too soon after the player closed the last one.",
+        "",
+        "  SEND NOTHING BACK for a refusal — no error, no acknowledgement.",
+        "",
+        "NOT AN AUTHORIZATION CONTROL. The player's own choice in the parent's",
+        "picker is the control, and the account-session save is the",
+        "enforcement."
+      ],
+      "fields": {},
+      "rateLimit": {
+        "perMinute": 6,
+        "$comment": "Bounds a BUGGY game. NOT a security control: a hostile game posts on the port it holds rather than calling the SDK. What stops a game nagging is the parent's one-at-a-time rule and its freedom to drop an ask."
+      }
+    },
+
     {
       "type": "gem.vibrate",
       "direction": "frameToParent",