@indiegems/gem-web-sdk 12.0.0 → 13.0.0

package/docs/arcade-avatars.md

@@ -0,0 +1,303 @@
+# Arcade avatars: draw the 3D character a player wears, and sell your own
+
+Read this if your game draws the player as a character and you want that character to be the one
+they wear across the Arcade — or you want to sell characters of your own. A game that draws no
+player character needs none of it.
+
+**This page is about 3D avatars only.** The Arcade also has 2D portraits — the picture beside a
+player's name — and they are a separate system: wearing a 3D avatar never changes the portrait,
+and nothing here reads or changes one. Portraits are in
+[what-a-game-must-do.md](what-a-game-must-do.md#showing-a-player-one-identity-on-every-surface).
+
+## 1. What a 3D avatar is
+
+A 3D avatar is an Arcade item: a binary glTF model (`.glb`) built on a **rig family**, plus a
+rendered portrait of it. A player owns as many as they like and **wears one per family**. What
+they wear follows them into every game that accepts that family, and changes when they pick
+another in the Arcade's avatar picker or buy one.
+
+**The platform's item is the only copy that counts.** Your game reads the worn avatar's model URL
+at runtime and loads it — there is no shared avatar library to install and no copy to bundle. A
+model in your build is a model that drifts from what the player owns, and an avatar another game
+sells could never be in your build at all. Ship your own **default look** for a player who wears
+nothing, and nothing else.
+
+Everything your game calls is on [`gem.avatars3d`](api/api-reference-game.md#gem-avatars3d).
+
+## 2. Rig families, and the `small_human` rig
+
+A family is a skeleton contract: the node names and parent-child shape every model in it has, so a
+game that animates the family animates every avatar in it. The first family is `small_human`:
+
+```
+root
+└── body
+    ├── head
+    ├── arm_l
+    ├── arm_r
+    │   └── hand_socket
+    ├── leg_l
+    └── leg_r
+```
+
+The platform checks every `small_human` model when it is uploaded and refuses one that breaks any
+of these:
+
+- **The names are exact and case-sensitive**, and each of the eight appears **exactly once**.
+  `root` is a root node of the scene, `body` is its child, `head`, `arm_l`, `arm_r`, `leg_l` and
+  `leg_r` are children of `body`, and `hand_socket` is a child of `arm_r`. A held item goes on
+  `hand_socket`.
+- **Anything else is allowed**: extra nodes anywhere, meshes, materials, skins and animation
+  clips. A rig is a floor, not a ceiling.
+- **Nothing outside the file.** Buffers are embedded, and an image is embedded or a `data:` URI.
+  An external URI is refused.
+- **No compression extension.** Draco and meshopt are refused. The extensions a model may
+  _require_ are `KHR_materials_unlit`, `KHR_texture_transform` and `KHR_mesh_quantization`.
+- **At most 2 MiB** for the `.glb`.
+- **A portrait**: a still, square PNG, 256 to 1024 pixels, at most 2 MiB — what shop tiles and
+  rosters show where loading the model is too much.
+
+| What you get                  | What happened                                             | What to do                                                                                        |
+| ----------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `rig_mismatch`                | a node is missing, under the wrong parent, or named twice | read `details.missing`, `misplaced` and `duplicated`, rename in your modelling tool, upload again |
+| `model_external_reference`    | the file points at a buffer or image outside it           | export as a single binary `.glb` with textures embedded                                           |
+| `model_extension_unsupported` | the file requires Draco, meshopt or another extension     | export without compression                                                                        |
+| `unknown_avatar_family`       | the family name is not one the platform knows             | use `small_human`                                                                                 |
+
+## 3. Declare the families your game accepts
+
+A game accepts no family until its config says so. Add the section to
+`gem-backend-game-config.yaml`:
+
+```yaml
+avatars_3d:
+  families: [small_human]
+```
+
+Then upload the config and point each channel at it:
+
+```sh
+gemctl config upload --wait
+gemctl config promote <version> --channel dev
+gemctl config promote <version> --channel test
+gemctl config promote <version> --channel release --yes
+```
+
+- **The order is meaningful.** The first family is your default: it is the one the flat
+  `gem.player.avatar3dId` fields describe. Up to eight families, no repeats.
+- **Each channel reads its own config.** A channel whose config declares no families accepts
+  none: the Arcade shows no 3D picker in your game there, and nothing is for sale.
+- **Read it back** with `gem.avatars3d.families()`, which resolves the declared list from the
+  config the channel serves — `[]` when there is none.
+
+## 4. Upload an avatar
+
+```sh
+gemctl item upload red-knight.glb --family small_human --portrait red-knight.png \
+  --slug red-knight --name "Red Knight" --description "Sworn to the hearth."
+```
+
+A `.glb` file makes an avatar. gemctl checks the rig, the size and the external references on
+your machine before it uploads, so a broken model costs no upload; the platform checks again and
+renders the item, and the command waits until it is `ready`.
+
+- **An avatar cannot be changed after upload.** A fixed model is a new item with a new slug — the
+  old one stays owned by everyone who has it.
+- **It counts toward your game's items**, which are capped at 200 per game.
+
+## 5. Sell it
+
+An avatar is for sale only when you put it on sale, priced in Tickets, Gems or both:
+
+```sh
+gemctl item sell red-knight --tickets 50 --gems 300
+gemctl item retire red-knight
+```
+
+- **Prices are whole numbers from 1 to 1,000,000**, one or two of them. A player picks which
+  currency to pay in when you list both.
+- **At most 30 avatars are on sale at once.** Selling a 31st is refused with
+  `avatar_3d_sale_limit_reached`. Retiring one frees its slot immediately.
+- **Retiring never takes an avatar away.** A player who bought it keeps it, keeps wearing it, and
+  it keeps loading in your game. Retired means only that nobody new can buy it.
+- **On sale means on sale on every channel** where your game declares the avatar's family.
+
+### Award it as a prize
+
+An avatar can also be **won** — an event prize, a first-run gift, the end of a journey. A won avatar
+is a real Arcade avatar: the player owns it and can wear it in every game that accepts its family.
+First mark it awardable, then have your server award it:
+
+```sh
+gemctl item awardable red-knight        # may be awarded
+gemctl item awardable red-knight --off  # stop awarding; winners keep it
+```
+
+```http
+POST /v1/games/{game_id}/avatars-3d/{item_id}/award
+{ "player_id": "<uuid>", "wear": false }
+→ { "item_id", "player_id", "family", "newly_awarded", "worn" }
+```
+
+- **Only your server awards.** The call takes your game's server credential, or a serverless
+  function's for the player who called it. A browser never awards, and a server you started with a
+  developer credential is refused on `release` (it works on `dev` and `test`, so you can test).
+- **It works on every channel** and is written once per player and avatar: awarding it again answers
+  `newly_awarded: false` and changes nothing, so retrying is safe.
+- **At most 30 avatars are awardable at once**, counted apart from the 30 on sale; the 31st is
+  refused with `avatar_3d_award_limit_reached`. An avatar may be both on sale and awardable.
+- **`wear: true` puts it on** for the player, as buying does.
+- Don't award an avatar through an achievement reward: achievements unlock only on `release` and
+  share the 2D icon budget. Unlock the achievement as usual, and award the avatar from the same
+  server code.
+
+## 6. The purchase flow
+
+Your game draws the shop; the Arcade takes the money. Read the offers from the platform, show
+them, and call `purchase` from the player's own click:
+
+```js
+const offers = await gem.avatars3d.offers(); // what is on sale, priced by the platform
+
+for (const offer of offers) {
+  const tile = shop.addTile(offer.displayName, platformIconUrl(offer.iconUrl));
+  for (const { currencySlug, price } of offer.prices) {
+    tile.addButton(`${price} ${currencySlug === 'GEMS' ? 'Gems' : 'Tickets'}`, async () => {
+      const result = await gem.avatars3d.purchase({ itemId: offer.itemId, currencySlug });
+      if (result.outcome === 'declined' && result.reason === 'already_owned') {
+        gem.openAvatarPicker({ tab: '3d' }); // they have it: let them put it on
+      } else if (result.outcome === 'unavailable') {
+        shop.showMessage('The store is unavailable right now.');
+      }
+      // `ok`: nothing to do here — onChange already brought the new look.
+    });
+  }
+}
+```
+
+- **Render prices from `offers()`, never from numbers of your own.** The Arcade prices the sheet
+  again from the platform's record, so a price you typed is a price that disagrees with it.
+- **Call `purchase` from a click or key press.** The Arcade shows its confirmation sheet only on
+  one; anything else is answered `declined` with reason `busy`.
+- **A bought avatar is worn at once.** The Arcade wears it in its family and sends the player
+  again **before** it answers, so `onChange` runs and `worn()` already shows it when `purchase`
+  resolves `ok`.
+- **`ok` is checked.** The SDK asks the platform whether the player now owns the avatar before it
+  tells you `ok`; an answer it cannot confirm becomes `unavailable`.
+
+Every outcome resolves; nothing rejects.
+
+| What you get                      | What happened                                         | What to do                                                        |
+| --------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------- |
+| `ok`                              | bought, worn, and confirmed with the platform         | nothing — `onChange` has redrawn                                  |
+| `declined` / `already_owned`      | the player owns it already                            | offer `gem.openAvatarPicker({ tab: '3d' })`                       |
+| `declined` / `cancelled`          | the player closed the sheet                           | return to your shop silently                                      |
+| `declined` / `insufficient_funds` | the player cannot afford it                           | return silently; never draw a top-up                              |
+| `declined` / `not_purchasable`    | not on sale, retired, or not an id from `offers()`    | read `offers()` again                                             |
+| `declined` / `busy`               | no click, another sheet open, or a purchase in flight | let the player press again                                        |
+| `unavailable`                     | no reliable answer                                    | one neutral message; read `worn()` again; never retry on your own |
+
+**Outside the Arcade, `purchase` asks nobody.** Opened outside any Arcade, before the bridge is
+up, or under an Arcade that does not sell 3D avatars, it resolves `unavailable` with reason
+`error` at once — the same as `gem.purchases.request` does there. `offers()` still reads the
+platform with your game's token, so a shop can show what is on sale.
+
+**Purchases are real on every channel.** On `dev` and `test` a purchase spends the player's real
+Gems or Tickets and grants a real avatar they keep, exactly as on `release`. Test with your
+organization's test accounts.
+
+## 7. Read the worn avatar, and load it at runtime
+
+The SDK is the package [getting-started.md](getting-started.md#3-add-the-sdk) installs; three.js
+is your own dependency.
+
+```js
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { platformIconUrl } from '@indiegems/gem-web-sdk/sdk';
+
+const loader = new GLTFLoader();
+let shown = null; // the model URL on screen now
+
+async function wear() {
+  const worn = gem.avatars3d.worn('small_human'); // or worn(): your first declared family
+  const url = worn && platformIconUrl(worn.modelUrl);
+  if (!url) return hero.useDefaultLook(); // nothing worn, or a host the platform does not own
+  if (url === shown) return;
+  shown = url;
+  try {
+    const gltf = await loader.loadAsync(url);
+    if (shown === url) hero.setCharacter(gltf.scene, gltf.animations);
+  } catch {
+    if (shown === url) hero.useDefaultLook(); // a model that fails is not a reason to show nothing
+  }
+}
+
+hero.useDefaultLook(); // never hold the boot for a model
+wear();
+gem.avatars3d.onChange(wear);
+```
+
+- **`worn()` is read live** from the player the Arcade pushed. It is `undefined` before the player
+  arrives, outside the Arcade, and when nothing is worn in that family — draw your default look.
+- **`onChange` runs whenever what is worn changes**: the player picked another avatar in the
+  Arcade's picker — from your own "Change avatar" button (`gem.openAvatarPicker({ tab: '3d' })`)
+  or the Arcade's menu — bought one, or their avatars arrived for the first time. It does not run
+  for the avatar already worn when you subscribe; read `worn()` for that.
+- **Pass every URL through `platformIconUrl`** before you load it. Loading a model is a request
+  that carries your player's `Referer`, so only the platform's own item host is allowed; anything
+  else reads as `undefined`. Against a development backend that includes its own item host, so
+  there you see your default look.
+- **A model URL never changes what it serves**, so cache by URL. When one fails to load, show your
+  default look and do not retry in a loop; the next `onChange` is the next chance.
+- **Attach and animate by the rig's names.** Look nodes up by name, never by index:
+
+  ```js
+  function setCharacter(scene, clips) {
+    const node = (name) => scene.getObjectByName(name);
+    node('hand_socket').add(sword); // a held item goes on the socket
+    if (clips.length > 0) {
+      mixer = new THREE.AnimationMixer(scene); // the model's own clips, when it has them
+      mixer.clipAction(clips[0]).play();
+    } else {
+      walk = (t) => {
+        // otherwise, swing the limbs yourself
+        node('arm_l').rotation.x = Math.sin(t * 6) * 0.6;
+        node('arm_r').rotation.x = -Math.sin(t * 6) * 0.6;
+        node('leg_l').rotation.x = -Math.sin(t * 6) * 0.5;
+        node('leg_r').rotation.x = Math.sin(t * 6) * 0.5;
+      };
+    }
+  }
+  ```
+
+  Clip names are the model maker's, not a contract — play one only by a name you checked for, or
+  animate the named nodes, which every model in the family has.
+
+**Other players' avatars** come the same way on every surface that shows a player: a room member,
+a leaderboard row, a friend. Each carries `avatars3d` — one per family — and the flat
+`avatar3dId`, `avatar3dModelUrl` and `avatar3dIconUrl` of your first family. A server reads
+`avatars_3d` and `avatar_3d_id` from the room read; nothing tells a server a player changed, so
+when `onChange` fires, have your client tell your server and have the server **re-read the room**
+— never trust an id the client sends.
+
+## 8. Moving from 2D items, achievements and the `arcade-avatars` tag
+
+Games that drew characters before 3D avatars existed did it with 2D portrait items granted by
+achievements, a bundled copy of each character's model keyed on `avatarIconId`, and the store tag
+`arcade-avatars`. Move to 3D avatars like this:
+
+1. **Upload one `small_human` avatar per old character** with `gemctl item upload`, as in
+   section 4.
+2. **Ask the platform team to map each old 2D item to its new avatar.** The platform then grants
+   every player who owns the 2D item the matching 3D avatar, and wears it for a player whose 3D
+   slot is empty and who wears that portrait. Players keep their 2D portraits.
+3. **Declare `avatars_3d: { families: [small_human] }` on every channel** (section 3), and **remove
+   the achievements and progressions that granted the 2D items**.
+4. **Put the avatars on sale** with `gemctl item sell`, and **make the ones players win
+   awardable** and award them from your server (section 5).
+5. **Ship a build that reads `gem.avatars3d.worn()` and loads the model at runtime** (section 7),
+   and delete the bundled character models and the `avatarIconId` mapping.
+6. **Remove the `arcade-avatars` tag from your store page.** It is deprecated. For a game whose
+   config declares no families the Arcade still reads the tag as accepting `small_human`, which
+   is what keeps an unmoved game working while you switch; do not rely on it once you have — a
+   declared family is what the Arcade reads.

package/docs/changelog.md

@@ -16,6 +16,29 @@ 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.
 
+## 13.0.0
+
+Upgrading from 12.0.0. Impact: required.
+
+### Must change
+
+- The controls declaration is gone. Remove every call that declares controls, along with any code that builds a controls declaration or a control choice, because these no longer exist and the game will not compile against them. Follow the updated settings guidance for how the game now exposes settings and controls.
+- If you embed the game in your own host, remove the controls-declare callback from the host options and callbacks, because the host no longer receives that message and the property is no longer accepted.
+- setMenu no longer takes a settings flag as its first argument. Pass only the optional list of menu items. Also remove any onSettings handler from the game menu, since that handler is gone.
+
+### Rebuild
+
+- The purchase refusal code gains a new value, already_owned, for purchases of something the player already has. Recompile; if the game switches over refusal codes exhaustively, add a branch for it.
+- The list of messages a game frame sends to its parent, the frame message type, and the capability names each gain an entry for 3D avatar purchases, including the new avatar3dPurchases capability. Recompiling is enough unless the game or host switches over these values exhaustively.
+
+### New capability
+
+- A game can now work with 3D avatars. The new avatars3d API lists the avatar rig families the game supports, reports the avatar a player wears per family, lists avatar offers and their prices, starts a purchase, and notifies the game when the worn avatar changes. Purchases are also available through the frame, gated by the avatar3dPurchases capability, and are answered like other purchases. Outside the Arcade, avatar purchases are unavailable immediately.
+- The worn 3D avatar, one per rig family, is now available on the current player and on other players' data, including friends, leaderboard entries, profiles, showcase friends, player identities and room members. Use it to render other players with the avatar they wear.
+- The game configuration can now declare the 3D avatar families the game supports through avatar_3d_families.
+- If you embed games in your own host, you can now supply worn 3D avatars when sending player information, handle 3D avatar purchase requests with the new request callback, and validate those requests with the new validator and message type.
+- Server-side code can now read the worn 3D avatars in avatars_3d on player and subject identity data, using the new worn avatar type.
+
 ## 12.0.0
 
 Upgrading from 11.1.2. Impact: required.

package/docs/getting-started.md

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

package/docs/manifest.json

@@ -16,6 +16,11 @@
       "sha256": "57fb07c3d649c2758a35660707d31b05164b363e9a425156978aed394d086339",
       "updated": "2026-10-02T14:04:37Z"
     },
+    {
+      "file": "arcade-avatars.md",
+      "sha256": "355bba7936ec7f0a65d52ec65a6add323c75a992d931de9cd23319ed9d8aeb52",
+      "updated": "2026-10-14T06:27:58Z"
+    },
     {
       "file": "arcade-economy.md",
       "sha256": "9058c26bc11266f235dfa3c72c80a3fc962aa9f204ef491006e6d34545f5eeeb",
@@ -33,8 +38,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "bf2786be31121bb229d10d98f701165aefb2e7166271299450c926401661dfd2",
-      "updated": "2026-10-12T22:12:20Z"
+      "sha256": "914fb511d6f15af9ccf0d71e2309dcaf35369d4e4272233927ab7e48b47921a3",
+      "updated": "2026-10-14T06:33:54Z"
     },
     {
       "file": "cross-promotion.md",
@@ -68,8 +73,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "19bf05cd8f7afe5e9f406af6aef090a73bb3c2fb713f06185ead36fc2bb104dc",
-      "updated": "2026-10-12T22:12:20Z"
+      "sha256": "6aef9e454064492b2164417e1b31050e0f487c48edab07d5b58b5df9bb089bff",
+      "updated": "2026-10-14T06:33:54Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -118,13 +123,13 @@
     },
     {
       "file": "saving-player-progress.md",
-      "sha256": "08778cccc7d7a9a26a005a070bb2cc98784752ebec9dfce9873ef3d4e674e1e0",
-      "updated": "2026-10-05T16:53:25Z"
+      "sha256": "11ab0684247cfc43d6d8faba6dbb897192354af5f5622b16fd96abcb156ca0cd",
+      "updated": "2026-10-12T21:21:05Z"
     },
     {
       "file": "server-bundles.md",
-      "sha256": "52054ceeb56b7130bfaf3461c2d81a9bd3b3dcd0f95097753ebfffc08f7a1cbb",
-      "updated": "2026-10-12T22:12:20Z"
+      "sha256": "8b19574001cefea73b1892dd864d360dc0e5dfd252e9d291f7ccb08a170b48d9",
+      "updated": "2026-10-14T06:33:54Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -148,8 +153,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "275ca0984cdeb9d52221df0700516f85d3b24d41457ee09e0e1326f6ed3c8112",
-      "updated": "2026-10-12T16:40:39Z"
+      "sha256": "ca29417cbe0c337efe44c3d6f44f943ff27425fbb11e208faff1207d2b6f912c",
+      "updated": "2026-10-13T14:23:52Z"
     }
   ]
 }

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.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v13.0.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

@@ -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": "12.0.0",
+  "version": "13.0.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",