@indiegems/gem-web-sdk 10.4.0 → 11.1.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "10.4.0"
+    "version": "11.1.0"
   },
   "entries": [
     {
@@ -6632,11 +6632,18 @@
           "name": "requestAvatarPicker",
           "anchor": "gemframe-requestavatarpicker",
           "group": "frame",
-          "signature": "requestAvatarPicker(): boolean",
+          "signature": "requestAvatarPicker(tab?: \"2d\" | \"3d\"): boolean",
           "documented": true,
-          "summary": "Ask the arcade to open its own avatar picker over your game. Nothing comes\nback: a changed portrait arrives as a new `gem.player`, through `onPlayer`.\n\nPrefer `gem.openAvatarPicker`, which documents what a game does with the\nchange.",
+          "summary": "Ask the arcade to open its own avatar picker over your game. Nothing comes\nback: a changed portrait or 3D character arrives as a new `gem.player`,\nthrough `onPlayer`.\n\nPrefer `gem.openAvatarPicker`, which documents what a game does with the\nchange.",
           "deprecated": null,
-          "params": [],
+          "params": [
+            {
+              "name": "tab",
+              "type": "\"2d\" | \"3d\"",
+              "optional": true,
+              "summary": "Which tab to open on — `'2d'` (the portrait) or `'3d'` (the 3D\n  character). Omit it to let the arcade decide. Anything else is treated as\n  omitted. An arcade older than the tabs ignores it."
+            }
+          ],
           "returns": "whether the message left the frame — `false` before the bridge is\n  up, for an arcade that has no avatar picker here, and past this frame's\n  own limit of six a minute.",
           "throws": null,
           "example": null,
@@ -6824,6 +6831,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Friend.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "friend-avatar3did",
+          "group": "friends",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Friend.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "friend-avatar3dmodelurl",
+          "group": "friends",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Friend.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "friend-avatar3diconurl",
+          "group": "friends",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Friend.badges",
           "name": "badges",
@@ -8594,6 +8649,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemPlayer.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "gemplayer-avatar3did",
+          "group": "player",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemPlayer.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "gemplayer-avatar3dmodelurl",
+          "group": "player",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemPlayer.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "gemplayer-avatar3diconurl",
+          "group": "player",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemPlayer.badges",
           "name": "badges",
@@ -9756,11 +9859,18 @@
           "name": "openAvatarPicker",
           "anchor": "gem-openavatarpicker",
           "group": "start",
-          "signature": "openAvatarPicker(): boolean",
+          "signature": "openAvatarPicker(options?: { tab?: \"2d\" | \"3d\" }): boolean",
           "documented": true,
-          "summary": "Open the arcade's avatar picker over your game, so the player can change\nthe Arcade avatar they wear without leaving it. For a game that draws\nArcade avatars — whole characters the player owns as Arcade items — put a\n\"Change avatar\" button in your own UI and call this from it:\n\n```js\nchangeAvatar.hidden = !gem.avatarPickerAvailable;\nchangeAvatar.onclick = () => {\n  if (!gem.openAvatarPicker()) changeAvatar.hidden = true;\n};\n```\n\n**The change arrives as a new player, not as an answer.** Nothing comes\nback from this call. When the player picks a different avatar, the arcade\npauses your game while the picker is open, then sends the player again —\nyour `onPlayer` callback runs and [Gem.player](api-reference-game.md#gem-player) holds the new\n[PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) — and resumes it. Redraw from\n`onPlayer`, which also runs when the player changes their avatar from the\narcade's own menu without your game asking. A player who closes the picker\nunchanged produces nothing at all.\n\n**Your server learns it only when it reads the room again.** A\nserver-authoritative game reads each member's `avatar_icon_id` from the\nroom read (`GET /v1/games/{game_id}/game-rooms/{game_room_id}`, or\n`gem.room.get()` on a dedicated server); nothing tells the server the\nplayer changed. So when `onPlayer` brings a different `avatarIconId`, have\nyour client tell your server, and have the server re-read the room — never\ntrust the id the client sends.",
+          "summary": "Open the arcade's avatar picker over your game, so the player can change\nthe Arcade avatar they wear without leaving it. For a game that draws\nArcade avatars — whole characters the player owns as Arcade items — put a\n\"Change avatar\" button in your own UI and call this from it:\n\n```js\nchangeAvatar.hidden = !gem.avatarPickerAvailable;\nchangeAvatar.onclick = () => {\n  if (!gem.openAvatarPicker()) changeAvatar.hidden = true;\n};\n```\n\n**Two tabs: 2D and 3D.** The picker has a 2D tab — the portrait, a\npicture ([PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid)) — and a 3D tab — a whole\ncharacter with its own model ([PlayerIdentity.avatar3dId](api-reference-game.md#playeridentity-avatar3did),\n[PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl)). They are separate choices: wearing\none never changes the other. Pass `{ tab: '3d' }` or `{ tab: '2d' }` to\nopen on one; omit it and the arcade decides (a game that draws Arcade\navatars gets the 3D tab). An arcade older than the tabs ignores it.\n\n**The change arrives as a new player, not as an answer.** Nothing comes\nback from this call. When the player picks a different avatar, the arcade\npauses your game while the picker is open, then sends the player again —\nyour `onPlayer` callback runs and [Gem.player](api-reference-game.md#gem-player) holds the new\n[PlayerIdentity.avatar3dId](api-reference-game.md#playeridentity-avatar3did) or [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) —\nand resumes it. Redraw from `onPlayer`, which also runs when the player\nchanges their avatar from the arcade's own menu without your game asking.\nA player who closes the picker unchanged produces nothing at all.\n\n**Your server learns it only when it reads the room again.** A\nserver-authoritative game reads each member's `avatar_3d_id` and\n`avatar_icon_id` from the room read\n(`GET /v1/games/{game_id}/game-rooms/{game_room_id}`, or `gem.room.get()`\non a dedicated server); nothing tells the server the player changed. So\nwhen `onPlayer` brings a different avatar, have your client tell your\nserver, and have the server re-read the room — never trust the id the\nclient sends.",
           "deprecated": null,
-          "params": [],
+          "params": [
+            {
+              "name": "options",
+              "type": "{ tab?: \"2d\" | \"3d\" }",
+              "optional": true,
+              "summary": "`tab` — `'2d'` or `'3d'`, the tab to open on. Omit it to let\n  the arcade decide; any other value is treated as omitted."
+            }
+          ],
           "returns": "`true` when the arcade was asked; `false` when it was not and\n  never will be for this call — outside the arcade, before the bridge is\n  up, under an embedder with no avatar picker, or past six asks a minute.\n  It never throws and never waits.",
           "throws": null,
           "example": null,
@@ -11419,6 +11529,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlayerIdentity.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "playeridentity-avatar3did",
+          "group": "player",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlayerIdentity.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "playeridentity-avatar3dmodelurl",
+          "group": "player",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlayerIdentity.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "playeridentity-avatar3diconurl",
+          "group": "player",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PlayerIdentity.badges",
           "name": "badges",
@@ -11442,7 +11600,7 @@
           "group": "player",
           "signature": "function mapIdentity(row: unknown): PlayerIdentity",
           "documented": true,
-          "summary": "Map one row's identity fields, as the platform's API sends them, to\n[PlayerIdentity](api-reference-game.md#playeridentity).\n\nEvery surface this SDK names maps its rows through this already. You need it\nonly for a row you fetched yourself through the raw client — an async\nopponent, for instance:\n\n```js\nimport { mapIdentity, text } from '@indiegems/gem-web-sdk/sdk';\n\nconst { opponents } = await gem.client.get('/v1/async-opponents?opponent_type=ghost-lap');\nfor (const row of opponents) {\n  const who = mapIdentity(row);\n  label(who.displayName ? text.toPlain(who.displayName) : 'Anonymous player');\n}\n```\n\nReads `player_id`, `display_name`, `discriminator`, `display_tag`,\n`avatar_icon_id`, `avatar_icon_url` and `badges`, and nothing else from the\nrow. Anything missing, empty or of the wrong type is absent in the result.",
+          "summary": "Map one row's identity fields, as the platform's API sends them, to\n[PlayerIdentity](api-reference-game.md#playeridentity).\n\nEvery surface this SDK names maps its rows through this already. You need it\nonly for a row you fetched yourself through the raw client — an async\nopponent, for instance:\n\n```js\nimport { mapIdentity, text } from '@indiegems/gem-web-sdk/sdk';\n\nconst { opponents } = await gem.client.get('/v1/async-opponents?opponent_type=ghost-lap');\nfor (const row of opponents) {\n  const who = mapIdentity(row);\n  label(who.displayName ? text.toPlain(who.displayName) : 'Anonymous player');\n}\n```\n\nReads `player_id`, `display_name`, `discriminator`, `display_tag`,\n`avatar_icon_id`, `avatar_icon_url`, `avatar_3d_id`, `avatar_3d_model_url`,\n`avatar_3d_icon_url` and `badges`, and nothing else from the row. Anything missing, empty or of the wrong type is absent in the result.",
           "deprecated": null,
           "params": [
             {
@@ -11465,7 +11623,7 @@
           "group": "player",
           "signature": "function platformIconUrl(url: string | undefined): string | undefined",
           "documented": true,
-          "summary": "The icon URL, if and only if the platform serves it — otherwise `undefined`.\n\nUse it on every [PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl) and\n[PlayerBadge.iconUrl](api-reference-game.md#playerbadge-iconurl) before it reaches an `<img src>`, a texture\nloader or a `fetch`:\n\n```js\nimport { platformIconUrl } from '@indiegems/gem-web-sdk/sdk';\n\nconst src = platformIconUrl(member.avatarIconUrl);\nif (src) img.src = src; else drawPlaceholder();\n```\n\n**Why it exists.** Loading an image is a request, and a request carries the\npage's `Referer` and the moment it happened. The URLs the SDK hands you are\nchecked for shape — `https`, no credentials — but a shape check cannot know\nwhich host is the platform's, so an icon URL from anywhere but the platform's\nown image host would be a beacon on your player. This compares the whole\norigin against the hosts the platform serves item icons from in production. A\nURL on `localhost` passes too, for a stack running on one machine.\n\nAn unrecognised host answers `undefined` — draw your placeholder, as for a\nplayer with no portrait. That includes a development backend's image host,\nso portraits appear only against production and loopback.",
+          "summary": "The icon URL, if and only if the platform serves it — otherwise `undefined`.\n\nUse it on every [PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl),\n[PlayerIdentity.avatar3dIconUrl](api-reference-game.md#playeridentity-avatar3diconurl), [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl)\nand [PlayerBadge.iconUrl](api-reference-game.md#playerbadge-iconurl) before it reaches an `<img src>`, a texture\nloader, a `GLTFLoader` or a `fetch`:\n\n```js\nimport { platformIconUrl } from '@indiegems/gem-web-sdk/sdk';\n\nconst src = platformIconUrl(member.avatarIconUrl);\nif (src) img.src = src; else drawPlaceholder();\n```\n\n**Why it exists.** Loading an image is a request, and a request carries the\npage's `Referer` and the moment it happened. The URLs the SDK hands you are\nchecked for shape — `https`, no credentials — but a shape check cannot know\nwhich host is the platform's, so an icon URL from anywhere but the platform's\nown image host would be a beacon on your player. This compares the whole\norigin against the hosts the platform serves item icons from in production. A\nURL on `localhost` passes too, for a stack running on one machine.\n\nAn unrecognised host answers `undefined` — draw your placeholder, as for a\nplayer with no portrait. That includes a development backend's image host,\nso portraits appear only against production and loopback.",
           "deprecated": null,
           "params": [
             {
@@ -14207,6 +14365,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "LeaderboardEntry.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "leaderboardentry-avatar3did",
+          "group": "leaderboards",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "LeaderboardEntry.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "leaderboardentry-avatar3dmodelurl",
+          "group": "leaderboards",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "LeaderboardEntry.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "leaderboardentry-avatar3diconurl",
+          "group": "leaderboards",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "LeaderboardEntry.badges",
           "name": "badges",
@@ -15970,6 +16176,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlayerProfile.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "playerprofile-avatar3did",
+          "group": "profiles",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlayerProfile.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "playerprofile-avatar3dmodelurl",
+          "group": "profiles",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlayerProfile.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "playerprofile-avatar3diconurl",
+          "group": "profiles",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PlayerProfile.badges",
           "name": "badges",
@@ -16387,6 +16641,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "QuickJoinOptions.templateSlugs",
+          "name": "templateSlugs",
+          "anchor": "quickjoinoptions-templateslugs",
+          "group": "rooms",
+          "signature": "readonly templateSlugs?: readonly string[]",
+          "documented": true,
+          "summary": "Several templates this player accepts, by slug — one to eight of them, for\na game that offers \"any of these modes\". Pass it INSTEAD of\n[QuickJoinOptions.templateSlug](api-reference-game.md#quickjoinoptions-templateslug), never beside it.\n\nOpen rooms of every listed template are candidates together, and the\nfullest one is joined. **The order matters only when there is none:** the\nroom that gets created is made from the first slug listed. Read\n`room.templateSlug` to learn which mode the player landed in.\n\nEvery listed template must be one players can quick-join; one that is not\nrefuses the whole call rather than being skipped.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": "```ts\nconst room = await gem.rooms.quickJoin({ templateSlugs: ['duel', 'brawl'] });\nstartMode(room.templateSlug);\n```",
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "QuickJoinOptions.templateId",
           "name": "templateId",
@@ -17270,7 +17540,7 @@
             }
           ],
           "returns": "The ticket, still `queued` unless a lobby was waiting for exactly\nthis player.",
-          "throws": "`GemApiError` when the platform refuses the ticket. Two refusals\nare worth their own branch, by [GemApiError.code](api-reference-game.md#gemapierror-code):\n`already_queued` — this player, or someone in their party, is already\non a ticket, possibly in another tab or another game — and\n`matchmaking_unavailable`, which means matchmaking is turned off or not\nanswering. Tell the player; do not loop on it, and do not quietly\nsubstitute `quickJoin`, which puts them in a different kind of room.",
+          "throws": "`GemApiError` when the platform refuses the ticket. Two refusals\nare worth their own branch, by [GemApiError.code](api-reference-game.md#gemapierror-code):\n`already_queued` — this player, or someone in their party, is already\non a ticket, possibly in another tab or another game — and\n`matchmaking_unavailable`, which means matchmaking is turned off or not\nanswering. Tell the player; do not loop on it, and do not quietly\nsubstitute `quickJoin`, which puts them in a different kind of room.\n\nA party leader can meet three more, when the party could not be seated\ntogether: `version_data_required` — the party did not launch this game\ntogether; `party_versions_incomplete` — a member's game has not finished\nstarting, so wait a moment and queue again; and `party_version_mismatch`\n— a member is on a build that cannot play with the leader's, so everyone\nreloads the game. No ticket was made in any of the three.",
           "example": null,
           "defaultValue": null,
           "guides": []
@@ -18786,6 +19056,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "RoomMember.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "roommember-avatar3did",
+          "group": "rooms",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RoomMember.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "roommember-avatar3dmodelurl",
+          "group": "rooms",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RoomMember.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "roommember-avatar3diconurl",
+          "group": "rooms",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "RoomMember.badges",
           "name": "badges",
@@ -19244,6 +19562,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Room.templateSlug",
+          "name": "templateSlug",
+          "anchor": "room-templateslug",
+          "group": "rooms",
+          "signature": "readonly templateSlug?: string",
+          "documented": true,
+          "summary": "The slug of the template this room was made from — the same slug you pass\nas `templateSlug`. After a `quickJoin` naming several templates, this is\nhow a game learns which mode the player landed in.\n\nAbsent for a room made without a template.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Room.roomType",
           "name": "roomType",
@@ -19868,6 +20202,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "ShowcaseFriendEntry.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "showcasefriendentry-avatar3did",
+          "group": "showcase",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ShowcaseFriendEntry.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "showcasefriendentry-avatar3dmodelurl",
+          "group": "showcase",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ShowcaseFriendEntry.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "showcasefriendentry-avatar3diconurl",
+          "group": "showcase",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "ShowcaseFriendEntry.badges",
           "name": "badges",

package/docs/changelog.md

@@ -16,6 +16,32 @@ 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.
 
+## 11.1.0
+
+Upgrading from 11.0.0. Impact: none.
+
+### New capability
+
+- Quick join options now accept templateSlugs, a list of one to eight templates. Open rooms of every listed template are candidates together, and if a room has to be created it is made from the first template in the list. Do not pass the list together with a single template, and do not pass an empty list or more than eight, because those calls are refused locally. When a local tool hosts your game's server, only the first template is sent and the room is always created from it. Games that pass a single template keep working unchanged.
+- A room now reports which template it was made from through Room.templateSlug. Use it to tell which mode a player landed in, especially when you offer several templates at once.
+
+## 11.0.0
+
+Upgrading from 10.4.0. Impact: required.
+
+### Rebuild
+
+- The calls that ask the Arcade to open the avatar picker now accept an optional tab, either 2d or 3d. Existing calls without arguments still compile and behave as before. Recompile; pass a tab only if you want the picker to open on a specific one.
+- The host callback for avatar picker requests now receives a request object that may carry the requested tab. Handlers that take no arguments still compile. Recompile, and if you host games, read the tab to open the picker on the right one.
+
+### New capability
+
+- The current player now carries optional 3D avatar fields: an identifier, a model URL and an icon URL. They describe the 3D character the player wears in the Arcade, which is chosen independently of the 2D portrait. The fields may be absent, so keep a fallback to the portrait. They are sent again whenever the worn 3D character changes, so a game that shows the player's avatar should update when they change.
+- Room members, leaderboard rows, friends and showcase friend rows now carry the same optional 3D avatar identifier, model URL and icon URL. A game can show other players' 3D characters wherever it already shows their portraits. Treat the fields as optional and fall back to the portrait when they are missing.
+- Code that embeds a game and sends player details to it can now pass the 3D avatar identifier, model URL and icon URL along with the other player fields. Send them whenever the player's worn 3D character changes.
+- The raw server and API identity types now include optional 3D avatar identifier, model URL and icon URL properties for players and subjects. Code that reads these types directly can use them. They may not be populated by the service yet, so handle their absence.
+- The Arcade avatar picker now has a 2D tab and a 3D tab. A game asking the Arcade to open the picker can say which tab to show, and a host receiving that request can read the requested tab. Omitting the tab keeps the previous behaviour. An unknown tab value is dropped rather than failing the request.
+
 ## 10.4.0
 
 Upgrading from 10.3.1. Impact: required.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "10.4.0"
+  "@indiegems/gem-web-sdk": "11.1.0"
 }
 ```
 

package/docs/manifest.json

@@ -33,8 +33,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "fd69a4c08141e0646d695adedce0d313de2295cfd6bc656433ce33dd02ec731a",
-      "updated": "2026-10-11T19:38:28Z"
+      "sha256": "0b0740920776dd0eae95fec66d21fcdb3370eaec1ddedfc960abc87e88aa4fb5",
+      "updated": "2026-10-12T00:35:07Z"
     },
     {
       "file": "cross-promotion.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "f2c13478823888b777058bbdc4de41216dd8b48d7e7efab3a31334f980d647ec",
-      "updated": "2026-10-11T19:38:28Z"
+      "sha256": "550015876f24c9e928e40ddc4faf0531ccb9a58697b0012156d86509f67e55b4",
+      "updated": "2026-10-12T00:35:07Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -113,8 +113,8 @@
     },
     {
       "file": "rooms-and-matches.md",
-      "sha256": "be22367f8dc9147e815a14ddb417788fa6614720a0df4f9f01624bf4667877d3",
-      "updated": "2026-10-11T10:17:11Z"
+      "sha256": "e5cd7655713aba7d3b978cfa579bbbb14cb85f271668002e1c41975f5967a2c8",
+      "updated": "2026-10-12T00:19:34Z"
     },
     {
       "file": "saving-player-progress.md",
@@ -123,8 +123,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "04bb5fb5f631a52c7962728a74602ce7eec6ee6a1a3efa6197542ce5aa4cce95",
-      "updated": "2026-10-11T19:38:28Z"
+      "sha256": "cfa1bcfcd8f46c4208a009d36adadffc3dbb23162df01f83e11e4d504fa8afc1",
+      "updated": "2026-10-12T00:35:07Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -148,8 +148,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "ce2abba4b32ee1c0dd69eabaaac1f33e2534ac5b58e9a45c4f8a7b3bd3e11f27",
-      "updated": "2026-10-11T19:25:48Z"
+      "sha256": "ab4f18f2c1cfccf54b01027dea77d229f0a9f086e373d6cfd4c741fd0004557f",
+      "updated": "2026-10-11T19:48:44Z"
     }
   ]
 }