@indiegems/gem-web-sdk 11.1.2 → 13.0.0

package/docs/serverless-functions-js.md

@@ -1,9 +1,5 @@
 # Serverless functions in JavaScript
 
-**The platform does not run JavaScript functions yet.** This page describes how one is written
-and how it behaves; today a function you publish is a WebAssembly component, as
-[serverless-functions.md](serverless-functions.md) describes.
-
 A serverless function can be written in JavaScript or TypeScript instead of Rust: the language your
 game is already written in, so the verification code in your browser game moves into a function
 with no change beyond bundling. You upload one bundled ES module, and the platform runs it on a
@@ -51,31 +47,46 @@ are read and written:
 | `handle(input)`     | `Uint8Array`: the request body, byte for byte         | `Uint8Array`, `ArrayBuffer` or `string` (sent as UTF-8); anything else is an error                        |
 | `handleJson(input)` | the body parsed as JSON; an empty body is `undefined` | any JSON-serializable value, sent as its JSON text; `undefined` is sent as `null`; a `BigInt` is an error |
 
-Either may be `async`; the platform waits for the promise. Exporting neither, or both, is refused
-when you upload. A caller cannot tell which kind of function answered: `gem.functions.invoke`, the
-limits and the refusals in serverless-functions.md are identical for both.
+Either may be `async`; the platform waits for the promise, and a promise that never settles fails
+the call. Exporting neither, or both, is refused when you upload. A caller cannot tell which kind of
+function answered: `gem.functions.invoke`, the limits and the refusals in serverless-functions.md
+are identical for both.
+
+**Each call gets the same limits as a component:** 5 seconds of wall clock, 1 second of CPU,
+256 MiB of memory, 32 platform calls, 256 KiB of input and 1 MiB of output, and the module itself
+may be at most 32 MiB. The full list is
+[the limits on one call](serverless-functions.md#the-limits-on-one-call).
 
 **A thrown exception is `Err`.** The call fails with `function_error`, and `err.functionMessage` is
 the exception's `name: message` (a thrown value that is not an `Error` is its `String()`). The
-message and the stack go to the platform's log for the invocation, never to the caller. A
-`handleJson` whose input is not JSON, or whose return value JSON cannot carry, fails the same way.
+message and the stack are also logged for the invocation at `error`; the stack never reaches the
+caller. A `handleJson` whose input is not JSON, or whose return value JSON cannot carry, fails the
+same way.
 
 **`console.*` reaches the invocation's log** at the matching level (`debug`, `info`, `warn`,
 `error`); `console.log` and every other method log at `info`. As with a component's `log`,
 `gemctl function logs` reads it back for a call on `dev`, and a call on `test` or `release` keeps
-no line.
+no line. Each line is cut at 1 KiB, and one call keeps at most **100 lines or 64 KiB** of them,
+whichever comes first. Every `console` call past that goes unrecorded, and the call's closing log
+line counts them in `dropped_log_lines` (serverless-functions.md section 7).
 
 ## 2. Writing one
 
 ```bash
 gemctl function init --lang js functions/score-check
-cd functions/score-check && npm install && npm run build
-gemctl function upload dist/function.js
+(cd functions/score-check && npm install && npm run build)
+gemctl function upload --file functions/score-check/dist/function.js --version 1.0.0
+gemctl function promote 1.0.0 --channel dev
 ```
 
 **`init --lang js`** writes a `package.json` whose `build` script type-checks and then bundles to
-one ES module, a TypeScript starter handler and a `tsconfig.json`. gemctl runs neither step:
-`npm run build` is yours, the way `cargo build` is for a component.
+one ES module in `dist`, a TypeScript starter handler and a `tsconfig.json`. gemctl runs neither
+step: `npm run build` is yours, the way `cargo build` is for a component. The starter lists the SDK
+in `devDependencies`, and its build bundles the SDK into the one module you upload. Nothing is
+provided to a function you upload now, so that module is the whole of your function. That is why
+the SDK is a dev dependency here while [getting-started.md](getting-started.md) puts it in
+`dependencies` for a game: what a game ships is built from its install, and what a function ships
+is the bundle.
 
 A handler looks like this:
 
