@indiegems/gem-web-sdk 12.0.0 → 13.1.0

package/docs/saving-player-progress.md

@@ -363,13 +363,18 @@ often rather than to retry harder.
 ## For something small, reach for settings instead
 
 `gem.me.settings` needs no declaration and is one call: `put(key, value)` with a **string**
-value, up to **8 KiB** each and **32** keys per player per game. It is the right home for a
-chosen difficulty, a control scheme, a level counter.
+value, up to **8 KiB** each and **32** keys per player per game. It is the right home for a small
+value that follows the player, such as a level counter, and for the player's settings that do too.
+
+**Which store a setting goes in** ([game settings](what-a-game-must-do.md#game-settings) has the
+whole model): 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`. Either
+way, save only what the player chose, never a value your game started from `gem.prefs.recommended`.
 
 Reach for a save when the payload is a document rather than a value — a world, an inventory, a
-replay. Something that belongs to **this device** rather than to the player — a volume, a graphics
-quality — belongs in neither; that is the next section. Progress a player would be upset to lose
-belongs in a save, and nowhere else.
+replay. Device configuration belongs in neither; that is the next section. Progress a player would
+be upset to lose belongs in a save, and nowhere else.
 
 ### Device settings: local to this device, and only that
 
@@ -380,9 +385,10 @@ browser storage cannot do this: every build of a web game runs on its own origin
 game kept in `localStorage` is gone the moment you publish again. The Arcade's own storage outlives
 your builds; that is the whole mechanism.
 
-**What goes here:** a master volume and the music/SFX mix, a graphics quality or resolution scale,
-a chosen input layout, a tip the player dismissed, a "skip intro" toggle. Configuration that is
-about **this screen and these speakers**.
+**What goes here:** device configuration — a master volume and the music/SFX mix, a graphics
+quality or resolution scale, a look sensitivity, a touch-stick style — and a tip the player
+dismissed or a "skip intro" toggle. Configuration that is about **this screen, these speakers and
+this input**. Key bindings and a difficulty follow the player, so they go in `gem.me.settings`.
 
 ⚠️ **What never goes here: progression, unlocks, currency, anything a player would mind losing,
 and anything that must follow them to another device.** This is not a save and it is not a
@@ -433,8 +439,8 @@ game, and a key you experiment with on `dev` cannot break a shipped build.
 | You want | Where it goes | Follows the player? |
 | -------- | ------------- | ------------------- |
 | a world, an inventory, a replay | `gem.me.saves` — a declared slot | yes |
-| a difficulty, a control scheme, a level counter | `gem.me.settings` — a string per key | yes |
-| a volume, a quality preset, a dismissed tip | `gem.deviceSettings` — one object per device | **no** |
+| a difficulty, key bindings, an accessibility toggle your game owns, a level counter | `gem.me.settings` — a string per key | yes |
+| a volume, a graphics quality, a look sensitivity, a touch-stick style, a dismissed tip | `gem.deviceSettings` — one object per device | **no** |
 
 ## Starting over as a new player while you test
 

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/v12.0.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v12.0.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v13.1.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v13.1.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

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

@@ -708,46 +708,54 @@ the `var()` above, or read `gem.viewport`. The release checklist looks for the b
 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).
+- **The Gem button**, the Gem Arcade's gem, always there (a touch target, about 50px across), in
+  the **top-left corner** unless your game [asks for another](#moving-the-gem-gemsetgemcorner). 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:**
+### The top of the screen
 
-| 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)).                                                                                                                                             |
+**The top of the screen has one layout, in every game, wherever the Gem sits.** A player learns
+where "back" and "settings" are once, across every game:
 
-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.
+| Where                     | Whose        | What goes there                                                                                                                                                                                                        |
+| ------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **The Gem's corner**      | the Arcade's | Its Gem button — top-left unless you [ask for another corner](#moving-the-gem-gemsetgemcorner). Nothing of yours under it.                                                                                             |
+| **Top-right**             | yours        | Your **settings** button ([Game settings](#game-settings)) at the end of the row, and your **Back / Home** button just to its left, level with it and about 16px apart, so a fingertip lands on one and not the other. |
+| **Centre of the top row** | yours        | Your **information**: a title, score, moves, a timer, a level name.                                                                                                                                                    |
 
-**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.
+- **Back / Home is drawn when a screen needs it, always in that spot.** It moves around _inside_
+  your game — back to your level select or title screen — and never leaves it: leaving is the
+  Arcade's menu, so a player always knows which control does which.
+- **Whichever of your controls shares the Gem's corner sits level with the Gem, on the side toward
+  the centre.** With the Gem top-left, nothing of yours does. With the Gem top-right, your Back and
+  settings sit just left of it.
+- **Your settings button is there on every screen.** It goes top-right even where no Arcade control
+  is: another embedder may keep one in that corner, so place it from the reserved areas below and it
+  moves aside for whatever is there.
 
-Those rectangles of your frame are **reserved**: keep essential UI and every touch target out of
-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.
+The parts of your frame under the Gem and any other Arcade control are **reserved**: keep
+essential UI and every touch target out of them. **Never hard-code their size or position.** They
+differ by phone, orientation and mode. The Gem sits at the edge of the safe area and never rises
+into the camera band, but that edge is somewhere else on every device — read them, as below.
 
 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:
+readout while the player shows it. Each is grown out to the frame edges it sits nearest, because the
+sliver between the Gem and the edge is no place for a button either. On a notched phone in portrait,
+with the Gem top-left:
 
 ```json
 {
   "insets": { "top": 47, "right": 0, "bottom": 34, "left": 0 },
-  "reserved": [{ "x": 8, "y": 55, "width": 52, "height": 52 }]
+  "reserved": [{ "x": 0, "y": 0, "width": 60, "height": 99 }]
 }
 ```
 
@@ -755,35 +763,37 @@ readout while the player shows it:
 `--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. Under the Gem Arcade the Gem button is a top-left rectangle, so:
+nearest to. Lay the top row out between the two top corners, and it is right wherever the Gem is:
 
 ```css
-/* ONE Home or Back button, level with the Gem, just to its right */
-#back {
+/* The top row: clear of whatever the Arcade reserves in either top corner */
+#top-row {
+  position: absolute;
   top: var(--gem-safe-top, env(safe-area-inset-top, 0px));
   left: max(var(--gem-safe-left, 0px), var(--gem-reserved-tl-width, 0px));
+  right: max(var(--gem-safe-right, 0px), var(--gem-reserved-tr-width, 0px));
+  display: flex;
+  align-items: center;
+  gap: 16px;
 }
-/* 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-tr-height, 0px)
-  );
-  left: max(var(--gem-safe-left, 0px), var(--gem-reserved-tl-width, 0px));
-  right: var(--gem-safe-right, 0px);
+/* your information takes the middle; Back, then settings, at the right end */
+#top-row .info {
+  flex: 1;
+  text-align: center;
 }
 ```
 
 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.
+them. To know whether your top row fits between the Arcade's controls, read the rectangles from
+script: the room is what lies between the top rectangles on the left and those on the right.
 
 ```js
-const reserved = gem.viewport?.reserved ?? [];
-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);
+const w = window.innerWidth;
+const top = (gem.viewport?.reserved ?? []).filter((r) => r.y === 0);
+const isLeft = (r) => r.x + r.width / 2 < w / 2;
+const from = Math.max(0, ...top.filter(isLeft).map((r) => r.x + r.width));
+const to = Math.min(w, ...top.filter((r) => !isLeft(r)).map((r) => r.x));
+row.classList.toggle('below-arcade-row', to - from < row.scrollWidth + 8);
 ```
 
 All eight properties are written on every push, `0px` for a clear corner, so a rotation never leaves
@@ -791,8 +801,39 @@ a stale value; they are never set under an embedder that sends no viewport, whic
 fallback is for. `gem.viewport.reserved` is `[]` when nothing is covered.
 
 **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.
+session, and it moves with a rotation, a resize, the frame-rate readout and a change of corner. Read
+every corner, not only the one you asked for: a layout that honours all four is right under any
+embedder.
+
+### Moving the Gem: `gem.setGemCorner`
+
+**Leave the Gem top-left unless your own HUD needs that corner.** If it does, ask for another:
+
+```js
+// This game's minimap needs the top-left, so the Gem goes bottom-left.
+gem.setGemCorner('bottom-left'); // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+```
+
+- **One corner per game**, at most one per orientation (one in portrait, another in landscape).
+  Call it once at boot, and again on a rotation if the two differ. A Gem that moves from screen to
+  screen is a way out the player has to look for.
+- **In landscape the bottom corners are where a player's thumbs hold the sticks.** Ask for one only
+  if your controls do not live there.
+- **Lay out around the reserved rectangles you receive, never around the corner you asked for.**
+  The Arcade moves the Gem on its own terms: not while the player is using it or its menu is open,
+  no more often than every few seconds, and a corner the player chooses for themselves, should the
+  Arcade ever offer that, wins over yours. The rectangles — and the `--gem-reserved-*` properties —
+  say where the Gem is now; a game that reads them is right whatever the Arcade decided, and a game
+  that assumed its corner is not.
+- **The top row does not change.** Back and settings stay top-right and information top-centre,
+  wherever the Gem goes ([the top of the screen](#the-top-of-the-screen)).
+- **It is screen state, not a toggle**: each call is the whole answer, held before the Arcade
+  connects and sent again after any reconnect. A value that is not one of the four corners is
+  ignored, with a warning on the console.
+
+`gem.setGemCorner` returns `true` when the Arcade was told, and `false` before it connects and
+under an embedder that cannot move its Gem. On `false` the Gem stays where the embedder puts it,
+and the rectangles say where that is: there is nothing else to do.
 
 **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
@@ -891,22 +932,38 @@ 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 ([the top of the
+  screen](#the-top-of-the-screen)), 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, with your Back button just to its left when a screen has one. Place it with the
+reserved-area properties so it never sits under an Arcade control: if the Gem is in that corner, the
+button sits level with it, just inside it.
 
 ```css
 #settings-button {
   position: absolute;
-  top: max(
-    var(--gem-safe-top, env(safe-area-inset-top, 0px)),
-    var(--gem-reserved-tr-height, 0px)
-  );
-  right: var(--gem-safe-right, 0px);
+  top: var(--gem-safe-top, env(safe-area-inset-top, 0px));
+  right: max(var(--gem-safe-right, 0px), var(--gem-reserved-tr-width, 0px));
 }
 ```
 
@@ -931,8 +988,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 +1038,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 +1055,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 +1109,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
 
@@ -1139,7 +1182,8 @@ What it does, so you know what to expect:
 
 ## The Arcade's menu
 
-The Arcade keeps one button over every game, on every device: the Gem, at the top-left. Its menu is
+The Arcade keeps one button over every game, on every device: the Gem, top-left unless your game
+[asks for another corner](#moving-the-gem-gemsetgemcorner). 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:
@@ -1150,10 +1194,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
@@ -1173,9 +1215,9 @@ gem.setMenu({
 settings button is there either way; what such a game also needs is a way out of its own, a control
 that calls `gem.exit()`.
 
-Your own **back or home** button — the one that moves around inside your game — goes **top-left**,
-which the Arcade [leaves clear](#the-arcades-own-controls-reserved-areas). It never leaves the game:
-leaving is the Arcade's menu, so a player always knows which control does which.
+Your own **back or home** button — the one that moves around inside your game — goes **top-right,
+just left of your settings button** ([the top of the screen](#the-top-of-the-screen)). It never
+leaves the game: leaving is the Arcade's menu, so a player always knows which control does which.
 
 ## Sound: your own mute control, and the Arcade's
 
@@ -1265,8 +1307,8 @@ belong to the Arcade. **Your game never draws one**, and never shows a pending s
 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
+row, at rest or when a balance moves. The player opens the Gem menu — the Gem button, in whichever
+corner it sits — 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.
@@ -1460,9 +1502,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 +1521,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 +1569,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": "12.0.0",
+  "version": "13.1.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",
@@ -40,7 +40,8 @@
       "import": "./dist/gem-web-sdk.quality.js"
     },
     "./schema": "./schema/bridge.v1.json",
-    "./brand/*": "./brand/*"
+    "./brand/*": "./brand/*",
+    "./rigs/*": "./rigs/*"
   },
   "files": [
     "bin",
@@ -50,6 +51,7 @@
     "schema/bridge.v1.json",
     "schema/capabilities.public.json",
     "brand/*.png",
+    "rigs/*.glb",
     "docs/*.md",
     "docs/manifest.json",
     "docs/api/*.md",