@indiegems/gem-web-sdk 14.0.3 → 15.1.0

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

@@ -585,12 +585,15 @@ credit for it until you say so.
 Five messages arrive that a game cannot ask for — the parent pushes them on its own schedule, and
 there is no route by which the frame could request one. `createGem` forwards all five:
 
-- **`onPrefs`** — `reducedMotion`, `muted`, `locale`, `showFrameStats` and `recommended`, sent
-  once after the handshake and again on every change. Also **held**, as `gem.prefs`, because a component mounted
+- **`onPrefs`** — `reducedMotion`, `muted`, `music`, `sounds`, `locale`, `showFrameStats` and
+  `recommended`, sent once after the handshake and again on every change. Also **held**, as `gem.prefs`, because a component mounted
   after the push would otherwise have missed it and cannot ask again. Read it where you need it
   rather than caching it — the locale changes mid-session. `muted` is the Arcade's mute: the SDK
   silences your page itself, and your own mute control follows it — see
-  [sound](#sound-your-own-mute-control-and-the-arcades) below. `showFrameStats` you need not act
+  [sound](#sound-your-own-mute-control-and-the-arcades) below. `music` and `sounds` are the
+  Arcade's Music and Sound switches, which your game honours itself — see
+  [the Arcade's Music and Sound switches](#the-arcades-music-and-sound-switches-onaudiochannels).
+  `showFrameStats` you need not act
   on: the SDK counts your frames itself — see [the Arcade's FPS overlay](#the-arcades-fps-overlay). See the language section for how to combine
   `locale` with your own detection. `recommended` is the player's Arcade-wide defaults, which your
   own settings start from — see [game settings](#game-settings).
@@ -1017,11 +1020,15 @@ 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.
+- **The quick row's Music and Sound switches are the Arcade's, for every game**: they reach your
+  game as `gem.prefs.music` and `gem.prefs.sounds`, and `onAudioChannels` is how your game honours
+  them ([the Arcade's Music and Sound switches](#the-arcades-music-and-sound-switches-onaudiochannels)).
 - **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 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
+  with `gem.settings.declare`: the Arcade's Settings screen lists every one, and the first
+  colour-help toggle fills the Color slot of its fixed quick row (the first music toggle fills Music
+  for a game that does not pass `onAudioChannels`). 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
@@ -1149,12 +1156,15 @@ player's Arcade-wide ones, in two places:
   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.
+  own labels; Vibration is there on phones and tablets only. **Music and Sound are the Arcade's
+  switches for your music and your sound effects**, which reach your game as `gem.prefs.music` and
+  `gem.prefs.sounds` — pass `onAudioChannels` so both work for your game
+  ([the Arcade's Music and Sound switches](#the-arcades-music-and-sound-switches-onaudiochannels)).
+  For a game that does not, the Arcade's Music falls back to the first `toggle` you declare with
+  `icon: 'music'`. Vibration is the player's Arcade setting. **Color** is your game's: the first
+  `toggle` you declare with `icon: 'eye'` — a colour-help, colour-blind or high-contrast switch. A
+  slot that nothing fills 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
@@ -1220,10 +1230,10 @@ musicToggle.onchange = () => {
 - **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. 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
+- **Never declare a second mute or vibration switch.** The quick row already has the Arcade's Music
+  and Sound (`gem.prefs.music` and `gem.prefs.sounds`, on top of the Arcade's mute) and Vibration
+  (the player's Arcade setting); a "Mute", "All 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,
@@ -1473,6 +1483,45 @@ calls above, the Arcade's entry and yours stay in step whichever the player uses
   starts, and nothing earlier. The boot order on this page already does that; an `AudioContext` made
   in a module that runs before `createGem` is out of reach.
 
+### The Arcade's Music and Sound switches: `onAudioChannels`
+
+The quick row of the Arcade's Gem menu has a **Music** switch and a **Sound** switch, for every
+game. They tell your game whether to play its **music** and whether to play its **sound effects**
+(everything that is not music: effects, ambience, interface sounds, voices). Only your game knows
+which of its sounds is which, so **your game does the switching**: pass `onAudioChannels` to
+`createGem`, turn your music off when `music` is false, and turn your effects off when `sounds` is
+false.
+
+```js
+const gem = createGem({
+  // ...
+  onAudioChannels: ({ music, sounds }) => {
+    musicBus.gain.value = music ? 1 : 0; // false: stop the music, keep the effects
+    effectsBus.gain.value = sounds ? 1 : 0; // false: silence the effects, keep the music
+  },
+});
+```
+
+- **Passing it is how the Arcade knows.** The SDK tells the Arcade your game honours the two
+  switches only when you pass `onAudioChannels`. Without it the Arcade cannot split your audio: it
+  mutes your whole game (`muted`) when the player turns both off, and its Music switch flips your own
+  music toggle if you [declared one](#mirror-your-settings-into-the-arcades-menu-gemsettings) with
+  `icon: 'music'`. Turning only Sound off then does nothing to your game.
+- **Called when the Arcade's preferences first arrive, and again whenever either value changes** —
+  not on every `gem.prefs` push. The same two values are always readable as `gem.prefs.music` and
+  `gem.prefs.sounds`.
+- **Both are `true` until the Arcade says otherwise**, and stay `true` under an Arcade or an
+  embedder that has no such switches, so the default is the audio your game plays today.
+- **They sit on top of your own settings, and are never saved as them.** Your music plays while
+  `music` is true **and** your own music setting is on; your effects play while `sounds` is true
+  **and** your own sound setting is on. Do not write the Arcade's switch into your saved settings or
+  change your own toggle because it moved: when the player turns it back on, your game's own choice
+  is still there. A music or effects **volume** of yours stays yours too.
+- **Apply them at once, even while paused.** The Gem menu holds your game paused while it is open,
+  and a player who turns Music off expects the music to stop while the menu is still open.
+- **`muted` is unchanged.** It is still the master mute the SDK applies for you, above both
+  switches.
+
 ### Start sound right away; a lift releases it where the browser holds it
 
 **Start your music and sound as soon as the game is ready.** Don't wait for a touch you may not

package/package.json

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

package/schema/bridge.v1.json

@@ -891,6 +891,51 @@
             "the frame would be counting for nobody."
           ]
         },
+        "music": {
+          "kind": "boolean",
+          "optional": true,
+          "$comment": [
+            "The player wants this game's MUSIC on (true) or off (false) — the",
+            "Arcade's Music switch (owner decision 2026-10-22). Absent means true.",
+            "",
+            "A WISH A COOPERATING GAME HONOURS, NOT A MUTE THE SDK ENFORCES. `muted`",
+            "above stays the master mute: the SDK silences the whole frame on it,",
+            "whatever the game does. `music` and `sounds` split the game's audio",
+            "into its two channels, and only the game knows which of its sounds is",
+            "which, so nothing below the game can act on them: a game that opted in",
+            "(capability `audioChannels`) stops its music while this is false and",
+            "starts it again on true, and leaves its sound effects alone. Both",
+            "apply on top of `muted` and on top of the game's own settings — music",
+            "plays only while `muted` is false, this is true, and the game's own",
+            "music setting is on — and a game never writes this into its own saved",
+            "setting.",
+            "",
+            "OPTIONAL because it is additive: a parent that predates it sends none,",
+            "and the frame reads the absence as true — the music the game would",
+            "have played anyway. A parent may send it to any frame (an older one",
+            "ignores the unknown field), but only a frame that advertised",
+            "`audioChannels` is promising to act on it; see that row for what a",
+            "parent does for one that did not.",
+            "",
+            "Sent in every push, like `muted`, and again whenever it changes."
+          ]
+        },
+        "sounds": {
+          "kind": "boolean",
+          "optional": true,
+          "$comment": [
+            "The player wants this game's SOUND EFFECTS on (true) or off (false) —",
+            "the Arcade's Sound switch (owner decision 2026-10-22): every sound the",
+            "game makes that is not its music (effects, ambience, interface clicks,",
+            "voices). Absent means true.",
+            "",
+            "The same contract as `music` above, for the other channel: a wish a",
+            "game that advertised `audioChannels` honours by silencing its effects",
+            "while this is false and leaving its music alone, on top of `muted`",
+            "(still the master mute the SDK enforces) and of the game's own",
+            "settings. OPTIONAL because it is additive; absence is true."
+          ]
+        },
         "locale": {
           "kind": "string",
           "maxLength": 35,

package/schema/capabilities.public.json

@@ -161,6 +161,14 @@
         }
       ]
     },
+    "audioChannels": {
+      "implemented": true,
+      "gates": [
+        {
+          "namespace": "gem.prefs"
+        }
+      ]
+    },
     "walletDisplay": {
       "implemented": true,
       "gates": [