@@ -96,23 +107,38 @@ The package is the one your game already depends on, installed as
 serverless-functions.md section 1, and it applies unchanged: a save or a setting the player's own
 browser can write is the player's claim, not evidence.
 
-**Imports.** The module may import the SDK and nothing else, under any of the three names a game
-already uses: `@indiegems/gem-web-sdk/function`, `@indiegems/gem-web-sdk/sdk`, or
-`@indiegems/gem-web-sdk/game`. Inside a function all three are the same module, the function
-entry, so shared code keeps its import. A name that module does not export, such as
-`defineServer`, fails every call with `function_error`. Everything else your code needs is bundled
-in, which is what the starter's build does. An `import()` at runtime is refused at upload.
-Top-level `await` is allowed and runs on every call.
-
-**What the engine gives you.** `Date`, `performance`, `Math.random`, `crypto.getRandomValues`,
-`crypto.randomUUID`, `TextEncoder`, `URL` and `fetch` all work. `fetch` reaches only the platform
-API, through the SDK, and the save links the platform hands you; any other URL is refused. A timer
-waits at most 10 ms: a function has no reason to sleep, and a long one would run out the wall
-clock.
-
-**The SDK version your function runs is the one the platform bundles**, not the one in your
-`package.json`; the starter pins the matching version. A method added in a newer SDK reaches a
-function when the platform's engine picks that version up.
+**Imports.** The module you upload imports nothing. Everything it uses, the SDK included, is
+bundled into it, which is what the starter's build does. A file shared with your game may keep its
+`@indiegems/gem-web-sdk/sdk` or `@indiegems/gem-web-sdk/game` import, because the starter's build
+resolves both to `@indiegems/gem-web-sdk/function` when it bundles your function. A name the
+function entry does not export, such as `defineServer`, then fails the build rather than a call.
+For a function still on the engine's built-in copy (below) the same name fails the call with
+`function_error`. An `import()` at runtime is refused at upload. Your module is evaluated afresh
+for every call, so its top level, including any top-level `await`, runs on every call and inside
+that call's limits; the engine's built-in copy, by contrast, was evaluated once when the engine was
+built, which is one reason it stays at 7.6.0.
+
+**What the platform gives your function.** `fetch`, `URL`, `URLSearchParams`, `TextEncoder`,
+`TextDecoder`, `AbortController`, `AbortSignal.timeout`, `setTimeout`, `setInterval`,
+`crypto.randomUUID`, `crypto.getRandomValues`, `atob`, `btoa`, `console`, `Date` and `Math.random`
+all work. `fetch` reaches only the platform API, through the SDK, and the save links the platform
+hands you; any other URL is refused before anything is sent, and every request counts toward the
+call's platform-call limit. Timers and `AbortSignal.timeout` wait their full length, and the engine
+sets no limit of its own: what bounds a wait is the call's wall clock, and a call still waiting when
+it runs out fails with `function_timeout`. A wait spends wall clock, not CPU.
+
+**The SDK your function runs is the one you bundle.** A function published importing the SDK from
+the engine runs the engine's built-in copy instead (the next paragraph). The starter's build
+bundles the version your `package.json` names, so pin the version your game pins and the same code
+runs in both places. A method added in a newer SDK reaches your function when you bundle that
+version: update the pin, build, upload and promote.
+
+**A function published importing the SDK from the engine** (the earlier starter marked it external)
+keeps running on the engine's built-in copy, gem-web-sdk 7.6.0, which is not updated and is removed
+once no published function imports it. Nothing fails at an engine roll. A new upload cannot import
+it: the platform refuses every import, so a function moves off the built-in by a rebuild with the
+current starter's build (which bundles the SDK), an upload of a new version and a promote. A method
+added in a newer SDK reaches a function only when that version is bundled.
 
 ## 3. The SDK inside a function
 
