@indiegems/gem-web-sdk 13.4.2 → 14.0.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "13.4.2"
+    "version": "14.0.0"
   },
   "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.",
+          "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.",
+          "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": "Ask for this toggle in the menu's quick row, beside the Arcade's own Sound\nand Vibration. The first two toggles that ask get it; a third is shown only\nin the settings list.",
+          "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.",
+          "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.",
+          "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 up to eight of your game's own settings into the\nArcade's Gem menu. Your own settings button and screen stay: this is a\nsecond door to a few of 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, quick: true, icon: 'music' },\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 a few of those settings; it never replaces them, and an\nembedder that draws no game settings shows none of it.\n\n**Declare again whenever your own screen changes a value**, so the menu\nnever shows a stale one. Mark at most two toggles `quick` (good ones:\nMusic, Sound effects, Color help). **Never declare the Arcade's own\nsettings** — master volume or mute, vibration, graphics quality, controls:\nthe Arcade already has them and they reach you as `gem.prefs`.\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",
@@ -8790,7 +9455,7 @@
           "group": "start",
           "signature": "readonly onScreenshot?: (request: { maxWidth: number; maxHeight: number }) => Promise<ImageBitmap | null>",
           "documented": true,
-          "summary": "Supply the screenshot yourself, instead of letting the SDK find it.\n\n**You do not need this to get screenshots.** By default the SDK captures\nyour largest visible canvas, which is right for almost every game.\n\n⚠️ A WebGL game must create its context with `{ preserveDrawingBuffer: true }`\nfor that default to work — without it the SDK refuses the capture rather\nthan sending your team a black image, and your reports arrive with no\npicture. That is a one-line change and NOT a reason to reach for this\noption.\n\nReach for it when the default genuinely cannot work, or when you want a say\nper moment:\n\n- your canvas is an `OffscreenCanvas` driven from a worker, or a WebGPU\n  surface — nothing on the page can read either, no flag changes that, and\n  the platform reports `unreadable` rather than `unsupported` precisely so\n  you do not go looking for a flag;\n- you draw across several layered canvases and want them composited;\n- you want to decline while something specific is on screen.\n\n**Return `null` to decline** — a cutscene, licensed art you may not\nredistribute, another player's private board. Declining is a normal answer,\nnot an error: the player is told a picture was not available and can still\nsend their report. Nothing is logged against you for it, and returning\n`null` unconditionally is how a game opts out of screenshots entirely.\n\n```js\nonScreenshot: async ({ maxWidth, maxHeight }) => {\n  if (inCutscene) return null;\n  return createImageBitmap(myCanvas);\n}\n```\n\nFit the result within `maxWidth` / `maxHeight` if you can; the SDK\ndownscales for you if you overshoot.",
+          "summary": "Supply the screenshot yourself, instead of letting the SDK find it.\n\n**You do not need this to get screenshots.** By default the SDK captures\nyour largest visible canvas, which is right for almost every game: 2D,\nWebGL or WebGPU, and WITHOUT `preserveDrawingBuffer`, which you should leave\noff. The SDK reads the canvas right after a frame you draw, or keeps the\nlast one you drew before your loop stopped. That needs `createGem` called\nbefore your renderer is made, and drawing inside `requestAnimationFrame`.\n\nReach for it when the default genuinely cannot work, or when you want a say\nper moment:\n\n- your canvas is an `OffscreenCanvas` driven from a worker. Nothing on the\n  page can read it, no flag changes that, and the platform reports\n  `unreadable` rather than `unsupported` precisely so you do not go looking\n  for a flag;\n- you draw outside `requestAnimationFrame`, so there is no moment the SDK\n  can read your canvas in: render, then `createImageBitmap(canvas)`, in the\n  same task;\n- you draw across several layered canvases and want them composited;\n- you want to decline while something specific is on screen.\n\n**Return `null` to decline** — a cutscene, licensed art you may not\nredistribute, another player's private board. Declining is a normal answer,\nnot an error: the player is told a picture was not available and can still\nsend their report. Nothing is logged against you for it, and returning\n`null` unconditionally is how a game opts out of screenshots entirely.\n\n```js\nonScreenshot: async ({ maxWidth, maxHeight }) => {\n  if (inCutscene) return null;\n  return createImageBitmap(myCanvas);\n}\n```\n\nFit the result within `maxWidth` / `maxHeight` if you can; the SDK\ndownscales for you if you overshoot.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -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 up to eight of your game's own settings — Music, Color help, Game\nspeed — into the Arcade's Gem menu, and hear when the player changes one\nthere. Up to two toggles can sit in the menu's quick row.\n\n```js\ngem.settings.declare([\n  { id: 'music', label: t('Music'), kind: 'toggle', value: music.on, quick: true, 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 the\nArcade's own settings — master volume or mute, vibration, graphics,\ncontrols; they reach you as `gem.prefs`.\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",