@indiegems/gem-web-sdk 13.4.2 → 14.0.0

package/docs/changelog.md

@@ -16,6 +16,25 @@ 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.
 
+## 14.0.0
+
+Upgrading from 13.4.3. Impact: required.
+
+### Rebuild
+
+- The message name lists, the frame and parent message unions, and the capability union each gained new members for game settings (the gameSettings capability among them). Recompiling is enough for most games. If your code switches exhaustively over message kinds or capability names, add handling for the new members.
+
+### New capability
+
+- A game can now mirror up to eight of its own settings into the Arcade's in-game menu using Gem.settings. A setting is a toggle, a slider or a choice. The Arcade shows up to two game toggles in the quick row next to its own sound and vibration controls, and lists the game's settings at the top of its settings screen. The game receives a change whenever the player alters one of them, but only for a setting it declared and only with a value of that setting's kind. Slider values are clamped and stepped. Keep drawing your own settings button and screen, because the declaration only mirrors a few settings. Do not declare the Arcade's own settings such as master volume, mute, vibration, graphics or controls.
+- A game that talks to the Arcade through the frame object directly can now declare its settings with GemFrame.declareSettings and receive player changes through the onSettingChange option or callback. The declaration is held until the connection is ready and re-sent after each handshake. Updates are paced to about two per second.
+
+## 13.4.3
+
+Upgrading from 13.4.2. Impact: none.
+
+Nothing in this release asks anything of a game.
+
 ## 13.4.2
 
 Upgrading from 13.4.1. Impact: none.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "13.4.2"
