@indiegems/gem-web-sdk 11.1.2 → 13.0.0

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v11.1.2, 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.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.
 
 `@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,262 @@ 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="gemapierror"></a>
 
 ## GemApiError
@@ -3832,8 +4088,10 @@ the callback instead.
 
 - `ready` — a usable token is held.
 - `pending` — no token yet, or one is being fetched.
-- `degraded` — the last attempt failed but another may succeed. Keep playing;
-  a retry is worthwhile.
+- `degraded` — the last attempt failed but another may succeed, and the SDK
+  makes it on its own: once any wait the platform named has passed, or
+  otherwise at growing intervals of up to a minute. Keep playing. `ready`
+  follows when an attempt succeeds, with no call of yours needed to cause it.
 - `lost` — terminal for this session. Signing back in is the only way
   forward, and retrying will not produce one.
 
@@ -4849,50 +5107,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
@@ -4935,72 +5154,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
@@ -5561,41 +5714,17 @@ 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>
-
-## GemFrame.declareControls
-
-```ts
-declareControls(uses: GemControlsDeclaration): 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.
-
-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.
-
-| Parameter | Type |
-| --- | --- |
-| `uses` | `GemControlsDeclaration` |
-
-**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.
-
 <a id="gemframe-setmenu"></a>
 
 ## GemFrame.setMenu
 
 ```ts
-setMenu(settings: boolean, items?: readonly { id: string; label: string }[]): boolean
+setMenu(items?: readonly { id: string; label: string }[]): 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.
+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.setMenu`, which holds the state across a reconnect and calls
 your handlers when the player chooses an entry. This one sends only while
@@ -5603,7 +5732,6 @@ connected, and only to an arcade that draws a menu.
 
 | Parameter | Type |
 | --- | --- |
-| `settings` | `boolean` |
 | `items` | `readonly { id: string; label: string }[]` |
 
 **Returns.** whether the message left the frame — `false` before the bridge is
@@ -5858,6 +5986,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
@@ -7719,6 +7865,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
@@ -8277,20 +8441,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>
 
@@ -8828,6 +8980,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
@@ -8872,13 +9050,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);
@@ -9357,10 +9532,8 @@ 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, 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
@@ -9374,7 +9547,7 @@ 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
@@ -10366,6 +10539,76 @@ 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" | string & object
+```
+
+A rig family — the skeleton contract a 3D avatar is built on, and what a
+game declares it can animate. `small_human` is the first: 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`.
+
+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
@@ -10509,6 +10752,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
@@ -10548,7 +10809,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 |
 | --- | --- |
@@ -11808,12 +12069,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.
@@ -11839,6 +12132,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.
@@ -13125,6 +13421,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
@@ -14618,6 +14932,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
@@ -15307,6 +15639,36 @@ room. A double fire — the push and the reconcile landing together, or the
 event arriving just as the player presses your own button — costs one
 redundant request and never a second seat.
 
