@indiegems/gem-web-sdk 10.4.0 → 11.1.0

package/docs/rooms-and-matches.md

@@ -872,11 +872,54 @@ seat stands, so `myRooms()` shows the room and `join(id)` enters it.
 | `matchmaking_not_enabled` (400) | A named template has no enabled `matchmaking` block. A config fault, not a player one. |
 | `matchmaking_unavailable` (503) | Matchmaking is turned off for the whole platform, or its store is not answering. |
 
+**A party leader can meet three more.** The platform checks that a party can be seated together
+before it queues it, so a party that could not play is told at once rather than matched and then
+dropped. Only the leader queues, so only the leader's game sees these. No ticket was made, and the
+button can be pressed again.
+
+| Code | Meaning | What to show the leader |
+| --- | --- | --- |
+| `version_data_required` (400) | The party has not launched this game together, so the platform has no record of what each member is running. | "Start the game with your party from the Arcade to queue together." Pressing again will not help until they do. |
+| `party_versions_incomplete` (409) | A member's game has not finished starting, so their version has not arrived yet. | "Waiting for your party to finish loading." This one clears by itself: queue again after a few seconds, on the player's press or on a short timer. |
+| `party_version_mismatch` (409) | A member is running a build that cannot play with the leader's. | "Someone in your party is on a different version. Everyone reload the game." |
+
+A party's `quickJoin()` and `create()` are refused the same way, with the same codes.
+
 ⚠️ **Nothing falls back to quick-join, and a game should not either.** Not on
 `matchmaking_unavailable`, not on `expired`. Quick-join puts the player in a different kind of room —
 alone, in a mode that was queued for precisely because it needs a lobby. Tell the player matchmaking is
 unavailable and leave the button where it is.
 
+## 5d. Quick-joining any of several modes
+
+A drop-in game with more than one mode can ask for whichever has players, in one call:
+
+```js
+const room = await gem.rooms.quickJoin({ templateSlugs: ['duel', 'brawl'] });
+startMode(room.templateSlug); // which one the player landed in
+```
+
+- **Open rooms of every listed template are candidates together**, ranked as a single-template
+  quick-join ranks them: the fullest first, then the closest cluster.
+- **The order matters only when no room is open.** The room that gets created is made from the
+  **first** slug listed, so put the mode an empty lobby should start in first.
+- **One to eight slugs, in place of `templateSlug`, never beside it.** A list together with
+  `templateSlug` or `templateId`, an empty list, or more than eight is refused locally, before
+  the platform is asked.
+- **Every listed template must be one players can quick-join.** One that is not refuses the whole
+  call; it is not skipped.
+- **`room.templateSlug` says which template the room is from.** It is on every room, however it was
+  entered.
+
+A call that passes `templateSlug` behaves exactly as it always has.
+
+Under a developer's tool that runs the game's server on the developer's own machine, only the first
+slug is sent. Such a room is always created rather than joined, so it would be made from the first
+template either way.
+
+This is still quick-join: the player is in a room at once, possibly alone. For "any of these modes,
+but never start short", name the same slugs on `queueForMatch()` instead.
+
 ## 6. Scope
 
 **In:** rooms, membership, host, ready state, the match lifecycle, and the dedicated-server connect

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

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.1.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."