@indiegems/gem-web-sdk 13.4.3 → 14.0.1

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "13.4.3"
+    "version": "14.0.1"
   },
   "entries": [
     {
@@ -77,6 +77,10 @@
           "key": "controls",
           "title": "Camera and look controls"
         },
+        {
+          "key": "gameSettings",
+          "title": "Game settings in the Arcade menu"
+        },
         {
           "key": "config",
           "title": "Your published config"
@@ -6901,6 +6905,29 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemFrame.declareSettings",
+          "name": "declareSettings",
+          "anchor": "gemframe-declaresettings",
+          "group": "frame",
+          "signature": "declareSettings(settings: { id: string; label: string; kind: \"toggle\" | \"slider\" | \"choice\"; value: string | number | boolean; quick?: boolean; icon?: string; min?: number; max?: number; step?: number; options?: { id: string; label: string }[] }[]): boolean",
+          "documented": true,
+          "summary": "Mirror up to eight of your game's own settings into the arcade's menu —\nthe whole list each time, the latest one winning.\n\nPrefer `gem.settings.declare`, which checks each entry, holds the list\nacross a reconnect and calls your handlers when the player changes one.\nThis one sends only while connected, and only to an arcade that draws game\nsettings.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "settings",
+              "type": "{ id: string; label: string; kind: \"toggle\" | \"slider\" | \"choice\"; value: string | number | boolean; quick?: boolean; icon?: string; min?: number; max?: number; step?: number; options?: { id: string; label: string }[] }[]",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "whether the message left the frame — `false` before the bridge is\n  up, for an arcade that draws no game settings, for a list the schema\n  refuses, and past this frame's own limit.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemFrame.setGemCorner",
           "name": "setGemCorner",
@@ -8335,6 +8362,644 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemGameSettingIcon",
+          "name": "GemGameSettingIcon",
+          "anchor": "gemgamesettingicon",
+          "group": "gameSettings",
+          "signature": "type GemGameSettingIcon = \"music\" | \"sfx\" | \"voice\" | \"eye\" | \"text\" | \"hint\" | \"speed\" | \"bright\" | \"controls\" | \"star\"",
+          "documented": true,
+          "summary": "The icon codes a declared setting may carry — the Arcade draws the glyph. An\nicon is optional, and a setting without one gets the Arcade's generic glyph.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSettingValue",
+          "name": "GemGameSettingValue",
+          "anchor": "gemgamesettingvalue",
+          "group": "gameSettings",
+          "signature": "type GemGameSettingValue = boolean | number | string",
+          "documented": true,
+          "summary": "The value of a declared setting: `boolean` for a toggle, `number` for a\nslider, and an option's `id` for a choice.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSettingBase",
+          "name": "GemGameSettingBase",
+          "anchor": "gemgamesettingbase",
+          "group": "gameSettings",
+          "signature": "interface GemGameSettingBase",
+          "documented": true,
+          "summary": "What every declared setting has, whatever its kind.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSettingBase.id",
+          "name": "id",
+          "anchor": "gemgamesettingbase-id",
+          "group": "gameSettings",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "Your own name for the setting — 1 to 40 of `A-Z a-z 0-9 _ -`, unique in\none declaration. It is what [GemGameSettingChange.id](api-reference-game.md#gemgamesettingchange-id) carries back.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSettingBase.label",
+          "name": "label",
+          "anchor": "gemgamesettingbase-label",
+          "group": "gameSettings",
+          "signature": "readonly label: string",
+          "documented": true,
+          "summary": "What the player reads, 1 to 40 characters, **already in the player's\nlanguage** (`gem.prefs.locale`): the Arcade does not translate it. Cut at\n40 characters.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSettingBase.icon",
+          "name": "icon",
+          "anchor": "gemgamesettingbase-icon",
+          "group": "gameSettings",
+          "signature": "readonly icon?: GemGameSettingIcon",
+          "documented": true,
+          "summary": "One of the Arcade's icon codes; a code this SDK does not know is left out\n(with a warning) and the setting is kept with the generic glyph.\n\nIn the Gem Arcade the icon also fills its fixed quick row (Music, Sound,\nColor, Vibration): the first **toggle** with `'music'` is the Music slot\nand the first toggle with `'eye'` is the Color slot. Give those two icons\nto your music on/off and colour-help toggles, and to no other setting.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameToggleSetting",
+          "name": "GemGameToggleSetting",
+          "anchor": "gemgametogglesetting",
+          "group": "gameSettings",
+          "signature": "interface GemGameToggleSetting",
+          "documented": true,
+          "summary": "An on/off setting — Music, Color help.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameToggleSetting.id",
+          "name": "id",
+          "anchor": "gemgametogglesetting-id",
+          "group": "gameSettings",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "Your own name for the setting — 1 to 40 of `A-Z a-z 0-9 _ -`, unique in\none declaration. It is what [GemGameSettingChange.id](api-reference-game.md#gemgamesettingchange-id) carries back.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameToggleSetting.label",
+          "name": "label",
+          "anchor": "gemgametogglesetting-label",
+          "group": "gameSettings",
+          "signature": "readonly label: string",
+          "documented": true,
+          "summary": "What the player reads, 1 to 40 characters, **already in the player's\nlanguage** (`gem.prefs.locale`): the Arcade does not translate it. Cut at\n40 characters.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameToggleSetting.icon",
+          "name": "icon",
+          "anchor": "gemgametogglesetting-icon",
+          "group": "gameSettings",
+          "signature": "readonly icon?: GemGameSettingIcon",
+          "documented": true,
+          "summary": "One of the Arcade's icon codes; a code this SDK does not know is left out\n(with a warning) and the setting is kept with the generic glyph.\n\nIn the Gem Arcade the icon also fills its fixed quick row (Music, Sound,\nColor, Vibration): the first **toggle** with `'music'` is the Music slot\nand the first toggle with `'eye'` is the Color slot. Give those two icons\nto your music on/off and colour-help toggles, and to no other setting.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameToggleSetting.kind",
+          "name": "kind",
+          "anchor": "gemgametogglesetting-kind",
+          "group": "gameSettings",
+          "signature": "readonly kind: \"toggle\"",
+          "documented": true,
+          "summary": "`'toggle'`: what kind of setting this is.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameToggleSetting.value",
+          "name": "value",
+          "anchor": "gemgametogglesetting-value",
+          "group": "gameSettings",
+          "signature": "readonly value: boolean",
+          "documented": true,
+          "summary": "Whether it is on now.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameToggleSetting.quick",
+          "name": "quick",
+          "anchor": "gemgametogglesetting-quick",
+          "group": "gameSettings",
+          "signature": "readonly quick?: boolean",
+          "documented": true,
+          "summary": "**Ignored by the Gem Arcade**, whose quick row is fixed — Music, Sound,\nColor, Vibration — and filled by [GemGameSettingBase.icon](api-reference-game.md#gemgamesettingbase-icon)\n(`'music'`, `'eye'`), not by this flag. Kept for other embedders, which\nmay show the first two toggles that ask in a quick row of their own;\nleaving it out is fine.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSliderSetting",
+          "name": "GemGameSliderSetting",
+          "anchor": "gemgameslidersetting",
+          "group": "gameSettings",
+          "signature": "interface GemGameSliderSetting",
+          "documented": true,
+          "summary": "A number between two ends — Music volume, Game speed.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSliderSetting.id",
+          "name": "id",
+          "anchor": "gemgameslidersetting-id",
+          "group": "gameSettings",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "Your own name for the setting — 1 to 40 of `A-Z a-z 0-9 _ -`, unique in\none declaration. It is what [GemGameSettingChange.id](api-reference-game.md#gemgamesettingchange-id) carries back.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSliderSetting.label",
+          "name": "label",
+          "anchor": "gemgameslidersetting-label",
+          "group": "gameSettings",
+          "signature": "readonly label: string",
+          "documented": true,
+          "summary": "What the player reads, 1 to 40 characters, **already in the player's\nlanguage** (`gem.prefs.locale`): the Arcade does not translate it. Cut at\n40 characters.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSliderSetting.icon",
+          "name": "icon",
+          "anchor": "gemgameslidersetting-icon",
+          "group": "gameSettings",
+          "signature": "readonly icon?: GemGameSettingIcon",
+          "documented": true,
+          "summary": "One of the Arcade's icon codes; a code this SDK does not know is left out\n(with a warning) and the setting is kept with the generic glyph.\n\nIn the Gem Arcade the icon also fills its fixed quick row (Music, Sound,\nColor, Vibration): the first **toggle** with `'music'` is the Music slot\nand the first toggle with `'eye'` is the Color slot. Give those two icons\nto your music on/off and colour-help toggles, and to no other setting.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSliderSetting.kind",
+          "name": "kind",
+          "anchor": "gemgameslidersetting-kind",
+          "group": "gameSettings",
+          "signature": "readonly kind: \"slider\"",
+          "documented": true,
+          "summary": "`'slider'`: what kind of setting this is.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSliderSetting.value",
+          "name": "value",
+          "anchor": "gemgameslidersetting-value",
+          "group": "gameSettings",
+          "signature": "readonly value: number",
+          "documented": true,
+          "summary": "The number now. Clamped into `[min, max]` and snapped onto `step` before it\nis sent.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSliderSetting.min",
+          "name": "min",
+          "anchor": "gemgameslidersetting-min",
+          "group": "gameSettings",
+          "signature": "readonly min?: number",
+          "documented": true,
+          "summary": "The lowest value, `0` when left out. Within ±1 000 000, below `max`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSliderSetting.max",
+          "name": "max",
+          "anchor": "gemgameslidersetting-max",
+          "group": "gameSettings",
+          "signature": "readonly max?: number",
+          "documented": true,
+          "summary": "The highest value, `100` when left out. Within ±1 000 000, above `min`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSliderSetting.step",
+          "name": "step",
+          "anchor": "gemgameslidersetting-step",
+          "group": "gameSettings",
+          "signature": "readonly step?: number",
+          "documented": true,
+          "summary": "The increment from `min`, `1` when left out. Greater than `0`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSettingOption",
+          "name": "GemGameSettingOption",
+          "anchor": "gemgamesettingoption",
+          "group": "gameSettings",
+          "signature": "interface GemGameSettingOption",
+          "documented": true,
+          "summary": "One answer of a [GemGameChoiceSetting](api-reference-game.md#gemgamechoicesetting).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSettingOption.id",
+          "name": "id",
+          "anchor": "gemgamesettingoption-id",
+          "group": "gameSettings",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "Your own name for the answer, 1 to 40 of `A-Z a-z 0-9 _ -`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSettingOption.label",
+          "name": "label",
+          "anchor": "gemgamesettingoption-label",
+          "group": "gameSettings",
+          "signature": "readonly label: string",
+          "documented": true,
+          "summary": "What the player reads, 1 to 40 characters, already translated.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameChoiceSetting",
+          "name": "GemGameChoiceSetting",
+          "anchor": "gemgamechoicesetting",
+          "group": "gameSettings",
+          "signature": "interface GemGameChoiceSetting",
+          "documented": true,
+          "summary": "One of two to four answers — Difficulty: Easy, Normal, Hard.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameChoiceSetting.id",
+          "name": "id",
+          "anchor": "gemgamechoicesetting-id",
+          "group": "gameSettings",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "Your own name for the setting — 1 to 40 of `A-Z a-z 0-9 _ -`, unique in\none declaration. It is what [GemGameSettingChange.id](api-reference-game.md#gemgamesettingchange-id) carries back.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameChoiceSetting.label",
+          "name": "label",
+          "anchor": "gemgamechoicesetting-label",
+          "group": "gameSettings",
+          "signature": "readonly label: string",
+          "documented": true,
+          "summary": "What the player reads, 1 to 40 characters, **already in the player's\nlanguage** (`gem.prefs.locale`): the Arcade does not translate it. Cut at\n40 characters.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameChoiceSetting.icon",
+          "name": "icon",
+          "anchor": "gemgamechoicesetting-icon",
+          "group": "gameSettings",
+          "signature": "readonly icon?: GemGameSettingIcon",
+          "documented": true,
+          "summary": "One of the Arcade's icon codes; a code this SDK does not know is left out\n(with a warning) and the setting is kept with the generic glyph.\n\nIn the Gem Arcade the icon also fills its fixed quick row (Music, Sound,\nColor, Vibration): the first **toggle** with `'music'` is the Music slot\nand the first toggle with `'eye'` is the Color slot. Give those two icons\nto your music on/off and colour-help toggles, and to no other setting.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameChoiceSetting.kind",
+          "name": "kind",
+          "anchor": "gemgamechoicesetting-kind",
+          "group": "gameSettings",
+          "signature": "readonly kind: \"choice\"",
+          "documented": true,
+          "summary": "`'choice'`: what kind of setting this is.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameChoiceSetting.value",
+          "name": "value",
+          "anchor": "gemgamechoicesetting-value",
+          "group": "gameSettings",
+          "signature": "readonly value: string",
+          "documented": true,
+          "summary": "The `id` of the option chosen now.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameChoiceSetting.options",
+          "name": "options",
+          "anchor": "gemgamechoicesetting-options",
+          "group": "gameSettings",
+          "signature": "readonly options: readonly GemGameSettingOption[]",
+          "documented": true,
+          "summary": "Two to four answers, ids unique. A fifth and later are left out.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSetting",
+          "name": "GemGameSetting",
+          "anchor": "gemgamesetting",
+          "group": "gameSettings",
+          "signature": "type GemGameSetting = GemGameToggleSetting | GemGameSliderSetting | GemGameChoiceSetting",
+          "documented": true,
+          "summary": "One of your game's settings, as `gem.settings.declare` mirrors it into the\nArcade's menu: a toggle, a slider or a choice.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSettingChange",
+          "name": "GemGameSettingChange",
+          "anchor": "gemgamesettingchange",
+          "group": "gameSettings",
+          "signature": "interface GemGameSettingChange",
+          "documented": true,
+          "summary": "The player changed one of your declared settings in the Arcade's menu.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSettingChange.id",
+          "name": "id",
+          "anchor": "gemgamesettingchange-id",
+          "group": "gameSettings",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "The setting's `id`, from your latest declaration.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GemGameSettingChange.value",
+          "name": "value",
+          "anchor": "gemgamesettingchange-value",
+          "group": "gameSettings",
+          "signature": "readonly value: GemGameSettingValue",
+          "documented": true,
+          "summary": "The new value, of the setting's kind: a `boolean` for a toggle, a `number`\ninside a slider's range and on its step, an option's `id` for a choice.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GameSettingsApi",
+          "name": "GameSettingsApi",
+          "anchor": "gamesettingsapi",
+          "group": "gameSettings",
+          "signature": "interface GameSettingsApi",
+          "documented": true,
+          "summary": "`gem.settings` — mirror your game's own settings, up to eight, into the\nArcade's Gem menu. Your own settings button and screen stay: this is a\nsecond door to the same settings, never the only one.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GameSettingsApi.declare",
+          "name": "declare",
+          "anchor": "gamesettingsapi-declare",
+          "group": "gameSettings",
+          "signature": "declare(settings: readonly GemGameSetting[]): boolean",
+          "documented": true,
+          "summary": "Show up to eight of your settings in the Arcade's menu, in this order — the\nwhole list each time, the latest call winning. `declare([])` takes them\nall back out.\n\n```js\ngem.settings.declare([\n  { id: 'music', label: t('Music'), kind: 'toggle', value: music.on, icon: 'music' },\n  { id: 'colors', label: t('Color help'), kind: 'toggle', value: colorHelp, icon: 'eye' },\n  { id: 'speed', label: t('Game speed'), kind: 'slider', value: speed, min: 0.5, max: 2, step: 0.25 },\n]);\n```\n\n**Keep your own settings button and screen** — top-right, on every screen.\nThis mirrors those settings; it never replaces them, and an embedder that\ndraws no game settings shows none of it.\n\nThe Gem Arcade's Settings screen lists **every** setting you declare, so\ndeclare all of yours. Its quick row is fixed — Music, Sound, Color and\nVibration (phones and tablets), with the Arcade's own labels: your first\ntoggle with `icon: 'music'` fills Music, your first with `icon: 'eye'`\nfills Color, and a slot you do not fill stays greyed. It ignores `quick`.\n\n**Declare again whenever your own screen changes a value**, so the menu\nnever shows a stale one. **Never declare a second mute or vibration\nswitch** — the quick row has the Arcade's own. Your game's own volume,\nmusic and sound-effects levels are yours to declare; graphics quality and\nthe controls defaults stay the Arcade's and reach you as\n`gem.prefs.recommended`.\n\nAn entry that breaks a rule is left out, with a warning through your\n`log`; nothing throws.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "settings",
+              "type": "readonly GemGameSetting[]",
+              "optional": false,
+              "summary": "Up to eight settings, in the order to show them."
+            }
+          ],
+          "returns": "`true` when the Arcade has been told, or will be within half a\n  second; `false` before the bridge is up (the list is held and sent when\n  it connects), under an embedder that draws no game settings, and for an\n  argument that is not an array.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "GameSettingsApi.onChange",
+          "name": "onChange",
+          "anchor": "gamesettingsapi-onchange",
+          "group": "gameSettings",
+          "signature": "onChange(handler: (change: GemGameSettingChange) => void): () => void",
+          "documented": true,
+          "summary": "Called when the player changes one of your declared settings in the\nArcade's menu. Apply it at once, **even while paused** — the menu holds\nthe pause, and the player should hear the music stop while it is open —\nand keep it where you keep that setting's other changes.\n\n```js\ngem.settings.onChange(({ id, value }) => {\n  if (id === 'music') setMusic(value === true);\n});\n```\n\nThe SDK has already written the new value into your declaration, so there\nis no need to declare again for this change.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "handler",
+              "type": "(change: GemGameSettingChange) => void",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "A function that removes the handler.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "ARCADE_EMBEDDERS",
           "name": "ARCADE_EMBEDDERS",