@@ -120,8 +146,47 @@ function when the platform's engine picks that version up.
 `awaitIdentity()` resolve at once, and `gem.me` is the player who called. So a game's boot sequence
 runs unchanged, and the same `gem.me.saves.get`, `gem.leaderboards.get` and `gem.profiles.of` calls
 work, with the same types and the same errors. The function's game and channel come from the call;
-nothing you write names them. `gem.context` is who called, for which game and channel, and
-`gem.identity` is the same three fields a browser game reads from its own `gem.identity`.
+nothing you write names them.
+
+```ts
+function createGem(options?: unknown): GemFunction; // options is accepted and ignored
+```
+
+| Member            | Type                           | What it is                                                            |
+| ----------------- | ------------------------------ | --------------------------------------------------------------------- |
+| `context`         | `FunctionContext`              | Who called, for which game and channel, and this call's invocation id |
+| `identity`        | `GemFunctionIdentity \| null`  | `playerId`, `gameId` and `channel`; `null` when a game server called  |
+| `awaitIdentity()` | `Promise<GemFunctionIdentity>` | `identity`, at once; rejects when a game server called                |
+| `awaitBridge()`   | `Promise<'connected'>`         | `'connected'`, at once                                                |
+| `me`              | `EntityScope`                  | The calling player's settings, inventory, currencies and saves        |
+| `characters`      | `CharactersApi`                | The calling player's characters                                       |
+| `transfers`       | `TransfersApi`                 | Moving items and currency between players                             |
+| `analytics`       | `AnalyticsApi`                 | Your game's analytics, as the calling player                          |
+| `leaderboards`    | `LeaderboardsApi`              | The leaderboards your game config declares                            |
+| `challenges`      | `ChallengesApi`                | Daily challenge periods and subjects                                  |
+| `showcase`        | `ShowcaseApi`                  | Display-only values other players may read                            |
+| `friends`         | `FriendsApi`                   | The calling player's accepted friends                                 |
+| `platform`        | `PlatformApi`                  | The calling player's platform-currency balances and earn allowance    |
+| `profiles`        | `ProfilesApi`                  | Another player's per-game profile                                     |
+| `client`          | `GemClient`                    | The platform API by path, for what the members above do not cover     |
+
+```ts
+interface FunctionContext {
+  readonly gameId: string;
+  readonly channel: 'dev' | 'test' | 'release';
+  readonly invocationId: string; // the id `gemctl function invoke` reports
+  readonly caller:
+    | { readonly type: 'player'; readonly playerId: string }
+    | { readonly type: 'game-server'; readonly serverId: string | null };
+}
+```
+
+`gem.identity` is the same three fields a browser game reads from its own `gem.identity`, so code
+that keys records on `playerId` runs unchanged. The entry also exports the error classes a game
+already catches (`GemApiError`, `AuthError`, `TransportRefusal`, `GemSaveError` and
+`FriendChallengeError`), so an `instanceof` check reads the same in both places. The
+[function API reference](api/api-reference-function.md) documents each member above, and the
+methods, types and errors behind all of them but `characters`, `transfers` and `client`.
 
 What a browser game has that is backed by the page or the arcade (ads, purchases, rooms, device
 settings, sharing) is not on `gem` inside a function. Four more differences, each following from
@@ -149,20 +214,29 @@ events may be lost.
 ## 4. Check before you upload
 
 ```bash
-gemctl function check dist/function.js
+gemctl function check functions/score-check/dist/function.js
 ```
 
 `check` runs the platform's publish-time validation for JavaScript on your machine, and an upload
-answers `400 source_invalid` with the same `details.reason`:
+runs it first and answers `400 source_invalid` with the same `details.reason`:
 
