@indiegems/gem-web-sdk 13.0.0 → 13.1.0

package/docs/arcade-avatars.md

@@ -24,10 +24,46 @@ 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
+## 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. The first family is `small_human`:
+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
@@ -40,29 +76,155 @@ root
     └── leg_r
 ```
 
-The platform checks every `small_human` model when it is uploaded and refuses one that breaks any
-of these:
+`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.
 
-- **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.
+### `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 |
-| `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`                                                                                 |
+| 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
 
@@ -85,6 +247,10 @@ 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
@@ -97,8 +263,9 @@ 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
+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
@@ -249,7 +416,8 @@ gem.avatars3d.onChange(wear);
   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:
+- **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) {

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,20 @@ 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.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "13.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

@@ -18,8 +18,8 @@
     },
     {
       "file": "arcade-avatars.md",
-      "sha256": "355bba7936ec7f0a65d52ec65a6add323c75a992d931de9cd23319ed9d8aeb52",
-      "updated": "2026-10-14T06:27:58Z"
+      "sha256": "7269a0dbd515e2c52e63f9fad2b3028e136396522aa68aa177c44f7eceb2c0e0",
+      "updated": "2026-10-14T19:48:50Z"
     },
     {
       "file": "arcade-economy.md",
@@ -33,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": "914fb511d6f15af9ccf0d71e2309dcaf35369d4e4272233927ab7e48b47921a3",
-      "updated": "2026-10-14T06:33:54Z"
+      "sha256": "3041e5a29aec35ed4a1d299410d9a0795a7c48958f314a6497ca2b567ccaf000",
+      "updated": "2026-10-14T22:00:06Z"
     },
     {
       "file": "cross-promotion.md",
@@ -73,13 +73,13 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "6aef9e454064492b2164417e1b31050e0f487c48edab07d5b58b5df9bb089bff",
-      "updated": "2026-10-14T06:33:54Z"
+      "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",
@@ -128,8 +128,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "8b19574001cefea73b1892dd864d360dc0e5dfd252e9d291f7ccb08a170b48d9",
-      "updated": "2026-10-14T06:33:54Z"
+      "sha256": "c83325c8471f0ea2578f3476660751ad7f4fd96a51eb902336e57d7553ec5e46",
+      "updated": "2026-10-14T22:00:06Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -153,8 +153,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "ca29417cbe0c337efe44c3d6f44f943ff27425fbb11e208faff1207d2b6f912c",
-      "updated": "2026-10-13T14:23:52Z"
+      "sha256": "7006e2e2900d71417002937d51a8d10ad9bcfdf02cd1b27f0f923e4cbe4ee79b",
+      "updated": "2026-10-14T21:18:16Z"
     }
   ]
 }

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