@@ -10383,6 +11048,22 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "Gem.settings",
+          "name": "settings",
+          "anchor": "gem-settings",
+          "group": "start",
+          "signature": "readonly settings: GameSettingsApi",
+          "documented": true,
+          "summary": "Mirror your game's own settings, up to eight — Music, Color help, Game\nspeed — into the Arcade's Gem menu, and hear when the player changes one\nthere. The Arcade's Settings screen lists every one; its fixed quick row\ntakes your first toggle with `icon: 'music'` as Music and your first with\n`icon: 'eye'` as Color (`quick` is ignored by the Gem Arcade).\n\n```js\ngem.settings.declare([\n  { id: 'music', label: t('Music'), kind: 'toggle', value: music.on, icon: 'music' },\n]);\ngem.settings.onChange(({ id, value }) => {\n  if (id === 'music') setMusic(value === true); // even while paused\n});\n```\n\n**A mirror, never a replacement: your game still draws its own settings\nbutton and screen**, and every setting you declare is on that screen too.\nDeclare again whenever your screen changes a value. Never declare a\nsecond mute or vibration switch — the Arcade's quick row has them; your\nown volume and music or sound-effects levels are fine, and graphics and\ncontrols defaults stay the Arcade's (`gem.prefs.recommended`).\n\nSee the guide's \"Game settings\" section.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "Gem.analytics",
           "name": "analytics",