@indiegems/gem-web-sdk 10.4.0 → 11.0.0

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

@@ -1457,41 +1457,91 @@ This is a platform rule, not advice — see
 
 ### Arcade avatars: the character the player wears, and changing it mid-game
 
-Some games draw **Arcade avatars**: whole characters the player owns as Arcade portrait items and
-wears as their Arcade portrait (store tag `arcade-avatars`). Such a game keys its own model on
-**`avatarIconId`**, the worn item's id — on `gem.player` for the signed-in player, as on every room
-member — rather than on the thumbnail.
+Some games draw **Arcade avatars** (store tag `arcade-avatars`): the player's look in your game is
+something they own and wear in the Arcade. The Arcade's avatar picker has **two tabs**, and they
+are **two separate worn choices** — wearing one never changes the other:
+
+| Tab | What the player wears | On `gem.player` and every room member |
+|---|---|---|
+| **2D** | a portrait — a picture | `avatarIconId`, `avatarIconUrl` (`avatar_icon_id`, `avatar_icon_url` on the wire) |
+| **3D** | a 3D character — a rigged model | `avatar3dId`, `avatar3dModelUrl`, `avatar3dIconUrl` (`avatar_3d_id`, `avatar_3d_model_url`, `avatar_3d_icon_url`) |
+
+- **`avatar3dId`** is the worn 3D character's item id. Absent means none is worn — draw your
+  game's default look.
+- **`avatar3dModelUrl`** is its model: a binary glTF (`.glb`, a few hundred kB) with one rig,
+  `root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, sometimes with animation clips
+  (an idle, say). It never changes at its URL, so cache it by URL.
+- **`avatar3dIconUrl`** is a rendered portrait of that character, for a roster or a menu where
+  loading the model is too much. It is **not** the 2D portrait.
+
+**Draw the 3D character, falling back to what you did before.** A game that drew characters
+before the 3D tab existed keyed its own models on `avatarIconId`. Keep that mapping as the
+fallback, and prefer the 3D character when one is worn:
 
-**Redraw from `onPlayer`, not from boot alone.** The Arcade sends the player again whenever the
-portrait they wear changes, including mid-game from the Arcade's own menu, without your game
-asking. `onPlayer` runs and `gem.player` holds the new value; a field missing from the new player
-is missing now.
+```js
+import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
+import { platformIconUrl } from '@indiegems/gem-web-sdk/sdk';
+
+const loader = new GLTFLoader();
+
+async function characterFor(p) {
+  // 1. The 3D character the player wears — the platform's own model.
+  const url = platformIconUrl(p.avatar3dModelUrl); // pins the host, as for pictures
+  if (p.avatar3dId && url) {
+    try {
+      const gltf = await loader.loadAsync(url);
+      return { scene: gltf.scene, clips: gltf.animations };
+    } catch {
+      // A model that fails to load is not a reason to show nothing.
+    }
+  }
+  // 2. Your old mapping of the worn 2D portrait, then your default.
+  return myModelForPortrait(p.avatarIconId) ?? myDefaultCharacter();
+}
+
+const gem = createGem({ onPlayer: async (p) => hero.wear(await characterFor(p)) });
+```
+
+- **Pass every URL through `platformIconUrl` first** — the model too. Loading it is a request that
+  carries your player's `Referer`, so only the platform's own item host is allowed; anything else
+  reads as absent. Against a development backend that includes the development image host, so
+  there the fallback is what you see.
+- **Attach things by the rig's names**, not by your old model's: a held item goes on
+  `hand_socket`. Play the model's own clips when it has them; your game's animations may not fit
+  its rig.
+- **Keep loading off the critical path.** Start the boot with your default look and swap the
+  character in when the model arrives; a player on a slow connection should not wait for it.
+
+**Redraw from `onPlayer`, not from boot alone.** The Arcade sends the player again whenever what
+they wear changes — either tab — including mid-game from the Arcade's own menu, without your game
+asking. `onPlayer` runs and `gem.player` holds the new values; a field missing from the new player
+is missing now (a player who takes off their 3D character has no `avatar3dId`).
 
 **A "Change avatar" button belongs in your own UI**, and `gem.openAvatarPicker()` opens the
-Arcade's picker from it. The Arcade pauses your game while the picker is open, saves the player's
-choice, sends the player again, and resumes you:
+Arcade's picker from it. Pass `{ tab: '3d' }` or `{ tab: '2d' }` to open on a tab; omit it and
+the Arcade decides (a game tagged `arcade-avatars` gets the 3D tab). The Arcade pauses your game
+while the picker is open, saves the player's choice, sends the player again, and resumes you:
 
 ```js
