@indiegems/gem-web-sdk 10.3.1 → 11.0.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "10.3.1"
+    "version": "11.0.0"
   },
   "entries": [
     {
@@ -6632,11 +6632,18 @@
           "name": "requestAvatarPicker",
           "anchor": "gemframe-requestavatarpicker",
           "group": "frame",
-          "signature": "requestAvatarPicker(): boolean",
+          "signature": "requestAvatarPicker(tab?: \"2d\" | \"3d\"): boolean",
           "documented": true,
-          "summary": "Ask the arcade to open its own avatar picker over your game. Nothing comes\nback: a changed portrait arrives as a new `gem.player`, through `onPlayer`.\n\nPrefer `gem.openAvatarPicker`, which documents what a game does with the\nchange.",
+          "summary": "Ask the arcade to open its own avatar picker over your game. Nothing comes\nback: a changed portrait or 3D character arrives as a new `gem.player`,\nthrough `onPlayer`.\n\nPrefer `gem.openAvatarPicker`, which documents what a game does with the\nchange.",
           "deprecated": null,
-          "params": [],
+          "params": [
+            {
+              "name": "tab",
+              "type": "\"2d\" | \"3d\"",
+              "optional": true,
+              "summary": "Which tab to open on — `'2d'` (the portrait) or `'3d'` (the 3D\n  character). Omit it to let the arcade decide. Anything else is treated as\n  omitted. An arcade older than the tabs ignores it."
+            }
+          ],
           "returns": "whether the message left the frame — `false` before the bridge is\n  up, for an arcade that has no avatar picker here, and past this frame's\n  own limit of six a minute.",
           "throws": null,
           "example": null,
@@ -6824,6 +6831,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Friend.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "friend-avatar3did",
+          "group": "friends",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Friend.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "friend-avatar3dmodelurl",
+          "group": "friends",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "Friend.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "friend-avatar3diconurl",
+          "group": "friends",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Friend.badges",
           "name": "badges",
@@ -8594,6 +8649,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemPlayer.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "gemplayer-avatar3did",
+          "group": "player",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemPlayer.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "gemplayer-avatar3dmodelurl",
+          "group": "player",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemPlayer.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "gemplayer-avatar3diconurl",
+          "group": "player",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemPlayer.badges",
           "name": "badges",
@@ -8702,7 +8805,7 @@
           "group": "player",
           "signature": "readonly recommended: GemRecommendedSettings | null",
           "documented": true,
-          "summary": "The player's Arcade-wide defaults for this device — a volume, battery\nsaver, a keyboard layout, the gamepad's confirm button, vibration, and the\ncamera and controls settings (look sensitivity, gamepad look sensitivity,\ninvert look, touch movement) — or `null` when the Arcade did not send them.\n\n**Recommendations only; the player's own choice in your game wins.** Start\na setting from here while the player has made no choice of their own for\nit, and never overwrite one they made because this changed:\n\n```js\nconst saved = gem.deviceSettings.current ?? {};\nconst volume = saved.volume ?? gem.prefs?.recommended?.volume ?? 100;\n```\n\nUnlike `muted` and `reducedMotion`, nothing here is applied for you, and\nnothing obliges you to use it. See the guide's \"Game settings\" section.",
+          "summary": "The player's Arcade-wide defaults for this device — a volume, battery\nsaver, a keyboard layout, the gamepad's confirm button, vibration, the\ncamera and controls settings (look sensitivity, gamepad look sensitivity,\ninvert look, touch movement) and a starting graphics quality — or `null`\nwhen the Arcade did not send them.\n\n**Recommendations only; the player's own choice in your game wins.** Start\na setting from here while the player has made no choice of their own for\nit, and never overwrite one they made because this changed:\n\n```js\nconst saved = gem.deviceSettings.current ?? {};\nconst volume = saved.volume ?? gem.prefs?.recommended?.volume ?? 100;\n```\n\nUnlike `muted` and `reducedMotion`, nothing here is applied for you, and\nnothing obliges you to use it. See the guide's \"Game settings\" section.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -8876,6 +8979,38 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemRecommendedSettings.graphicsQuality",
+          "name": "graphicsQuality",
+          "anchor": "gemrecommendedsettings-graphicsquality",
+          "group": "player",
+          "signature": "readonly graphicsQuality: GemGraphicsQuality",
+          "documented": true,
+          "summary": "The graphics quality to START at on this device: `'low'`, `'medium'` or\n`'high'`. The Arcade picks it per device — the tier it detected, or the\nplayer's own Graphics choice — so a game opens at a quality that suits the\ndevice instead of guessing. A starting point, not a cap: while\n`graphicsQualityAuto` is true your game may adapt from here as it runs,\nand `createQualityGovernor` from `@indiegems/gem-web-sdk/quality` does\nthat for you. When the Arcade did not say, `'low'` with `batterySaver`\non and `'medium'` otherwise.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemRecommendedSettings.graphicsQualityAuto",
+          "name": "graphicsQualityAuto",
+          "anchor": "gemrecommendedsettings-graphicsqualityauto",
+          "group": "player",
+          "signature": "readonly graphicsQualityAuto: boolean",
+          "documented": true,
+          "summary": "Whether the Arcade chose `graphicsQuality` for this device (`true`, the\nplayer left Graphics on Auto) or the player picked it by hand (`false`).\nWhile it is `false`, hold that quality: never step it down or up on your\nown. `true` when the Arcade did not say.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemCohort",
           "name": "GemCohort",
@@ -9724,11 +9859,18 @@
           "name": "openAvatarPicker",
           "anchor": "gem-openavatarpicker",
           "group": "start",
-          "signature": "openAvatarPicker(): boolean",
+          "signature": "openAvatarPicker(options?: { tab?: \"2d\" | \"3d\" }): boolean",
           "documented": true,
-          "summary": "Open the arcade's avatar picker over your game, so the player can change\nthe Arcade avatar they wear without leaving it. For a game that draws\nArcade avatars — whole characters the player owns as Arcade items — put a\n\"Change avatar\" button in your own UI and call this from it:\n\n```js\nchangeAvatar.hidden = !gem.avatarPickerAvailable;\nchangeAvatar.onclick = () => {\n  if (!gem.openAvatarPicker()) changeAvatar.hidden = true;\n};\n```\n\n**The change arrives as a new player, not as an answer.** Nothing comes\nback from this call. When the player picks a different avatar, the arcade\npauses your game while the picker is open, then sends the player again —\nyour `onPlayer` callback runs and [Gem.player](api-reference-game.md#gem-player) holds the new\n[PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) — and resumes it. Redraw from\n`onPlayer`, which also runs when the player changes their avatar from the\narcade's own menu without your game asking. A player who closes the picker\nunchanged produces nothing at all.\n\n**Your server learns it only when it reads the room again.** A\nserver-authoritative game reads each member's `avatar_icon_id` from the\nroom read (`GET /v1/games/{game_id}/game-rooms/{game_room_id}`, or\n`gem.room.get()` on a dedicated server); nothing tells the server the\nplayer changed. So when `onPlayer` brings a different `avatarIconId`, have\nyour client tell your server, and have the server re-read the room — never\ntrust the id the client sends.",
+          "summary": "Open the arcade's avatar picker over your game, so the player can change\nthe Arcade avatar they wear without leaving it. For a game that draws\nArcade avatars — whole characters the player owns as Arcade items — put a\n\"Change avatar\" button in your own UI and call this from it:\n\n```js\nchangeAvatar.hidden = !gem.avatarPickerAvailable;\nchangeAvatar.onclick = () => {\n  if (!gem.openAvatarPicker()) changeAvatar.hidden = true;\n};\n```\n\n**Two tabs: 2D and 3D.** The picker has a 2D tab — the portrait, a\npicture ([PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid)) — and a 3D tab — a whole\ncharacter with its own model ([PlayerIdentity.avatar3dId](api-reference-game.md#playeridentity-avatar3did),\n[PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl)). They are separate choices: wearing\none never changes the other. Pass `{ tab: '3d' }` or `{ tab: '2d' }` to\nopen on one; omit it and the arcade decides (a game that draws Arcade\navatars gets the 3D tab). An arcade older than the tabs ignores it.\n\n**The change arrives as a new player, not as an answer.** Nothing comes\nback from this call. When the player picks a different avatar, the arcade\npauses your game while the picker is open, then sends the player again —\nyour `onPlayer` callback runs and [Gem.player](api-reference-game.md#gem-player) holds the new\n[PlayerIdentity.avatar3dId](api-reference-game.md#playeridentity-avatar3did) or [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) —\nand resumes it. Redraw from `onPlayer`, which also runs when the player\nchanges their avatar from the arcade's own menu without your game asking.\nA player who closes the picker unchanged produces nothing at all.\n\n**Your server learns it only when it reads the room again.** A\nserver-authoritative game reads each member's `avatar_3d_id` and\n`avatar_icon_id` from the room read\n(`GET /v1/games/{game_id}/game-rooms/{game_room_id}`, or `gem.room.get()`\non a dedicated server); nothing tells the server the player changed. So\nwhen `onPlayer` brings a different avatar, have your client tell your\nserver, and have the server re-read the room — never trust the id the\nclient sends.",
           "deprecated": null,
-          "params": [],
+          "params": [
+            {
+              "name": "options",
+              "type": "{ tab?: \"2d\" | \"3d\" }",
+              "optional": true,
+              "summary": "`tab` — `'2d'` or `'3d'`, the tab to open on. Omit it to let\n  the arcade decide; any other value is treated as omitted."
+            }
+          ],
           "returns": "`true` when the arcade was asked; `false` when it was not and\n  never will be for this call — outside the arcade, before the bridge is\n  up, under an embedder with no avatar picker, or past six asks a minute.\n  It never throws and never waits.",
           "throws": null,
           "example": null,
@@ -9949,6 +10091,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.paused",
+          "name": "paused",
+          "anchor": "gem-paused",
+          "group": "start",
+          "signature": "readonly paused: boolean",
+          "documented": true,
+          "summary": "Whether the arcade has your game paused right now: `true` from an\n`onPause(true)` until the `onPause(false)` that follows it, `false` before\nany. The same pause `onPause` tells you about, readable at any moment —\nfor code that was not around when the edge arrived, such as a frame-time\nmonitor deciding whether a slow frame counts.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.cohorts",
           "name": "cohorts",
@@ -11371,6 +11529,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlayerIdentity.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "playeridentity-avatar3did",
+          "group": "player",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlayerIdentity.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "playeridentity-avatar3dmodelurl",
+          "group": "player",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlayerIdentity.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "playeridentity-avatar3diconurl",
+          "group": "player",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PlayerIdentity.badges",
           "name": "badges",
@@ -11394,7 +11600,7 @@
           "group": "player",
           "signature": "function mapIdentity(row: unknown): PlayerIdentity",
           "documented": true,
-          "summary": "Map one row's identity fields, as the platform's API sends them, to\n[PlayerIdentity](api-reference-game.md#playeridentity).\n\nEvery surface this SDK names maps its rows through this already. You need it\nonly for a row you fetched yourself through the raw client — an async\nopponent, for instance:\n\n```js\nimport { mapIdentity, text } from '@indiegems/gem-web-sdk/sdk';\n\nconst { opponents } = await gem.client.get('/v1/async-opponents?opponent_type=ghost-lap');\nfor (const row of opponents) {\n  const who = mapIdentity(row);\n  label(who.displayName ? text.toPlain(who.displayName) : 'Anonymous player');\n}\n```\n\nReads `player_id`, `display_name`, `discriminator`, `display_tag`,\n`avatar_icon_id`, `avatar_icon_url` and `badges`, and nothing else from the\nrow. Anything missing, empty or of the wrong type is absent in the result.",
+          "summary": "Map one row's identity fields, as the platform's API sends them, to\n[PlayerIdentity](api-reference-game.md#playeridentity).\n\nEvery surface this SDK names maps its rows through this already. You need it\nonly for a row you fetched yourself through the raw client — an async\nopponent, for instance:\n\n```js\nimport { mapIdentity, text } from '@indiegems/gem-web-sdk/sdk';\n\nconst { opponents } = await gem.client.get('/v1/async-opponents?opponent_type=ghost-lap');\nfor (const row of opponents) {\n  const who = mapIdentity(row);\n  label(who.displayName ? text.toPlain(who.displayName) : 'Anonymous player');\n}\n```\n\nReads `player_id`, `display_name`, `discriminator`, `display_tag`,\n`avatar_icon_id`, `avatar_icon_url`, `avatar_3d_id`, `avatar_3d_model_url`,\n`avatar_3d_icon_url` and `badges`, and nothing else from the row. Anything missing, empty or of the wrong type is absent in the result.",
           "deprecated": null,
           "params": [
             {
@@ -11417,7 +11623,7 @@
           "group": "player",
           "signature": "function platformIconUrl(url: string | undefined): string | undefined",
           "documented": true,
-          "summary": "The icon URL, if and only if the platform serves it — otherwise `undefined`.\n\nUse it on every [PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl) and\n[PlayerBadge.iconUrl](api-reference-game.md#playerbadge-iconurl) before it reaches an `<img src>`, a texture\nloader or a `fetch`:\n\n```js\nimport { platformIconUrl } from '@indiegems/gem-web-sdk/sdk';\n\nconst src = platformIconUrl(member.avatarIconUrl);\nif (src) img.src = src; else drawPlaceholder();\n```\n\n**Why it exists.** Loading an image is a request, and a request carries the\npage's `Referer` and the moment it happened. The URLs the SDK hands you are\nchecked for shape — `https`, no credentials — but a shape check cannot know\nwhich host is the platform's, so an icon URL from anywhere but the platform's\nown image host would be a beacon on your player. This compares the whole\norigin against the hosts the platform serves item icons from in production. A\nURL on `localhost` passes too, for a stack running on one machine.\n\nAn unrecognised host answers `undefined` — draw your placeholder, as for a\nplayer with no portrait. That includes a development backend's image host,\nso portraits appear only against production and loopback.",
+          "summary": "The icon URL, if and only if the platform serves it — otherwise `undefined`.\n\nUse it on every [PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl),\n[PlayerIdentity.avatar3dIconUrl](api-reference-game.md#playeridentity-avatar3diconurl), [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl)\nand [PlayerBadge.iconUrl](api-reference-game.md#playerbadge-iconurl) before it reaches an `<img src>`, a texture\nloader, a `GLTFLoader` or a `fetch`:\n\n```js\nimport { platformIconUrl } from '@indiegems/gem-web-sdk/sdk';\n\nconst src = platformIconUrl(member.avatarIconUrl);\nif (src) img.src = src; else drawPlaceholder();\n```\n\n**Why it exists.** Loading an image is a request, and a request carries the\npage's `Referer` and the moment it happened. The URLs the SDK hands you are\nchecked for shape — `https`, no credentials — but a shape check cannot know\nwhich host is the platform's, so an icon URL from anywhere but the platform's\nown image host would be a beacon on your player. This compares the whole\norigin against the hosts the platform serves item icons from in production. A\nURL on `localhost` passes too, for a stack running on one machine.\n\nAn unrecognised host answers `undefined` — draw your placeholder, as for a\nplayer with no portrait. That includes a development backend's image host,\nso portraits appear only against production and loopback.",
           "deprecated": null,
           "params": [
             {
@@ -12778,6 +12984,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemGraphicsQuality",
+          "name": "GemGraphicsQuality",
+          "anchor": "gemgraphicsquality",
+          "group": "player",
+          "signature": "type GemGraphicsQuality = \"low\" | \"medium\" | \"high\"",
+          "documented": true,
+          "summary": "A graphics quality tier: `'low'`, `'medium'` or `'high'`. What\n`gem.prefs.recommended.graphicsQuality` holds.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "ServerTokenGrant",
           "name": "ServerTokenGrant",
@@ -14143,6 +14365,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "LeaderboardEntry.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "leaderboardentry-avatar3did",
+          "group": "leaderboards",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "LeaderboardEntry.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "leaderboardentry-avatar3dmodelurl",
+          "group": "leaderboards",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "LeaderboardEntry.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "leaderboardentry-avatar3diconurl",
+          "group": "leaderboards",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "LeaderboardEntry.badges",
           "name": "badges",
@@ -15906,6 +16176,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "PlayerProfile.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "playerprofile-avatar3did",
+          "group": "profiles",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlayerProfile.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "playerprofile-avatar3dmodelurl",
+          "group": "profiles",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "PlayerProfile.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "playerprofile-avatar3diconurl",
+          "group": "profiles",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "PlayerProfile.badges",
           "name": "badges",
@@ -18722,6 +19040,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "RoomMember.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "roommember-avatar3did",
+          "group": "rooms",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RoomMember.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "roommember-avatar3dmodelurl",
+          "group": "rooms",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RoomMember.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "roommember-avatar3diconurl",
+          "group": "rooms",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "RoomMember.badges",
           "name": "badges",
@@ -19804,6 +20170,54 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "ShowcaseFriendEntry.avatar3dId",
+          "name": "avatar3dId",
+          "anchor": "showcasefriendentry-avatar3did",
+          "group": "showcase",
+          "signature": "readonly avatar3dId?: string",
+          "documented": true,
+          "summary": "The id of the 3D character the player wears, when they wear one — an\nArcade item of type `avatar_3d`, chosen on the 3D tab of the Arcade's\navatar picker. What a game that draws Arcade avatars keys its character\non: prefer it, load [PlayerIdentity.avatar3dModelUrl](api-reference-game.md#playeridentity-avatar3dmodelurl), and fall back\nto your own mapping of [PlayerIdentity.avatarIconId](api-reference-game.md#playeridentity-avatariconid) when it is\nabsent.\n\nIndependent of the portrait: wearing a 3D character never changes\n`avatarIconId`, and the other way round. Absent means the game's default\nlook. On `gem.player` it changes when the player wears another one, and\n`onPlayer` runs again; see `gem.openAvatarPicker`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ShowcaseFriendEntry.avatar3dModelUrl",
+          "name": "avatar3dModelUrl",
+          "anchor": "showcasefriendentry-avatar3dmodelurl",
+          "group": "showcase",
+          "signature": "readonly avatar3dModelUrl?: string",
+          "documented": true,
+          "summary": "The worn 3D character's model — a binary glTF (`.glb`) with one rig,\n`root > body > (head, arm_l, arm_r > hand_socket, leg_l, leg_r)`, and\npossibly animation clips. Load it with three.js's `GLTFLoader`, after\npassing it through [platformIconUrl](api-reference-game.md#platformiconurl), which pins models to the\nplatform's item host exactly as it pins pictures. Absent when no 3D\ncharacter is worn.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ShowcaseFriendEntry.avatar3dIconUrl",
+          "name": "avatar3dIconUrl",
+          "anchor": "showcasefriendentry-avatar3diconurl",
+          "group": "showcase",
+          "signature": "readonly avatar3dIconUrl?: string",
+          "documented": true,
+          "summary": "A rendered portrait of the worn 3D character, for a roster or a menu where\nloading the model is too much. Not the 2D portrait\n([PlayerIdentity.avatarIconUrl](api-reference-game.md#playeridentity-avatariconurl)), which is a separate choice. Pass it\nthrough [platformIconUrl](api-reference-game.md#platformiconurl) before putting it in an `<img src>`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "ShowcaseFriendEntry.badges",
           "name": "badges",

package/docs/changelog.md

@@ -16,6 +16,37 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 11.0.0
+
+Upgrading from 10.4.0. Impact: required.
+
+### Rebuild
+
+- The calls that ask the Arcade to open the avatar picker now accept an optional tab, either 2d or 3d. Existing calls without arguments still compile and behave as before. Recompile; pass a tab only if you want the picker to open on a specific one.
+- The host callback for avatar picker requests now receives a request object that may carry the requested tab. Handlers that take no arguments still compile. Recompile, and if you host games, read the tab to open the picker on the right one.
+
+### New capability
+
+- The current player now carries optional 3D avatar fields: an identifier, a model URL and an icon URL. They describe the 3D character the player wears in the Arcade, which is chosen independently of the 2D portrait. The fields may be absent, so keep a fallback to the portrait. They are sent again whenever the worn 3D character changes, so a game that shows the player's avatar should update when they change.
+- Room members, leaderboard rows, friends and showcase friend rows now carry the same optional 3D avatar identifier, model URL and icon URL. A game can show other players' 3D characters wherever it already shows their portraits. Treat the fields as optional and fall back to the portrait when they are missing.
+- Code that embeds a game and sends player details to it can now pass the 3D avatar identifier, model URL and icon URL along with the other player fields. Send them whenever the player's worn 3D character changes.
+- The raw server and API identity types now include optional 3D avatar identifier, model URL and icon URL properties for players and subjects. Code that reads these types directly can use them. They may not be populated by the service yet, so handle their absence.
+- The Arcade avatar picker now has a 2D tab and a 3D tab. A game asking the Arcade to open the picker can say which tab to show, and a host receiving that request can read the requested tab. Omitting the tab keeps the previous behaviour. An unknown tab value is dropped rather than failing the request.
+
+## 10.4.0
+
+Upgrading from 10.3.1. Impact: required.
+
+### Rebuild
+
+- The recommended preferences type gained optional graphics quality and automatic fields, and the host method that sends preferences accepts the same two fields. Existing code keeps working; recompile your game against the new types. Host or test-harness code that sends preferences can now also pass the graphics quality tier and the automatic flag.
+
+### New capability
+
+- The recommended settings now carry a graphics quality tier and an automatic flag. The Arcade picks a starting tier per device (low, medium or high) and a game can start from it. An unknown tier is read as medium, a missing tier follows the battery saver setting (low when it is on, otherwise medium), and a missing automatic flag is read as true, so both values are always present in the game. When the automatic flag is false the player picked the tier by hand, and the game should keep it rather than adapt it.
+- The new paused value holds the latest state of the pause signal. Code that starts after the pause signal has already arrived, such as a frame-time monitor created mid-game, can read it to learn whether the game is currently paused.
+- A new optional quality entry point lets a game adapt its graphics level to frame time. It starts at the Arcade's tier mapped onto the game's own levels. It steps down one level after about two seconds of slow frames and up one level after about ten seconds of comfortably fast frames, never going above one level over its start. It ignores paused and hidden time, holds steady when the player chose the tier by hand, and restarts when a new recommendation arrives. It can run on animation frames or be fed frame times manually. A game that does not import it pays nothing in size.
+
 ## 10.3.1
 
 Upgrading from 10.3.0. Impact: none.

package/docs/getting-started.md

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