@indiegems/gem-web-sdk 12.0.0 → 13.0.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "12.0.0"
+    "version": "13.0.0"
   },
   "entries": [
     {
@@ -45,6 +45,10 @@
           "key": "purchases",
           "title": "Selling for platform currency"
         },
+        {
+          "key": "avatars3d",
+          "title": "Arcade 3D avatars"
+        },
         {
           "key": "deviceSettings",
           "title": "Settings kept on this device"
@@ -4484,6 +4488,315 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Avatar3dPrice",
+          "name": "Avatar3dPrice",
+          "anchor": "avatar3dprice",
+          "group": "avatars3d",
+          "signature": "interface Avatar3dPrice",
+          "documented": true,
+          "summary": "One price of a 3D avatar on sale, in one platform currency.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatar3dPrice.currencySlug",
+          "name": "currencySlug",
+          "anchor": "avatar3dprice-currencyslug",
+          "group": "avatars3d",
+          "signature": "readonly currencySlug: string",
+          "documented": true,
+          "summary": "`GEMS` or `ARCADE_TICKETS` — what to pass as `currencySlug`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatar3dPrice.price",
+          "name": "price",
+          "anchor": "avatar3dprice-price",
+          "group": "avatars3d",
+          "signature": "readonly price: number",
+          "documented": true,
+          "summary": "The price, a whole number of that currency.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatar3dOffer",
+          "name": "Avatar3dOffer",
+          "anchor": "avatar3doffer",
+          "group": "avatars3d",
+          "signature": "interface Avatar3dOffer",
+          "documented": true,
+          "summary": "One of your game's 3D avatars on sale, as the platform prices it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatar3dOffer.itemId",
+          "name": "itemId",
+          "anchor": "avatar3doffer-itemid",
+          "group": "avatars3d",
+          "signature": "readonly itemId: string",
+          "documented": true,
+          "summary": "The avatar's item id — what [Avatars3dApi.purchase](api-reference-game.md#avatars3dapi-purchase) takes.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatar3dOffer.slug",
+          "name": "slug",
+          "anchor": "avatar3doffer-slug",
+          "group": "avatars3d",
+          "signature": "readonly slug: string",
+          "documented": true,
+          "summary": "The slug you uploaded it under. A key, not display text.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatar3dOffer.family",
+          "name": "family",
+          "anchor": "avatar3doffer-family",
+          "group": "avatars3d",
+          "signature": "readonly family: Avatar3dFamily",
+          "documented": true,
+          "summary": "The rig family the model is built on.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatar3dOffer.displayName",
+          "name": "displayName",
+          "anchor": "avatar3doffer-displayname",
+          "group": "avatars3d",
+          "signature": "readonly displayName: string",
+          "documented": true,
+          "summary": "The avatar's name, as you uploaded it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatar3dOffer.description",
+          "name": "description",
+          "anchor": "avatar3doffer-description",
+          "group": "avatars3d",
+          "signature": "readonly description?: string",
+          "documented": true,
+          "summary": "The avatar's description, when it has one.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatar3dOffer.iconUrl",
+          "name": "iconUrl",
+          "anchor": "avatar3doffer-iconurl",
+          "group": "avatars3d",
+          "signature": "readonly iconUrl: string",
+          "documented": true,
+          "summary": "A rendered portrait of the avatar, for a shop tile. Pass it through\n`platformIconUrl` before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatar3dOffer.modelUrl",
+          "name": "modelUrl",
+          "anchor": "avatar3doffer-modelurl",
+          "group": "avatars3d",
+          "signature": "readonly modelUrl: string",
+          "documented": true,
+          "summary": "The avatar's model, for a preview. Pass it through `platformIconUrl`\nbefore loading it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatar3dOffer.prices",
+          "name": "prices",
+          "anchor": "avatar3doffer-prices",
+          "group": "avatars3d",
+          "signature": "readonly prices: readonly Avatar3dPrice[]",
+          "documented": true,
+          "summary": "One or two prices, each in a currency a player can pay with. Show each\none the player can choose; pass the chosen one's `currencySlug` to\n[Avatars3dApi.purchase](api-reference-game.md#avatars3dapi-purchase).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatars3dApi",
+          "name": "Avatars3dApi",
+          "anchor": "avatars3dapi",
+          "group": "avatars3d",
+          "signature": "interface Avatars3dApi",
+          "documented": true,
+          "summary": "Arcade 3D avatars — `gem.avatars3d`. What the player wears, the rig families\nyour game accepts, the avatars you sell, and buying one.\n\n```js\nfunction draw() {\n  const worn = gem.avatars3d.worn();\n  if (worn) loadCharacter(platformIconUrl(worn.modelUrl));\n  else useDefaultCharacter();\n}\ndraw();\ngem.avatars3d.onChange(draw);\n```\n\nThe guide is `docs/arcade-avatars.md`: the rig, the config, uploading and\nselling with gemctl, and loading the model at runtime.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatars3dApi.families",
+          "name": "families",
+          "anchor": "avatars3dapi-families",
+          "group": "avatars3d",
+          "signature": "families(): Promise<readonly Avatar3dFamily[]>",
+          "documented": true,
+          "summary": "The rig families your game accepts, in the order your published config\ndeclares them (`avatars_3d.families`) — the first is your default.\n\nResolves `[]` when your game has no published config on this channel, or\nits config declares no families. Loads the config through\n`gem.gameConfig.load()` and shares that one fetch; rejects when the config\ncannot be loaded, as `load()` does.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatars3dApi.worn",
+          "name": "worn",
+          "anchor": "avatars3dapi-worn",
+          "group": "avatars3d",
+          "signature": "worn(family?: Avatar3dFamily): WornAvatar3d | undefined",
+          "documented": true,
+          "summary": "The 3D avatar the player wears — in `family` when you name one, otherwise\nin your game's first declared family that has one. `undefined` when none\nis worn there, before the player arrives, and outside the Arcade: draw\nyour default look.\n\nRead live from [Gem.player](api-reference-game.md#gem-player), so it changes when the player wears\nanother avatar or buys one; [Avatars3dApi.onChange](api-reference-game.md#avatars3dapi-onchange) tells you when.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "family",
+              "type": "Avatar3dFamily",
+              "optional": true,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatars3dApi.offers",
+          "name": "offers",
+          "anchor": "avatars3dapi-offers",
+          "group": "avatars3d",
+          "signature": "offers(): Promise<readonly Avatar3dOffer[]>",
+          "documented": true,
+          "summary": "Your game's 3D avatars on sale on this channel, with their prices, read\nfrom the platform with your game's own token. Render your shop from this,\nnever from prices of your own.\n\nResolves `[]` when you have nothing on sale. Rejects with a `GemApiError`\nwhen the platform cannot be read — a shop that cannot load says so.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatars3dApi.purchase",
+          "name": "purchase",
+          "anchor": "avatars3dapi-purchase",
+          "group": "avatars3d",
+          "signature": "purchase(request: Avatar3dPurchaseRequest): Promise<PurchaseOutcome>",
+          "documented": true,
+          "summary": "Buy one of your 3D avatars for the player and put it on. The Arcade\nprices it again, shows its own confirmation sheet, takes the currency and\nwears the avatar; your game then receives the player again, with the new\navatar worn, and [Avatars3dApi.onChange](api-reference-game.md#avatars3dapi-onchange) runs.\n\nCall it from the player's own click or key press — the Arcade shows no\nsheet without one and answers `declined` / `busy`.\n\nNOTHING REJECTS. Every outcome resolves, exactly as on\n`gem.purchases.request`:\n\n- `ok` — bought and worn, and the platform confirmed the player owns it.\n- `declined` — definitely not bought. `reason` says why:\n  `already_owned` (the player has it — offer to wear it with\n  `gem.openAvatarPicker({ tab: '3d' })`), `cancelled`, `insufficient_funds`,\n  `no_price_in_currency`, `not_purchasable` (not on sale, or not an id from\n  [Avatars3dApi.offers](api-reference-game.md#avatars3dapi-offers)), `busy`, and the rest of\n  `PurchaseRefusalCode`. Return to your shop silently.\n- `unavailable` — no reliable answer. Show one neutral message, never\n  retry on your own, and read [Avatars3dApi.worn](api-reference-game.md#avatars3dapi-worn) again.\n\n**Outside the Arcade** — opened at the top level of a page with no Arcade\naround it, or under an Arcade that does not sell 3D avatars yet — it\nresolves `unavailable` with reason `error` at once and asks nobody.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "request",
+              "type": "Avatar3dPurchaseRequest",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatars3dApi.onChange",
+          "name": "onChange",
+          "anchor": "avatars3dapi-onchange",
+          "group": "avatars3d",
+          "signature": "onChange(listener: (worn: readonly WornAvatar3d[]) => void): () => void",
+          "documented": true,
+          "summary": "Call `listener` whenever the avatars the player wears change — they wore\nanother one in the Arcade's picker, bought one, or their avatars arrived\nfor the first time — with every worn avatar, one per family. Not called\nfor the avatars already worn when you subscribe: read\n[Avatars3dApi.worn](api-reference-game.md#avatars3dapi-worn) for those.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "listener",
+              "type": "(worn: readonly WornAvatar3d[]) => void",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "a function that stops the calls. Calling it twice is harmless.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemApiError",
           "name": "GemApiError",
@@ -5783,7 +6096,7 @@
           "group": "controls",
           "signature": "interface ControlsApi",
           "documented": true,
-          "summary": "`gem.controls` — the player's camera and controls settings: tell the Arcade\nwhich ones your game leaves to the player, and turn look input into a camera\nturn at the player's sensitivity.",
+          "summary": "`gem.controls` — the player's camera and controls settings: turn look input\ninto a camera turn at the player's sensitivity.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -5797,29 +6110,6 @@
             }
           ]
         },
