@indiegems/gem-web-sdk 13.4.3 → 14.0.0

package/docs/changelog.md

@@ -16,6 +16,19 @@ 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.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "13.4.3"
+  "@indiegems/gem-web-sdk": "14.0.0"
 }
 ```
 
@@ -178,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": "90dc1aab037353e930fe1d16d8cc3f9fd6d2b60579c16146683f34fec0a0e9a1",
-      "updated": "2026-10-19T18:28:26Z"
+      "sha256": "3ccaf70d80a6164736920b4df6f817d600b2a80287d4a14783f72fbb470863f6",
+      "updated": "2026-10-21T13:51:48Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "bb6a59e57e0e5498388e6c436c3b0c0949bb4c115e2e42ad8e53fbfef59eb5f7",
-      "updated": "2026-10-19T18:28:26Z"
+      "sha256": "dbda9199712f4112bfe316b7af6e63a11fcce6842e778672459e1532947cf21f",
+      "updated": "2026-10-21T13:51:48Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -128,8 +128,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "028e89d4bd33272eb82631a753f10d05853fa68d81da02e3b6e2fd64758a0848",
-      "updated": "2026-10-19T18:28:26Z"
+      "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": "d696ecadad20b7f0e78fbc2b171fb4d767d2c6e8b9bcebc4c920432ab5799db1",
-      "updated": "2026-10-19T18:03:10Z"
+      "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.3/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v13.4.3/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

package/package.json

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

package/schema/bridge.v1.json

@@ -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": [