@indiegems/gem-web-sdk 10.1.0 → 10.2.0

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

@@ -1310,6 +1310,44 @@ your own page. It carries a day count and never a date, and nothing about what t
 This is a platform rule, not advice — see
 [platform rules §8](platform-rules.md#8-a-players-boost-is-for-display-never-a-gate).
 
+### 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.
+
+**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.
+
+**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:
+
+```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;
+};
+```
+
+- **`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.
+- **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.
+
 ## Which backend — no longer yours, and what the override is for
 
 The Arcade names the API root on every `gem.token`, and the SDK sends there. Your game never types

package/package.json

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

package/schema/bridge.v1.json

@@ -547,7 +547,17 @@
         "",
         "ADDITIVE, so no `v` bump: every new field is optional (an older parent",
         "sends none of them and must still be accepted), and an older frame",
-        "ignores fields it does not know (rule 4)."
+        "ignores fields it does not know (rule 4).",
+        "",
+        "RE-SENT WHENEVER IT CHANGES, and always the whole message. The parent",
+        "sends it after the handshake, again whenever the identity changes (a",
+        "sign-in in place), and again whenever the WORN PORTRAIT changes — the",
+        "player picked another one in the parent's own avatar picker, whether a",
+        "game opened it (`gem.requestAvatarPicker`) or the player did, mid-game,",
+        "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."
       ],
       "fields": {
         "untrusted": {
@@ -586,6 +596,30 @@
           "optional": true,
           "$comment": "The portrait's THUMBNAIL (gem-api `avatar_icon_url`). Absent means no portrait; a parent never sends an empty string. Structurally validated only — https (or loopback), no userinfo, parsed rather than regex-matched. It is NOT origin-pinned: the validator is a pure function with no configuration, so it cannot know the CDN origin. An earlier version of this comment claimed a pin that the generated code did not emit — a documented control that did not exist. THE CONSUMER MUST PIN THE ORIGIN before putting this in an <img src> — the SDK's `platformIconUrl` does — or a hostile parent supplies a request-time beacon carrying the Referer."
         },
+        "avatarIconId": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": [
+            "The item-definition id of the portrait the player WEARS (gem-api",
+            "`avatar_icon_id`, a UUID) — the same id a game-room member's",
+            "`avatar_icon_id` carries, so a game that draws whole characters as",
+            "Arcade avatars (store tag `arcade-avatars`) can map it to its own",
+            "model rather than to the thumbnail.",
+            "",
+            "Platform-assigned, so it sits on the trusted side of the `untrusted`",
+            "split, beside `playerId` and the badges' `itemId`. Absent means no",
+            "portrait is worn, or an older parent; a parent never sends an empty",
+            "string. Sent with `avatarIconUrl` and describing the same item.",
+            "",
+            "BOUNDED HERE, SHAPE-CHECKED BY THE FRAME. The schema has no pattern",
+            "kind, and a format here would cost a frame the WHOLE message for one",
+            "bad id — its name and portrait with it. So the validator bounds the",
+            "length only, and the frame keeps the value only when it is a UUID",
+            "(`8-4-4-4-12` hex, either case), dropping anything else to absent,",
+            "the way it drops a non-digit `discriminator`."
+          ]
+        },
         "badges": {
           "kind": "array",
           "maxItems": 2,
@@ -2673,6 +2707,64 @@
       }
     },
 
+    {
+      "type": "gem.requestAvatarPicker",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask the arcade to open its own avatar picker over the game, so the",
+        "player can change the portrait they wear without leaving it — the",
+        "\"Change avatar\" button of a game that draws Arcade avatars. Gated by",
+        "the `avatarPicker` capability: sent only to a parent that advertised",
+        "it.",
+        "",
+        "WHY THE PARENT OPENS IT. Wearing a portrait is an account act: the",
+        "account surface refuses the game-scoped token by construction, and the",
+        "list of portraits a player owns is theirs, not the game's. So the game",
+        "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",
+        "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",
+        "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",
+        "long as the player browses, which no wait should be sized for. A",
+        "player who closes it unchanged produces nothing at all.",
+        "",
+        "WHAT THE PARENT OWES, none of which this schema can enforce:",
+        "",
+        "  ADVERTISE IT ONLY WHERE IT OPENS. `avatarPicker` is the game's cue to",
+        "  show its own Change avatar button, so a parent with no picker on this",
+        "  surface does not advertise it. A player who cannot wear a portrait",
+        "  yet (no account) is the parent's to explain in its own chrome.",
+        "",
+        "  PAUSE THE GAME while the picker is open (`gem.pause`) and lift it when",
+        "  the picker closes, returning focus to the frame. When the portrait",
+        "  changed, send `gem.player` BEFORE lifting the pause, so the game",
+        "  redraws before it runs again.",
+        "",
+        "  ONE AT A TIME. An ask arriving while the picker, or any other sheet",
+        "  that holds the stage, is open is dropped. A parent may also drop an",
+        "  ask that arrives without transient user activation in the frame, or",
+        "  too soon after the player closed the last one.",
+        "",
+        "  SEND NOTHING BACK for a refusal — no error, no acknowledgement.",
+        "",
+        "NOT AN AUTHORIZATION CONTROL. The player's own choice in the parent's",
+        "picker is the control, and the account-session save is the",
+        "enforcement."
+      ],
+      "fields": {},
+      "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."
+      }
+    },
+
     {
       "type": "gem.vibrate",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -197,6 +197,12 @@
         "gem.requestShare"
       ]
     },
+    "avatarPicker": {
+      "implemented": true,
+      "gates": [
+        "gem.requestAvatarPicker"
+      ]
+    },
     "vibration": {
       "implemented": true,
       "gates": [