-        {
-          "id": "ControlsApi.declare",
-          "name": "declare",
-          "anchor": "controlsapi-declare",
-          "group": "controls",
-          "signature": "declare(uses: GemControlsDeclaration): boolean",
-          "documented": true,
-          "summary": "Tell the Arcade which of the player's camera and controls settings your\ngame uses, and for each one who decides it: `'player'` — you apply the\nArcade's value from `gem.prefs.recommended` (or the player's own choice\nin your settings, which wins) — or `'game'` — you decide it yourself, and\nthe Arcade's Settings shows that row as \"Set by this game\". Leave out a\nsetting your game does not use.\n\n```js\ngem.controls.declare({\n  lookSensitivity: 'player',\n  gamepadLookSensitivity: 'player',\n  invertLookY: 'player',\n  touchMovement: 'game', // this game always uses a fixed stick\n});\n```\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. The SDK holds it and sends it again after every\nreconnect, so call it once at boot, and again only when the answer\nchanges. Any other key or value is dropped.",
-          "deprecated": null,
-          "params": [
-            {
-              "name": "uses",
-              "type": "GemControlsDeclaration",
-              "optional": false,
-              "summary": null
-            }
-          ],
-          "returns": "`true` when the Arcade was told now; `false` before the bridge is\n  up (the declaration is held and sent when it connects), outside the\n  Arcade, and under an embedder that does not show these settings. Never\n  throws.",
-          "throws": null,
-          "example": null,
-          "defaultValue": null,
-          "guides": []
-        },
         {
           "id": "ControlsApi.look",
           "name": "look",
@@ -5859,102 +6149,6 @@
           "defaultValue": null,
           "guides": []
         },
