@indiegems/gem-web-sdk 12.0.0 → 13.1.0

package/docs/arcade-avatars.md

@@ -0,0 +1,471 @@
+# 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
+
+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. There are two:
+
+- **`small_human`**, a toy: rigid limbs on a body, eight nodes, no elbows, knees or fingers.
+- **`adult_human`**, a full adult skeleton with a spine, elbows, knees, toes and fingers, 56
+  nodes, built so one animation plays on every avatar in the family.
+
+Pick the one your characters are made of. A game that draws both kinds declares both (section 3).
+
+**Never retype the node names.** `AVATAR_RIGS` lists every node of each family with the node it
+is a direct child of, parents first, so your game finds its joints, and your tests check a model,
+by the names the platform checks:
+
+```js
+import { AVATAR_RIGS } from '@indiegems/gem-web-sdk/sdk';
+
+AVATAR_RIGS.adult_human; // [{ node: 'root', parent: null }, { node: 'hips', parent: 'root' }, …]
+```
+
+### What every family's upload must pass
+
+The platform checks every model when it is uploaded, and gemctl runs the same checks on your
+machine first. A model is refused when it breaks any of these:
+
+- **The names are exact and case-sensitive**, each appears **exactly once**, and each is the
+  **direct child** of the parent its family gives. The family's `root` is a root node of the
+  scene.
+- **Anything else is allowed**: extra nodes anywhere (twist bones, a cape, accessories), 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.
+
+### `small_human`
+
+```
+root
+└── body
+    ├── head
+    ├── arm_l
+    ├── arm_r
+    │   └── hand_socket
+    ├── leg_l
+    └── leg_r
+```
+
+`body` is the child of `root`; `head`, `arm_l`, `arm_r`, `leg_l` and `leg_r` are children of
+`body`; `hand_socket` is a child of `arm_r`. A held item goes on `hand_socket`. Nothing is checked
+about its pose or its size.
+
+### `adult_human`
+
+`_l` and `_r` are the **character's** left and right.
+
+```
+root                                    the ground between the feet
+└── hips
+    ├── spine
+    │   └── chest
+    │       └── upper_chest
+    │           ├── neck
+    │           │   └── head
+    │           │       └── head_socket       hats and helmets
+    │           ├── shoulder_l
+    │           │   └── upper_arm_l
+    │           │       └── lower_arm_l
+    │           │           └── hand_l
+    │           │               ├── hand_socket_l   held items
+    │           │               ├── thumb_1_l  > thumb_2_l  > thumb_3_l
+    │           │               ├── index_1_l  > index_2_l  > index_3_l
+    │           │               ├── middle_1_l > middle_2_l > middle_3_l
+    │           │               ├── ring_1_l   > ring_2_l   > ring_3_l
+    │           │               └── little_1_l > little_2_l > little_3_l
+    │           └── shoulder_r … the same as the left, with hand_socket_r
+    ├── upper_leg_l
+    │   └── lower_leg_l
+    │       └── foot_l
+    │           └── toes_l
+    └── upper_leg_r > lower_leg_r > foot_r > toes_r
+```
+
+`a > b > c` is a chain: `b` is the child of `a`, and `c` of `b`. That is 56 nodes: `root`, six
+down the middle, four in each arm, fifteen finger joints in each hand, four in each leg, and three
+sockets.
+
+**Space and units are glTF's own**: Y is up, the character faces **+Z**, and a unit is a
+**metre**. Its left hand is toward +X. `root` sits at the origin, on the ground between the feet.
+
+**The rest pose is a T-pose**: legs straight down, arms straight out to the sides (the left along
++X, the right along −X), palms down, fingers straight along the arm, and the thumb forward (+Z)
+and slightly out.
+
+**Every rig node is world-aligned at rest.** Each of the 56 has an identity rotation and a scale
+of 1; only its position differs from one avatar to the next. This is what makes animation
+portable: a rotation you set on a joint is measured from the same rest on every avatar, so a clip
+written for one plays the same on a tall, short, thin or wide one. A model whose bones keep the
+turn a modelling tool gives them (Blender, for one, exports each bone turned to point along its
+length) would play every clip twisted, so the platform refuses it. On top of the checks every
+family passes, an `adult_human` model is refused when:
+
+- **a rig node is rotated** more than 2° from identity, or **scaled** more than 0.001 from 1;
+- **a rig node uses `matrix`** instead of translation, rotation and scale;
+- **`root` is moved** more than 1 mm from the origin;
+- **the hips are not 0.6 to 1.3 m up** (the heights of `root` and `hips` added): a model exported
+  in centimetres is a hundred times too big, and a toy is too small.
+
+**The sockets** are plain nodes, empties or bones. `head_socket` sits on the crown of the head,
+where a cap's band rests. `hand_socket_l` and `hand_socket_r` sit at the centre of the closed
+grip, inside the curled fingers. Like every rig node they are world-aligned, so a hat or a bat
+modelled upright, facing +Z, with its grip at its origin, sits the same way on every avatar.
+Where a socket sits is not checked; the reference rig (below) follows it.
+
+**Keep it light for a phone.** Not checked, but every game that accepts the family loads the
+model, and other players' avatars beside it: up to 15,000 triangles, one 1024 × 1024 texture
+(embedded JPEG or PNG), and up to four bone influences per vertex.
+
+**Start from the reference rig.** The package ships one:
+`node_modules/@indiegems/gem-web-sdk/rigs/adult_human.glb`, a plain skinned mannequin about
+1.75 m tall, with no textures and no clips, that passes every check above. Make your game's clips
+on it, and test your own avatars against it; import it by path
+(`@indiegems/gem-web-sdk/rigs/adult_human.glb`) for a test scene. To export a rig of your own from
+Blender with an identity rest: give every bone the same orientation in armature space (pointing
+up, its local Z toward the character's front), make the sockets bones, keep the armature object
+as the node `root`, and export with **+Y Up** on, `export_rest_position_armature=True` and
+`export_def_bones=False`.
+
+**Uploads wait for the platform to enable the family.** Where it is not enabled yet, an
+`adult_human` upload is refused with `unknown_avatar_family`. Build and test against the
+reference rig until then; nothing in your game changes when it is.
+
+#### Pose it, or play your own clip on it
+
+The model's own clips are its maker's and no contract. Your game brings its own animations and
+plays them on the rig's names. Load the avatar as section 7 shows, then find the joints:
+
+```js
+import * as THREE from 'three';
+import { AVATAR_RIGS } from '@indiegems/gem-web-sdk/sdk';
+
+const joints = {};
+for (const { node } of AVATAR_RIGS.adult_human) joints[node] = avatar.getObjectByName(node);
+
+joints.hand_socket_r.add(bat); // a held item, modelled upright, facing +Z, grip at its origin
+joints.head_socket.add(cap);
+```
+
+**Pose it in code** by setting rotations on named joints. Every angle is measured from the
+T-pose, because the rest rotation is identity, and `quaternion.identity()` puts a joint back:
+
+```js
+function sitAtTheWheel() {
+  for (const joint of Object.values(joints)) joint.quaternion.identity(); // back to the T-pose
+  joints.upper_leg_l.rotation.x = joints.upper_leg_r.rotation.x = -Math.PI / 2; // thighs forward
+  joints.lower_leg_l.rotation.x = joints.lower_leg_r.rotation.x = Math.PI / 2; // shins down
+  joints.upper_arm_l.rotation.y = -Math.PI / 2; // left arm forward
+  joints.upper_arm_r.rotation.y = Math.PI / 2; // right arm forward
+  for (const finger of ['index', 'middle', 'ring', 'little']) {
+    for (const k of [1, 2, 3]) {
+      joints[`${finger}_${k}_l`].rotation.z = -1.2; // curl toward the palm
+      joints[`${finger}_${k}_r`].rotation.z = 1.2;
+    }
+  }
+}
+```
+
+**Play a clip** you made on the reference rig, from a file of your own. Its tracks name the rig's
+nodes, so a mixer on any avatar finds them:
+
+```js
+const { animations } = await loader.loadAsync('/anims/driver.glb'); // your clips, not the avatar's
+const seated = THREE.AnimationClip.findByName(animations, 'seated');
+seated.tracks = seated.tracks.filter((track) => track.name.endsWith('.quaternion'));
+
+const mixer = new THREE.AnimationMixer(avatar);
+mixer.clipAction(seated).play();
+// every frame: mixer.update(dt)
+```
+
+- **Keep only the rotation tracks.** A position or scale track carries the reference rig's bone
+  lengths onto every avatar: a short player's hips are lifted to the reference rig's height. Move
+  and turn the whole character by the object that holds it.
+- **Scale the object that holds the avatar, never a rig node**, when your world is not in metres.
+- **One loaded copy per character on screen.** Two players wearing the same avatar need two
+  copies: clone a skinned model with three.js's `SkeletonUtils.clone`, never `Object3D.clone`,
+  which leaves both copies' meshes moving with one skeleton.
+
+### When an upload is refused
+
+| 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                  |
+| `rig_mismatch` with `details.not_at_rest` | an `adult_human` rig node is not at rest, or the model is the wrong size | read each `{ node, reason }`, e.g. `"rotated 37°"` or `"hips at 92 m"`; apply rotation and scale, export in metres |
+| `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 is not one the platform knows, or not enabled yet             | use `small_human` or `adult_human`; an `adult_human` upload waits until it is enabled                              |
+
+## 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.
+- **A game can declare both families**, `families: [adult_human, small_human]`, when it draws
+  both kinds of character. A player wears one avatar in each family, so ask for the one you draw
+  by name, `worn('adult_human') ?? worn('small_human')`, and animate each on its own rig: a
+  clip made for one rig does not fit the other.
+- **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; `--family adult_human` uploads one on the adult rig. gemctl checks
+the rig (and an `adult_human` model's rest pose), 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. This is a
+  `small_human` model; an `adult_human` one is posed and animated as section 2 shows:
+
+  ```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/brand-art.md

@@ -283,7 +283,7 @@ decision of that date); the ruling's other rules are unchanged. In rules:
 
 - **Keep no Gems counter.** Your game shows no Gems balance, running total or wallet of its own, on
   any screen. The arcade's wallet is the only place Gems accrue, and the only place a total is shown
