@indiegems/gem-web-sdk 11.1.2 → 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,43 @@ 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.
+
+### Rebuild
+
+- The list of capability names gained ticketEvents. Recompile your game. If your code switches exhaustively over capability names, add a case for the new one.
+- The list of messages the parent sends to the frame, and the union of parent message types, each gained a ticket event message. Recompile your game. If your code switches exhaustively over these message names or types, handle or ignore the new one.
+
+### New capability
+
+- A party member's game can now show the matchmaking ticket its party is queued on. Read the ticket through the rooms manager, or listen for the new partyQueued room event. The view is read-only: it has a status, a party size, two instants and an outcome, and it cannot be cancelled. A matched ticket does not carry the room. The room is reported separately once the SDK has confirmed the player is seated in it. The view ends on its own as lost once the ticket's lifetime has passed with no ending heard. For the player who queued, the ticket still comes from the platform's own answer.
+- Games that build their own frame can now pass an onTicketEvent callback to receive ticket state changes pushed by the parent. It is delivered only when the parent relays ticket events and advertises the new ticketEvents capability. Under a parent that does not, nothing changes and the callback is never called. Ticket events name no player and do not carry the templates a ticket named.
+
 ## 11.1.2
 
 Upgrading from 11.1.1. Impact: none.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "11.1.2"