+  "@indiegems/gem-web-sdk": "14.0.0"
 }
 ```
 
@@ -149,19 +149,12 @@ reports. A `clientVersion` option still exists and is deprecated; see
 [what a game must do](what-a-game-must-do.md#2-your-version-number-which-you-no-longer-declare)
 for when an older arcade still needs it.
 
-**One more line if you render with WebGL**, and it is not part of `createGem`:
-
-```js
-const gl = canvas.getContext('webgl2', { preserveDrawingBuffer: true });
-```
-
-Players can attach a screenshot to a bug report, and without that flag the browser may clear
-your drawing buffer before the platform can read it. The SDK detects that and refuses rather
-than sending your team **a fully black image with no error attached** — but the cost is that
-your reports arrive with no picture. Two-dimensional canvas games need nothing here.
-[The full section](what-a-game-must-do.md#bug-reports-players-send-you-and-the-one-webgl-flag-that-decides-them)
-covers overriding the capture and attaching your own debug state, which is the part actually
-worth spending effort on.
+**Screenshots need nothing from you**, in 2D, WebGL or WebGPU, and that includes
+`preserveDrawingBuffer`, which you should leave off. Players can attach a screenshot to a bug
+report, and the SDK reads your canvas right after a frame you draw, so call `createGem` before you
+create your renderer and draw inside `requestAnimationFrame`, as every engine does.
+[The full section](what-a-game-must-do.md#bug-reports-players-send-you) covers overriding the
+capture and attaching your own debug state, which is the part actually worth spending effort on.
 
 **There is no offline mode.** A game must be framed by a page that speaks the bridge: opened
 at the top level, `createGem` throws `GemUnframedError`, which says how to run it. To run framed
@@ -185,7 +178,8 @@ And draw a settings button of your own — top-right, with your Back button just
 ([the top of the screen](what-a-game-must-do.md#the-top-of-the-screen)) — whose values start from
 the player's Arcade-wide defaults, `gem.prefs.recommended`, until the player chooses their own
 ([what a game must do](what-a-game-must-do.md#game-settings)). The Arcade's menu does not open
-your settings. Outside the Arcade there is no Arcade menu at all, so also give players a way out — a
+your settings screen; you may also mirror a few of your settings into it with
+`gem.settings.declare`, but never instead of your own button. Outside the Arcade there is no Arcade menu at all, so also give players a way out — a
 control that calls `gem.exit()`. A game a player cannot leave is one they leave by closing the tab.
 
 ## 6. Play it

package/docs/manifest.json

@@ -38,8 +38,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "4e64fa3d2f8aeeae3e9fb31b9adb500bbad34fcdfe9fa5ba0a2067d29f35bfd2",
-      "updated": "2026-10-19T17:54:55Z"
+      "sha256": "3ccaf70d80a6164736920b4df6f817d600b2a80287d4a14783f72fbb470863f6",
+      "updated": "2026-10-21T13:51:48Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "bbfe1f9550c8af5378a779cab63a5a7936e948def64aa451ec9f98c09dd8e059",
-      "updated": "2026-10-19T17:54:55Z"
+      "sha256": "dbda9199712f4112bfe316b7af6e63a11fcce6842e778672459e1532947cf21f",
+      "updated": "2026-10-21T13:51:48Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -128,8 +128,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "5fcb2a32a21c47586645fa16a9593f312171f1d794ed9b5602fc820ffd4627c3",
-      "updated": "2026-10-19T17:54:55Z"
+      "sha256": "2312a25bb11ce29f50b97b0737c708b31f6e0290f99fe2520179a9dbac67fb8c",
+      "updated": "2026-10-21T13:51:48Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -153,8 +153,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "97f97817fb087dbe2c637b4ea7f22f1ab624496bd32e427e4619c211c65d4f21",
-      "updated": "2026-10-18T15:05:29Z"
+      "sha256": "3a9c0e307b78cfb8b959c7b47a1ad0349699be944903a24834ee785c3823b402",
+      "updated": "2026-10-21T13:31:36Z"
     }
   ]
 }

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v13.4.2/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v13.4.2/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v14.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v14.0.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/docs/what-a-game-must-do.md

@@ -1016,10 +1016,13 @@ This is the whole model, and every other page that mentions settings links here:
 
 - **The Arcade's settings are the player's Arcade-wide defaults for this device.** Your game reads
   them from `gem.prefs.recommended` (and `muted` and `reducedMotion` from `gem.prefs`) and applies
-  them again on `onPrefs`. The Arcade never asks your game anything about them, and never shows
-  anything your game says.
+  them again on `onPrefs`. The Arcade never asks your game anything about them.
 - **Every game draws its own settings button, top-right ([the top of the
   screen](#the-top-of-the-screen)), and its own settings screen.** The Arcade's menu never opens it.
+- **A game may also mirror up to eight of its own settings into the Arcade's menu**, with
+  `gem.settings.declare` — a second way to reach a few of them, never the only one, and never a
+  setting the Arcade already has ([mirror a few settings into the Arcade's
+  menu](#mirror-a-few-settings-into-the-arcades-menu-gemsettings)).
 - **A setting starts from `recommended` until the player changes it in your game, and then the
   player's choice in your game wins.** Save only what the player chose, never a recommended value.
 - **Where a choice is kept.** Device configuration — volume, graphics quality, look sensitivity, a
@@ -1135,6 +1138,90 @@ owns — starts from `recommended` the same way and is kept in `gem.me.settings`
 ([sound](#sound-your-own-mute-control-and-the-arcades)), and `reducedMotion` is the player's
 accessibility setting, which your game honours.
 
+### Mirror a few settings into the Arcade's menu: `gem.settings`
+
+Optional. The Arcade's Gem menu can show a few of your game's own settings beside the player's
+Arcade-wide ones: in its Settings screen, in a group named for your game above the player's
+defaults for all games, and — for up to two toggles — in the menu's quick row, next to the
+Arcade's own Sound and Vibration buttons. A player who opens the menu mid-game can turn your music
+off without hunting for your settings screen.
+
+**It is a mirror, never a replacement: keep your own settings button and screen**, with every
+setting you declare on it too. An embedder that draws no game settings shows none of this, and the
+Arcade may leave an entry out when it is short of room — your own screen is what remains. A game
+that dropped its button because the Arcade's menu had its settings would have settings nobody can
+reach.
+
+```js
+// Built from the same state your own settings screen shows.
+const declared = () => [
+  { id: 'music', label: t('Music'), kind: 'toggle', value: music.on, quick: true, icon: 'music' },
+  { id: 'sfx', label: t('Sound effects'), kind: 'toggle', value: sfx.on, quick: true, icon: 'sfx' },
+  { id: 'colors', label: t('Color help'), kind: 'toggle', value: colorHelp, icon: 'eye' },
+  { id: 'speed', label: t('Game speed'), kind: 'slider', value: speed, min: 0.5, max: 2, step: 0.25 },
+  {
+    id: 'difficulty',
+    label: t('Difficulty'),
+    kind: 'choice',
+    value: difficulty,
+    options: [
+      { id: 'easy', label: t('Easy') },
+      { id: 'normal', label: t('Normal') },
+      { id: 'hard', label: t('Hard') },
+    ],
+  },
+];
+
+gem.settings.declare(declared());
+
+// The player changed one in the Arcade's menu. Your game is usually paused: apply it anyway.
+gem.settings.onChange(({ id, value }) => {
+  if (id === 'music') setMusic(value === true);
+  if (id === 'sfx') setSfx(value === true);
+  if (id === 'colors') setColorHelp(value === true);
+  if (id === 'speed') setSpeed(value);
+  if (id === 'difficulty') setDifficulty(value);
+  keepChoice(id, value); // where your own screen keeps the same choice
+});
+
+// Your own screen changed one: declare again, so the menu never shows a stale value.
+musicToggle.onchange = () => {
+  setMusic(musicToggle.checked);
+  keepChoice('music', musicToggle.checked);
+  gem.settings.declare(declared());
+};
+```
+
+- **Three kinds, up to eight settings, shown in your order.** A `toggle`'s `value` is `true` or
+  `false`; a `slider`'s is a number from `min` to `max` on `step` (defaults `0`, `100`, `1`); a
+  `choice` has two to four `options` and its `value` is one of their ids. `id` is your own name
+  for the setting, 1 to 40 of `A-Z a-z 0-9 _ -`, unique. An entry that breaks a rule is left out
+  with a warning on the console, and nothing throws.
+- **Mark at most two toggles `quick`** — the ones a player reaches for mid-game: Music, Sound
+  effects, Color help. A third that asks is shown only in the list. `icon` is optional: `music`,
+  `sfx`, `voice`, `eye`, `text`, `hint`, `speed`, `bright`, `controls` or `star`.
+- **Labels are already in the player's language** (`gem.prefs.locale`): the Arcade does not
+  translate them, and cuts them at 40 characters. Declare again when the language changes.
+- **Never declare a setting the Arcade already has.** Master volume and mute, vibration, graphics
+  quality and the controls defaults (look sensitivity, invert, touch stick, keyboard layout,
+  confirm button) are in the Arcade's own settings and reach you as `gem.prefs` and
+  `gem.prefs.recommended`. A "Vibration", "Volume" or "Mute" of yours beside them is a second
+  switch for the same thing, and the player cannot tell which one wins. Your own music and
+  sound-effect levels are yours to declare.
+- **It is screen state, not a toggle.** Each call is the whole list and replaces the last;
+  `gem.settings.declare([])` takes them all back out. **Declare again whenever your own screen
+  changes a value**, so the menu never shows a stale one. Before the Arcade connects the list is
+  held and sent when it does, and again after any reconnect; a burst — a slider being dragged — is
+  sent at most twice a second, always ending on the last value.
+- **Apply a change at once, even while paused.** The Arcade's menu holds your game paused
+  (`onPause(true)`) while it is open, and a player who turns Music off expects the music to stop
+  while the menu is still open. The change is the player's own choice, exactly as if they had made
+  it on your screen: keep it where you keep that setting (device settings or `gem.me.settings`,
+  [above](#game-settings)). The SDK has already written it into your declaration, so you do not
+  need to declare again for it.
+- **`declare` returns `false`** before the Arcade connects (the list is held) and under an
+  embedder that draws no game settings. Do nothing differently: your own screen has them all.
+
 ## Camera and look controls
 
 If your game turns a camera — a drag on a phone, a mouse under pointer lock, a gamepad's right
@@ -1289,8 +1376,10 @@ gem.setMenu({
 });
 ```
 