-        {
-          "id": "GemControlChoice",
-          "name": "GemControlChoice",
-          "anchor": "gemcontrolchoice",
-          "group": "controls",
-          "signature": "type GemControlChoice = \"player\" | \"game\"",
-          "documented": true,
-          "summary": "Who decides one camera or controls setting: `'player'` — your game applies\nthe Arcade's value, or the player's own in-game choice, which wins — or\n`'game'` — your game decides it itself, and the Arcade's Settings shows the\nrow as \"Set by this game\".",
-          "deprecated": null,
-          "params": [],
-          "returns": null,
-          "throws": null,
-          "example": null,
-          "defaultValue": null,
-          "guides": []
-        },
-        {
-          "id": "GemControlsDeclaration",
-          "name": "GemControlsDeclaration",
-          "anchor": "gemcontrolsdeclaration",
-          "group": "controls",
-          "signature": "interface GemControlsDeclaration",
-          "documented": true,
-          "summary": "What `gem.controls.declare` takes: for each of the player's camera and\ncontrols settings your game uses, who decides it. Leave a setting out when\nyour game does not use it at all — the Arcade then says \"This game doesn't\nuse this\" beside that row.",
-          "deprecated": null,
-          "params": [],
-          "returns": null,
-          "throws": null,
-          "example": null,
-          "defaultValue": null,
-          "guides": []
-        },
-        {
-          "id": "GemControlsDeclaration.lookSensitivity",
-          "name": "lookSensitivity",
-          "anchor": "gemcontrolsdeclaration-looksensitivity",
-          "group": "controls",
-          "signature": "readonly lookSensitivity?: GemControlChoice",
-          "documented": true,
-          "summary": "Look speed for touch, mouse and pen — `gem.prefs.recommended.lookSensitivity`.",
-          "deprecated": null,
-          "params": [],
-          "returns": null,
-          "throws": null,
-          "example": null,
-          "defaultValue": null,
-          "guides": []
-        },
-        {
-          "id": "GemControlsDeclaration.gamepadLookSensitivity",
-          "name": "gamepadLookSensitivity",
-          "anchor": "gemcontrolsdeclaration-gamepadlooksensitivity",
-          "group": "controls",
-          "signature": "readonly gamepadLookSensitivity?: GemControlChoice",
-          "documented": true,
-          "summary": "Look speed for a gamepad stick — `gem.prefs.recommended.gamepadLookSensitivity`.",
-          "deprecated": null,
-          "params": [],
-          "returns": null,
-          "throws": null,
-          "example": null,
-          "defaultValue": null,
-          "guides": []
-        },
-        {
-          "id": "GemControlsDeclaration.invertLookY",
-          "name": "invertLookY",
-          "anchor": "gemcontrolsdeclaration-invertlooky",
-          "group": "controls",
-          "signature": "readonly invertLookY?: GemControlChoice",
-          "documented": true,
-          "summary": "Inverted up/down look — `gem.prefs.recommended.invertLookY`.",
-          "deprecated": null,
-          "params": [],
-          "returns": null,
-          "throws": null,
-          "example": null,
-          "defaultValue": null,
-          "guides": []
-        },
-        {
-          "id": "GemControlsDeclaration.touchMovement",
-          "name": "touchMovement",
-          "anchor": "gemcontrolsdeclaration-touchmovement",
-          "group": "controls",
-          "signature": "readonly touchMovement?: GemControlChoice",
-          "documented": true,
-          "summary": "The touch movement thumbstick, floating or fixed — `gem.prefs.recommended.touchMovement`.",
-          "deprecated": null,
-          "params": [],
-          "returns": null,
-          "throws": null,
-          "example": null,
-          "defaultValue": null,
-          "guides": []
-        },
         {
           "id": "DEVICE_SETTINGS_MAX_BYTES",
           "name": "DEVICE_SETTINGS_MAX_BYTES",
@@ -6552,45 +6746,16 @@
           "defaultValue": null,
           "guides": []
         },
