@indiegems/gem-web-sdk 10.2.0 → 10.3.1

package/docs/brand-art.md

@@ -75,7 +75,7 @@ These are the Arcade's own icon renders — the files its wallet draws — with
 for byte, apart from stripping the colour-space and resolution tags every browser already assumes. They are the gem
 of the arcade's Gems flight — a 3D model rendered in Blender, a round cut with the icon's six facet
 colours — at rest and without its motion blur, so the gem a player sees in your price is the gem
-that flies into their wallet. Each size has its own recipe, in CSS px, so it carries the same visual
+that flies into the Gem button when they are paid. Each size has its own recipe, in CSS px, so it carries the same visual
 weight on every screen:
 
 | Size | Outline | Girdle line | Facet lines | Sparkle |
@@ -282,7 +282,8 @@ too, with the ticket in place of the gem. Amended 2026-09-30 for the earn allowa
 decision of that date); the ruling's other rules are unchanged. In rules:
 
 - **Keep no Gems counter.** Your game shows no Gems balance, running total or wallet of its own, on
-  any screen. The arcade's wallet is the only place Gems accrue, and the only place a total is shown.
+  any screen. The arcade's wallet is the only place Gems accrue, and the only place a total is shown
+  — in the Gem Arcade, the Gem menu, which the player opens from the Gem button at the top-left.
 - **Draw no Gems flight or celebration of your own.** No particles flying to a corner, no counting-up
   number, no burst of gems. `gem.cueReward` is the animation, and the arcade draws it.
 - **Show no Gems amount at all when you are not connected to the arcade.** Without the arcade there is
@@ -306,8 +307,9 @@ decision of that date); the ruling's other rules are unchanged. In rules:
   with the canvas's `getBoundingClientRect()`.
 
   A Tickets payout is cued the same way, from the ticket, with `currencySlug: 'ARCADE_TICKETS'`. The
-  arcade's wallet shows Gems and Tickets side by side and flies each payout into the total of the
-  currency the cue names, so the slug is what decides where your ticket lands.
+  slug decides what flies — gems or tickets — and which total the platform moves. In the Gem Arcade
+  every payout flies into the Gem button at the top-left of your frame; no wallet is drawn over
+  your game.
 - **If `cueReward` returns `false`, do nothing.** There is no fallback celebration. `false` means the
   arcade will not show the payout here — the bridge is not up, or the embedder has no wallet — and
   your game does not replace it with one of its own. Your reward screen still says what was earned;

package/docs/changelog.md

@@ -16,6 +16,28 @@ 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.1
+
+Upgrading from 10.3.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
+## 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/daily-challenges.md

@@ -320,11 +320,11 @@ Four things to know before you ship one:
   in" is not in general when the allowance refills. Each date's allowance is spent once, whatever
   the player does to their time zone.
 
-**When a completion pays a platform currency, show it where it happened.** The arcade draws the
-player's Gems and Tickets in its own chrome, and without a cue a payout lands there silently, in a
-corner the player is not looking at. At the moment your game shows the challenge complete, call
+**When a completion pays a platform currency, show it where it happened.** The arcade shows the
+player's Gems and Tickets in its own chrome, and without a cue a payout flies from the middle of
+your frame, not from the payout the player is looking at. At the moment your game shows the challenge complete, call
 `gem.cueReward` with the currency that paid (`GEMS` or `ARCADE_TICKETS`) and the centre of its icon
