@indiegems/gem-web-sdk 14.0.0 → 14.0.2

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

@@ -507,7 +507,7 @@ unlock_celebration: arcade
   always get the Arcade's card, whatever you declare.
 - **Only the store page on `release` is read**, and it takes effect when that page is
   promoted. It is display-only, and it needs no `schema_version` change.
-- **Gems or Tickets paid in the same moment** still go through `gem.cueReward`, with
+- **Gems or Coins paid in the same moment** still go through `gem.cueReward`, with
   no flight of your own.
 
 How your game learns an unlock happened, and the field's full rules, are in
@@ -618,7 +618,7 @@ there is no route by which the frame could request one. `createGem` forwards all
   player would mind losing there, and never hold it back for a terminate warning that may not come.
 
   **Re-read on resume.** Your game is told that it was paused and resumed, never why, and never
-  what the player did in the meantime. Their Gems and Tickets can change while you are paused, so
+  what the player did in the meantime. Their Gems and Coins can change while you are paused, so
   if your game keeps anything worked out from a balance, such as a Buy button it greyed out or a
   "not enough Gems" line, read `gem.platform.currencies.get()` again on every `onPause(false)`
   rather than trusting what it read before the pause
@@ -731,10 +731,10 @@ game, a framed or full-window game on a desktop, a tablet or a TV in native full
 
 - **The Gem button**, the Gem Arcade's gem, always there (a 44px square touch target), in
   the **top-left corner** unless your game [asks for another](#moving-the-gem-gemsetgemcorner). It
-  opens [the Arcade's menu](#the-arcades-menu): Return to the Arcade, the player's Gems, Tickets and
+  opens [the Arcade's menu](#the-arcades-menu): Return to the Arcade, the player's Gems, Coins and
   achievement score, mute, the player's Arcade-wide settings and the rest. Not your settings: those
   are [your own button](#game-settings).
-- **Nothing else.** The player's wallets (Gems, Tickets, their achievement score) are **not** drawn
+- **Nothing else.** The player's wallets (Gems, Coins, their achievement score) are **not** drawn
   over your game: the player opens the Gem menu to see them, and every platform-currency payout
   flies into the Gem button ([the Arcade's wallet](#the-arcades-wallet-in-the-gem-menu-never-drawn-by-you)).
   When the player switches the frame-rate readout on, it sits beside the gem and is reserved the
@@ -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
@@ -1366,7 +1387,7 @@ What it does, so you know what to expect:
 
 The Arcade keeps one button over every game, on every device: the Gem, top-left unless your game
 [asks for another corner](#moving-the-gem-gemsetgemcorner). Its menu is
-how a player leaves (**Return to the Arcade**), sees their Gems, Tickets and achievement score, mutes,
+how a player leaves (**Return to the Arcade**), sees their Gems, Coins and achievement score, mutes,
 goes fullscreen, reports a problem and changes their Arcade-wide settings — the ones that reach you as [`gem.prefs.recommended`](#game-settings). You can add up to
 four entries of your own:
 
@@ -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
@@ -1511,13 +1532,13 @@ and the release checklist checks that it does.
 
 ## The Arcade's wallet: in the Gem menu, never drawn by you
 
-The player's platform balances — Gems, Tickets (`ARCADE_TICKETS`) and their achievement score —
+The player's platform balances — Gems, Coins (`ARCADE_TICKETS`) and their achievement score —
 belong to the Arcade. **Your game never draws one**, and never shows a pending state for one: the
 Arcade takes every figure from the platform and shows them itself.
 
 **The Gem Arcade draws no wallet over your game** (since 2026-10-11). Nothing of it sits in your top
 row, at rest or when a balance moves. The player opens the Gem menu — the Gem button, in whichever
-corner it sits — to see their Gems, Tickets and achievement score, and every payout
+corner it sits — to see their Gems, Coins and achievement score, and every payout
 [`gem.cueReward`](inventory-and-catalogs.md#showing-the-reward-land-in-the-arcades-wallet) announces
 flies into the Gem button. A payout you do not cue flies too, from the middle of your frame, so cue
 the ones the player earns on screen and the flight starts where they are looking.
@@ -1804,7 +1825,7 @@ first:
 ### The signed-in player's Boost: show it, never gate on it
 
 `gem.player` also carries **`boost`** — the player's Boost, which the Arcade sells for real money.
-While it lasts the player earns Gems and Tickets faster (never achievement points), and the
+While it lasts the player earns Gems and Coins faster (never achievement points), and the
 platform raises their earning limits to match. The platform does all of that on its own side when
 it pays; your game does nothing to make a boost work.
 
@@ -1819,8 +1840,8 @@ backend without boosts, a read that has not landed yet — it reads as **not boo
 player who has no boost.
 
 ```js
-const tickets = gem.player?.boost.multipliers.find((m) => m.currencySlug === 'ARCADE_TICKETS');
-if (tickets && tickets.multiplier > 1) rewardScreen.showBadge(`${tickets.multiplier}× Tickets`);
+const coins = gem.player?.boost.multipliers.find((m) => m.currencySlug === 'ARCADE_TICKETS');
+if (coins && coins.multiplier > 1) rewardScreen.showBadge(`${coins.multiplier}× Coins`);
 ```
 
 ⚠️ **It is for display, and only for display** — a "2×" badge on a reward screen. Never gate

package/package.json

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

package/schema/bridge.v1.json

@@ -774,7 +774,7 @@
             "The player's Boost, FOR DISPLAY ONLY — a platform rule, not advice. A",
             "Boost is something the Arcade sells for real money: it",
             "multiplies what the player EARNS in platform currencies (Gems and",
-            "Tickets) and raises their earning limits. It never touches achievement",
+            "Coins) and raises their earning limits. It never touches achievement",
             "points.",
             "",
             "ADVISORY. It may lag: it is pushed on connect and again when the",
@@ -2737,9 +2737,9 @@
         "other, `gem.cueReward` returns false and the game does NOTHING. There is",
         "no fallback celebration: Gems display belongs to the arcade (the",
         "creator's ruling, 2026-09-24), so a game draws no Gems flight, counter or",
-        "celebration of its own. The same holds for Tickets (`ARCADE_TICKETS`):",
+        "celebration of its own. The same holds for Coins (`ARCADE_TICKETS`):",
         "`currencySlug` decides what flies and which total moves. `origin` is the",
-        "centre of the game's icon for that currency — its gem, or its ticket."
+        "centre of the game's icon for that currency — its gem, or its coin."
       ],
       "fields": {
         "currencySlug": { "kind": "string", "maxLength": 32 },
@@ -2761,7 +2761,7 @@
       "direction": "frameToParent",
       "transport": "port",
       "$comment": [
-        "Whether the arcade shows the player's platform wallets (Gems, Tickets, the",
+        "Whether the arcade shows the player's platform wallets (Gems, Coins, the",
         "achievement score) over the game right now — and, optionally, which of them.",
         "",
         "OPT-OUT. With no message at all, the parent shows EVERY wallet: a game that",
@@ -2775,7 +2775,7 @@
         "",
         "The narrowing is in force when EITHER optional field is present, and is",
         "ignored while `visible` is false. It is for a screen about one currency (a",
-        "ticket store); leaving it out is always safe. `currencies` are platform",
+        "Coins store); leaving it out is always safe. `currencies` are platform",
         "currency slugs (`GEMS`, `ARCADE_TICKETS`), matched exactly and",
         "case-sensitively against the wallets the parent draws; a slug it does not",
         "draw is ignored. `score` is its own field so it can never collide with a slug.",
@@ -3677,14 +3677,14 @@
         "  `unknown_currency` or `currency_not_in_game_payable`. Resolve it EXACTLY,",
         "  with no",
         "  alias table of your own: the retired `TICKETS` meant GEMS, and resolving",
-        "  it charged Gems to games that meant Tickets. An item may carry prices in",
+        "  it charged Gems to games that meant Coins. An item may carry prices in",
         "  more than one payable currency, so",
         "  the frame does choose which wallet pays; the prompt names that currency",
         "  and its price from platform records, which keeps the choice the player's.",
         "",
         "  A PAYABLE CURRENCY MAY BE ONE THE PLAYER BOUGHT. This shipped on the",
         "  argument that a payable currency is only ever EARNED: short of Gems or",
-        "  Tickets the answer was to go and play, and neither was sold for money.",
+        "  Coins the answer was to go and play, and neither was sold for money.",
         "  That is no longer true of Gems. The arcade's own store sells them, and",
         "  bought Gems stay payable in games (owner decision, 2026-10-06). So",
         "  where a balance came from protects",