-| Reason             | What it usually is                                                        | What to change                                    |
-| ------------------ | ------------------------------------------------------------------------- | ------------------------------------------------- |
-| `not_a_module`     | A parse error, with its line and column, or a file that is not UTF-8      | Fix the syntax; bundle to ES2022                  |
-| `forbidden_import` | An `import` or `export … from` of anything but the SDK, or an `import()`  | Bundle the dependency in; drop the dynamic import |
-| `missing_handle`   | Neither `handle` nor `handleJson` is exported (`export *` does not count) | Export one of them from the module itself         |
-| `ambiguous_handle` | Both are exported                                                         | Keep one                                          |
-| `too_large`        | Over the size limit, the same one a component has                         | Bundle less; check what your build pulled in      |
+| Reason             | What it usually is                                                                          | What to change                                    |
+| ------------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `not_a_module`     | A parse error, with its line and column, or a file that is not UTF-8                        | Fix the syntax; bundle to ES2022                  |
+| `forbidden_import` | Any `import` or `export … from`, or an `import()`                                           | Bundle all of it in, the SDK too; drop `import()` |
+| `missing_handle`   | Neither `handle` nor `handleJson` is a named export (`export *` and `default` do not count) | Export one of them from the module itself         |
+| `ambiguous_handle` | Both are exported                                                                           | Keep one                                          |
+| `too_large`        | Over the size limit, the same one a component has                                           | Bundle less; check what your build pulled in      |
 
 An upload also answers `source_invalid`, rather than `component_invalid`, for `not_uploaded`,
-`size_mismatch` and `sha256_mismatch`: upload again. Promoting, channels and invoking are the same
-as for a component (serverless-functions.md sections 4 to 7).
+`size_mismatch` and `sha256_mismatch`: upload again. gemctl uploads a `.js` or `.mjs` file as
+JavaScript; it does not accept TypeScript, so upload what your build wrote.
+
+## 5. Publishing
+
+Uploading, promoting, rolling back and channels are the same as for a component
+(serverless-functions.md sections 4 and 5). On the website, the **Functions** tab of your game's
+**Builds** page promotes a version to a channel, rolls back by promoting an earlier one, and shows
+each channel's calls and daily usage and the last 24 hours of `dev` logs; a JavaScript version is
+marked there as running as JavaScript. Uploading is gemctl's alone. Invoking a function from your
+game or the terminal is serverless-functions.md sections 6 and 7.

package/docs/serverless-functions.md

@@ -55,8 +55,10 @@ possible.
 
 ## 2. What a function is
 
-A function is one WebAssembly **component** per game per channel, built against the platform's
-`gem:functions` world. It exports exactly one function:
+A function is one WebAssembly **component** or one JavaScript module per game per channel. A
+JavaScript module is written against the SDK instead, and
+[serverless-functions-js.md](serverless-functions-js.md) covers what differs for one. A component
+is built against the platform's `gem:functions` world, and exports exactly one function:
 
 ```wit
 export handle: func(input: list<u8>) -> result<list<u8>, string>;
@@ -450,12 +452,13 @@ reason to move the work to a game server.
 | ------------------------------------------------------------------------------ | -------------------------------------- |
 | Wall clock                                                                     | 5 seconds                              |
 | CPU                                                                            | 1 second of that 5                     |
-| Memory                                                                         | 64 MiB                                 |
+| Memory                                                                         | 256 MiB                                |
 | `call-api`, `download-link` and `upload-link` calls                            | 32, all three together                 |
 | A value handed to one `log`, `call-api`, `download-link` or `upload-link` call | 16 MiB                                 |
 | Input                                                                          | 256 KiB                                |
 | Output                                                                         | 1 MiB                                  |
-| Component size                                                                 | 32 MiB                                 |
+| Lines your function logs, kept per call (`dev` only)                           | 100 lines or 64 KiB, whichever first   |
+| Component or JavaScript module size                                            | 32 MiB                                 |
 | Calls, per caller per minute                                                   | 30 for a player, 120 for a game server |
 
 **The per-minute budget belongs to the caller, not to your game.** A player who spends theirs is
@@ -464,8 +467,9 @@ decision point, such as the end of a run or a claim, and never on a timer or onc
 
 ## 3. Writing one
 
-The reference toolchain is Rust. gemctl writes the starter crate and wraps what your build
-produces, and the build in between is yours:
+The reference toolchain for a component is Rust; to write a function in JavaScript or TypeScript,
+see [serverless-functions-js.md](serverless-functions-js.md). gemctl writes the starter crate and
+wraps what your build produces, and the build in between is yours:
 
 ```bash
 gemctl function init functions/score-check