-beside the payout on your completion screen, and the payout flies from there into the wallet:
+beside the payout on your completion screen, and the payout flies from there into the Gem button:
 [inventory-and-catalogs.md](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet).
 **If it returns `false`, do nothing** — no celebration of your own, no counter, no flight;
 platform-currency display belongs to the arcade, and a game not connected to it shows no

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.1"
 }
 ```
 

package/docs/inventory-and-catalogs.md

@@ -589,14 +589,15 @@ the source progression from a function the player calls, on a progression that o
 ### Showing the reward land in the arcade's wallet
 
 **Platform-currency display belongs to the arcade** (the creator's ruling, 2026-09-24) — Gems and
-Tickets alike. The arcade draws the player's platform currencies in its own chrome while your game
-runs, and moves a total when the platform confirms a grant. Your game keeps no counter or balance
+Tickets alike. The arcade shows the player's platform currencies in its own chrome — in the Gem
+Arcade, the Gem menu the player opens from the Gem button at the top-left of your frame; no wallet
+is drawn over your game — and moves a total when the platform confirms a grant. Your game keeps no counter or balance
 of a platform currency of its own, draws no flight or celebration of its own, and shows no
 platform-currency amount at all when it is not connected to the arcade.
 
 What your game does is ask for the payout to start on **your** screen, from the currency's icon (or
-hero) beside the reward, so the currency flies from there into the wallet and the total bounces up
-as it lands. A Gems payout is cued from the gem:
+hero) beside the reward, so the currency flies from there into the arcade — in the Gem Arcade,
+into the Gem button, which pops as each mark lands. A Gems payout is cued from the gem:
 
 ```js
 const { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem element's own box
@@ -609,8 +610,10 @@ gem.cueReward({
 
 `origin` is the **centre of the gem on screen** — measure the gem element itself, not the row or
 panel around it. A Tickets payout is the same call with `currencySlug: 'ARCADE_TICKETS'`, from the
-ticket: the slug decides which total the payout flies into. **If `cueReward` returns `false`, do
-nothing**: there is no fallback celebration.
+ticket: the slug decides what flies and which total moves. **A payout you do not cue still flies**
+in the Gem Arcade, from the middle of your frame, once the platform confirms it — cue it so the
+flight starts where the player is looking. **If `cueReward` returns `false`, do nothing**: there is
+no fallback celebration.
 `false` means the arcade will not show it here — the bridge is not up, or the embedder has no wallet
 — and your game does not draw one of its own in its place.
 
@@ -898,7 +901,8 @@ buyButton.disabled = !gems || gems.balance < price; // can the player afford it?
 ```
 
 **Read it to decide, never to display.** Platform-currency display belongs to the arcade: its
-wallet shows the player's Gems and Tickets totals while your game runs, and your game keeps no
+wallet — the Gem menu, in the Gem Arcade — shows the player's Gems and Tickets totals while your
+game runs, and your game keeps no
 counter, balance or wallet total of either of its own ([brand-art.md](brand-art.md) §5). Use the
 balance to enable a purchase or to say "not enough Gems" — not to draw a number.
 

package/docs/manifest.json

@@ -28,13 +28,13 @@
     },
     {
       "file": "brand-art.md",
-      "sha256": "cf54939a0fcee1f5a6e11b9de52b5ed498ec8c373683e92aa5bc6654b12eb0ab",
-      "updated": "2026-10-01T03:49:20Z"
+      "sha256": "87267dca53e5506b1aee77ac9819aef8025c8e0de2780e65a2ea3b7236a9c0ab",
+      "updated": "2026-10-11T18:48:12Z"
     },
     {
       "file": "changelog.md",
-      "sha256": "d7178e17c79418dc26cb685c667eb998b0d09dca6b1b2760268812c6af466151",
-      "updated": "2026-10-11T16:47:39Z"
+      "sha256": "25047a1c8498f92990b4d50768cf49d1cd4acd2a27dd42db595ca322aa56a2a9",
+      "updated": "2026-10-11T19:08:27Z"
     },
     {
       "file": "cross-promotion.md",
@@ -43,8 +43,8 @@
     },
     {
       "file": "daily-challenges.md",
-      "sha256": "f4842b2fe01c8780020326f4722ab69dc01c1f40e1e6455cf2fb27752094383d",
-      "updated": "2026-10-10T14:37:50Z"
+      "sha256": "0423168355c22724e705def15ca19a5651b7f0da3598ec5aabcc69c32e0bb401",
+      "updated": "2026-10-11T18:48:12Z"
     },
     {
       "file": "dedicated-server-flow.md",
@@ -68,13 +68,13 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "5758f3a68307af4650e6af3e74cba48e7110dd9c405aefa33b4eaa1c73b3f85a",
-      "updated": "2026-10-11T16:47:39Z"
+      "sha256": "327be77c7b742f7ecfb3ca8f4869480e72942ea9f7293e25634c47c056a38eae",
+      "updated": "2026-10-11T19:08:27Z"
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "3e0f71db5b4f5d2d256289f90ffec3ed2887a70b1e72b02f55ec64815043d900",
-      "updated": "2026-10-09T00:13:03Z"
+      "sha256": "fecd1299ef19bc50ea17abe96bbe49f62dc366a9fc0f354c843a42b2d5a2f9e2",
+      "updated": "2026-10-11T18:48:12Z"
     },
     {
       "file": "leaderboards.md",
@@ -123,8 +123,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "a0e995c9a4f05515f39c5958918bd38bccb53e1c20bf13959f81d7694aa72ef0",
-      "updated": "2026-10-11T16:47:39Z"
+      "sha256": "c6bf3689c928b6cb24d86faa380e6ed4bece1f3dd6e8dfc71c1ff9de1ed0dd42",
+      "updated": "2026-10-11T19:08:27Z"
     },
     {
       "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": "c5797bd913fbd8c62fb3fbe83b6c8c6cb22f5aec984c0d56f3f0198c917fee7d",
+      "updated": "2026-10-11T18:48:12Z"
     }
   ]
 }

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.1/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v10.3.1/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

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

@@ -702,53 +702,49 @@ the `var()` above, or read `gem.viewport`. The release checklist looks for the b
 
 ### The arcade's own controls: reserved areas
 
-On a phone your game is full-bleed, and the arcade keeps one row of its own over the top of it:
-
-- **The menu button**, in the **top-right corner**, always there. It opens
-  [the Arcade's menu](#the-arcades-menu): Return to the Arcade, mute, the player's Arcade-wide
-  settings and the rest. Not your settings: those are [your own button](#game-settings).
-- **The player's wallets** (Gems, Tickets, their achievement score), in the **middle of the row**,
-  [there unless your game hides them](#the-arcades-wallet-shown-unless-you-hide-it-never-drawn),
-  during play as well as on your menus. They are translucent, so your game shows through them — but they are still the Arcade's,
-  and still taps the Arcade takes.
+The Arcade keeps **one control of its own over every game**, on every device — a phone's full-bleed
+game, a framed or full-window game on a desktop, a tablet or a TV in native fullscreen:
+
+- **The Gem button**, the Gem Arcade's gem, in the **top-left corner**, always there (a touch target, about
+  50px across). It opens [the Arcade's menu](#the-arcades-menu): Return to the Arcade, the player's Gems,
+  Tickets and achievement score, mute, the player's Arcade-wide settings and the rest. Not your
+  settings: those are [your own button](#game-settings).
+- **Nothing else.** The player's wallets (Gems, Tickets, their achievement score) are **not** drawn
+  over your game: the player opens the Gem menu to see them, and every platform-currency payout
+  flies into the Gem button ([the Arcade's wallet](#the-arcades-wallet-in-the-gem-menu-never-drawn-by-you)).
+  When the player switches the frame-rate readout on, it sits beside the gem and is reserved the
+  same way.
 
 **The top of the screen has one layout, in every game:**
 
-| Where                                        | Whose        | What goes there                                                                                                                                                                                              |
-| -------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **Top-left**                                 | yours        | Your **Home / Back** buttons, drawn when a screen needs them, in the space to the left of the wallets. They move around _inside_ your game — back to your level select or title screen — and never leave it. |
-| **Middle and top-right**                     | the Arcade's | Its wallets and its menu button. Nothing of yours.                                                                                                                                                           |
-| **Centre and right, below the Arcade's row** | yours        | Your **information**: score, moves, a timer, a level name. It starts under the bottom of the Arcade's row, never beside it or under it.                                                                      |
-
-Keep the left for Home / Back even on a screen that has neither today: a player learns where "back"
-is once, across every game, and information that sits there on one screen teaches them the wrong
-thing on the next.
+| Where                                | Whose        | What goes there                                                                                                                                                                                         |
+| ------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Top-left corner**                  | the Arcade's | Its Gem button. Nothing of yours under it.                                                                                                                                                              |
+| **Top-left, right of the Gem**       | yours        | Your **Home / Back** buttons, drawn when a screen needs them, level with the Gem and just to its right. They move around _inside_ your game — back to your level select or title screen — and never leave it. |
+| **Centre of the top row**            | yours        | Your **information**: score, moves, a timer, a level name.                                                                                                                                              |
+| **Top-right**                        | yours        | Your **settings** button ([Game settings](#game-settings)).                                                                                                                                             |
 
-**Your settings button goes top-right, clear of the Arcade's controls**: never under one, and below
-any the Arcade keeps in that corner. [Game settings](#game-settings) shows how to place it.
+Keep the spot beside the Gem for Home / Back even on a screen that has neither today: a player
+learns where "back" is once, across every game, and information that sits there on one screen
+teaches them the wrong thing on the next.
 
-**How much room the top-left has.** The menu button is about 48px across — the size of a Home or
-Back button. With every wallet shown, the narrowest phones (360px wide) leave roughly 68px to the
-left of the wallets: room for **one** button. Two buttons, or a wide one, go on their own row below
-the Arcade's. Do not copy those numbers — read the space, as below.
+**Your settings button goes top-right**, clear of any Arcade control: under the Gem Arcade there is
+none in that corner, but another embedder may keep one there. [Game settings](#game-settings) shows
+how to place it.
 
 Those rectangles of your frame are **reserved**: keep essential UI and every touch target out of
-them. **Never hard-code their size or height.** They differ by phone, and in native fullscreen the
-whole row may rise into the camera band — read them, as below.
+them. **Never hard-code their size or position.** They differ by phone, and in native fullscreen the
+gem may rise into the camera band — read them, as below.
 
-An inset cannot say that — as a top inset, a button a few dozen pixels wide would take your whole top
-strip. So `gem.viewport` also carries the rectangles, in the same CSS pixels of your frame, measured
-from its top-left corner — one per wallet shown, and one for the menu button:
+An inset cannot say that — as a left or top inset, a button a few dozen pixels wide would take a whole
+strip of your screen. So `gem.viewport` also carries the rectangles, in the same CSS pixels of your
+frame, measured from its top-left corner — one for the Gem button, and one for the frame-rate
+readout while the player shows it:
 
 ```json
 {
   "insets": { "top": 47, "right": 0, "bottom": 34, "left": 0 },
-  "reserved": [
-    { "x": 68, "y": 51, "width": 72, "height": 28 },
-    { "x": 144, "y": 51, "width": 72, "height": 28 },
-    { "x": 220, "y": 51, "width": 72, "height": 28 },
-    { "x": 304, "y": 51, "width": 48, "height": 48 }
-  ]
+  "reserved": [{ "x": 8, "y": 55, "width": 52, "height": 52 }]
 }
 ```
 
@@ -756,59 +752,44 @@ from its top-left corner — one per wallet shown, and one for the menu button:
 `--gem-safe-*` before anything else hears the push: `--gem-reserved-tl-width` and
 `--gem-reserved-tl-height`, and the same pair for `tr`, `bl` and `br` — how far that corner's
 reserved rectangles reach in from its two edges. A rectangle belongs to the corner its centre lies
-nearest to.
-
-⚠️ **The wallets sit in the middle, so they count toward BOTH top corners.** A wallet left of
-centre is a top-left rectangle, one right of centre a top-right one. While wallets are shown,
-`--gem-reserved-tl-height` is the bottom of the wallets and `--gem-reserved-tl-width` reaches to the
-middle of the screen — even though the corner itself, left of the first wallet, is clear. So:
+nearest to. Under the Gem Arcade the Gem button is a top-left rectangle, so:
 
 ```css
-/* your information — score, moves, a timer — below the WHOLE of the arcade's row: the taller of
-   the two top corners. It moves up by itself when gameplay hides the wallets. */
-#info {
-  top: max(
-    var(--gem-safe-top, env(safe-area-inset-top, 0px)),
-    var(--gem-reserved-tl-height, 0px),
-    var(--gem-reserved-tr-height, 0px)
-  );
-  right: var(--gem-safe-right, 0px);
-}
-/* ONE Home or Back button, level with the arcade's row, in the clear corner to the wallets' left */
+/* ONE Home or Back button, level with the Gem, just to its right */
 #back {
   top: var(--gem-safe-top, env(safe-area-inset-top, 0px));
-  left: var(--gem-safe-left, 0px);
+  left: max(var(--gem-safe-left, 0px), var(--gem-reserved-tl-width, 0px));
 }
-/* a ROW of your own buttons does not fit beside the wallets: start it below the arcade's row,
-   like your information */
-#nav {
+/* your information — score, moves, a timer — clear of every top corner the arcade reserves */
+#info {
   top: max(
     var(--gem-safe-top, env(safe-area-inset-top, 0px)),
-    var(--gem-reserved-tl-height, 0px),
     var(--gem-reserved-tr-height, 0px)
   );
+  left: max(var(--gem-safe-left, 0px), var(--gem-reserved-tl-width, 0px));
+  right: var(--gem-safe-right, 0px);
 }
 ```
 
-The per-corner properties cannot say how wide the clear corner is — only that the corner's
-rectangles reach in to the middle. To know whether your button fits beside the wallets, read the
-rectangles from script: the clear width at the top-left is the smallest `x` among
-`gem.viewport.reserved` (the whole width when the list is empty).
+The per-corner properties say how far a corner's rectangles reach, not how much room is left beside
+them. To know whether a row of your own buttons fits beside the Gem, read the rectangles from
+script: the room to the right of the top-left ones is the frame's width less the furthest right
+edge among them.
 
 ```js
 const reserved = gem.viewport?.reserved ?? [];
