@indiegems/gem-web-sdk 12.0.0 → 13.1.0

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v12.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v13.1.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -3669,6 +3669,356 @@ The runtime companion to [PlatformEventName](#platformeventname), for a game tha
 show what it gets for free, or to check a funnel step it authored against
 what the platform actually emits.
 
+<a id="avatar3dprice"></a>
+
+## Avatar3dPrice
+
+```ts
+interface Avatar3dPrice
+```
+
+One price of a 3D avatar on sale, in one platform currency.
+
+<a id="avatar3dprice-currencyslug"></a>
+
+## Avatar3dPrice.currencySlug
+
+```ts
+readonly currencySlug: string
+```
+
+`GEMS` or `ARCADE_TICKETS` — what to pass as `currencySlug`.
+
+<a id="avatar3dprice-price"></a>
+
+## Avatar3dPrice.price
+
+```ts
+readonly price: number
+```
+
+The price, a whole number of that currency.
+
+<a id="avatar3doffer"></a>
+
+## Avatar3dOffer
+
+```ts
+interface Avatar3dOffer
+```
+
+One of your game's 3D avatars on sale, as the platform prices it.
+
+<a id="avatar3doffer-itemid"></a>
+
+## Avatar3dOffer.itemId
+
+```ts
+readonly itemId: string
+```
+
+The avatar's item id — what [Avatars3dApi.purchase](#avatars3dapi-purchase) takes.
+
+<a id="avatar3doffer-slug"></a>
+
+## Avatar3dOffer.slug
+
+```ts
+readonly slug: string
+```
+
+The slug you uploaded it under. A key, not display text.
+
+<a id="avatar3doffer-family"></a>
+
+## Avatar3dOffer.family
+
+```ts
+readonly family: Avatar3dFamily
+```
+
+The rig family the model is built on.
+
+<a id="avatar3doffer-displayname"></a>
+
+## Avatar3dOffer.displayName
+
+```ts
+readonly displayName: string
+```
+
+The avatar's name, as you uploaded it.
+
+<a id="avatar3doffer-description"></a>
+
+## Avatar3dOffer.description
+
+```ts
+readonly description?: string
+```
+
+The avatar's description, when it has one.
+
+<a id="avatar3doffer-iconurl"></a>
+
+## Avatar3dOffer.iconUrl
+
+```ts
+readonly iconUrl: string
+```
+
+A rendered portrait of the avatar, for a shop tile. Pass it through
+`platformIconUrl` before putting it in an `<img src>`.
+
+<a id="avatar3doffer-modelurl"></a>
+
+## Avatar3dOffer.modelUrl
+
+```ts
+readonly modelUrl: string
+```
+
+The avatar's model, for a preview. Pass it through `platformIconUrl`
+before loading it.
+
+<a id="avatar3doffer-prices"></a>
+
+## Avatar3dOffer.prices
+
+```ts
+readonly prices: readonly Avatar3dPrice[]
+```
+
+One or two prices, each in a currency a player can pay with. Show each
+one the player can choose; pass the chosen one's `currencySlug` to
+[Avatars3dApi.purchase](#avatars3dapi-purchase).
+
+<a id="avatars3dapi"></a>
+
+## Avatars3dApi
+
+```ts
+interface Avatars3dApi
+```
+
+Arcade 3D avatars — `gem.avatars3d`. What the player wears, the rig families
+your game accepts, the avatars you sell, and buying one.
+
+```js
+function draw() {
+  const worn = gem.avatars3d.worn();
+  if (worn) loadCharacter(platformIconUrl(worn.modelUrl));
+  else useDefaultCharacter();
+}
+draw();
+gem.avatars3d.onChange(draw);
+```
+
+The guide is `docs/arcade-avatars.md`: the rig, the config, uploading and
+selling with gemctl, and loading the model at runtime.
+
+<a id="avatars3dapi-families"></a>
+
+## Avatars3dApi.families
+
+```ts
+families(): Promise<readonly Avatar3dFamily[]>
+```
+
+The rig families your game accepts, in the order your published config
+declares them (`avatars_3d.families`) — the first is your default.
+
+Resolves `[]` when your game has no published config on this channel, or
+its config declares no families. Loads the config through
+`gem.gameConfig.load()` and shares that one fetch; rejects when the config
+cannot be loaded, as `load()` does.
+
+<a id="avatars3dapi-worn"></a>
+
+## Avatars3dApi.worn
+
+```ts
+worn(family?: Avatar3dFamily): WornAvatar3d | undefined
+```
+
+The 3D avatar the player wears — in `family` when you name one, otherwise
+in your game's first declared family that has one. `undefined` when none
+is worn there, before the player arrives, and outside the Arcade: draw
+your default look.
+
+Read live from [Gem.player](#gem-player), so it changes when the player wears
+another avatar or buys one; [Avatars3dApi.onChange](#avatars3dapi-onchange) tells you when.
+
+| Parameter | Type |
+| --- | --- |
+| `family` | `Avatar3dFamily` |
+
+<a id="avatars3dapi-offers"></a>
+
+## Avatars3dApi.offers
+
+```ts
+offers(): Promise<readonly Avatar3dOffer[]>
+```
+
+Your game's 3D avatars on sale on this channel, with their prices, read
+from the platform with your game's own token. Render your shop from this,
+never from prices of your own.
+
+Resolves `[]` when you have nothing on sale. Rejects with a `GemApiError`
+when the platform cannot be read — a shop that cannot load says so.
+
+<a id="avatars3dapi-purchase"></a>
+
+## Avatars3dApi.purchase
+
+```ts
+purchase(request: Avatar3dPurchaseRequest): Promise<PurchaseOutcome>
+```
+
+Buy one of your 3D avatars for the player and put it on. The Arcade
+prices it again, shows its own confirmation sheet, takes the currency and
+wears the avatar; your game then receives the player again, with the new
+avatar worn, and [Avatars3dApi.onChange](#avatars3dapi-onchange) runs.
+
+Call it from the player's own click or key press — the Arcade shows no
+sheet without one and answers `declined` / `busy`.
+
+NOTHING REJECTS. Every outcome resolves, exactly as on
+`gem.purchases.request`:
+
+- `ok` — bought and worn, and the platform confirmed the player owns it.
+- `declined` — definitely not bought. `reason` says why:
+  `already_owned` (the player has it — offer to wear it with
+  `gem.openAvatarPicker({ tab: '3d' })`), `cancelled`, `insufficient_funds`,
+  `no_price_in_currency`, `not_purchasable` (not on sale, or not an id from
+  [Avatars3dApi.offers](#avatars3dapi-offers)), `busy`, and the rest of
+  `PurchaseRefusalCode`. Return to your shop silently.
+- `unavailable` — no reliable answer. Show one neutral message, never
+  retry on your own, and read [Avatars3dApi.worn](#avatars3dapi-worn) again.
+
+**Outside the Arcade** — opened at the top level of a page with no Arcade
+around it, or under an Arcade that does not sell 3D avatars yet — it
+resolves `unavailable` with reason `error` at once and asks nobody.
+
+| Parameter | Type |
+| --- | --- |
+| `request` | `Avatar3dPurchaseRequest` |
+
+<a id="avatars3dapi-onchange"></a>
+
+## Avatars3dApi.onChange
+
+```ts
+onChange(listener: (worn: readonly WornAvatar3d[]) => void): () => void
+```
+
+Call `listener` whenever the avatars the player wears change — they wore
+another one in the Arcade's picker, bought one, or their avatars arrived
+for the first time — with every worn avatar, one per family. Not called
+for the avatars already worn when you subscribe: read
+[Avatars3dApi.worn](#avatars3dapi-worn) for those.
+
+| Parameter | Type |
+| --- | --- |
+| `listener` | `(worn: readonly WornAvatar3d[]) => void` |
+
+**Returns.** a function that stops the calls. Calling it twice is harmless.
+
+<a id="avatarrignode"></a>
+
+## AvatarRigNode
+
+```ts
+interface AvatarRigNode
+```
+
+One node of a rig family's tree: its exact, case-sensitive name, and the
+name of the node it is a DIRECT child of. `parent` is `null` for the rig's
+root, which is a root node of the scene.
+
+<a id="avatarrignode-node"></a>
+
+## AvatarRigNode.node
+
+```ts
+readonly node: string
+```
+
+The node's name, exact and case-sensitive.
+
+<a id="avatarrignode-parent"></a>
+
+## AvatarRigNode.parent
+
+```ts
+readonly parent: string | null
+```
+
+The node it is a direct child of; `null` for the rig's root.
+
+<a id="avatarrigs"></a>
+
+## AvatarRigs
+
+```ts
+interface AvatarRigs
+```
+
+The rig families this SDK knows, by name.
+
+<a id="avatarrigs-small_human"></a>
+
+## AvatarRigs.small_human
+
+```ts
+readonly small_human: readonly AvatarRigNode[]
+```
+
+The toy rig: rigid limbs on a body, eight nodes.
+
+<a id="avatarrigs-adult_human"></a>
+
+## AvatarRigs.adult_human
+
+```ts
+readonly adult_human: readonly AvatarRigNode[]
+```
+
+The adult humanoid with fingers: 56 nodes, world-aligned at rest.
+
+<a id="avatar_rigs"></a>
+
+## AVATAR_RIGS
+
+```ts
+AVATAR_RIGS: AvatarRigs
+```
+
+Every node each rig family requires, with the node it is a direct child of,
+parents before children. Frozen: read it, never change it.
+
+The platform refuses an upload whose model is missing one of these, has one
+under another parent, or has one twice (`rig_mismatch`). Extra nodes are
+allowed anywhere. `adult_human` also requires every one of its nodes to be
+world-aligned at rest; that rule is not in this list, see the guide.
+
+```js
+import { AVATAR_RIGS } from '@indiegems/gem-web-sdk/sdk';
+
+// Every joint of the worn avatar, by name.
+const joints = new Map(
+  AVATAR_RIGS.adult_human.map(({ node }) => [node, gltf.scene.getObjectByName(node)]),
+);
+
+// A test that one of your own models is on the rig.
+for (const { node, parent } of AVATAR_RIGS.adult_human) {
+  const found = gltf.scene.getObjectByName(node);
+  if (!found) throw new Error(`missing ${node}`);
+  if (parent !== null && found.parent?.name !== parent) throw new Error(`${node} is not under ${parent}`);
+}
+```
+
 <a id="gemapierror"></a>
 
 ## GemApiError
@@ -4851,50 +5201,11 @@ a key you leave out is unchanged.
 interface ControlsApi
 ```
 
-`gem.controls` — the player's camera and controls settings: tell the Arcade
-which ones your game leaves to the player, and turn look input into a camera
-turn at the player's sensitivity.
+`gem.controls` — the player's camera and controls settings: turn look input
+into a camera turn at the player's sensitivity.
 
 **Guides.** [what-a-game-must-do](../what-a-game-must-do.md)
 
-<a id="controlsapi-declare"></a>
-
-## ControlsApi.declare
-
-```ts
-declare(uses: GemControlsDeclaration): boolean
-```
-
-Tell the Arcade which of the player's camera and controls settings your
-game uses, and for each one who decides it: `'player'` — you apply the
-Arcade's value from `gem.prefs.recommended` (or the player's own choice
-in your settings, which wins) — or `'game'` — you decide it yourself, and
-the Arcade's Settings shows that row as "Set by this game". Leave out a
-setting your game does not use.
-
-```js
-gem.controls.declare({
-  lookSensitivity: 'player',
-  gamepadLookSensitivity: 'player',
-  invertLookY: 'player',
-  touchMovement: 'game', // this game always uses a fixed stick
-});
-```
-
-**It is screen state, not a toggle.** Each call is the whole answer and
-replaces the last. The SDK holds it and sends it again after every
-reconnect, so call it once at boot, and again only when the answer
-changes. Any other key or value is dropped.
-
-| Parameter | Type |
-| --- | --- |
-| `uses` | `GemControlsDeclaration` |
-
-**Returns.** `true` when the Arcade was told now; `false` before the bridge is
-  up (the declaration is held and sent when it connects), outside the
-  Arcade, and under an embedder that does not show these settings. Never
-  throws.
-
 <a id="controlsapi-look"></a>
 
 ## ControlsApi.look
@@ -4937,72 +5248,6 @@ readonly LOOK_BASE: GemLookBase
 
 The base speeds `look` applies at 1×, in radians. Frozen.
 
-<a id="gemcontrolchoice"></a>
-
-## GemControlChoice
-
-```ts
-type GemControlChoice = "player" | "game"
-```
-
-Who decides one camera or controls setting: `'player'` — your game applies
-the Arcade's value, or the player's own in-game choice, which wins — or
-`'game'` — your game decides it itself, and the Arcade's Settings shows the
-row as "Set by this game".
-
-<a id="gemcontrolsdeclaration"></a>
-
-## GemControlsDeclaration
-
-```ts
-interface GemControlsDeclaration
-```
-
-What `gem.controls.declare` takes: for each of the player's camera and
-controls settings your game uses, who decides it. Leave a setting out when
-your game does not use it at all — the Arcade then says "This game doesn't
-use this" beside that row.
-
-<a id="gemcontrolsdeclaration-looksensitivity"></a>
-
-## GemControlsDeclaration.lookSensitivity
-
-```ts
-readonly lookSensitivity?: GemControlChoice
-```
-
-Look speed for touch, mouse and pen — `gem.prefs.recommended.lookSensitivity`.
-
-<a id="gemcontrolsdeclaration-gamepadlooksensitivity"></a>
-
-## GemControlsDeclaration.gamepadLookSensitivity
-
-```ts
-readonly gamepadLookSensitivity?: GemControlChoice
-```
-
-Look speed for a gamepad stick — `gem.prefs.recommended.gamepadLookSensitivity`.
-
-<a id="gemcontrolsdeclaration-invertlooky"></a>
-
-## GemControlsDeclaration.invertLookY
-
-```ts
-readonly invertLookY?: GemControlChoice
-```
-
-Inverted up/down look — `gem.prefs.recommended.invertLookY`.
-
-<a id="gemcontrolsdeclaration-touchmovement"></a>
-
-## GemControlsDeclaration.touchMovement
-
-```ts
-readonly touchMovement?: GemControlChoice
-```
-
-The touch movement thumbstick, floating or fixed — `gem.prefs.recommended.touchMovement`.
-
 <a id="device_settings_max_bytes"></a>
 
 ## DEVICE_SETTINGS_MAX_BYTES
@@ -5196,7 +5441,7 @@ interface RewardCue
 ```
 
 A platform-currency reward on its way to the arcade — in the Gem Arcade, a
-flight into the Gem button at the top-left of your frame — what
+flight into the Gem button, in whichever corner of your frame it sits — what
 `gem.cueReward` takes.
 
 <a id="rewardcue-currencyslug"></a>
@@ -5257,6 +5502,18 @@ y: number
 
 From the top edge of your viewport.
 
+<a id="gemcorner"></a>
+
+## GemCorner
+
+```ts
+type GemCorner = "top-left" | "top-right" | "bottom-left" | "bottom-right"
+```
+
+A corner of your frame, for `gem.setGemCorner`: where you would like the
+arcade's Gem button to sit. `'top-left'` is where it sits unless you ask.
+Physical corners: `'top-left'` is the top-left in every language.
+
 <a id="framestate"></a>
 
 ## FrameState
@@ -5563,53 +5820,52 @@ wallet.
 **Returns.** whether the message left the frame — `false` before the bridge is
   up, for an arcade with no wallet, and past this frame's own limit.
 
-<a id="gemframe-declarecontrols"></a>
+<a id="gemframe-setmenu"></a>
 
-## GemFrame.declareControls
+## GemFrame.setMenu
 
 ```ts
-declareControls(uses: GemControlsDeclaration): boolean
+setMenu(items?: readonly { id: string; label: string }[]): boolean
 ```
 
-Tell the arcade which of the player's camera and controls settings your
-game leaves to the player and which it decides itself — the whole answer
-each time, the latest one winning.
+Tell the arcade what your game adds to its menu: up to four entries of its
+own — the whole answer each time, the latest one winning. Your settings
+are not among them: a game opens its settings from its own button.
 
-Prefer `gem.controls.declare`, which holds the declaration across a
-reconnect. This one sends only while connected, and only to an arcade
-that shows these settings.
+Prefer `gem.setMenu`, which holds the state across a reconnect and calls
+your handlers when the player chooses an entry. This one sends only while
+connected, and only to an arcade that draws a menu.
 
 | Parameter | Type |
 | --- | --- |
-| `uses` | `GemControlsDeclaration` |
+| `items` | `readonly { id: string; label: string }[]` |
 
 **Returns.** whether the message left the frame — `false` before the bridge is
-  up, for an arcade that does not show these settings, and past this
-  frame's own limit.
+  up, for an arcade with no menu, and past this frame's own limit.
 
-<a id="gemframe-setmenu"></a>
+<a id="gemframe-setgemcorner"></a>
 
-## GemFrame.setMenu
+## GemFrame.setGemCorner
 
 ```ts
-setMenu(settings: boolean, items?: readonly { id: string; label: string }[]): boolean
+setGemCorner(corner: GemCorner): boolean
 ```
 
-Tell the arcade what your game adds to its menu: whether it has a settings
-screen, and up to four entries of its own — the whole answer each time, the
-latest one winning.
+Ask the arcade to put its own control over your game — the Gem button —
+in this corner of your frame: the whole answer each time, the latest one
+winning.
 
-Prefer `gem.setMenu`, which holds the state across a reconnect and calls
-your handlers when the player chooses an entry. This one sends only while
-connected, and only to an arcade that draws a menu.
+Prefer `gem.setGemCorner`, which holds the corner across a reconnect.
+This one sends only while connected, and only to an arcade that can move
+its control.
 
 | Parameter | Type |
 | --- | --- |
-| `settings` | `boolean` |
-| `items` | `readonly { id: string; label: string }[]` |
+| `corner` | `GemCorner` |
 
 **Returns.** whether the message left the frame — `false` before the bridge is
-  up, for an arcade with no menu, and past this frame's own limit.
+  up, for an arcade that cannot move its control, for a value that is not
+  one of the four corners, and past this frame's own limit.
 
 <a id="gemframe-requestshare"></a>
 
@@ -5860,6 +6116,24 @@ loading the model is too much. Not the 2D portrait
 ([PlayerIdentity.avatarIconUrl](#playeridentity-avatariconurl)), which is a separate choice. Pass it
 through [platformIconUrl](#platformiconurl) before putting it in an `<img src>`.
 
+<a id="friend-avatars3d"></a>
+
+## Friend.avatars3d
+
+```ts
+readonly avatars3d?: readonly WornAvatar3d[]
+```
+
+Every 3D avatar the player wears, one per rig family, in the order the game
+declared its families. Absent or empty means none is worn — draw your
+default look.
+
+[PlayerIdentity.avatar3dId](#playeridentity-avatar3did) and its two URLs are one of these: the
+avatar of the game's first declared family that has one. A game that
+accepts a single family can read either; one that accepts several picks by
+`family` here. Absent too where the platform does not send it yet — read
+the flat fields then.
+
 <a id="friend-badges"></a>
 
 ## Friend.badges
@@ -7721,6 +7995,24 @@ loading the model is too much. Not the 2D portrait
 ([PlayerIdentity.avatarIconUrl](#playeridentity-avatariconurl)), which is a separate choice. Pass it
 through [platformIconUrl](#platformiconurl) before putting it in an `<img src>`.
 
+<a id="gemplayer-avatars3d"></a>
+
+## GemPlayer.avatars3d
+
+```ts
+readonly avatars3d?: readonly WornAvatar3d[]
+```
+
+Every 3D avatar the player wears, one per rig family, in the order the game
+declared its families. Absent or empty means none is worn — draw your
+default look.
+
+[PlayerIdentity.avatar3dId](#playeridentity-avatar3did) and its two URLs are one of these: the
+avatar of the game's first declared family that has one. A game that
+accepts a single family can read either; one that accepts several picks by
+`family` here. Absent too where the platform does not send it yet — read
+the flat fields then.
+
 <a id="gemplayer-badges"></a>
 
 ## GemPlayer.badges
@@ -8141,7 +8433,7 @@ readonly reserved: readonly GemReservedArea[]
 ```
 
 Rectangles of your frame the arcade's own controls cover — in the Gem
-Arcade, its Gem button in the top-left corner, and the frame-rate readout
+Arcade, its Gem button in whichever corner it sits, and the frame-rate readout
 beside it while the player shows it; an embedder that draws wallets over
 your game adds theirs (see `setWalletVisible`). Keep essential UI and touch
 targets out of them. Empty when the arcade covers nothing.
@@ -8279,20 +8571,8 @@ and your game is running again by the time this fires.
 interface GameMenu
 ```
 
-What your game adds to the arcade's menu — see `gem.setMenu`.
-
-<a id="gamemenu-onsettings"></a>
-
-## GameMenu.onSettings
-
-```ts
-readonly onSettings?: () => void
-```
-
-Open your settings screen. Another embedder may show a Settings entry that
-calls it, but **the Gem Arcade no longer does**: draw a settings button of
-your own, always (top-right is the recommendation). Passing this is still
-accepted and harmless.
+What your game adds to the arcade's menu — see `gem.setMenu`. Your settings
+are not part of it: they open from your own settings button.
 
 <a id="gamemenu-items"></a>
 
@@ -8830,6 +9110,32 @@ client sends.
   up, under an embedder with no avatar picker, or past six asks a minute.
   It never throws and never waits.
 
+<a id="gem-avatars3d"></a>
+
+## Gem.avatars3d
+
+```ts
+readonly avatars3d: Avatars3dApi
+```
+
+Arcade 3D avatars: what the player wears, the rig families your game
+accepts, the avatars your game sells, and buying one — which wears it.
+2D portraits are a separate system and are not here.
+
+```js
+const draw = () => {
+  const worn = gem.avatars3d.worn();
+  const url = worn && platformIconUrl(worn.modelUrl);
+  if (url) loadCharacter(url);
+  else useDefaultCharacter();
+};
+draw();
+gem.avatars3d.onChange(draw);
+```
+
+See [Arcade avatars](../arcade-avatars.md) for the rig, the config, and
+uploading and selling avatars with gemctl.
+
 <a id="gem-vibration"></a>
 
 ## Gem.vibration
@@ -8874,13 +9180,10 @@ readonly controls: ControlsApi
 
 The player's camera and controls settings — look sensitivity, gamepad look
 sensitivity, invert look and touch movement, which arrive in
-`gem.prefs.recommended`. Two things to do with them:
+`gem.prefs.recommended` as the player's Arcade-wide defaults. Turn look
+input into a camera turn at the player's sensitivity:
 
 ```js
-// 1. Tell the Arcade which ones your game leaves to the player.
-gem.controls.declare({ lookSensitivity: 'player', invertLookY: 'player' });
-
-// 2. Turn look input into a camera turn at the player's sensitivity.
 const look = gem.controls.look();
 // dx, dy: the pointer's move in CSS px since the last event.
 const t = look.fromPointer(dx, dy, e.pointerType, camera.pitch);
@@ -9257,7 +9560,7 @@ cueReward(cue: RewardCue): boolean
 
 Tell the arcade a platform-currency reward is on its way, so it **shows it
 landing**: in the Gem Arcade the currency flies from `origin` into the Gem
-button at the top-left of your frame, which pops as each mark lands, and
+button, wherever on your frame it sits, which pops as each mark lands, and
 the player's total moves once the platform confirms the grant. The Gem
 Arcade draws no wallet over your game: the player sees their Gems and
 Tickets in the Gem menu. A payout you do not cue still flies, from the
@@ -9359,10 +9662,9 @@ gem.setMenu({
 ```
 
 **Your settings are not in it: draw your own settings button, always** —
-top-right is the recommendation. `onSettings` is still accepted, and
-another embedder may show an entry for it, but the Gem Arcade no longer
-shows a Settings entry, so a game whose settings open only from there has
-none a player can reach.
+top-right, with your Back button just to its left, clear of
+`gem.viewport.reserved`. The Arcade's menu never opens your settings
+screen.
 
 **It is screen state, not a toggle.** Each call is the whole answer and
 replaces the last, so call it again when the entries change — a new
@@ -9376,12 +9678,52 @@ should not assume the game was paused by you.
 
 | Parameter | Type | Description |
 | --- | --- | --- |
-| `menu` | `GameMenu` | Your settings handler and your own entries. |
+| `menu` | `GameMenu` | Your own entries. |
 
 **Returns.** `true` when the arcade was told now; `false` before the bridge is
   up (the menu is held and sent when it connects) and under an embedder
   that draws no menu.
 
+<a id="gem-setgemcorner"></a>
+
+## Gem.setGemCorner
+
+```ts
+setGemCorner(corner: GemCorner): boolean
+```
+
+Ask the arcade to put its Gem button — its one control over your game,
+top-left unless you ask — in another corner of your frame.
+
+```js
+// This game's own HUD needs the top-left, so the Gem goes top-right.
+gem.setGemCorner('top-right');
+```
+
+**Leave it top-left unless your own HUD needs that corner**, and then pick
+one corner for the whole game — at most one per orientation. A Gem that
+moves between screens is a way out the player has to look for. In
+landscape the bottom corners sit where a player's thumbs hold the sticks.
+
+**Lay out around `gem.viewport.reserved`, never around the corner you
+asked for.** The arcade moves the Gem on its own terms: not while the
+player is using it or its menu is open, not more often than every few
+seconds, and never over a corner the player chose for themselves. The
+rectangles say where it actually is, and the `--gem-reserved-*` CSS
+properties follow them.
+
+**It is screen state, not a toggle.** Each call is the whole answer and
+replaces the last. A value that is not one of the four corners is ignored,
+with a warning on the console, and changes nothing.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `corner` | `GemCorner` | `'top-left'`, `'top-right'`, `'bottom-left'` or `'bottom-right'`. |
+
+**Returns.** `true` when the arcade was told now; `false` before the bridge is
+  up (the corner is held and sent when it connects), under an embedder that
+  cannot move its control, and for a value that is not a corner.
+
 <a id="gem-exit"></a>
 
 ## Gem.exit
@@ -10181,7 +10523,7 @@ The match this connection belongs to.
 ## MatchConnection.protocol
 
 ```ts
-readonly protocol: "dedicated" | "p2p" | "loopback"
+readonly protocol: "p2p" | "dedicated" | "loopback"
 ```
 
 What is on the other end: `dedicated` (the platform's server), `p2p` (the
@@ -10368,6 +10710,84 @@ readonly iconUrl: string
 The badge's thumbnail. Pass it through [platformIconUrl](#platformiconurl) before
 putting it in an `<img src>`.
 
+<a id="avatar3dfamily"></a>
+
+## Avatar3dFamily
+
+```ts
+type Avatar3dFamily = "small_human" | "adult_human" | string & object
+```
+
+A rig family — the skeleton contract a 3D avatar is built on, and what a
+game declares it can animate. Two today:
+
+- `small_human`, the toy rig: a `root` node with a `body` child, which holds
+  `head`, `arm_l`, `arm_r`, `leg_l` and `leg_r`, and a `hand_socket` under
+  `arm_r`.
+- `adult_human`, a full humanoid with fingers: 56 nodes from `root` and
+  `hips` down to `toes_r`, every one world-aligned at rest, so one clip plays
+  on every avatar in the family.
+
+`AVATAR_RIGS` (from `@indiegems/gem-web-sdk/sdk`) lists every node of
+both, with its parent.
+
+Open-ended (`| (string & {})`) so a family the platform adds later does not
+break a `switch` you compiled against this version: keep a `default` arm and
+skip a family you do not draw.
+
+<a id="wornavatar3d"></a>
+
+## WornAvatar3d
+
+```ts
+interface WornAvatar3d
+```
+
+One 3D avatar a player wears — at most one per [Avatar3dFamily](#avatar3dfamily).
+
+<a id="wornavatar3d-family"></a>
+
+## WornAvatar3d.family
+
+```ts
+readonly family: Avatar3dFamily
+```
+
+The rig family this avatar is built on.
+
+<a id="wornavatar3d-id"></a>
+
+## WornAvatar3d.id
+
+```ts
+readonly id: string
+```
+
+The avatar's item id — a stable key for the model, never something to
+show as text.
+
+<a id="wornavatar3d-modelurl"></a>
+
+## WornAvatar3d.modelUrl
+
+```ts
+readonly modelUrl: string
+```
+
+The avatar's model, a binary glTF (`.glb`) on the family's rig. Pass it
+through [platformIconUrl](#platformiconurl) before loading it.
+
+<a id="wornavatar3d-iconurl"></a>
+
+## WornAvatar3d.iconUrl
+
+```ts
+readonly iconUrl: string
+```
+
+A rendered portrait of the avatar, for a roster or a menu. Pass it through
+[platformIconUrl](#platformiconurl) before putting it in an `<img src>`.
+
 <a id="playeridentity"></a>
 
 ## PlayerIdentity
@@ -10511,6 +10931,24 @@ loading the model is too much. Not the 2D portrait
 ([PlayerIdentity.avatarIconUrl](#playeridentity-avatariconurl)), which is a separate choice. Pass it
 through [platformIconUrl](#platformiconurl) before putting it in an `<img src>`.
 
+<a id="playeridentity-avatars3d"></a>
+
+## PlayerIdentity.avatars3d
+
+```ts
+readonly avatars3d?: readonly WornAvatar3d[]
+```
+
+Every 3D avatar the player wears, one per rig family, in the order the game
+declared its families. Absent or empty means none is worn — draw your
+default look.
+
+[PlayerIdentity.avatar3dId](#playeridentity-avatar3did) and its two URLs are one of these: the
+avatar of the game's first declared family that has one. A game that
+accepts a single family can read either; one that accepts several picks by
+`family` here. Absent too where the platform does not send it yet — read
+the flat fields then.
+
 <a id="playeridentity-badges"></a>
 
 ## PlayerIdentity.badges
@@ -10550,7 +10988,7 @@ for (const row of opponents) {
 
 Reads `player_id`, `display_name`, `discriminator`, `display_tag`,
 `avatar_icon_id`, `avatar_icon_url`, `avatar_3d_id`, `avatar_3d_model_url`,
-`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.
+`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.
 
 | Parameter | Type |
 | --- | --- |
@@ -11810,12 +12248,44 @@ a Buy button mostly does not write one.
 | --- | --- |
 | `req` | `PurchaseRequest` |
 
+<a id="avatar3dpurchaserequest"></a>
+
+## Avatar3dPurchaseRequest
+
+```ts
+interface Avatar3dPurchaseRequest
+```
+
+What a game asks for when it buys one of its own 3D avatars for the player
+with `gem.avatars3d.purchase`.
+
+<a id="avatar3dpurchaserequest-itemid"></a>
+
+## Avatar3dPurchaseRequest.itemId
+
+```ts
+itemId: string
+```
+
+The avatar's item id — `itemId` on an `Avatar3dOffer`.
+
+<a id="avatar3dpurchaserequest-currencyslug"></a>
+
+## Avatar3dPurchaseRequest.currencySlug
+
+```ts
+currencySlug: string
+```
+
+The platform currency to pay in, `GEMS` or `ARCADE_TICKETS`. The offer
+must carry a price in it.
+
 <a id="purchaserefusalcode"></a>
 
 ## PurchaseRefusalCode
 
 ```ts
-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"
+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"
 ```
 
 Every reason a purchase can be refused, on either purchase path.
@@ -11841,6 +12311,9 @@ Every reason a purchase can be refused, on either purchase path.
 - `not_available` — the recipe is outside its availability window, or
   inactive; nothing was charged. Hide or disable it until its window opens.
 - `recipe_locked` — the recipe's prerequisites are not met.
+- `already_owned` — the player already owns the 3D avatar
+  `gem.avatars3d.purchase` asked for; nothing was charged. Only that call
+  answers it.
 - `recipe_on_cooldown`, `recipe_max_uses_exceeded`, `item_max_stack_exceeded`,
   `recipe_costs_unmet`, `quantity_invalid` — the recipe or item refused this
   purchase, before any charge.
@@ -13127,6 +13600,24 @@ loading the model is too much. Not the 2D portrait
 ([PlayerIdentity.avatarIconUrl](#playeridentity-avatariconurl)), which is a separate choice. Pass it
 through [platformIconUrl](#platformiconurl) before putting it in an `<img src>`.
 
+<a id="leaderboardentry-avatars3d"></a>
+
+## LeaderboardEntry.avatars3d
+
+```ts
+readonly avatars3d?: readonly WornAvatar3d[]
+```
+
+Every 3D avatar the player wears, one per rig family, in the order the game
+declared its families. Absent or empty means none is worn — draw your
+default look.
+
+[PlayerIdentity.avatar3dId](#playeridentity-avatar3did) and its two URLs are one of these: the
+avatar of the game's first declared family that has one. A game that
+accepts a single family can read either; one that accepts several picks by
+`family` here. Absent too where the platform does not send it yet — read
+the flat fields then.
+
 <a id="leaderboardentry-badges"></a>
 
 ## LeaderboardEntry.badges
@@ -14620,6 +15111,24 @@ loading the model is too much. Not the 2D portrait
 ([PlayerIdentity.avatarIconUrl](#playeridentity-avatariconurl)), which is a separate choice. Pass it
 through [platformIconUrl](#platformiconurl) before putting it in an `<img src>`.
 
+<a id="playerprofile-avatars3d"></a>
+
+## PlayerProfile.avatars3d
+
+```ts
+readonly avatars3d?: readonly WornAvatar3d[]
+```
+
+Every 3D avatar the player wears, one per rig family, in the order the game
+declared its families. Absent or empty means none is worn — draw your
+default look.
+
+[PlayerIdentity.avatar3dId](#playeridentity-avatar3did) and its two URLs are one of these: the
+avatar of the game's first declared family that has one. A game that
+accepts a single family can read either; one that accepts several picks by
+`family` here. Absent too where the platform does not send it yet — read
+the flat fields then.
+
 <a id="playerprofile-badges"></a>
 
 ## PlayerProfile.badges
@@ -17206,6 +17715,24 @@ loading the model is too much. Not the 2D portrait
 ([PlayerIdentity.avatarIconUrl](#playeridentity-avatariconurl)), which is a separate choice. Pass it
 through [platformIconUrl](#platformiconurl) before putting it in an `<img src>`.
 
+<a id="roommember-avatars3d"></a>
+
+## RoomMember.avatars3d
+
+```ts
+readonly avatars3d?: readonly WornAvatar3d[]
+```
+
+Every 3D avatar the player wears, one per rig family, in the order the game
+declared its families. Absent or empty means none is worn — draw your
+default look.
+
+[PlayerIdentity.avatar3dId](#playeridentity-avatar3did) and its two URLs are one of these: the
+avatar of the game's first declared family that has one. A game that
+accepts a single family can read either; one that accepts several picks by
+`family` here. Absent too where the platform does not send it yet — read
+the flat fields then.
+
 <a id="roommember-badges"></a>
 
 ## RoomMember.badges
@@ -18036,6 +18563,24 @@ loading the model is too much. Not the 2D portrait
 ([PlayerIdentity.avatarIconUrl](#playeridentity-avatariconurl)), which is a separate choice. Pass it
 through [platformIconUrl](#platformiconurl) before putting it in an `<img src>`.
 
+<a id="showcasefriendentry-avatars3d"></a>
+
+## ShowcaseFriendEntry.avatars3d
+
+```ts
+readonly avatars3d?: readonly WornAvatar3d[]
+```
+
+Every 3D avatar the player wears, one per rig family, in the order the game
+declared its families. Absent or empty means none is worn — draw your
+default look.
+
+[PlayerIdentity.avatar3dId](#playeridentity-avatar3did) and its two URLs are one of these: the
+avatar of the game's first declared family that has one. A game that
+accepts a single family can read either; one that accepts several picks by
+`family` here. Absent too where the platform does not send it yet — read
+the flat fields then.
+
 <a id="showcasefriendentry-badges"></a>
 
 ## ShowcaseFriendEntry.badges