-        {
-          "id": "GemFrame.declareControls",
-          "name": "declareControls",
-          "anchor": "gemframe-declarecontrols",
-          "group": "frame",
-          "signature": "declareControls(uses: GemControlsDeclaration): boolean",
-          "documented": true,
-          "summary": "Tell the arcade which of the player's camera and controls settings your\ngame leaves to the player and which it decides itself — the whole answer\neach time, the latest one winning.\n\nPrefer `gem.controls.declare`, which holds the declaration across a\nreconnect. This one sends only while connected, and only to an arcade\nthat shows these settings.",
-          "deprecated": null,
-          "params": [
-            {
-              "name": "uses",
-              "type": "GemControlsDeclaration",
-              "optional": false,
-              "summary": null
-            }
-          ],
-          "returns": "whether the message left the frame — `false` before the bridge is\n  up, for an arcade that does not show these settings, and past this\n  frame's own limit.",
-          "throws": null,
-          "example": null,
-          "defaultValue": null,
-          "guides": []
-        },
         {
           "id": "GemFrame.setMenu",
           "name": "setMenu",
           "anchor": "gemframe-setmenu",
           "group": "frame",
-          "signature": "setMenu(settings: boolean, items?: readonly { id: string; label: string }[]): boolean",
+          "signature": "setMenu(items?: readonly { id: string; label: string }[]): boolean",
           "documented": true,
-          "summary": "Tell the arcade what your game adds to its menu: whether it has a settings\nscreen, and up to four entries of its own — the whole answer each time, the\nlatest one winning.\n\nPrefer `gem.setMenu`, which holds the state across a reconnect and calls\nyour handlers when the player chooses an entry. This one sends only while\nconnected, and only to an arcade that draws a menu.",
+          "summary": "Tell the arcade what your game adds to its menu: up to four entries of its\nown — the whole answer each time, the latest one winning. Your settings\nare not among them: a game opens its settings from its own button.\n\nPrefer `gem.setMenu`, which holds the state across a reconnect and calls\nyour handlers when the player chooses an entry. This one sends only while\nconnected, and only to an arcade that draws a menu.",
           "deprecated": null,
           "params": [
-            {
-              "name": "settings",
-              "type": "boolean",
-              "optional": false,
-              "summary": null
-            },
             {
               "name": "items",
               "type": "readonly { id: string; label: string }[]",
@@ -6879,6 +7044,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Friend.avatars3d",
+          "name": "avatars3d",
+          "anchor": "friend-avatars3d",
+          "group": "friends",
+          "signature": "readonly avatars3d?: readonly WornAvatar3d[]",
+          "documented": true,
+          "summary": "Every 3D avatar the player wears, one per rig family, in the order the game\ndeclared its families. Absent or empty means none is worn — draw your\ndefault look.\n\n[PlayerIdentity.avatar3dId](api-reference-game.md#playeridentity-avatar3did) and its two URLs are one of these: the\navatar of the game's first declared family that has one. A game that\naccepts a single family can read either; one that accepts several picks by\n`family` here. Absent too where the platform does not send it yet — read\nthe flat fields then.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Friend.badges",
           "name": "badges",
@@ -8697,6 +8878,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemPlayer.avatars3d",
+          "name": "avatars3d",
+          "anchor": "gemplayer-avatars3d",
+          "group": "player",
+          "signature": "readonly avatars3d?: readonly WornAvatar3d[]",
+          "documented": true,
+          "summary": "Every 3D avatar the player wears, one per rig family, in the order the game\ndeclared its families. Absent or empty means none is worn — draw your\ndefault look.\n\n[PlayerIdentity.avatar3dId](api-reference-game.md#playeridentity-avatar3did) and its two URLs are one of these: the\navatar of the game's first declared family that has one. A game that\naccepts a single family can read either; one that accepts several picks by\n`family` here. Absent too where the platform does not send it yet — read\nthe flat fields then.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemPlayer.badges",
           "name": "badges",
@@ -9396,23 +9593,7 @@
           "group": "frame",
           "signature": "interface GameMenu",
           "documented": true,
-          "summary": "What your game adds to the arcade's menu — see `gem.setMenu`.",
-          "deprecated": null,
-          "params": [],
-          "returns": null,
-          "throws": null,
-          "example": null,
-          "defaultValue": null,
-          "guides": []
-        },
-        {
-          "id": "GameMenu.onSettings",
-          "name": "onSettings",
-          "anchor": "gamemenu-onsettings",
-          "group": "frame",
-          "signature": "readonly onSettings?: () => void",
-          "documented": true,
-          "summary": "Open your settings screen. Another embedder may show a Settings entry that\ncalls it, but **the Gem Arcade no longer does**: draw a settings button of\nyour own, always (top-right is the recommendation). Passing this is still\naccepted and harmless.",
+          "summary": "What your game adds to the arcade's menu — see `gem.setMenu`. Your settings\nare not part of it: they open from your own settings button.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9877,6 +10058,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.avatars3d",
+          "name": "avatars3d",
+          "anchor": "gem-avatars3d",
+          "group": "start",
+          "signature": "readonly avatars3d: Avatars3dApi",
+          "documented": true,
+          "summary": "Arcade 3D avatars: what the player wears, the rig families your game\naccepts, the avatars your game sells, and buying one — which wears it.\n2D portraits are a separate system and are not here.\n\n```js\nconst draw = () => {\n  const worn = gem.avatars3d.worn();\n  const url = worn && platformIconUrl(worn.modelUrl);\n  if (url) loadCharacter(url);\n  else useDefaultCharacter();\n};\ndraw();\ngem.avatars3d.onChange(draw);\n```\n\nSee [Arcade avatars](../arcade-avatars.md) for the rig, the config, and\nuploading and selling avatars with gemctl.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.vibration",
           "name": "vibration",
@@ -9905,7 +10102,7 @@
           "group": "start",
           "signature": "readonly controls: ControlsApi",
           "documented": true,
-          "summary": "The player's camera and controls settings — look sensitivity, gamepad look\nsensitivity, invert look and touch movement, which arrive in\n`gem.prefs.recommended`. Two things to do with them:\n\n```js\n// 1. Tell the Arcade which ones your game leaves to the player.\ngem.controls.declare({ lookSensitivity: 'player', invertLookY: 'player' });\n\n// 2. Turn look input into a camera turn at the player's sensitivity.\nconst look = gem.controls.look();\n// dx, dy: the pointer's move in CSS px since the last event.\nconst t = look.fromPointer(dx, dy, e.pointerType, camera.pitch);\ncamera.yaw += t.yaw;\ncamera.pitch += t.pitch;\n```\n\nSee the guide's \"Camera and look controls\" section.",
+          "summary": "The player's camera and controls settings — look sensitivity, gamepad look\nsensitivity, invert look and touch movement, which arrive in\n`gem.prefs.recommended` as the player's Arcade-wide defaults. Turn look\ninput into a camera turn at the player's sensitivity:\n\n```js\nconst look = gem.controls.look();\n// dx, dy: the pointer's move in CSS px since the last event.\nconst t = look.fromPointer(dx, dy, e.pointerType, camera.pitch);\ncamera.yaw += t.yaw;\ncamera.pitch += t.pitch;\n```\n\nSee the guide's \"Camera and look controls\" section.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -10267,14 +10464,14 @@
           "group": "start",
           "signature": "setMenu(menu: GameMenu): boolean",
           "documented": true,
-          "summary": "Put up to four entries of your own in the arcade's menu. The arcade keeps\none menu button over your game: it is how a player leaves, mutes, goes\nfullscreen, reports a problem and changes their Arcade-wide settings.\n\n```js\ngem.setMenu({\n  items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],\n});\n```\n\n**Your settings are not in it: draw your own settings button, always** —\ntop-right is the recommendation. `onSettings` is still accepted, and\nanother embedder may show an entry for it, but the Gem Arcade no longer\nshows a Settings entry, so a game whose settings open only from there has\nnone a player can reach.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last, so call it again when the entries change — a new\nlanguage, a screen with different options. `gem.setMenu({})` takes\neverything of yours back out. The arcade's own entries are not yours to\nchange, and Return to the Arcade is always among them.\n\n**The arcade pauses your game while its menu is open** (`onPause`), and\nresumes it before a handler of yours runs. A handler opens a screen; it\nshould not assume the game was paused by you.",
+          "summary": "Put up to four entries of your own in the arcade's menu. The arcade keeps\none menu button over your game: it is how a player leaves, mutes, goes\nfullscreen, reports a problem and changes their Arcade-wide settings.\n\n```js\ngem.setMenu({\n  items: [{ id: 'how-to-play', label: t('How to play'), onSelect: () => help.open() }],\n});\n```\n\n**Your settings are not in it: draw your own settings button, always** —\ntop-right, clear of `gem.viewport.reserved`. The Arcade's menu never opens\nyour settings screen.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last, so call it again when the entries change — a new\nlanguage, a screen with different options. `gem.setMenu({})` takes\neverything of yours back out. The arcade's own entries are not yours to\nchange, and Return to the Arcade is always among them.\n\n**The arcade pauses your game while its menu is open** (`onPause`), and\nresumes it before a handler of yours runs. A handler opens a screen; it\nshould not assume the game was paused by you.",
           "deprecated": null,
           "params": [
             {
               "name": "menu",
               "type": "GameMenu",
               "optional": false,
-              "summary": "Your settings handler and your own entries."
+              "summary": "Your own entries."
             }
           ],
           "returns": "`true` when the arcade was told now; `false` before the bridge is\n  up (the menu is held and sent when it connects) and under an embedder\n  that draws no menu.",
@@ -11417,6 +11614,102 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Avatar3dFamily",
+          "name": "Avatar3dFamily",
+          "anchor": "avatar3dfamily",
+          "group": "avatars3d",
+          "signature": "type Avatar3dFamily = \"small_human\" | string & object",
+          "documented": true,
+          "summary": "A rig family — the skeleton contract a 3D avatar is built on, and what a\ngame declares it can animate. `small_human` is the first: a `root` node\nwith a `body` child, which holds `head`, `arm_l`, `arm_r`, `leg_l` and\n`leg_r`, and a `hand_socket` under `arm_r`.\n\nOpen-ended (`| (string & {})`) so a family the platform adds later does not\nbreak a `switch` you compiled against this version: keep a `default` arm and\nskip a family you do not draw.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "WornAvatar3d",
+          "name": "WornAvatar3d",
+          "anchor": "wornavatar3d",
+          "group": "avatars3d",
+          "signature": "interface WornAvatar3d",
+          "documented": true,
+          "summary": "One 3D avatar a player wears — at most one per [Avatar3dFamily](api-reference-game.md#avatar3dfamily).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "WornAvatar3d.family",
+          "name": "family",
+          "anchor": "wornavatar3d-family",
+          "group": "avatars3d",
+          "signature": "readonly family: Avatar3dFamily",
+          "documented": true,
+          "summary": "The rig family this avatar is built on.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "WornAvatar3d.id",
+          "name": "id",
+          "anchor": "wornavatar3d-id",
+          "group": "avatars3d",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "The avatar's item id — a stable key for the model, never something to\nshow as text.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "WornAvatar3d.modelUrl",
+          "name": "modelUrl",
+          "anchor": "wornavatar3d-modelurl",
+          "group": "avatars3d",
+          "signature": "readonly modelUrl: string",
+          "documented": true,
+          "summary": "The avatar's model, a binary glTF (`.glb`) on the family's rig. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before loading it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "WornAvatar3d.iconUrl",
+          "name": "iconUrl",
+          "anchor": "wornavatar3d-iconurl",
+          "group": "avatars3d",
+          "signature": "readonly iconUrl: string",
+          "documented": true,
+          "summary": "A rendered portrait of the avatar, for a roster or a menu. Pass it through\n[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",
           "name": "PlayerIdentity",
@@ -11577,6 +11870,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlayerIdentity.avatars3d",
+          "name": "avatars3d",
+          "anchor": "playeridentity-avatars3d",
+          "group": "player",
+          "signature": "readonly avatars3d?: readonly WornAvatar3d[]",
+          "documented": true,
+          "summary": "Every 3D avatar the player wears, one per rig family, in the order the game\ndeclared its families. Absent or empty means none is worn — draw your\ndefault look.\n\n[PlayerIdentity.avatar3dId](api-reference-game.md#playeridentity-avatar3did) and its two URLs are one of these: the\navatar of the game's first declared family that has one. A game that\naccepts a single family can read either; one that accepts several picks by\n`family` here. Absent too where the platform does not send it yet — read\nthe flat fields then.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PlayerIdentity.badges",
           "name": "badges",
@@ -11600,7 +11909,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`, `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.",
+          "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`, `avatars_3d` and `badges`, and nothing else from the row. Anything missing, empty or of the wrong type is absent in the result.",
           "deprecated": null,
           "params": [
             {
@@ -12920,14 +13229,62 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Avatar3dPurchaseRequest",
+          "name": "Avatar3dPurchaseRequest",
+          "anchor": "avatar3dpurchaserequest",
+          "group": "avatars3d",
+          "signature": "interface Avatar3dPurchaseRequest",
+          "documented": true,
+          "summary": "What a game asks for when it buys one of its own 3D avatars for the player\nwith `gem.avatars3d.purchase`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatar3dPurchaseRequest.itemId",
+          "name": "itemId",
+          "anchor": "avatar3dpurchaserequest-itemid",
+          "group": "avatars3d",
+          "signature": "itemId: string",
+          "documented": true,
+          "summary": "The avatar's item id — `itemId` on an `Avatar3dOffer`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Avatar3dPurchaseRequest.currencySlug",
+          "name": "currencySlug",
+          "anchor": "avatar3dpurchaserequest-currencyslug",
+          "group": "avatars3d",
+          "signature": "currencySlug: string",
+          "documented": true,
+          "summary": "The platform currency to pay in, `GEMS` or `ARCADE_TICKETS`. The offer\nmust carry a price in it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PurchaseRefusalCode",
           "name": "PurchaseRefusalCode",
           "anchor": "purchaserefusalcode",
           "group": "purchases",
-          "signature": "type PurchaseRefusalCode = \"unknown_currency\" | \"currency_not_in_game_payable\" | \"not_purchasable\" | \"no_price_in_currency\" | \"busy\" | \"cancelled\" | \"insufficient_funds\" | \"price_mismatch\" | \"config_version_stale\" | \"platform_currency_unavailable\" | \"not_available\" | \"recipe_locked\" | \"recipe_on_cooldown\" | \"recipe_max_uses_exceeded\" | \"item_max_stack_exceeded\" | \"recipe_costs_unmet\" | \"quantity_invalid\" | \"error\"",
+          "signature": "type PurchaseRefusalCode = \"unknown_currency\" | \"currency_not_in_game_payable\" | \"not_purchasable\" | \"no_price_in_currency\" | \"busy\" | \"cancelled\" | \"insufficient_funds\" | \"price_mismatch\" | \"config_version_stale\" | \"platform_currency_unavailable\" | \"not_available\" | \"recipe_locked\" | \"already_owned\" | \"recipe_on_cooldown\" | \"recipe_max_uses_exceeded\" | \"item_max_stack_exceeded\" | \"recipe_costs_unmet\" | \"quantity_invalid\" | \"error\"",
           "documented": true,
-          "summary": "Every reason a purchase can be refused, on either purchase path.\n\n- `unknown_currency` — the slug names no active platform currency. There are\n  no aliases: `TICKETS` is the retired name for Gems and is refused, never\n  resolved. Write `GEMS` or `ARCADE_TICKETS`.\n- `currency_not_in_game_payable` — the currency exists but cannot pay for game\n  items.\n- `not_purchasable` — the target is not in the purchase catalog, or cannot be\n  bought (not published on this channel, inactive, or its config does not\n  convert).\n- `no_price_in_currency` — the target has prices, but none in that currency.\n- `busy` — another purchase is in flight, a sheet is already open, the\n  platform is backing off after a cancel, or the ask came without a player's\n  click or key press.\n- `cancelled` — the player dismissed the platform sheet.\n- `insufficient_funds` — the player cannot afford it.\n- `price_mismatch`, `config_version_stale` — the price or config changed\n  between reading the catalog and buying; nothing was charged. Re-read.\n- `platform_currency_unavailable` — the currency is not available to this\n  purchase right now.\n- `not_available` — the recipe is outside its availability window, or\n  inactive; nothing was charged. Hide or disable it until its window opens.\n- `recipe_locked` — the recipe's prerequisites are not met.\n- `recipe_on_cooldown`, `recipe_max_uses_exceeded`, `item_max_stack_exceeded`,\n  `recipe_costs_unmet`, `quantity_invalid` — the recipe or item refused this\n  purchase, before any charge.\n- `error` — anything else, including a reason this SDK version does not know\n  and an answer that never arrived.\n\nFOR YOUR LOGS AND YOUR SHOP'S STATE, NEVER FOR A PAYMENT SCREEN. Grey out a\nlocked recipe; fix a slug. Never draw a top-up, \"buy more\" or payment UI of\nyour own — only the arcade may, and a game screen that looks like one is an\nimitation of platform payment chrome.",
+          "summary": "Every reason a purchase can be refused, on either purchase path.\n\n- `unknown_currency` — the slug names no active platform currency. There are\n  no aliases: `TICKETS` is the retired name for Gems and is refused, never\n  resolved. Write `GEMS` or `ARCADE_TICKETS`.\n- `currency_not_in_game_payable` — the currency exists but cannot pay for game\n  items.\n- `not_purchasable` — the target is not in the purchase catalog, or cannot be\n  bought (not published on this channel, inactive, or its config does not\n  convert).\n- `no_price_in_currency` — the target has prices, but none in that currency.\n- `busy` — another purchase is in flight, a sheet is already open, the\n  platform is backing off after a cancel, or the ask came without a player's\n  click or key press.\n- `cancelled` — the player dismissed the platform sheet.\n- `insufficient_funds` — the player cannot afford it.\n- `price_mismatch`, `config_version_stale` — the price or config changed\n  between reading the catalog and buying; nothing was charged. Re-read.\n- `platform_currency_unavailable` — the currency is not available to this\n  purchase right now.\n- `not_available` — the recipe is outside its availability window, or\n  inactive; nothing was charged. Hide or disable it until its window opens.\n- `recipe_locked` — the recipe's prerequisites are not met.\n- `already_owned` — the player already owns the 3D avatar\n  `gem.avatars3d.purchase` asked for; nothing was charged. Only that call\n  answers it.\n- `recipe_on_cooldown`, `recipe_max_uses_exceeded`, `item_max_stack_exceeded`,\n  `recipe_costs_unmet`, `quantity_invalid` — the recipe or item refused this\n  purchase, before any charge.\n- `error` — anything else, including a reason this SDK version does not know\n  and an answer that never arrived.\n\nFOR YOUR LOGS AND YOUR SHOP'S STATE, NEVER FOR A PAYMENT SCREEN. Grey out a\nlocked recipe; fix a slug. Never draw a top-up, \"buy more\" or payment UI of\nyour own — only the arcade may, and a game screen that looks like one is an\nimitation of platform payment chrome.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -14413,6 +14770,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "LeaderboardEntry.avatars3d",
+          "name": "avatars3d",
+          "anchor": "leaderboardentry-avatars3d",
+          "group": "leaderboards",
+          "signature": "readonly avatars3d?: readonly WornAvatar3d[]",
+          "documented": true,
+          "summary": "Every 3D avatar the player wears, one per rig family, in the order the game\ndeclared its families. Absent or empty means none is worn — draw your\ndefault look.\n\n[PlayerIdentity.avatar3dId](api-reference-game.md#playeridentity-avatar3did) and its two URLs are one of these: the\navatar of the game's first declared family that has one. A game that\naccepts a single family can read either; one that accepts several picks by\n`family` here. Absent too where the platform does not send it yet — read\nthe flat fields then.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "LeaderboardEntry.badges",
           "name": "badges",
@@ -16224,6 +16597,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlayerProfile.avatars3d",
+          "name": "avatars3d",
+          "anchor": "playerprofile-avatars3d",
+          "group": "profiles",
+          "signature": "readonly avatars3d?: readonly WornAvatar3d[]",
+          "documented": true,
+          "summary": "Every 3D avatar the player wears, one per rig family, in the order the game\ndeclared its families. Absent or empty means none is worn — draw your\ndefault look.\n\n[PlayerIdentity.avatar3dId](api-reference-game.md#playeridentity-avatar3did) and its two URLs are one of these: the\navatar of the game's first declared family that has one. A game that\naccepts a single family can read either; one that accepts several picks by\n`family` here. Absent too where the platform does not send it yet — read\nthe flat fields then.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PlayerProfile.badges",
           "name": "badges",
@@ -19285,6 +19674,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "RoomMember.avatars3d",
+          "name": "avatars3d",
+          "anchor": "roommember-avatars3d",
+          "group": "rooms",
+          "signature": "readonly avatars3d?: readonly WornAvatar3d[]",
+          "documented": true,
+          "summary": "Every 3D avatar the player wears, one per rig family, in the order the game\ndeclared its families. Absent or empty means none is worn — draw your\ndefault look.\n\n[PlayerIdentity.avatar3dId](api-reference-game.md#playeridentity-avatar3did) and its two URLs are one of these: the\navatar of the game's first declared family that has one. A game that\naccepts a single family can read either; one that accepts several picks by\n`family` here. Absent too where the platform does not send it yet — read\nthe flat fields then.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "RoomMember.badges",
           "name": "badges",
@@ -20431,6 +20836,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "ShowcaseFriendEntry.avatars3d",
+          "name": "avatars3d",
+          "anchor": "showcasefriendentry-avatars3d",
+          "group": "showcase",
+          "signature": "readonly avatars3d?: readonly WornAvatar3d[]",
+          "documented": true,
+          "summary": "Every 3D avatar the player wears, one per rig family, in the order the game\ndeclared its families. Absent or empty means none is worn — draw your\ndefault look.\n\n[PlayerIdentity.avatar3dId](api-reference-game.md#playeridentity-avatar3did) and its two URLs are one of these: the\navatar of the game's first declared family that has one. A game that\naccepts a single family can read either; one that accepts several picks by\n`family` here. Absent too where the platform does not send it yet — read\nthe flat fields then.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "ShowcaseFriendEntry.badges",
           "name": "badges",
@@ -30711,6 +31132,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Friend.avatars3d",
+          "name": "avatars3d",
+          "anchor": "friend-avatars3d",
+          "group": "friends",
+          "signature": "readonly avatars3d?: readonly WornAvatar3d[]",
+          "documented": true,
+          "summary": "Every 3D avatar the player wears, one per rig family, in the order the game\ndeclared its families. Absent or empty means none is worn — draw your\ndefault look.\n\n[PlayerIdentity.avatar3dId](api-reference-function.md#playeridentity-avatar3did) and its two URLs are one of these: the\navatar of the game's first declared family that has one. A game that\naccepts a single family can read either; one that accepts several picks by\n`family` here. Absent too where the platform does not send it yet — read\nthe flat fields then.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Friend.badges",
           "name": "badges",
@@ -31627,6 +32064,102 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Avatar3dFamily",
+          "name": "Avatar3dFamily",
+          "anchor": "avatar3dfamily",
+          "group": "identity",
+          "signature": "type Avatar3dFamily = \"small_human\" | string & object",
+          "documented": true,
+          "summary": "A rig family — the skeleton contract a 3D avatar is built on, and what a\ngame declares it can animate. `small_human` is the first: a `root` node\nwith a `body` child, which holds `head`, `arm_l`, `arm_r`, `leg_l` and\n`leg_r`, and a `hand_socket` under `arm_r`.\n\nOpen-ended (`| (string & {})`) so a family the platform adds later does not\nbreak a `switch` you compiled against this version: keep a `default` arm and\nskip a family you do not draw.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "WornAvatar3d",
+          "name": "WornAvatar3d",
+          "anchor": "wornavatar3d",
+          "group": "identity",
+          "signature": "interface WornAvatar3d",
+          "documented": true,
+          "summary": "One 3D avatar a player wears — at most one per [Avatar3dFamily](api-reference-function.md#avatar3dfamily).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "WornAvatar3d.family",
+          "name": "family",
+          "anchor": "wornavatar3d-family",
+          "group": "identity",
+          "signature": "readonly family: Avatar3dFamily",
+          "documented": true,
+          "summary": "The rig family this avatar is built on.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "WornAvatar3d.id",
+          "name": "id",
+          "anchor": "wornavatar3d-id",
+          "group": "identity",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "The avatar's item id — a stable key for the model, never something to\nshow as text.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "WornAvatar3d.modelUrl",
+          "name": "modelUrl",
+          "anchor": "wornavatar3d-modelurl",
+          "group": "identity",
+          "signature": "readonly modelUrl: string",
+          "documented": true,
+          "summary": "The avatar's model, a binary glTF (`.glb`) on the family's rig. Pass it\nthrough [platformIconUrl](api-reference-function.md#platformiconurl) before loading it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "WornAvatar3d.iconUrl",
+          "name": "iconUrl",
+          "anchor": "wornavatar3d-iconurl",
+          "group": "identity",
+          "signature": "readonly iconUrl: string",
+          "documented": true,
+          "summary": "A rendered portrait of the avatar, for a roster or a menu. Pass it through\n[platformIconUrl](api-reference-function.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PlayerIdentity",
           "name": "PlayerIdentity",
@@ -31787,6 +32320,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlayerIdentity.avatars3d",
+          "name": "avatars3d",
+          "anchor": "playeridentity-avatars3d",
+          "group": "identity",
+          "signature": "readonly avatars3d?: readonly WornAvatar3d[]",
+          "documented": true,
+          "summary": "Every 3D avatar the player wears, one per rig family, in the order the game\ndeclared its families. Absent or empty means none is worn — draw your\ndefault look.\n\n[PlayerIdentity.avatar3dId](api-reference-function.md#playeridentity-avatar3did) and its two URLs are one of these: the\navatar of the game's first declared family that has one. A game that\naccepts a single family can read either; one that accepts several picks by\n`family` here. Absent too where the platform does not send it yet — read\nthe flat fields then.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PlayerIdentity.badges",
           "name": "badges",
@@ -31810,7 +32359,7 @@
           "group": "identity",
           "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-function.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.",
+          "summary": "Map one row's identity fields, as the platform's API sends them, to\n[PlayerIdentity](api-reference-function.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`, `avatars_3d` and `badges`, and nothing else from the row. Anything missing, empty or of the wrong type is absent in the result.",
           "deprecated": null,
           "params": [
             {
@@ -32137,6 +32686,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "LeaderboardEntry.avatars3d",
+          "name": "avatars3d",
+          "anchor": "leaderboardentry-avatars3d",
+          "group": "leaderboards",
+          "signature": "readonly avatars3d?: readonly WornAvatar3d[]",
+          "documented": true,
+          "summary": "Every 3D avatar the player wears, one per rig family, in the order the game\ndeclared its families. Absent or empty means none is worn — draw your\ndefault look.\n\n[PlayerIdentity.avatar3dId](api-reference-function.md#playeridentity-avatar3did) and its two URLs are one of these: the\navatar of the game's first declared family that has one. A game that\naccepts a single family can read either; one that accepts several picks by\n`family` here. Absent too where the platform does not send it yet — read\nthe flat fields then.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "LeaderboardEntry.badges",
           "name": "badges",
@@ -33939,6 +34504,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlayerProfile.avatars3d",
+          "name": "avatars3d",
+          "anchor": "playerprofile-avatars3d",
+          "group": "profiles",
+          "signature": "readonly avatars3d?: readonly WornAvatar3d[]",
+          "documented": true,
+          "summary": "Every 3D avatar the player wears, one per rig family, in the order the game\ndeclared its families. Absent or empty means none is worn — draw your\ndefault look.\n\n[PlayerIdentity.avatar3dId](api-reference-function.md#playeridentity-avatar3did) and its two URLs are one of these: the\navatar of the game's first declared family that has one. A game that\naccepts a single family can read either; one that accepts several picks by\n`family` here. Absent too where the platform does not send it yet — read\nthe flat fields then.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PlayerProfile.badges",
           "name": "badges",
@@ -34398,6 +34979,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "ShowcaseFriendEntry.avatars3d",
+          "name": "avatars3d",
+          "anchor": "showcasefriendentry-avatars3d",
+          "group": "showcase",
+          "signature": "readonly avatars3d?: readonly WornAvatar3d[]",
+          "documented": true,
+          "summary": "Every 3D avatar the player wears, one per rig family, in the order the game\ndeclared its families. Absent or empty means none is worn — draw your\ndefault look.\n\n[PlayerIdentity.avatar3dId](api-reference-function.md#playeridentity-avatar3did) and its two URLs are one of these: the\navatar of the game's first declared family that has one. A game that\naccepts a single family can read either; one that accepts several picks by\n`family` here. Absent too where the platform does not send it yet — read\nthe flat fields then.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "ShowcaseFriendEntry.badges",
           "name": "badges",