-const clearLeft = reserved.length ? Math.min(...reserved.map((r) => r.x)) : window.innerWidth;
-nav.classList.toggle('below-arcade-row', clearLeft < nav.offsetWidth + 8);
+const topLeft = reserved.filter((r) => r.x + r.width / 2 < window.innerWidth / 2);
+const from = topLeft.length ? Math.max(...topLeft.map((r) => r.x + r.width)) : 0;
+nav.classList.toggle('below-arcade-row', window.innerWidth - from < nav.offsetWidth + 8);
 ```
 
 All eight properties are written on every push, `0px` for a clear corner, so a rotation never leaves
 a stale value; they are never set under an embedder that sends no viewport, which is what the `0px`
 fallback is for. `gem.viewport.reserved` is `[]` when nothing is covered.
 
-**Lay out against it whenever it changes.** The wallets' rectangles are there for the whole
-session on the Arcade's phone layout, and their number and width can change as the player's
-balances and currencies do. Read every corner, not only the ones this page names today: a layout that honours
-all four is right under any embedder.
+**Lay out against it whenever it changes.** The Gem button's rectangle is there for the whole
+session, and it moves with a rotation, a resize or the frame-rate readout. Read every corner, not
+only the one this page names today: a layout that honours all four is right under any embedder.
 
 **Older SDKs get it folded into the top inset.** A game on an SDK from before reserved areas cannot
 read the rectangles, so the arcade sends it none and instead raises `insets.top` — and so
@@ -939,6 +920,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 +946,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,11 +979,99 @@ 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-in-the-gem-menu-never-drawn-by-you):
+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
-(**Return to the Arcade**), mutes, goes fullscreen, reports a problem and changes their Arcade-wide
-settings — the ones that reach you as [`gem.prefs.recommended`](#game-settings). You can add up to
+The Arcade keeps one button over every game, on every device: the Gem, at the top-left. Its menu is
+how a player leaves (**Return to the Arcade**), sees their Gems, Tickets and achievement score, mutes,
+goes fullscreen, reports a problem and changes their Arcade-wide settings — the ones that reach you as [`gem.prefs.recommended`](#game-settings). You can add up to
 four entries of your own:
 
 ```js