+<a id="roomeventmap-partyqueued"></a>
+
+## RoomEventMap.partyQueued
+
+```ts
+partyQueued: [PartyTicket]
+```
+
+This player's party is queued for a match: its leader called
+`queueForMatch`, and this player is on that ticket.
+
+The ticket is a view — show a searching screen from it, and await its
+`outcome` to take the screen down. It has no `cancel()`: the ticket is
+the leader's.
+
+```js
+gem.rooms.on('partyQueued', async (ticket) => {
+  showSearching({ canCancel: false });
+  const outcome = await ticket.outcome;
+  if (outcome.status !== 'matched') backToMenu(outcome.status);
+});
+```
+
+When the outcome is `matched` the room arrives as `seated`, as it does
+for any seat this player's party was given.
+
+NOT RAISED FOR THE PLAYER WHO QUEUED — they hold the ticket itself — and
+not raised at all under an arcade page that does not relay ticket
+events. See [PartyTicket](#partyticket).
+
 <a id="roomeventmap-listed"></a>
 
 ## RoomEventMap.listed
@@ -16125,6 +16487,25 @@ Set from the moment [RoomManager.queueForMatch](#roommanager-queueformatch) answ
 ticket ends — so it is `null` again by the time a matched ticket's room is
 [RoomManager.currentRoom](#roommanager-currentroom).
 
+<a id="roommanager-partyticket"></a>
+
+## RoomManager.partyTicket
+
+```ts
+readonly partyTicket: PartyTicket | null
+```
+
+The matchmaking ticket this player's PARTY is waiting on, or `null` — a
+ticket this game did not create, which it can show and cannot cancel.
+
+Set when the arcade page reports that the party's leader queued, and
+`null` again once that ticket ends. Never set beside
+[RoomManager.currentTicket](#roommanager-currentticket): the player who queued holds that one.
+The `partyQueued` event is raised when this is set.
+
+Always `null` under a page that does not relay ticket events. See
+[PartyTicket](#partyticket).
+
 <a id="roommanager-currentmatch"></a>
 
 ## RoomManager.currentMatch
@@ -16549,6 +16930,143 @@ Safe to call more than once, and after the ticket has ended.
 
 **Returns.** The same promise as [MatchTicket.outcome](#matchticket-outcome).
 
+<a id="partyticketstatus"></a>
+
+## PartyTicketStatus
+
+```ts
+type PartyTicketStatus = "queued" | "matched" | "expired" | "cancelled" | "failed" | "lost"
+```
+
+Where a party's ticket is, as far as this player's game has been told:
+`queued` while it waits, and anything else for good.
+
+- `matched` — the party is seated and the match is starting. The room arrives
+  as a `seated` event.
+- `expired` — it waited too long, or its owner's game stopped keeping it alive.
+- `cancelled` — the leader backed out, or the party changed.
+- `failed` — the platform formed a match and could not start it, repeatedly.
+- `lost` — nothing more was heard about it by the time it must have ended.
+
+<a id="partyticketoutcome"></a>
+
+## PartyTicketOutcome
+
+```ts
+type PartyTicketOutcome = { status: "matched" } | { status: "expired"; reason: string } | { status: "cancelled"; reason: string } | { status: "failed"; reason: string } | { status: "lost" }
+```
+
+How a party's ticket ended. Branch on `status`.
+
+`matched` CARRIES NO ROOM. The room is reported the way a party's seat always
+is — the `seated` event — and that is where a game joins it. The SDK looks
+for the seat the moment it hears `matched`.
+
+`reason` says why, where the platform gave one: `timed_out` or
+`heartbeat_lapsed` for `expired`, `requested` or `party_changed` for
+`cancelled`, `handoff_failed` for `failed`. Treat a value you do not
+recognise as the status alone.
+
+`lost` is the SDK's own ending, not the platform's: the ticket's lifetime
+ran out and no ending was heard. Whatever happened, the party is not
+waiting any more.
+
+<a id="partyticket"></a>
+
+## PartyTicket
+
+```ts
+interface PartyTicket
+```
+
+The matchmaking ticket this player's party is waiting on — a ticket this
+game did not create. What `gem.rooms.partyTicket` holds, and what the
+`partyQueued` event hands you.
+
+READ-ONLY, ON PURPOSE. There is no `cancel()`: a party is one ticket and it
+is its leader's to cancel. A player who wants out leaves the party, which
+ends the ticket for everyone.
+
+```js
+gem.rooms.on('partyQueued', async (ticket) => {
+  showSearching({ canCancel: false });
+  const outcome = await ticket.outcome;
+  if (outcome.status !== 'matched') backToMenu(outcome.status);
+  // `matched`: your `seated` handler has the room.
+});
+```
+
+ONLY WHERE THE ARCADE PAGE RELAYS IT. Under a page that does not, there is
+no party ticket and no `partyQueued`, and a member is carried into the match
+by `seated` with no lead-up. Build the searching screen as an extra, never
+as a step the match depends on.
+
+**Guides.** [rooms-and-matches](../rooms-and-matches.md)
+
+<a id="partyticket-id"></a>
+
+## PartyTicket.id
+
+```ts
+readonly id: string
+```
+
+The ticket's id. For logs and bug reports; nothing you call takes it.
+
+<a id="partyticket-status"></a>
+
+## PartyTicket.status
+
+```ts
+readonly status: PartyTicketStatus
+```
+
+Where the ticket is, as far as this game has been told. Changes once, from
+`queued` to how it ended.
+
+<a id="partyticket-partysize"></a>
+
+## PartyTicket.partySize
+
+```ts
+readonly partySize: number
+```
+
+How many players the ticket seats: the size of the party. 0 when the page
+did not say.
+
+<a id="partyticket-queuedat"></a>
+
+## PartyTicket.queuedAt
+
+```ts
+readonly queuedAt: number
+```
+
+When the ticket joined the queue, in Unix seconds. 0 when the page did not
+say.
+
+<a id="partyticket-expiresat"></a>
+
+## PartyTicket.expiresAt
+
+```ts
+readonly expiresAt: number
+```
+
+When the ticket gives up if it is still waiting, in Unix seconds. Good for
+a countdown. 0 when the page did not say.
+
+<a id="partyticket-outcome"></a>
+
+## PartyTicket.outcome
+
+```ts
+readonly outcome: Promise<PartyTicketOutcome>
+```
+
+How the ticket ends. Settles exactly once and never rejects.
+
 <a id="roomstatus"></a>
 
 ## RoomStatus
@@ -17018,6 +17536,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
@@ -17848,6 +18384,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