+  "@indiegems/gem-web-sdk": "13.0.0"
 }
 ```
 
@@ -66,7 +66,10 @@ is involved, and nothing is built when you install.
 **`/sdk` is the import, from every seat.** It carries the whole surface, so client code, a
 dedicated server bundle and a listen host all import the same path and the same names.
 `.`, `/game` and `/server` stay published as narrow doors over the same modules — a game
-wants none of them unless it knows why.
+wants none of them unless it knows why. `/function` is the fourth door, for code that runs as
+a serverless function ([serverless-functions-js.md](serverless-functions-js.md)). The function
+starter's build resolves `/sdk` and `/game` to it, so verification code shared with your game
+keeps its import.
 
 **`dependencies`, not `devDependencies`.** The SDK is part of what your game ships — your
 bundler compiles it into the browser build and into the server bundle — so a `--production`

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": "f88799ff04404b0ad76c5774375a66772c9ed7a64b59ca566f473f1302c9b2d7",
-      "updated": "2026-10-12T17:30:48Z"
+      "sha256": "914fb511d6f15af9ccf0d71e2309dcaf35369d4e4272233927ab7e48b47921a3",
+      "updated": "2026-10-14T06:33:54Z"
     },
     {
       "file": "cross-promotion.md",
@@ -68,8 +73,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "4a824bccf87d75c2884a7159b44c768b39096f815b80fa7b5018da2862add89e",
-      "updated": "2026-10-12T17:30:48Z"
+      "sha256": "6aef9e454064492b2164417e1b31050e0f487c48edab07d5b58b5df9bb089bff",
+      "updated": "2026-10-14T06:33:54Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -113,28 +118,28 @@
     },
     {
       "file": "rooms-and-matches.md",
-      "sha256": "971e67d9cb74a046cddc0ff76cdea64f1aef3af8e9376944388ca8aa87730729",
-      "updated": "2026-10-12T02:26:43Z"
+      "sha256": "29cf42a4334d3d9702e6a7f6e04c52fb2b414af3340043c2f98b2bfafa7dc64d",
+      "updated": "2026-10-12T19:59:08Z"
     },
     {
       "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": "f1ff81f3ee1950dae0d8b0fab66994eeec99d6e6bf1684b121c742f29d63e0b9",
-      "updated": "2026-10-12T17:30:48Z"
+      "sha256": "8b19574001cefea73b1892dd864d360dc0e5dfd252e9d291f7ccb08a170b48d9",
+      "updated": "2026-10-14T06:33:54Z"
     },
     {
       "file": "serverless-functions-js.md",
-      "sha256": "56588d50d5a59f066164565470663f8f9da03fe85d98a96d3754e6ec14eb9fac",
-      "updated": "2026-10-10T00:12:33Z"
+      "sha256": "3904704418f9c6c246c8e1fa83f96901f6e493a3f4499b16fd6845620515e57d",
+      "updated": "2026-10-12T17:39:05Z"
     },
     {
       "file": "serverless-functions.md",
-      "sha256": "b1562b4442b69bb6895198def7b00ccd7a8c56133862a939c2cce9b6e9d30290",
-      "updated": "2026-10-07T19:27:16Z"
+      "sha256": "84881bcc40c6203c731ebf9092be575158d0ad3b3a65120321b695ae6558f63f",
+      "updated": "2026-10-12T17:39:05Z"
     },
     {
       "file": "trading-and-gifting.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/rooms-and-matches.md

@@ -140,6 +140,13 @@ frame that advertises `autoStartFailure`. It is not a sixth `gem.roomEvent` beca
 refuses an enum value it does not know, and reports that to the game as a protocol error; an unknown
 message type it ignores. The game sees it as `matchAutoStartFailed` (§4.4).
 
+**The matchmaking-ticket pushes cross the same way**, as `gem.ticketEvent`, to a frame that
+advertises `ticketEvents`. The platform tells every player a ticket seats when it is created,
+matched, or ended without a match, and the parent relays each one for the frame's own game: the
+ticket's id and new status, plus the party size and the two instants on creation, the reason on an
+ending without a match, and the room to look in on a match. The templates the ticket named do not
+cross, and no player is named on either side of the bridge. What a game does with it is §5c.
+
 There is exactly one filtering point and this is it. The engine keeps a full match event in native
 code and hands its scripting layer an allowlisted subset, because native code can hold a secret
 from a sandboxed script. **The frame-side SDK cannot** — it shares a JavaScript realm with the game,
@@ -794,11 +801,15 @@ every game.
   platform sends the push a moment before it marks the ticket. So on a page that relays, a match is
   noticed in about the time the push takes, not at the next heartbeat. A tab returning to the
   foreground is the same cue. Like every relay it is a hint: nothing is entered on its strength.
+  **A relayed ticket push is the same cue**, so an ending without a match is noticed as quickly as a
+  match is. The ticket's outcome still comes from the platform's answer, never from the push.
 - **It refuses a second thing in flight.** While a ticket waits, `create`, `join`, `joinByCode`,
   `quickJoin` and another `queueForMatch` are refused locally.
 - **It cancels the ticket when the tab closes.** See below.
 - **It raises no `seated` for the ticket's own room.** The owner is told by the outcome. Party
-  members, who hold no ticket, are told by `seated` as they are for any room their leader enters.
+  members, who hold no ticket, are told by `seated` as they are for any room their leader enters —
+  and, on a page that relays ticket events, by `partyQueued` while the party waits. See
+  [A party member's view](#a-party-members-view-of-the-ticket).
 
 ### Queueing from inside a room
 
@@ -862,6 +873,58 @@ seat stands, so `myRooms()` shows the room and `join(id)` enters it.
 `cancel()` resolves the ticket's real outcome, and that may be `matched`. Backing out from there is
 `gem.rooms.leave()`.
 
+### A party member's view of the ticket
+
+A party queues as **one ticket, and it is the leader's**. Only the leader calls `queueForMatch()`,
+and only a ticket's owner can read it, keep it alive or cancel it. So a member's game holds no
+ticket — and without help it knows nothing about the queue its player is standing in until the match
+pulls them in.
+
+On an arcade page that relays ticket events, the member's game is told. When the leader queues,
+`gem.rooms.partyTicket` is set and `partyQueued` is raised with it:
+
+```js
+gem.rooms.on('partyQueued', async (ticket) => {
+  showSearching({ expiresAt: ticket.expiresAt, canCancel: false });
+  const outcome = await ticket.outcome;
+  if (outcome.status !== 'matched') backToMenu(outcome.status);
+  // `matched`: the room arrives through your `seated` handler.
+});
+```
+
+- **It is a view. There is no `cancel()`.** The ticket is the leader's to cancel. A member who wants
+  out leaves the party, which ends the ticket for everyone with reason `party_changed`. Draw the
+  searching screen without a leave-queue button.
+- **It costs no request.** Nothing is heartbeated and nothing is polled for it; everything the view
+  says came from a relayed push.
+- **`matched` carries no room.** The room is reported the way a party's seat always is, the `seated`
+  event, and that handler is where a game joins it. The SDK looks for the seat as soon as it hears
+  `matched`, and reports it only after reading the room over the game's own token and finding this
+  player in it.
+- **It ends by itself.** The pushes are sent once. A member's game that missed the ending would
+  otherwise show a searching screen for ever, so the view ends as `lost` a few seconds after the
+  ticket's lifetime has run out with nothing more heard. A seat found by the SDK's own seat check
+  ends it as `matched`, whether or not that push arrived.
+- **Never set beside `currentTicket`.** The player who queued holds the ticket itself and gets no
+  `partyQueued`.
+
+| `status` | `reason` | What happened |
+| --- | --- | --- |
+| `matched` | — | The party is seated and the match is starting. `seated` has the room. |
+| `expired` | `timed_out` | Nobody to play with before the ticket's expiry. |
+| `expired` | `heartbeat_lapsed` | The leader's game stopped keeping the ticket alive: a closed, throttled or offline tab. |
+| `cancelled` | `requested` | The leader cancelled. |
+| `cancelled` | `party_changed` | The party gained or lost a member while it waited. |
+| `failed` | `handoff_failed` | A match formed and could not be started, several times over. |
+| `lost` | — | The SDK's own conclusion: the ticket's lifetime ran out and no ending was heard. |
+
+⚠️ **Build it as an extra, never as a step.** The view exists only where the page relays ticket
+events, and only for a game that was already running when the leader queued: a push sent before the
+game was listening is not sent again. In every other case `partyTicket` stays `null`, no
+`partyQueued` is raised, and the member is carried into the match by `seated` with no lead-up. That
+path has to keep working, so the `seated` handler is what enters the match and the searching screen
+is only something shown on the way.
+
 ### The refusals when queueing
 
 `queueForMatch()` itself rejects with `GemApiError` when no ticket was made. Branch on `code`:

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/v11.1.2/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v11.1.2/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
 ```