@@ -618,6 +622,15 @@ been purged yet.
 `gemctl function delete <version> --yes` is refused while any channel serves the version, and
 gemctl cannot undo it.
 
+**The website does the same from the Functions tab of your game's Builds page.** It lists every
+version with its description, size, SHA-256 and the channels serving it, and promotes, unassigns and
+deletes, asking you to confirm before it promotes to `release`. Rolling back there is the same act:
+promote the earlier version. It cannot upload; that is `gemctl function upload`. The tab also shows
+each channel's calls today and its daily usage over the last 7, 28 or 90 days (calls, unsuccessful
+calls, CPU time, the longest call and peak memory), and the last 24 hours of `dev` logs, filtered by
+time, level, outcome or invocation id. Promoting, unassigning and deleting there take an Owner,
+Admin or Contributor role on the game; anyone else on the team can only look.
+
 ## 5. Channels
 
 Each channel (`dev`, `test` and `release`) serves at most one function version. A call never names
@@ -674,7 +687,8 @@ it is the progression's own state, or a key the platform decides (section 2).
 platform's code from section 8, and the error adds what that code needs:
 
 - `err.functionMessage` is the text your `handle` returned in `Err`, on `function_error`. Your
-  function wrote it and it may repeat what the caller sent, so log it and never render it as markup;
+  function wrote it and it may repeat what the caller sent, so log it and never render it as markup.
+  For a JavaScript function it is the thrown exception's `name: message`;
 - `err.failure` says which limit or fault ended the call, on `function_failed`;
 - `err.retryable` is decided by the code. It is `false` for `function_timeout`, because the same
   input runs out of time again, and for `functions_not_configured`, because functions are switched
@@ -777,9 +791,10 @@ or `game_server`:
   exceeded. The platform writes it and never copies your function's data into it.
 
 Newest first means a call's closing line comes before what it logged. **A call's logging is
-capped**: once it reaches its per-call log limit, that `log` call and every later one go
-unrecorded, and the closing line's `dropped_log_lines` says how many. A log that stops part-way
-with a nonzero count means your function logged too much, not that it went quiet.
+capped**: once it reaches 100 lines or 64 KiB of logged text, whichever comes first, that `log`
+call and every later one go unrecorded, and the closing line's `dropped_log_lines` says how many.
+A log that stops part-way with a nonzero count means your function logged too much, not that it
+went quiet.
 
 `--invocation-id`, `--level` (`debug`, `info`, `warn` or `error`) and `--outcome` narrow the page.
 `--level` picks what your function logged and `--outcome` picks closing lines, so the two cannot be
@@ -804,7 +819,7 @@ the last column: it is `true` exactly where this table says to retry.
 
 | What you get                                               | What happened                                                                                                                                       | What to do                                                             |
 | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `422 function_error`                                       | Your `handle` returned `Err`. The text is `err.functionMessage`                                                                                     | Fix your code or the input. Return verdicts in `Ok`                    |
+| `422 function_error`                                       | Your `handle` returned `Err`, or your JavaScript function threw. The text is `err.functionMessage`                                                  | Fix your code or the input. Return verdicts in `Ok`                    |
 | `422 function_failed`                                      | It did not finish. `err.failure` is `trap`, `memory_exceeded`, `cpu_budget_exceeded`, `host_call_limit`, `output_too_large` or `argument_too_large` | A bug or a limit in the function. Reproduce with the same input        |
 | `504 function_timeout`                                     | It ran past the wall clock                                                                                                                          | Do not retry: the same input takes as long again                       |
 | `404 function_not_published`                               | Nothing is promoted on the caller's channel                                                                                                         | `gemctl function promote <version> --channel <channel>`                |

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