-const gem = createGem({ onPlayer: (p) => hero.wear(avatarOfItem(p.avatarIconId)) });
-
 changeAvatar.hidden = !gem.avatarPickerAvailable; // read it live
 changeAvatar.onclick = () => {
-  if (!gem.openAvatarPicker()) changeAvatar.hidden = true;
+  if (!gem.openAvatarPicker({ tab: '3d' })) changeAvatar.hidden = true;
 };
 ```
 
 - **`gem.avatarPickerAvailable`** says whether the Arcade will open its picker here. It is `false`
   outside the Arcade, before the bridge is up, and under an embedder that has no picker.
 - **`gem.openAvatarPicker()`** returns `true` when the Arcade was asked and `false` when it was not
-  (the same cases, or more than six asks a minute). It never throws and never waits.
+  (the same cases, or more than six asks a minute). It never throws and never waits. An Arcade
+  older than the tabs ignores `tab` and opens its picker as before.
 - **Nothing answers it.** The outcome is the new player through `onPlayer`. A player who closes the
   picker unchanged produces nothing, so never wait for an answer or poll `gem.player`.
 
-**Your server is not told.** A server-authoritative game reads each member's `avatar_icon_id` from
-the room read (`GET /v1/games/{game_id}/game-rooms/{game_room_id}`, or `gem.room.get()` on a
-dedicated server), and nothing pushes a change to it. So when `onPlayer` brings a different
-`avatarIconId`, have your client tell your server, and have the server **re-read the room** —
-never trust the id the client sends.
+**Your server is not told.** A server-authoritative game reads each member's `avatar_3d_id`,
+`avatar_3d_model_url` and `avatar_icon_id` from the room read
+(`GET /v1/games/{game_id}/game-rooms/{game_room_id}`, or `gem.room.get()` on a dedicated server),
+and nothing pushes a change to it. So when `onPlayer` brings a different avatar, have your client
+tell your server, and have the server **re-read the room** — never trust an id the client sends.
 
 ## Which backend — no longer yours, and what the override is for
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "10.4.0",
+  "version": "11.0.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -557,7 +557,13 @@
         "from the parent's menu. A frame replaces its whole copy with each one; a",
         "field absent from the latest message is absent now. There is no other",
         "signal that the portrait changed, and no reply to the request that",
-        "opened the picker: this message is the outcome."
+        "opened the picker: this message is the outcome.",
+        "",
+        "The WORN 3D CHARACTER (`avatar3dId`, `avatar3dModelUrl`,",
+        "`avatar3dIconUrl`) is re-sent the same way: whenever it changes, from",
+        "either tab of the parent's picker, the whole message goes again. It is",
+        "a separate worn choice from the portrait — wearing one never changes",
+        "the other — so a message may carry either, both or neither."
       ],
       "fields": {
         "untrusted": {
@@ -620,6 +626,52 @@
             "the way it drops a non-digit `discriminator`."
           ]
         },
+        "avatar3dId": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": [
+            "The item-definition id of the 3D CHARACTER the player wears (gem-api",
+            "`avatar_3d_id`, a UUID; item type `avatar_3d`) — the same id a",
+            "game-room member's `avatar_3d_id` carries. A game that draws Arcade",
+            "avatars keys its character on this first, and falls back to its own",
+            "mapping of `avatarIconId` when it is absent.",
+            "",
+            "INDEPENDENT of `avatarIconId`: the portrait and the 3D character are",
+            "two worn choices, and wearing one never changes the other. Absent",
+            "means no 3D character is worn (the game's default look), or an older",
+            "parent; a parent never sends an empty string. Sent with",
+            "`avatar3dModelUrl` and `avatar3dIconUrl`, all three describing the",
+            "same item.",
+            "",
+            "Bounded here and shape-checked by the frame, exactly as `avatarIconId`",
+            "is and for the same reason: the frame keeps it only when it is a UUID."
+          ]
+        },
+        "avatar3dModelUrl": {
+          "kind": "string",
+          "maxLength": 2048,
+          "format": "url",
+          "optional": true,
+          "$comment": [
+            "The worn 3D character's MODEL (gem-api `avatar_3d_model_url`): a",
+            "binary glTF (`.glb`, `model/gltf-binary`) on the platform's item CDN,",
+            "one rig `root > body > (head, arm_l, arm_r > hand_socket, leg_l,",
+            "leg_r)`, possibly with animation clips. Immutable at its URL. Absent",
+            "when no 3D character is worn. Structurally validated only, like",
+            "`avatarIconUrl`, with the same pin caveat: THE CONSUMER MUST PIN THE",
+            "ORIGIN before fetching it — the SDK's `platformIconUrl` does, for",
+            "models as for pictures — or a hostile parent supplies a request-time",
+            "beacon carrying the Referer."
+          ]
+        },
+        "avatar3dIconUrl": {
+          "kind": "string",
+          "maxLength": 2048,
+          "format": "url",
+          "optional": true,
+          "$comment": "The worn 3D character's PORTRAIT RENDER (gem-api `avatar_3d_icon_url`) — a picture of the model, for a roster or a menu where loading the model is too much. NOT the 2D portrait (`avatarIconUrl`), which is a separate worn choice. Absent when no 3D character is worn. Same pin caveat as `avatarIconUrl`."
+        },
         "badges": {
           "kind": "array",
           "maxItems": 2,
@@ -2888,11 +2940,14 @@
         "ASKS, and the parent, which holds the account session, renders the",
         "picker in its own chrome and saves the choice.",
         "",
-        "NO FIELDS, AND NO REPLY. The game names nothing — not an item, not a",
-        "filter, not a line of text: which portraits are offered and what the",
+        "ONE OPTIONAL FIELD, AND NO REPLY. The game names nothing but which tab",
+        "it would like the picker to open on (`tab`, below) — not an item, not",
+        "a filter, not a line of text: which avatars are offered and what the",
         "picker says are the parent's. And nothing answers this message. THE",
-        "OUTCOME IS A NEW `gem.player`: when the worn portrait changes, the",
-        "parent re-sends it with the new `avatarIconId` and `avatarIconUrl`, as",
+        "OUTCOME IS A NEW `gem.player`: when the worn portrait or 3D character",
+        "changes, the parent re-sends it with the new `avatarIconId` and",
+        "`avatarIconUrl`, or `avatar3dId`, `avatar3dModelUrl` and",
+        "`avatar3dIconUrl`, as",
         "it does for a change the player makes from the parent's menu without",
         "the game asking. A reply would be a second copy of an identity fact",
         "(`gem.signInResult`'s argument), and the picker may stay open for as",
@@ -2922,7 +2977,25 @@
         "picker is the control, and the account-session save is the",
         "enforcement."
       ],
-      "fields": {},
+      "fields": {
+        "tab": {
+          "kind": "enum",
+          "values": ["2d", "3d"],
+          "optional": true,
+          "$comment": [
+            "Which tab the picker opens on: `2d` the portrait (`avatarIconId`),",
+            "`3d` the 3D character (`avatar3dId`). Absent",
+            "means the parent decides — for a game that draws Arcade avatars it",
+            "opens the 3D tab. A HINT, not a restriction: the player may switch",
+            "tabs, and a parent with one tab ignores it.",
+            "",
+            "ADDITIVE, so no `v` bump: an older parent validated this message",
+            "with no fields and ignores an unknown one (rule 4), so it opens its",
+            "picker as before. A CLOSED enum, so a third value is a breaking",
+            "change under the freeze — an older parent would refuse the whole ask."
+          ]
+        }
+      },
       "rateLimit": {
         "perMinute": 6,
         "$comment": "Bounds a BUGGY game. NOT a security control: a hostile game posts on the port it holds rather than calling the SDK. What stops a game nagging is the parent's one-at-a-time rule and its freedom to drop an ask."