-  — in the Gem Arcade, the Gem menu, which the player opens from the Gem button at the top-left.
+  — in the Gem Arcade, the Gem menu, which the player opens from the Gem button.
 - **Draw no Gems flight or celebration of your own.** No particles flying to a corner, no counting-up
   number, no burst of gems. `gem.cueReward` is the animation, and the arcade draws it.
 - **Show no Gems amount at all when you are not connected to the arcade.** Without the arcade there is
@@ -308,8 +308,8 @@ decision of that date); the ruling's other rules are unchanged. In rules:
 
   A Tickets payout is cued the same way, from the ticket, with `currencySlug: 'ARCADE_TICKETS'`. The
   slug decides what flies — gems or tickets — and which total the platform moves. In the Gem Arcade
-  every payout flies into the Gem button at the top-left of your frame; no wallet is drawn over
-  your game.
+  every payout flies into the Gem button, in whichever corner of your frame it sits; no wallet is
+  drawn over your game.
 - **If `cueReward` returns `false`, do nothing.** There is no fallback celebration. `false` means the
   arcade will not show the payout here — the bridge is not up, or the embedder has no wallet — and
   your game does not replace it with one of its own. Your reward screen still says what was earned;

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.1.0
+
+Upgrading from 13.0.0. Impact: required.
+
+### Rebuild
+
+- Avatar3dFamily now also accepts adult_human alongside small_human. Recompile your game. If any code switches over the family and assumes small_human is the only named value, add handling for adult_human or a sensible default.
+- The list of messages a frame sends to its parent, the FrameMessage type, and the GemCapability type each gained a member for the Gem button corner (the gem.gemCorner message and the gemCorner capability). Recompile your game. If your code matches these unions exhaustively, add a case for the new member.
+
+### New capability
+
+- Your game can now ask the Arcade to move its Gem button to another corner by calling setGemCorner, using the GemCorner type for the value. Check that the gemCorner capability is available before relying on it, since the Arcade decides whether to honour the request.
+- The adult_human avatar rig family is now available, and AVATAR_RIGS exposes the node and parent trees of both the small_human and adult_human rigs, described by the AvatarRigNode and AvatarRigs types. The package also ships a reference rig for adult_human, reachable through a new rigs export. Use these to attach items or animations to the right nodes of either family.
+
+## 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.1.0"
 }
 ```
 
@@ -178,7 +178,8 @@ gem.frame.progress(loaded, total); // while assets load
 gem.frame.ready(); // once the player can actually play
 ```
 
