@indiegems/gem-web-sdk 14.0.0 → 14.0.1

package/docs/manifest.json

@@ -38,8 +38,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "3ccaf70d80a6164736920b4df6f817d600b2a80287d4a14783f72fbb470863f6",
-      "updated": "2026-10-21T13:51:48Z"
+      "sha256": "93e10641e13f8e45156a822194ca163a5cbdf700899d3a0b4c89dec124623091",
+      "updated": "2026-10-21T18:58:27Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "dbda9199712f4112bfe316b7af6e63a11fcce6842e778672459e1532947cf21f",
-      "updated": "2026-10-21T13:51:48Z"
+      "sha256": "c00bc1a56741a6f6101d3c911359b942f500d035e6d24f32a61dfb5dce478fdc",
+      "updated": "2026-10-21T18:58:27Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -128,8 +128,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "2312a25bb11ce29f50b97b0737c708b31f6e0290f99fe2520179a9dbac67fb8c",
-      "updated": "2026-10-21T13:51:48Z"
+      "sha256": "2500446431aeb8dce11499d5de8e03ebf9d00b012bcee30e137a5a82b0abe559",
+      "updated": "2026-10-21T18:58:27Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -153,8 +153,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "3a9c0e307b78cfb8b959c7b47a1ad0349699be944903a24834ee785c3823b402",
-      "updated": "2026-10-21T13:31:36Z"
+      "sha256": "56e5d7323750cc29c015d99bcce747285a1c592336be5b54ee09fa67b223adc6",
+      "updated": "2026-10-21T18:37:13Z"
     }
   ]
 }

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/v14.0.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v14.0.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v14.0.1/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v14.0.1/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

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

@@ -1019,10 +1019,11 @@ This is the whole model, and every other page that mentions settings links here:
   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 game should also declare its settings — all of them, up to eight — to the Arcade's menu**,
+  with `gem.settings.declare`: the Arcade's Settings screen lists every one, and the first music
+  and colour-help toggles fill the Music and Color slots of its fixed quick row. It is a second way
+  to reach them, never the only one, and never a second mute or vibration switch ([mirror your
+  settings into the Arcade's menu](#mirror-your-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
@@ -1138,13 +1139,22 @@ 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`
+### Mirror your 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.
+Optional, and worth doing. The Arcade's Gem menu shows your game's own settings beside the
+player's Arcade-wide ones, in two places:
+
+- **Its Settings screen lists every setting you declare**, up to eight, in a group named for your
+  game above the player's defaults for all games. So declare **all** of your game's settings that
+  fit the three kinds below, not a chosen few: a player who opens the menu mid-game finds every one
+  of them without hunting for your settings screen.
+- **Its quick row is fixed: Music, Sound, Color and Vibration, in that order**, with the Arcade's
+  own labels; Vibration is there on phones and tablets only. Sound (your game's mute) and Vibration
+  (the player's Arcade setting) are the Arcade's. Your game fills the other two: **Music** with the
+  first `toggle` you declare with `icon: 'music'`, and **Color** with the first `toggle` you
+  declare with `icon: 'eye'` — a colour-help, colour-blind or high-contrast switch. A slot your
+  game does not fill stays in its place, greyed and inert. Nothing else of yours reaches the quick
+  row.
 
 **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
@@ -1153,11 +1163,12 @@ that dropped its button because the Arcade's menu had its settings would have se
 reach.
 
 ```js
-// Built from the same state your own settings screen shows.
+// Built from the same state your own settings screen shows: every setting on it.
 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: 'music', label: t('Music'), kind: 'toggle', value: music.on, icon: 'music' }, // the quick row's Music
+  { id: 'sfx', label: t('Sound effects'), kind: 'toggle', value: sfx.on, icon: 'sfx' },
+  { id: 'colors', label: t('Color help'), kind: 'toggle', value: colorHelp, icon: 'eye' }, // its Color
+  { id: 'musicVolume', label: t('Music volume'), kind: 'slider', value: musicVolume, min: 0, max: 100, step: 5 },
   { id: 'speed', label: t('Game speed'), kind: 'slider', value: speed, min: 0.5, max: 2, step: 0.25 },
   {
     id: 'difficulty',
@@ -1179,6 +1190,7 @@ 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 === 'musicVolume') setMusicVolume(value);
   if (id === 'speed') setSpeed(value);
   if (id === 'difficulty') setDifficulty(value);
   keepChoice(id, value); // where your own screen keeps the same choice
@@ -1197,17 +1209,26 @@ musicToggle.onchange = () => {
   `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`.
+- **`icon` is what puts a toggle in the quick row.** Give `icon: 'music'` to your music on/off
+  toggle and `icon: 'eye'` to your colour-help toggle, and to no other setting: only the first
+  toggle with each fills its slot, and a later one is shown only in the Settings list. Elsewhere
+  `icon` is optional and only picks the glyph: `music`, `sfx`, `voice`, `eye`, `text`, `hint`,
+  `speed`, `bright`, `controls` or `star`.
+- **`quick` is ignored by the Gem Arcade.** The quick row is the fixed one above, so marking a
+  toggle `quick` changes nothing there. The field stays in the type and on the wire for other
+  embedders, which may still honour it on the first two toggles that ask; leaving it out is fine.
 - **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.
+  translate them, and cuts them at 40 characters. Declare again when the language changes. The
+  quick row shows the Arcade's own labels; yours are what its Settings list shows.
+- **Never declare a second mute or vibration switch.** The quick row already has the Arcade's Sound
+  (your game's mute) and Vibration (the player's Arcade setting); a "Mute", "Sound off" or
+  "Vibration" of yours beside them is a second switch for the same thing, and the player cannot
+  tell which one wins. **Your own levels are yours to declare**: a game volume, music volume or
+  sound-effects volume is your game's level, which starts from the Arcade's `recommended` volume
+  like any [game setting](#game-settings) and is set over it — and so are Music and Sound effects
+  on/off toggles. Graphics quality and the controls defaults (look sensitivity, invert, touch stick,
+  keyboard layout, confirm button) stay the Arcade's: they reach you as `gem.prefs.recommended`,
+  and you do not declare them.
 - **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
@@ -1377,8 +1398,8 @@ gem.setMenu({
 ```
 
 - **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
+  Arcade's menu never opens it. Your settings can also appear in the Arcade's menu, with
+  [`gem.settings`](#mirror-your-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

package/package.json

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