@indiegems/gem-web-sdk 12.0.0 → 13.1.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.1.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,427 @@
           "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": "AvatarRigNode",
+          "name": "AvatarRigNode",
+          "anchor": "avatarrignode",
+          "group": "avatars3d",
+          "signature": "interface AvatarRigNode",
+          "documented": true,
+          "summary": "One node of a rig family's tree: its exact, case-sensitive name, and the\nname of the node it is a DIRECT child of. `parent` is `null` for the rig's\nroot, which is a root node of the scene.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "AvatarRigNode.node",
+          "name": "node",
+          "anchor": "avatarrignode-node",
+          "group": "avatars3d",
+          "signature": "readonly node: string",
+          "documented": true,
+          "summary": "The node's name, exact and case-sensitive.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "AvatarRigNode.parent",
+          "name": "parent",
+          "anchor": "avatarrignode-parent",
+          "group": "avatars3d",
+          "signature": "readonly parent: string | null",
+          "documented": true,
+          "summary": "The node it is a direct child of; `null` for the rig's root.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "AvatarRigs",
+          "name": "AvatarRigs",
+          "anchor": "avatarrigs",
+          "group": "avatars3d",
+          "signature": "interface AvatarRigs",
+          "documented": true,
+          "summary": "The rig families this SDK knows, by name.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "AvatarRigs.small_human",
+          "name": "small_human",
+          "anchor": "avatarrigs-small_human",
+          "group": "avatars3d",
+          "signature": "readonly small_human: readonly AvatarRigNode[]",
+          "documented": true,
+          "summary": "The toy rig: rigid limbs on a body, eight nodes.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "AvatarRigs.adult_human",
+          "name": "adult_human",
+          "anchor": "avatarrigs-adult_human",
+          "group": "avatars3d",
+          "signature": "readonly adult_human: readonly AvatarRigNode[]",
+          "documented": true,
+          "summary": "The adult humanoid with fingers: 56 nodes, world-aligned at rest.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "AVATAR_RIGS",
+          "name": "AVATAR_RIGS",
+          "anchor": "avatar_rigs",
+          "group": "avatars3d",
+          "signature": "AVATAR_RIGS: AvatarRigs",
+          "documented": true,
+          "summary": "Every node each rig family requires, with the node it is a direct child of,\nparents before children. Frozen: read it, never change it.\n\nThe platform refuses an upload whose model is missing one of these, has one\nunder another parent, or has one twice (`rig_mismatch`). Extra nodes are\nallowed anywhere. `adult_human` also requires every one of its nodes to be\nworld-aligned at rest; that rule is not in this list, see the guide.\n\n```js\nimport { AVATAR_RIGS } from '@indiegems/gem-web-sdk/sdk';\n\n// Every joint of the worn avatar, by name.\nconst joints = new Map(\n  AVATAR_RIGS.adult_human.map(({ node }) => [node, gltf.scene.getObjectByName(node)]),\n);\n\n// A test that one of your own models is on the rig.\nfor (const { node, parent } of AVATAR_RIGS.adult_human) {\n  const found = gltf.scene.getObjectByName(node);\n  if (!found) throw new Error(`missing ${node}`);\n  if (parent !== null && found.parent?.name !== parent) throw new Error(`${node} is not under ${parent}`);\n}\n```",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemApiError",
           "name": "GemApiError",
@@ -5783,7 +6208,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 +6222,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 +6261,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",
@@ -6152,7 +6458,7 @@
           "group": "platform",
           "signature": "interface RewardCue",
           "documented": true,
-          "summary": "A platform-currency reward on its way to the arcade — in the Gem Arcade, a\nflight into the Gem button at the top-left of your frame — what\n`gem.cueReward` takes.",
+          "summary": "A platform-currency reward on its way to the arcade — in the Gem Arcade, a\nflight into the Gem button, in whichever corner of your frame it sits — what\n`gem.cueReward` takes.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -6241,6 +6547,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemCorner",
+          "name": "GemCorner",
+          "anchor": "gemcorner",
+          "group": "frame",
+          "signature": "type GemCorner = \"top-left\" | \"top-right\" | \"bottom-left\" | \"bottom-right\"",
+          "documented": true,
+          "summary": "A corner of your frame, for `gem.setGemCorner`: where you would like the\narcade's Gem button to sit. `'top-left'` is where it sits unless you ask.\nPhysical corners: `'top-left'` is the top-left in every language.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FrameState",
           "name": "FrameState",