-And draw a settings button of your own — top-right is the recommendation — whose values start from
+And draw a settings button of your own — top-right, with your Back button just to its left
+([the top of the screen](what-a-game-must-do.md#the-top-of-the-screen)) — whose values start from
 the player's Arcade-wide defaults, `gem.prefs.recommended`, until the player chooses their own
 ([what a game must do](what-a-game-must-do.md#game-settings)). The Arcade's menu does not open
 your settings. Outside the Arcade there is no Arcade menu at all, so also give players a way out — a

package/docs/inventory-and-catalogs.md

@@ -590,7 +590,7 @@ the source progression from a function the player calls, on a progression that o
 
 **Platform-currency display belongs to the arcade** (the creator's ruling, 2026-09-24) — Gems and
 Tickets alike. The arcade shows the player's platform currencies in its own chrome — in the Gem
-Arcade, the Gem menu the player opens from the Gem button at the top-left of your frame; no wallet
+Arcade, the Gem menu the player opens from the Gem button over your frame; no wallet
 is drawn over your game — and moves a total when the platform confirms a grant. Your game keeps no counter or balance
 of a platform currency of its own, draws no flight or celebration of its own, and shows no
 platform-currency amount at all when it is not connected to the arcade.

package/docs/manifest.json

@@ -16,6 +16,11 @@
       "sha256": "57fb07c3d649c2758a35660707d31b05164b363e9a425156978aed394d086339",
       "updated": "2026-10-02T14:04:37Z"
     },
+    {
+      "file": "arcade-avatars.md",
+      "sha256": "7269a0dbd515e2c52e63f9fad2b3028e136396522aa68aa177c44f7eceb2c0e0",
+      "updated": "2026-10-14T19:48:50Z"
+    },
     {
       "file": "arcade-economy.md",
       "sha256": "9058c26bc11266f235dfa3c72c80a3fc962aa9f204ef491006e6d34545f5eeeb",
@@ -28,13 +33,13 @@
     },
     {
       "file": "brand-art.md",
-      "sha256": "87267dca53e5506b1aee77ac9819aef8025c8e0de2780e65a2ea3b7236a9c0ab",
-      "updated": "2026-10-11T18:48:12Z"
+      "sha256": "44ba566da97e499f80b6c4898a5546bf7fb3dfba2290da9aa3e8d4e6056a7cce",
+      "updated": "2026-10-14T21:18:16Z"
     },
     {
       "file": "changelog.md",
-      "sha256": "bf2786be31121bb229d10d98f701165aefb2e7166271299450c926401661dfd2",
-      "updated": "2026-10-12T22:12:20Z"
+      "sha256": "3041e5a29aec35ed4a1d299410d9a0795a7c48958f314a6497ca2b567ccaf000",
+      "updated": "2026-10-14T22:00:06Z"
     },
     {
       "file": "cross-promotion.md",
@@ -68,13 +73,13 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "19bf05cd8f7afe5e9f406af6aef090a73bb3c2fb713f06185ead36fc2bb104dc",
-      "updated": "2026-10-12T22:12:20Z"
+      "sha256": "651392ad1b3bb28bd43cfb0a0df0a88b3d8c2e46a4bbb1cb9fcbbe762459f22e",
+      "updated": "2026-10-14T22:00:06Z"
     },
     {
       "file": "inventory-and-catalogs.md",
-      "sha256": "fecd1299ef19bc50ea17abe96bbe49f62dc366a9fc0f354c843a42b2d5a2f9e2",
-      "updated": "2026-10-11T18:48:12Z"
+      "sha256": "4251f451c48ab80bb7a9c50a6a717dfca6e057ff128d32ecb5e2cd13d28c5b7d",
+      "updated": "2026-10-14T21:18:16Z"
     },
     {
       "file": "leaderboards.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": "c83325c8471f0ea2578f3476660751ad7f4fd96a51eb902336e57d7553ec5e46",
+      "updated": "2026-10-14T22:00:06Z"
     },
     {
       "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": "7006e2e2900d71417002937d51a8d10ad9bcfdf02cd1b27f0f923e4cbe4ee79b",
+      "updated": "2026-10-14T21:18:16Z"
     }
   ]
 }