-- **Your settings are not in it.** They open from [your own button](#game-settings), and the
-  Arcade's menu never opens them.
+- **Your settings screen is not in it.** It opens from [your own button](#game-settings), and the
+  Arcade's menu never opens it. A few of your settings can also appear in the Arcade's menu, with
+  [`gem.settings`](#mirror-a-few-settings-into-the-arcades-menu-gemsettings) — a mirror of your
+  screen, never a replacement for it.
 - **`items` are up to four entries of your own**, shown in a group below the Arcade's. `id` is your
   name for the entry (1 to 32 characters); `label` is what the player reads, **already in their
   language** (`gem.prefs.locale`) — the Arcade does not translate it, cuts it at 40 characters, and
@@ -1951,34 +2040,40 @@ advice to a client you do not trust, so whatever it decides it must also carry o
 spending currency or granting an item is a recipe, which the platform already runs where a client
 cannot change it. [`serverless-functions.md`](serverless-functions.md) is the page.
 
-## Bug reports players send you, and the one WebGL flag that decides them
+## Bug reports players send you
 
 The arcade has a **Feedback** control. A player taps it, the platform asks your game for a picture
 of itself, the player draws on it and writes what happened, and it arrives on your game's feedback
 list. You get this for nothing — there is no option to set.
 
-There is one thing to get right, and it is easy to miss because getting it wrong produces no error
-anywhere.
-
-### ⚠️ WebGL games: `preserveDrawingBuffer: true`
-
-```js
-const gl = canvas.getContext('webgl2', { preserveDrawingBuffer: true });
-```
-
-Without it the browser is free to clear your drawing buffer once the frame is composited. Read it
-after that and you get **a fully black image and no error** — `createImageBitmap` resolves, the
-transfer succeeds, every layer reports success.
-
-The SDK checks the flag before it captures and **refuses** rather than sending you black. That is
-deliberate: a black screenshot costs the player their whole report and costs you the time to work
-out why the platform sent you a rectangle of nothing. The refusal reaches you instead, as
-`unsupported` in the report's diagnostics.
-
-The flag has a real cost — it can stop the browser discarding the buffer after compositing — so it
-is your call. But the default is to get no screenshots, silently, which is rarely what anyone wants.
-
-2D canvas games need nothing. `OffscreenCanvas` games need `onScreenshot`, below.
+### WebGL and WebGPU games: leave `preserveDrawingBuffer` off
+
+**You do not need `preserveDrawingBuffer: true` for screenshots, and should not set it.** With it
+on, the browser copies the whole drawing buffer every frame instead of swapping it (measured at
+about 0.4 ms of GPU time a frame on a 2021 Android flagship) to keep pixels readable that the SDK
+only needs once, when a player files a report.
+
+A WebGL canvas without the flag, and every WebGPU canvas, can be read only right after a frame is
+drawn: read it later and you get **a fully black image and no error**. So the SDK reads it there.
+It watches `requestAnimationFrame` and, when a capture is asked for, reads your canvas right after
+your next frame. When your game has stopped asking for frames, because nothing on screen is moving,
+it uses the picture it kept from the last frame you drew before you stopped. Every read is checked,
+and a blank one is never sent.
+
+Two things keep that working, and an ordinary game does both already:
+
+- **Call `createGem` before you create your renderer.** The SDK records each context as it is made,
+  so that it never has to ask a canvas for one. Asking would create a context on a canvas you had
+  not started yet, and take it from you.
+- **Draw inside `requestAnimationFrame`** (three.js's `setAnimationLoop`, Phaser, Babylon.js and
+  PixiJS all do), **from a loop that stops by not asking for the next frame.** A frame drawn from
+  an input handler or a timer has no moment the SDK can read it in, and a loop stopped with
+  `cancelAnimationFrame` from outside a frame leaves no last frame to keep.
+
+When neither read produced a picture, the report says so in its diagnostics: `unsupported` for
+WebGL (`preserveDrawingBuffer: true` would fix it, at the cost above), `unreadable` for WebGPU (only
+`onScreenshot` can). 2D canvas games need nothing. `OffscreenCanvas` games need `onScreenshot`,
+below.
 
 ### When the default capture is not right
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "13.4.2",
+  "version": "14.0.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",

package/schema/bridge.v1.json

@@ -2155,8 +2155,8 @@
           "$comment": [
             "`not_wired`   -- the capability was advertised but nothing implements it.",
             "`no_source`   -- the default strategy found no visible canvas, or one of zero area.",
-            "`unsupported` -- the WebGL context has `preserveDrawingBuffer: false`, or was lost. THE ONE THE FLAG FIXES, and it is kept narrow on purpose: it used to also cover the case below, so a developer whose canvas simply cannot be read was told to set a flag that would change nothing.",
-            "`unreadable` -- this page cannot read that canvas AT ALL: control was transferred to an OffscreenCanvas, or the context is one the SDK has no way to snapshot (WebGPU). No flag fixes it; the game must supply `onScreenshot`.",
+            "`unsupported` -- the WebGL context has `preserveDrawingBuffer: false` and no read produced a picture (no frame was drawn while the capture waited, and none was kept when the loop last stopped), or the context was lost. THE ONE THE FLAG FIXES, and it is kept narrow on purpose: it used to also cover the case below, so a developer whose canvas simply cannot be read was told to set a flag that would change nothing.",
+            "`unreadable` -- this page cannot read that canvas: control was transferred to an OffscreenCanvas, or a WebGPU canvas produced no picture in the frame or at rest. No flag fixes it; the game must supply `onScreenshot`.",
             "`tainted`     -- the canvas origin-clean flag is false. THE ONE A DEVELOPER CAN ACT ON (add `crossorigin` to the offending image), so it must stay distinguishable from `failed`.",
             "`too_large`   -- the source exceeds the requested caps and cannot be downscaled.",
             "`busy`        -- a capture is already in flight. Single-flight is enforced by the frame.",
@@ -3076,6 +3076,205 @@
       "rateLimit": { "perMinute": 12 }
     },
 
+    {
+      "type": "gem.settingsDeclare",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "A few of the game's OWN settings, mirrored into the arcade's menu - in",
+        "the Gem Arcade, a group headed with the game's name in its Settings",
+        "screen (\"only this game\"), above the player's Arcade-wide defaults,",
+        "and up to two toggles in the menu's quick row beside the arcade's own",
+        "Sound and Vibration (owner decision 2026-10-21).",
+        "",
+        "A MIRROR, NEVER A REPLACEMENT. A game that declares settings still draws",
+        "its own settings button and the screen it opens, and every one of these",
+        "settings is on that screen too. That is the answer to why the earlier",
+        "game-to-arcade settings channels (`gem.controlsDeclare`, `gem.menu`'s",
+        "`settings` flag) were withdrawn: games hid their own button, and their",
+        "settings became unreachable wherever the arcade showed nothing. A parent may",
+        "draw none of this - any embedder that did not advertise `gameSettings`,",
+        "a parent short of room - and the game's own screen is what remains.",
+        "",
+        "  settings   0..8 entries, in the order the game wants them shown;",
+        "             empty means the game shows none",
+        "",
+        "Each entry is one of three kinds:",
+        "",
+        "  toggle   `value` a boolean",
+        "  slider   `value` a number in [min, max], on `step` from `min`;",
+        "           `min`, `max` and `step` default to 0, 100 and 1",
+        "  choice   `value` one of `options`' ids; 2..4 options",
+        "",
+        "`id` is the game's own name for the setting, 1..40 characters of",
+        "A-Z a-z 0-9 _ -, and is what comes back in `gem.settingChange`;",
+        "unique within one message, and the parent keeps the first of a",
+        "repeated id. `label` (and each option's) is what the player reads,",
+        "1..40 characters, ALREADY IN THE PLAYER'S LANGUAGE (`gem.prefs.locale`):",
+        "the parent does not translate it. A parent drops an entry whose id,",
+        "kind, value or options break these rules rather than guessing; the SDK",
+        "never sends one.",
+        "",
+        "`quick` asks for a toggle in the menu's quick row. A parent honours it",
+        "on the first two toggles that ask, in order, and ignores it on any other",
+        "kind. `icon` is a CODE, not an enum: one of music, sfx, voice, eye,",
+        "text, hint, speed, bright, controls, star - and a parent draws its",
+        "generic glyph for one it does not know, so the vocabulary can grow",
+        "without an older parent refusing the message. The SDK drops a code it",
+        "does not know before sending.",
+        "",
+        "NOT THE ARCADE'S OWN SETTINGS. Master volume and mute, vibration,",
+        "graphics and the controls defaults are the arcade's, reaching the game",
+        "as `gem.prefs` and `gem.prefs.recommended`, and a game declares none of",
+        "them.",
+        "",
+        "A LABEL IS UNTRUSTED TEXT IN THE PARENT'S CHROME. A parent renders it as",
+        "text and never as markup, in the game's own group and never among its",
+        "own entries, truncated to fit, and may decline to show an entry at all.",
+        "",
+        "SCREEN STATE, NOT A TOGGLE, like `gem.menu`. Each message is the whole",
+        "answer and the latest one wins; nothing accumulates. The SDK holds it",
+        "from before the bridge is up and re-sends it after every handshake; a",
+        "game declares again whenever its own screen changes a value, and the",
+        "SDK writes a `gem.settingChange` into the declaration it holds, so a",
+        "reconnect never shows a stale value. A declaration is per game",
+        "session: the parent forgets it when the game is left.",
+        "",
+        "A PRESENTATION REQUEST ONLY, and not an authorization control. It",
+        "carries no player data and changes nothing but what the parent draws;",
+        "a change the player makes there reaches the game as",
+        "`gem.settingChange` and does nothing else.",
+        "",
+        "Gated by `gameSettings`: sent only to a parent that advertised it. To",
+        "any other, `gem.settings.declare` returns false."
+      ],
+      "fields": {
+        "settings": {
+          "kind": "array",
+          "maxItems": 8,
+          "items": {
+            "kind": "object",
+            "fields": {
+              "id": {
+                "kind": "string",
+                "maxLength": 40,
+                "$comment": "The game's own name for the setting, 1..40 characters of A-Z a-z 0-9 _ -, echoed in `gem.settingChange`."
+              },
+              "label": {
+                "kind": "string",
+                "maxLength": 40,
+                "$comment": "What the player reads, 1..40 characters, already translated. Untrusted text: rendered as text only."
+              },
+              "kind": {
+                "kind": "enum",
+                "values": ["toggle", "slider", "choice"]
+              },
+              "value": {
+                "kind": "scalar",
+                "maxLength": 40,
+                "min": -1000000,
+                "max": 1000000,
+                "$comment": "The setting's current value: a boolean for a toggle, a number in [min, max] for a slider, one of `options`' ids for a choice."
+              },
+              "quick": {
+                "kind": "boolean",
+                "optional": true,
+                "$comment": "Toggles only: ask to appear in the menu's quick row. A parent honours the first two that ask."
+              },
+              "icon": {
+                "kind": "string",
+                "maxLength": 16,
+                "format": "code",
+                "optional": true,
+                "$comment": "A code: music, sfx, voice, eye, text, hint, speed, bright, controls or star. Unknown means the parent's generic glyph."
+              },
+              "min": {
+                "kind": "number",
+                "min": -1000000,
+                "max": 1000000,
+                "optional": true,
+                "$comment": "Sliders only: the lowest value, 0 when absent. Below `max`."
+              },
+              "max": {
+                "kind": "number",
+                "min": -1000000,
+                "max": 1000000,
+                "optional": true,
+                "$comment": "Sliders only: the highest value, 100 when absent. Above `min`."
+              },
+              "step": {
+                "kind": "number",
+                "min": 0,
+                "max": 1000000,
+                "optional": true,
+                "$comment": "Sliders only: the increment from `min`, 1 when absent. Greater than 0."
+              },
+              "options": {
+                "kind": "array",
+                "maxItems": 4,
+                "optional": true,
+                "$comment": "Choices only: 2..4 options, ids unique, each with the same id and label rules as a setting.",
+                "items": {
+                  "kind": "object",
+                  "fields": {
+                    "id": { "kind": "string", "maxLength": 40 },
+                    "label": { "kind": "string", "maxLength": 40 }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "rateLimit": { "perMinute": 120 }
+    },
+
+    {
+      "type": "gem.settingChange",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The player changed one of the game's declared settings in the arcade's",
+        "own chrome: the setting with this `id`, now at `value`.",
+        "",
+        "Sent only for an id the frame's LATEST `gem.settingsDeclare` holds,",
+        "with a value of that setting's kind - a boolean for a toggle, a slider's",
+        "number clamped into [min, max] and onto its step, one of a choice's",
+        "option ids - and only to a frame that advertised `gameSettings`. A",
+        "parent coalesces a drag: it sends a slider's value when the player",
+        "lets go, or at most a few times a second while they hold it.",
+        "",
+        "THE GAME IS USUALLY PAUSED when this arrives - the menu holds the",
+        "`gem.pause` it opened with - and applies the change anyway, so the",
+        "player hears the music stop while the menu is still open. A frame",
+        "that hears an id it no longer declares ignores it: the menu may have",
+        "been open across a change.",
+        "",
+        "The SDK writes the new value into the declaration it holds before the",
+        "game's handlers run, so the next handshake re-sends what the player",
+        "chose rather than what the game last said.",
+        "",
+        "A PRESENTATION EVENT, NOT AN AUTHORIZATION CONTROL. It tells the game",
+        "what the player picked in a mirror of the game's own screen, and",
+        "nothing else; the game keeps the choice where it keeps any other."
+      ],
+      "fields": {
+        "id": {
+          "kind": "string",
+          "maxLength": 40,
+          "$comment": "The setting's id, from the latest `gem.settingsDeclare`."
+        },
+        "value": {
+          "kind": "scalar",
+          "maxLength": 40,
+          "min": -1000000,
+          "max": 1000000,
+          "$comment": "The new value, of the setting's kind."
+        }
+      },
+      "rateLimit": { "perMinute": 120 }
+    },
+
     {
       "type": "gem.requestShare",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -243,6 +243,13 @@
         "gem.gemCorner"
       ]
     },
+    "gameSettings": {
+      "implemented": true,
+      "gates": [
+        "gem.settingsDeclare",
+        "gem.settingChange"
+      ]
+    },
     "moments": {
       "implemented": true,
       "gates": [