@@ -1106,28 +1188,24 @@ its music out than cut it, say. The Arcade still shows its button for your game
 so this is a promise: your `onPrefs` handler must go quiet on `muted: true` and come back on `false`,
 and the release checklist checks that it does.
 
-## The Arcade's wallet: shown unless you hide it, never drawn
+## The Arcade's wallet: in the Gem menu, never drawn by you
 
 The player's platform balances — Gems, Tickets (`ARCADE_TICKETS`) and their achievement score —
 belong to the Arcade. **Your game never draws one**, and never shows a pending state for one: the
-Arcade takes every figure from the platform and draws the wallets itself, in the middle of the row
-across the top of your frame on a phone, with its menu button at the right end.
-
-**By default the Arcade shows every wallet the whole time, during play too.** They are small,
-translucent chips in the middle of the top row, and while shown they are
-[reserved rectangles](#the-arcades-own-controls-reserved-areas): lay every screen out below both
-`--gem-reserved-tl-height` and `--gem-reserved-tr-height`. A game that calls nothing keeps them.
-
-**A game may hide them for gameplay** (honoured again since 2026-10-08): call
-`gem.setWalletVisible(false)` when play starts and `gem.setWalletVisible(true)` when a menu opens.
-While hidden, their rectangles leave `gem.viewport.reserved` and the top row is the game's; the
-Arcade still pops a wallet up for a moment when something happens to it (a reward you cued, a
-spend, a landing), floating over the game without moving anything. This applies on a phone, where
-the wallets sit over your game; where the Arcade docks them beside the frame it changes nothing.
-Read the `--gem-reserved-*` properties rather than assuming either state.
-
-⚠️ **The Arcade ignores the `only` option**: a shown wallet is every wallet. Do not build a store
-screen that relies on narrowing them to one currency.
+Arcade takes every figure from the platform and shows them itself.
+
+**The Gem Arcade draws no wallet over your game** (since 2026-10-11). Nothing of it sits in your top
+row, at rest or when a balance moves. The player opens the Gem menu — the Gem button at the
+top-left — to see their Gems, Tickets and achievement score, and every payout
+[`gem.cueReward`](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet) announces
+flies into the Gem button. A payout you do not cue flies too, from the middle of your frame, so cue
+the ones the player earns on screen and the flight starts where they are looking.
+
+**`gem.setWalletVisible` changes nothing on the Gem Arcade.** It is still part of the contract, so a
+game that calls it keeps working, and it is the call to make for an embedder that draws wallets over
+games: hide them while you play, show them on your menus. Under the Gem Arcade there is no wallet to
+show or hide and no wallet rectangle in `gem.viewport.reserved`. The `only` option is ignored there
+as well.
 
 ## No accidental text selection
 

package/package.json

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