@@ -891,13 +891,31 @@ arrives.
 ## Game settings
 
 **Your settings belong to your game: draw a settings button of your own, and the screen it opens.**
-The Arcade does not put your settings in its menu any more — its menu holds the player's
-_Arcade-wide_ settings instead — so a game with no button of its own has settings nobody can reach.
-
-**Put the button in the top-right corner.** That is a recommendation, not a rule the Arcade
-enforces, but a player who finds settings in the same corner in every game never has to look. Place
-it with the reserved-area properties so it never sits under an Arcade control, whatever the Arcade
-keeps in that corner on this device:
+The Arcade's menu never opens your settings — it holds the player's _Arcade-wide_ settings
+instead — so a game with no button of its own has settings nobody can reach.
+
+This is the whole model, and every other page that mentions settings links here:
+
+- **The Arcade's settings are the player's Arcade-wide defaults for this device.** Your game reads
+  them from `gem.prefs.recommended` (and `muted` and `reducedMotion` from `gem.prefs`) and applies
+  them again on `onPrefs`. The Arcade never asks your game anything about them, and never shows
+  anything your game says.
+- **Every game draws its own settings button, top-right, and its own settings screen.** The
+  Arcade's menu never opens it.
+- **A setting starts from `recommended` until the player changes it in your game, and then the
+  player's choice in your game wins.** Save only what the player chose, never a recommended value.
+- **Where a choice is kept.** Device configuration — volume, graphics quality, look sensitivity, a
+  touch-stick style — goes in `gem.deviceSettings`; a choice that must follow the player across
+  devices — difficulty, key bindings, accessibility toggles the game owns — goes in
+  `gem.me.settings`.
+- **Mute and vibration are in your settings screen too**, wired both ways: your mute follows
+  `prefs.muted` and reports the player's own with `gem.reportMuted`
+  ([sound](#sound-your-own-mute-control-and-the-arcades)), and your vibration toggle shows only
+  while `gem.vibration.available` ([vibration](vibration.md)).
+
+**The button goes in the top-right corner**, the same corner in every game, so a player never has
+to look for it. Place it with the reserved-area properties so it never sits under an Arcade
+control, whatever the Arcade keeps in that corner on this device:
 
 ```css
 #settings-button {
@@ -931,8 +949,8 @@ same push as `muted` and `reducedMotion`, and again whenever the player changes
 | `graphicsQualityAuto` | `true` / `false` | `true`: the Arcade picked that tier for this device, so you may adapt from it. `false`: the player picked it, so hold it. |
 
 `lookSensitivity` to `touchMovement` 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
+[camera and look controls](#camera-and-look-controls) 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'`). The last two are the starting graphics quality: see
 [graphics quality](#graphics-quality-the-arcade-picks-the-start-your-game-adapts). An older Arcade
@@ -981,8 +999,11 @@ volumeSlider.oninput = () => {
 };
 ```
 
-[Device settings](#device-settings-what-this-device-remembers-about-your-game) above is where the
-player's choices are kept between sessions.
+`chosen` here is this device's configuration, so it is kept in
+[device settings](#device-settings-what-this-device-remembers-about-your-game). A choice that must
+follow the player to another device — a difficulty, key bindings, an accessibility toggle your game
+owns — starts from `recommended` the same way and is kept in `gem.me.settings` instead
+([saving player progress](saving-player-progress.md#for-something-small-reach-for-settings-instead)).
 
 **Read `muted` and `reducedMotion` as before.** They are not recommendations and they did not move:
 `muted` is the Arcade's mute, which the SDK applies for you
@@ -995,30 +1016,12 @@ If your game turns a camera — a drag on a phone, a mouse under pointer lock, a
 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.
+([the table above](#start-from-the-players-arcade-wide-defaults-gemprefsrecommended)) as the
+player's Arcade-wide defaults, and, like every [game setting](#game-settings), they are where your
+own settings start. There is nothing to tell the Arcade about them: its Settings show the player's
+defaults, never what a game uses.
 
-**2. Turn look input into a camera turn — `gem.controls.look()`.** It is pure math: it listens to
+**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°,
@@ -1067,15 +1070,16 @@ function frame(dt) {
   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: 1.5 })` — and that input stops following the Arcade. Keep it in
+  `gem.deviceSettings`: a look speed is this device's configuration.
   `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`.
+  `gem.prefs.recommended?.touchMovement` and draw a floating or a fixed one. A game with only one
+  kind draws that one and ignores the field.
+- **No camera, no call.** A game with no camera to turn never calls `look`.
 
 ## Graphics quality: the Arcade picks the start, your game adapts
 
@@ -1150,10 +1154,8 @@ gem.setMenu({
 });
 ```
 
-- **The Arcade no longer shows a "Game settings" row for `onSettings`.** Your settings open from
-  [your own button](#game-settings). `gem.setMenu({ onSettings })` is still accepted, so a game that
-  passes it keeps working, and another embedder may still show an entry for it — but in the Arcade
-  it adds nothing.
+- **Your settings are not in it.** They open from [your own button](#game-settings), and the
+  Arcade's menu never opens them.
 - **`items` are up to four entries of your own**, shown in a group below the Arcade's. `id` is your
   name for the entry (1 to 32 characters); `label` is what the player reads, **already in their
   language** (`gem.prefs.locale`) — the Arcade does not translate it, cuts it at 40 characters, and
@@ -1460,9 +1462,12 @@ This is a platform rule, not advice — see
 
 ### Arcade avatars: the character the player wears, and changing it mid-game
 
-Some games draw **Arcade avatars** (store tag `arcade-avatars`): the player's look in your game is
-something they own and wear in the Arcade. The Arcade's avatar picker has **two tabs**, and they
-are **two separate worn choices** — wearing one never changes the other:
+Some games draw **Arcade avatars**: the player's look in your game is something they own and wear
+in the Arcade. **The whole guide for 3D avatars — rig families, declaring the ones your game
+accepts, uploading and selling your own, the purchase flow and loading the model — is
+[arcade-avatars.md](arcade-avatars.md).** This section is the summary. The Arcade's avatar picker
+has **two tabs**, and they are **two separate worn choices** — wearing one never changes the
+other:
 
 | Tab | What the player wears | On `gem.player` and every room member |
 |---|---|---|
@@ -1476,6 +1481,8 @@ are **two separate worn choices** — wearing one never changes the other:
   (an idle, say). It never changes at its URL, so cache it by URL.
 - **`avatar3dIconUrl`** is a rendered portrait of that character, for a roster or a menu where
   loading the model is too much. It is **not** the 2D portrait.
+- **`avatars3d`** lists every worn 3D character, one per **rig family**; the three fields above
+  are your game's first declared family's. `gem.avatars3d.worn()` reads it for you.
 
 **Draw the 3D character, falling back to what you did before.** A game that drew characters
 before the 3D tab existed keyed its own models on `avatarIconId`. Keep that mapping as the
@@ -1522,7 +1529,7 @@ is missing now (a player who takes off their 3D character has no `avatar3dId`).
 
 **A "Change avatar" button belongs in your own UI**, and `gem.openAvatarPicker()` opens the
 Arcade's picker from it. Pass `{ tab: '3d' }` or `{ tab: '2d' }` to open on a tab; omit it and
-the Arcade decides (a game tagged `arcade-avatars` gets the 3D tab). The Arcade pauses your game
+the Arcade decides (a game that declares avatar families gets the 3D tab). The Arcade pauses your game
 while the picker is open, saves the player's choice, sends the player again, and resumes you:
 
 ```js

package/package.json

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