@@ -6553,52 +6875,46 @@
           "guides": []
         },
         {
-          "id": "GemFrame.declareControls",
-          "name": "declareControls",
-          "anchor": "gemframe-declarecontrols",
+          "id": "GemFrame.setMenu",
+          "name": "setMenu",
+          "anchor": "gemframe-setmenu",
           "group": "frame",
-          "signature": "declareControls(uses: GemControlsDeclaration): boolean",
+          "signature": "setMenu(items?: readonly { id: string; label: string }[]): 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.",
+          "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": "uses",
-              "type": "GemControlsDeclaration",
-              "optional": false,
+              "name": "items",
+              "type": "readonly { id: string; label: string }[]",
+              "optional": true,
               "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.",
+          "returns": "whether the message left the frame — `false` before the bridge is\n  up, for an arcade with no menu, and past this frame's own limit.",
           "throws": null,
           "example": null,
           "defaultValue": null,
           "guides": []
         },
         {
-          "id": "GemFrame.setMenu",
-          "name": "setMenu",
-          "anchor": "gemframe-setmenu",
+          "id": "GemFrame.setGemCorner",
+          "name": "setGemCorner",
+          "anchor": "gemframe-setgemcorner",
           "group": "frame",
-          "signature": "setMenu(settings: boolean, items?: readonly { id: string; label: string }[]): boolean",
+          "signature": "setGemCorner(corner: GemCorner): 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": "Ask the arcade to put its own control over your game — the Gem button —\nin this corner of your frame: the whole answer each time, the latest one\nwinning.\n\nPrefer `gem.setGemCorner`, which holds the corner across a reconnect.\nThis one sends only while connected, and only to an arcade that can move\nits control.",
           "deprecated": null,
           "params": [
             {
-              "name": "settings",
-              "type": "boolean",
+              "name": "corner",
+              "type": "GemCorner",
               "optional": false,
               "summary": null
-            },
-            {
-              "name": "items",
-              "type": "readonly { id: string; label: string }[]",
-              "optional": true,
-              "summary": null
             }
           ],
-          "returns": "whether the message left the frame — `false` before the bridge is\n  up, for an arcade with no menu, and past this frame's own limit.",
+          "returns": "whether the message left the frame — `false` before the bridge is\n  up, for an arcade that cannot move its control, for a value that is not\n  one of the four corners, and past this frame's own limit.",
           "throws": null,
           "example": null,
           "defaultValue": null,
@@ -6879,6 +7195,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 +9029,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",
@@ -9204,7 +9552,7 @@
           "group": "player",
           "signature": "readonly reserved: readonly GemReservedArea[]",
           "documented": true,
-          "summary": "Rectangles of your frame the arcade's own controls cover — in the Gem\nArcade, its Gem button in the top-left corner, and the frame-rate readout\nbeside it while the player shows it; an embedder that draws wallets over\nyour game adds theirs (see `setWalletVisible`). Keep essential UI and touch\ntargets out of them. Empty when the arcade covers nothing.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends.",
+          "summary": "Rectangles of your frame the arcade's own controls cover — in the Gem\nArcade, its Gem button in whichever corner it sits, and the frame-rate readout\nbeside it while the player shows it; an embedder that draws wallets over\nyour game adds theirs (see `setWalletVisible`). Keep essential UI and touch\ntargets out of them. Empty when the arcade covers nothing.\n\nA stylesheet reads the per-corner custom properties the SDK stamps from\nthese instead — `--gem-reserved-tl-height` and friends.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -9396,23 +9744,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 +10209,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 +10253,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,
@@ -10215,7 +10563,7 @@
           "group": "start",
           "signature": "cueReward(cue: RewardCue): boolean",
           "documented": true,
-          "summary": "Tell the arcade a platform-currency reward is on its way, so it **shows it\nlanding**: in the Gem Arcade the currency flies from `origin` into the Gem\nbutton at the top-left of your frame, which pops as each mark lands, and\nthe player's total moves once the platform confirms the grant. The Gem\nArcade draws no wallet over your game: the player sees their Gems and\nTickets in the Gem menu. A payout you do not cue still flies, from the\nmiddle of your frame, so cue the ones the player earns on screen.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the ticket\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Tickets alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
+          "summary": "Tell the arcade a platform-currency reward is on its way, so it **shows it\nlanding**: in the Gem Arcade the currency flies from `origin` into the Gem\nbutton, wherever on your frame it sits, which pops as each mark lands, and\nthe player's total moves once the platform confirms the grant. The Gem\nArcade draws no wallet over your game: the player sees their Gems and\nTickets in the Gem menu. A payout you do not cue still flies, from the\nmiddle of your frame, so cue the ones the player earns on screen.\n\nCall it the moment your game decides to award — when your server has moved\n(or is about to move) the progression mapped onto a platform currency —\nand pass the centre of that currency's icon (or hero) on your screen, so\nthe flight starts from the mark the player is looking at:\n\n```js\nconst { x, y, width, height } = rewardGem.getBoundingClientRect(); // the gem's own box\ngem.cueReward({\n  currencySlug: 'GEMS', // or 'ARCADE_TICKETS', from the ticket\n  expected: 15,\n  origin: { x: x + width / 2, y: y + height / 2 },\n});\n```\n\n**This is the platform-currency animation, and the only one.** The display\nof every platform currency — Gems and Tickets alike — belongs to the\narcade: a game draws no flight or celebration of its own for one and keeps\nno counter of one. **If this returns `false`, do nothing** — there is no\nfallback celebration.\n\n**The arcade never takes your word for the amount.** What lands, and the\nplayer's new total, come from the platform itself; `expected` is drawn as\nprovisional, and a cue the platform never confirms fades on its own — a\ngrant clamped to zero, say, or one the receipt reports `suppressed`. So\nthe cue can only ever make the wallet move for a reward that really\nlanded — which it does on every channel, dev and test included.",
           "deprecated": null,
           "params": [
             {
@@ -10267,14 +10615,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, with your Back button just to its left, clear of\n`gem.viewport.reserved`. The Arcade's menu never opens your settings\nscreen.\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.",
@@ -10283,6 +10631,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.setGemCorner",
+          "name": "setGemCorner",
+          "anchor": "gem-setgemcorner",
+          "group": "start",
+          "signature": "setGemCorner(corner: GemCorner): boolean",
+          "documented": true,
+          "summary": "Ask the arcade to put its Gem button — its one control over your game,\ntop-left unless you ask — in another corner of your frame.\n\n```js\n// This game's own HUD needs the top-left, so the Gem goes top-right.\ngem.setGemCorner('top-right');\n```\n\n**Leave it top-left unless your own HUD needs that corner**, and then pick\none corner for the whole game — at most one per orientation. A Gem that\nmoves between screens is a way out the player has to look for. In\nlandscape the bottom corners sit where a player's thumbs hold the sticks.\n\n**Lay out around `gem.viewport.reserved`, never around the corner you\nasked for.** The arcade moves the Gem on its own terms: not while the\nplayer is using it or its menu is open, not more often than every few\nseconds, and never over a corner the player chose for themselves. The\nrectangles say where it actually is, and the `--gem-reserved-*` CSS\nproperties follow them.\n\n**It is screen state, not a toggle.** Each call is the whole answer and\nreplaces the last. A value that is not one of the four corners is ignored,\nwith a warning on the console, and changes nothing.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "corner",
+              "type": "GemCorner",
+              "optional": false,
+              "summary": "`'top-left'`, `'top-right'`, `'bottom-left'` or `'bottom-right'`."
+            }
+          ],
+          "returns": "`true` when the arcade was told now; `false` before the bridge is\n  up (the corner is held and sent when it connects), under an embedder that\n  cannot move its control, and for a value that is not a corner.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.exit",
           "name": "exit",
@@ -11167,7 +11538,7 @@
           "name": "protocol",
           "anchor": "matchconnection-protocol",
           "group": "match",
-          "signature": "readonly protocol: \"dedicated\" | \"p2p\" | \"loopback\"",
+          "signature": "readonly protocol: \"p2p\" | \"dedicated\" | \"loopback\"",
           "documented": true,
           "summary": "What is on the other end: `dedicated` (the platform's server), `p2p` (the\nhosting player's browser), or `loopback` (this browser — you are the host,\nand this is the in-process link to your own bundle).",
           "deprecated": null,
@@ -11417,6 +11788,102 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Avatar3dFamily",
+          "name": "Avatar3dFamily",
+          "anchor": "avatar3dfamily",
+          "group": "avatars3d",
+          "signature": "type Avatar3dFamily = \"small_human\" | \"adult_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. Two today:\n\n- `small_human`, the toy rig: a `root` node with a `body` child, which holds\n  `head`, `arm_l`, `arm_r`, `leg_l` and `leg_r`, and a `hand_socket` under\n  `arm_r`.\n- `adult_human`, a full humanoid with fingers: 56 nodes from `root` and\n  `hips` down to `toes_r`, every one world-aligned at rest, so one clip plays\n  on every avatar in the family.\n\n`AVATAR_RIGS` (from `@indiegems/gem-web-sdk/sdk`) lists every node of\nboth, with its parent.\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 +12044,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 +12083,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 +13403,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 +14944,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 +16771,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 +19848,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 +21010,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 +31306,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 +32238,102 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Avatar3dFamily",
+          "name": "Avatar3dFamily",
+          "anchor": "avatar3dfamily",
+          "group": "identity",
+          "signature": "type Avatar3dFamily = \"small_human\" | \"adult_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. Two today:\n\n- `small_human`, the toy rig: a `root` node with a `body` child, which holds\n  `head`, `arm_l`, `arm_r`, `leg_l` and `leg_r`, and a `hand_socket` under\n  `arm_r`.\n- `adult_human`, a full humanoid with fingers: 56 nodes from `root` and\n  `hips` down to `toes_r`, every one world-aligned at rest, so one clip plays\n  on every avatar in the family.\n\n`AVATAR_RIGS` (from `@indiegems/gem-web-sdk/sdk`) lists every node of\nboth, with its parent.\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 +32494,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 +32533,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 +32860,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 +34678,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 +35153,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",