@indiegems/gem-web-sdk 10.2.0 → 10.3.1

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v10.2.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v10.3.1, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -4590,6 +4590,417 @@ only when your studio corrects a running period; clients may hold the old
 content for up to an hour afterwards, and the hash is how a verifier tells
 them apart.
 
+<a id="gemlookspeed"></a>
+
+## GemLookSpeed
+
+```ts
+interface GemLookSpeed
+```
+
+A look speed per axis, in radians: per CSS px for a pointer, per second at
+full tilt for a stick.
+
+<a id="gemlookspeed-yaw"></a>
+
+## GemLookSpeed.yaw
+
+```ts
+readonly yaw: number
+```
+
+Across: radians of yaw.
+
+<a id="gemlookspeed-pitch"></a>
+
+## GemLookSpeed.pitch
+
+```ts
+readonly pitch: number
+```
+
+Up/down: radians of pitch.
+
+<a id="gemlookbase"></a>
+
+## GemLookBase
+
+```ts
+interface GemLookBase
+```
+
+The shape of `gem.controls.LOOK_BASE`: Roblox's base look speeds and the
+stick and touch shaping constants `gem.controls.look()` applies.
+
+<a id="gemlookbase-touch"></a>
+
+## GemLookBase.touch
+
+```ts
+readonly touch: GemLookSpeed
+```
+
+Radians per CSS px, for touch and pen: 1° across, 0.66° up/down.
+
+<a id="gemlookbase-mouse"></a>
+
+## GemLookBase.mouse
+
+```ts
+readonly mouse: GemLookSpeed
+```
+
+Radians per CSS px, for a mouse: 0.5° across, 0.385° up/down.
+
+<a id="gemlookbase-stick"></a>
+
+## GemLookBase.stick
+
+```ts
+readonly stick: GemLookSpeed
+```
+
+Radians per second at full tilt, for a gamepad stick: 240° across, 184.8° up/down.
+
+<a id="gemlookbase-stickdeadzone"></a>
+
+## GemLookBase.stickDeadzone
+
+```ts
+readonly stickDeadzone: number
+```
+
+A stick axis below this magnitude turns nothing: 0.1.
+
+<a id="gemlookbase-stickcurve"></a>
+
+## GemLookBase.stickCurve
+
+```ts
+readonly stickCurve: number
+```
+
+The stick curve's curvature `k` in `(e^(k·d) − 1) / (e^k − 1)`: 2.
+
+<a id="gemlookbase-touchpitchmin"></a>
+
+## GemLookBase.touchPitchMin
+
+```ts
+readonly touchPitchMin: number
+```
+
+The least fraction of the pitch speed a touch drag keeps straight up or down: 0.25.
+
+<a id="gemlookoptions"></a>
+
+## GemLookOptions
+
+```ts
+interface GemLookOptions
+```
+
+The game's own overrides for `gem.controls.look()` — what the player chose in
+YOUR settings screen. Each one wins over the Arcade's value; leave one out to
+follow the Arcade.
+
+<a id="gemlookoptions-sensitivity"></a>
+
+## GemLookOptions.sensitivity
+
+```ts
+readonly sensitivity?: number
+```
+
+The player's own look speed for touch, mouse and pen, as a multiplier
+(`1` = the base speed). Wins over `gem.prefs.recommended.lookSensitivity`.
+
+<a id="gemlookoptions-gamepadsensitivity"></a>
+
+## GemLookOptions.gamepadSensitivity
+
+```ts
+readonly gamepadSensitivity?: number
+```
+
+The player's own look speed for a gamepad stick, as a multiplier. Wins
+over `gem.prefs.recommended.gamepadLookSensitivity`.
+
+<a id="gemlookoptions-inverty"></a>
+
+## GemLookOptions.invertY
+
+```ts
+readonly invertY?: boolean
+```
+
+The player's own inverted up/down look. Wins over
+`gem.prefs.recommended.invertLookY`.
+
+<a id="gemlookdelta"></a>
+
+## GemLookDelta
+
+```ts
+interface GemLookDelta
+```
+
+A turn to apply to your camera, in radians to ADD: `yaw` positive turns
+right (clockwise seen from above), `pitch` positive looks up.
+
+<a id="gemlookdelta-yaw"></a>
+
+## GemLookDelta.yaw
+
+```ts
+readonly yaw: number
+```
+
+Radians to add to the camera's yaw; positive turns right.
+
+<a id="gemlookdelta-pitch"></a>
+
+## GemLookDelta.pitch
+
+```ts
+readonly pitch: number
+```
+
+Radians to add to the camera's pitch; positive looks up.
+
+<a id="gemlook"></a>
+
+## GemLook
+
+```ts
+interface GemLook
+```
+
+The look helper `gem.controls.look()` returns. Pure math: it listens to
+nothing and moves no camera — feed it the deltas your input code already
+has and add what it returns to your camera's yaw and pitch, then clamp the
+pitch as you always do.
+
+<a id="gemlook-frompointer"></a>
+
+## GemLook.fromPointer
+
+```ts
+fromPointer(dx: number, dy: number, pointerType: string, pitch?: number): GemLookDelta
+```
+
+A pointer move — a touch drag, a mouse move (under pointer lock,
+`movementX` / `movementY`) or a pen — turned into a look turn.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `dx` | `number` | The move across, in CSS px, right positive. |
+| `dy` | `number` | The move down the screen, in CSS px, DOWN positive (as
+  `PointerEvent` reports it). Dragging up looks up. |
+| `pointerType` | `string` | The event's `pointerType`: `'touch'` and `'pen'` take
+  the touch speeds, anything else the mouse speeds. |
+| `pitch` | `number` | The camera's current pitch in radians (0 = the horizon,
+  positive = looking up), for the touch slowdown near straight up or
+  down. Leave it out to skip the slowdown. |
+
+<a id="gemlook-fromstick"></a>
+
+## GemLook.fromStick
+
+```ts
+fromStick(x: number, y: number, dt: number): GemLookDelta
+```
+
+A right stick turned into a look turn over one frame.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `x` | `number` | The stick's horizontal axis as the Gamepad API reports it,
+  −1..1, right positive. |
+| `y` | `number` | The stick's vertical axis as the Gamepad API reports it, −1..1,
+  DOWN positive. Pushing up looks up. |
+| `dt` | `number` | The frame's duration in seconds. |
+
+<a id="gemlook-set"></a>
+
+## GemLook.set
+
+```ts
+set(options: GemLookOptions): void
+```
+
+Change your game's overrides — call it when the player changes a setting
+in your settings screen. Each key you pass replaces that override; a key
+passed as `undefined` removes it, so that input follows the Arcade again;
+a key you leave out is unchanged.
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `GemLookOptions` |
+
+**Throws.** TypeError when a sensitivity is not a finite number above 0, or
+  `invertY` is not a boolean.
+
+<a id="controlsapi"></a>
+
+## ControlsApi
+
+```ts
+interface ControlsApi
+```
+
+`gem.controls` — the player's camera and controls settings: tell the Arcade
+which ones your game leaves to the player, and turn look input into a camera
+turn at the player's sensitivity.
+
+**Guides.** [what-a-game-must-do](../what-a-game-must-do.md)
+
+<a id="controlsapi-declare"></a>
+
+## ControlsApi.declare
+
+```ts
+declare(uses: GemControlsDeclaration): boolean
+```
+
+Tell the Arcade which of the player's camera and controls settings your
+game uses, and for each one who decides it: `'player'` — you apply the
+Arcade's value from `gem.prefs.recommended` (or the player's own choice
+in your settings, which wins) — or `'game'` — you decide it yourself, and
+the Arcade's Settings shows that row as "Set by this game". Leave out a
+setting your game does not use.
+
+```js
+gem.controls.declare({
+  lookSensitivity: 'player',
+  gamepadLookSensitivity: 'player',
+  invertLookY: 'player',
+  touchMovement: 'game', // this game always uses a fixed stick
+});
+```
+
+**It is screen state, not a toggle.** Each call is the whole answer and
+replaces the last. The SDK holds it and sends it again after every
+reconnect, so call it once at boot, and again only when the answer
+changes. Any other key or value is dropped.
+
+| Parameter | Type |
+| --- | --- |
+| `uses` | `GemControlsDeclaration` |
+
+**Returns.** `true` when the Arcade was told now; `false` before the bridge is
+  up (the declaration is held and sent when it connects), outside the
+  Arcade, and under an embedder that does not show these settings. Never
+  throws.
+
+<a id="controlsapi-look"></a>
+
+## ControlsApi.look
+
+```ts
+look(options?: GemLookOptions): GemLook
+```
+
+Make a look helper: Roblox's camera-input math at the player's look
+sensitivity and invert. Make one and keep it.
+
+```js
+const look = gem.controls.look();
+// A mouse under pointer lock; for touch, pass the change in clientX/clientY.
+canvas.addEventListener('pointermove', (e) => {
+  if (document.pointerLockElement !== canvas) return;
+  const t = look.fromPointer(e.movementX, e.movementY, e.pointerType, camera.pitch);
+  camera.yaw += t.yaw;
+  camera.pitch = clamp(camera.pitch + t.pitch, -1.4, 1.4);
+});
+```
+
+The sensitivity and invert are read **live** on every call: the Arcade's
+`gem.prefs.recommended` values, unless `options` (or a later
+[GemLook.set](#gemlook-set)) gives your game's own, which win.
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `GemLookOptions` |
+
+**Throws.** TypeError when an option is malformed, as [GemLook.set](#gemlook-set).
+
+<a id="controlsapi-look_base"></a>
+
+## ControlsApi.LOOK_BASE
+
+```ts
+readonly LOOK_BASE: GemLookBase
+```
+
+The base speeds `look` applies at 1×, in radians. Frozen.
+
+<a id="gemcontrolchoice"></a>
+
+## GemControlChoice
+
+```ts
+type GemControlChoice = "player" | "game"
+```
+
+Who decides one camera or controls setting: `'player'` — your game applies
+the Arcade's value, or the player's own in-game choice, which wins — or
+`'game'` — your game decides it itself, and the Arcade's Settings shows the
+row as "Set by this game".
+
+<a id="gemcontrolsdeclaration"></a>
+
+## GemControlsDeclaration
+
+```ts
+interface GemControlsDeclaration
+```
+
+What `gem.controls.declare` takes: for each of the player's camera and
+controls settings your game uses, who decides it. Leave a setting out when
+your game does not use it at all — the Arcade then says "This game doesn't
+use this" beside that row.
+
+<a id="gemcontrolsdeclaration-looksensitivity"></a>
+
+## GemControlsDeclaration.lookSensitivity
+
+```ts
+readonly lookSensitivity?: GemControlChoice
+```
+
+Look speed for touch, mouse and pen — `gem.prefs.recommended.lookSensitivity`.
+
+<a id="gemcontrolsdeclaration-gamepadlooksensitivity"></a>
+
+## GemControlsDeclaration.gamepadLookSensitivity
+
+```ts
+readonly gamepadLookSensitivity?: GemControlChoice
+```
+
+Look speed for a gamepad stick — `gem.prefs.recommended.gamepadLookSensitivity`.
+
+<a id="gemcontrolsdeclaration-invertlooky"></a>
+
+## GemControlsDeclaration.invertLookY
+
+```ts
+readonly invertLookY?: GemControlChoice
+```
+
+Inverted up/down look — `gem.prefs.recommended.invertLookY`.
+
+<a id="gemcontrolsdeclaration-touchmovement"></a>
+
+## GemControlsDeclaration.touchMovement
+
+```ts
+readonly touchMovement?: GemControlChoice
+```
+
+The touch movement thumbstick, floating or fixed — `gem.prefs.recommended.touchMovement`.
+
 <a id="device_settings_max_bytes"></a>
 
 ## DEVICE_SETTINGS_MAX_BYTES
@@ -4782,7 +5193,8 @@ Whether the panel is on screen right now.
 interface RewardCue
 ```
 
-A platform-currency reward on its way to the arcade's wallet — what
+A platform-currency reward on its way to the arcade — in the Gem Arcade, a
+flight into the Gem button at the top-left of your frame — what
 `gem.cueReward` takes.
 
 <a id="rewardcue-currencyslug"></a>
@@ -4794,8 +5206,8 @@ currencySlug: string
 ```
 
 The platform currency's slug, as `gem.platform.currencies.get()` lists it —
-`GEMS` or `ARCADE_TICKETS`. It decides which total in the arcade's wallet
-the payout flies into.
+`GEMS` or `ARCADE_TICKETS`. It decides what flies — gems or tickets — and
+which of the player's totals the payout moves.
 
 <a id="rewardcue-expected"></a>
 
@@ -4820,8 +5232,8 @@ origin?: { x: number; y: number }
 Where the flight starts, in CSS px of YOUR viewport: the centre of the
 currency's icon (or hero) your screen draws beside the reward — the gem
 for Gems, the ticket for Tickets. Measure that element's own box, not a
-row or panel around it. Leave it out and the arcade animates at its wallet
-alone.
+row or panel around it. Leave it out and the Gem Arcade flies the payout
+from the middle of your frame once the platform confirms it.
 
 <a id="rewardcue-origin-x"></a>
 
@@ -5089,9 +5501,9 @@ while connected, and only to an arcade that mirrors a game's mute.
 cueReward(cue: RewardCue): boolean
 ```
 
-Tell the arcade a platform-currency reward is on its way, so its wallet can
-show it landing — a pending state now and, once the platform confirms the
-grant, the currency flying from `origin` into the wallet.
+Tell the arcade a platform-currency reward is on its way, so it can show it
+landing — in the Gem Arcade, the currency flying from `origin` into the Gem
+button, the total moving once the platform confirms the grant.
 
 Prefer `gem.cueReward`, which says what the arcade does with it. This one
 sends only while connected, and only to an arcade that draws a wallet.
@@ -5149,6 +5561,30 @@ wallet.
 **Returns.** whether the message left the frame — `false` before the bridge is
   up, for an arcade with no wallet, and past this frame's own limit.
 
+<a id="gemframe-declarecontrols"></a>
+
+## GemFrame.declareControls
+
+```ts
+declareControls(uses: GemControlsDeclaration): boolean
+```
+
+Tell the arcade which of the player's camera and controls settings your
+game leaves to the player and which it decides itself — the whole answer
+each time, the latest one winning.
+
+Prefer `gem.controls.declare`, which holds the declaration across a
+reconnect. This one sends only while connected, and only to an arcade
+that shows these settings.
+
+| Parameter | Type |
+| --- | --- |
+| `uses` | `GemControlsDeclaration` |
+
+**Returns.** whether the message left the frame — `false` before the bridge is
+  up, for an arcade that does not show these settings, and past this
+  frame's own limit.
+
 <a id="gemframe-setmenu"></a>
 
 ## GemFrame.setMenu
@@ -7268,8 +7704,9 @@ readonly recommended: GemRecommendedSettings | null
 ```
 
 The player's Arcade-wide defaults for this device — a volume, battery
-saver, a keyboard layout, the gamepad's confirm button and vibration — or
-`null` when the Arcade did not send them.
+saver, a keyboard layout, the gamepad's confirm button, vibration, and the
+camera and controls settings (look sensitivity, gamepad look sensitivity,
+invert look, touch movement) — or `null` when the Arcade did not send them.
 
 **Recommendations only; the player's own choice in your game wins.** Start
 a setting from here while the player has made no choice of their own for
@@ -7353,6 +7790,54 @@ readonly vibration: boolean
 
 Whether the player wants vibration and controller rumble.
 
+<a id="gemrecommendedsettings-looksensitivity"></a>
+
+## GemRecommendedSettings.lookSensitivity
+
+```ts
+readonly lookSensitivity: number
+```
+
+The player's look speed for touch, mouse and pen, as a percentage of the
+base speeds: `100` is 1×, from `20` (0.2×) to `400` (4×). `100` when the
+Arcade did not say. `gem.controls.look()` applies it for you.
+
+<a id="gemrecommendedsettings-gamepadlooksensitivity"></a>
+
+## GemRecommendedSettings.gamepadLookSensitivity
+
+```ts
+readonly gamepadLookSensitivity: number
+```
+
+The player's look speed for a gamepad stick, as a percentage: `100` is 1×,
+from `20` to `400`. `100` when the Arcade did not say.
+`gem.controls.look()` applies it for you.
+
+<a id="gemrecommendedsettings-invertlooky"></a>
+
+## GemRecommendedSettings.invertLookY
+
+```ts
+readonly invertLookY: boolean
+```
+
+Whether the player wants up/down look inverted: pushing up or dragging up
+looks down. Flips pitch only, never yaw. `false` when the Arcade did not
+say. `gem.controls.look()` applies it for you.
+
+<a id="gemrecommendedsettings-touchmovement"></a>
+
+## GemRecommendedSettings.touchMovement
+
+```ts
+readonly touchMovement: "floating" | "fixed"
+```
+
+On a touch screen, the movement thumbstick the player wants: `'floating'`
+appears where the thumb lands, `'fixed'` stays in one place. `'floating'`
+when the Arcade did not say. Your game draws the stick.
+
 <a id="gemcohort"></a>
 
 ## GemCohort
@@ -7514,10 +7999,11 @@ The unsafe margin on each edge of your frame.
 readonly reserved: readonly GemReservedArea[]
 ```
 
-Rectangles of your frame the arcade's own controls cover — its menu button
-in the top-right corner, and the wallets in the middle of the top row while they are shown (see
-`setWalletVisible`). Keep essential UI and touch targets out of them. Empty
-when the arcade covers nothing.
+Rectangles of your frame the arcade's own controls cover — in the Gem
+Arcade, its Gem button in the top-left corner, and the frame-rate readout
+beside it while the player shows it; an embedder that draws wallets over
+your game adds theirs (see `setWalletVisible`). Keep essential UI and touch
+targets out of them. Empty when the arcade covers nothing.
 
 A stylesheet reads the per-corner custom properties the SDK stamps from
 these instead — `--gem-reserved-tl-height` and friends.
@@ -7596,8 +8082,8 @@ While shown, show ONLY these: platform currency slugs as
 `gem.platform.currencies.get()` lists them (`GEMS`, `ARCADE_TICKETS`),
 matched exactly, and the literal `'score'` for the achievement score. Only
 for a screen about one currency, such as a ticket store; leave it out and
-every wallet shows, which is always safe. The Gem Arcade ignores it and
-shows every wallet while shown.
+every wallet shows, which is always safe. The Gem Arcade draws no wallet
+over a game, so it has nothing to narrow and ignores it.
 
 <a id="gamemenuitem"></a>
 
@@ -8223,6 +8709,32 @@ function onHit() {
 
 **Guides.** [vibration](../vibration.md)
 
+<a id="gem-controls"></a>
+
+## Gem.controls
+
+```ts
+readonly controls: ControlsApi
+```
+
+The player's camera and controls settings — look sensitivity, gamepad look
+sensitivity, invert look and touch movement, which arrive in
+`gem.prefs.recommended`. Two things to do with them:
+
+```js
+// 1. Tell the Arcade which ones your game leaves to the player.
+gem.controls.declare({ lookSensitivity: 'player', invertLookY: 'player' });
+
+// 2. Turn look input into a camera turn at the player's sensitivity.
+const look = gem.controls.look();
+// dx, dy: the pointer's move in CSS px since the last event.
+const t = look.fromPointer(dx, dy, e.pointerType, camera.pitch);
+camera.yaw += t.yaw;
+camera.pitch += t.pitch;
+```
+
+See the guide's "Camera and look controls" section.
+
 <a id="gem-analytics"></a>
 
 ## Gem.analytics
@@ -8574,10 +9086,13 @@ is ignored by the arcade, which keeps the image it is showing.
 cueReward(cue: RewardCue): boolean
 ```
 
-Tell the arcade a platform-currency reward is on its way, so its **wallet
-shows it landing**: a pending state right away and, once the platform
-confirms the grant, the currency flying from `origin` into the wallet with
-a bounce as the total moves.
+Tell the arcade a platform-currency reward is on its way, so it **shows it
+landing**: in the Gem Arcade the currency flies from `origin` into the Gem
+button at the top-left of your frame, which pops as each mark lands, and
+the player's total moves once the platform confirms the grant. The Gem
+Arcade draws no wallet over your game: the player sees their Gems and
+Tickets in the Gem menu. A payout you do not cue still flies, from the
+middle of your frame, so cue the ones the player earns on screen.
 
 Call it the moment your game decides to award — when your server has moved
 (or is about to move) the progression mapped onto a platform currency —
@@ -8625,28 +9140,23 @@ setWalletVisible(visible: boolean, options?: WalletVisibleOptions): boolean
 Show or hide the player's wallets — Gems, Tickets, the achievement score —
 that an embedder draws over your game.
 
-**Shown unless you hide them.** Call nothing and the Gem Arcade shows
-every wallet the whole time, during play too. A game that wants the top
-row for gameplay hides them while it plays and shows them again on its
-menus (the Gem Arcade honours this again since 2026-10-08, on a phone,
-where the wallets sit over your game; where they sit beside the frame it
-changes nothing).
+**The Gem Arcade draws no wallet over a game** (since 2026-10-11): the
+player sees their balances in the Gem menu, and payouts fly into the Gem
+button. So under the Gem Arcade this changes nothing on screen — it is
+accepted and harmless, and a game that already calls it keeps working.
+Call it for an embedder that does draw wallets over your game: hide them
+while you play, show them on your menus.
 
 ```js
 level.onStart = () => gem.setWalletVisible(false);
 menu.onOpen = () => gem.setWalletVisible(true);
 ```
 
-The Gem Arcade does NOT act on `only`: a shown wallet there is every
-wallet. Another embedder may honour it.
-
 **It is screen state, not a toggle.** Each call is the whole answer and
-replaces the last. While hidden, the arcade still pops a wallet up for a
-moment when something happens to it — a reward you cued, a spend, a
-landing — and your state never cancels that. Shown wallets cover the
-middle of your frame's top row, each arriving as a rectangle in
-`gem.viewport.reserved`; hiding them gives that space back. A wallet the
-arcade pops up for a moment floats over your game and moves nothing.
+replaces the last. Where an embedder draws wallets, shown ones arrive as
+rectangles in `gem.viewport.reserved` and hiding them gives that space
+back; the Gem Arcade sends none for wallets. `only` narrows what shows,
+where an embedder honours it; the Gem Arcade does not.
 
 **Never draw a platform balance yourself**, and never show a pending state
 for one: the arcade takes every figure from the platform. If this returns

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v10.2.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v10.3.1, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.