@indiegems/gem-web-sdk 9.1.4 → 10.1.0

package/schema/bridge.v1.json

@@ -763,6 +763,67 @@
             "because removing it is a `v` bump and an embedder may legitimately send",
             "one."
           ]
+        },
+        "recommended": {
+          "kind": "object",
+          "optional": true,
+          "$comment": [
+            "The player's ARCADE-WIDE DEFAULTS for this device, which the Arcade",
+            "keeps in its own Settings: a starting volume, battery saver, a keyboard",
+            "layout, the gamepad's confirm button, and vibration. RECOMMENDATIONS",
+            "ONLY. The game's own saved settings win: a game starts a setting from",
+            "here only while the player has made no choice of their own in that",
+            "game, and never overwrites one the player made because this changed.",
+            "A game may ignore it entirely.",
+            "",
+            "OPTIONAL because it is additive: a parent that predates it sends the",
+            "fields above without it, and the SDK reports `null`. All five fields",
+            "come together or the object is absent -- a parent that keeps only some",
+            "of them fills the rest from the defaults below rather than sending a",
+            "partial object.",
+            "",
+            "`muted`, `reducedMotion` and `showFrameStats` stay where they are, at",
+            "the top of this message, and keep their meaning: they are the Arcade's",
+            "own state the frame acts on, not a recommendation. The Arcade starts",
+            "them from the same per-device defaults.",
+            "",
+            "A DISPLAY PREFERENCE OF THE DEVICE, like `showFrameStats`: the Arcade",
+            "keeps one copy per device in the player's account (a guest's on the",
+            "device only), so a phone and a television recommend different things.",
+            "Sent in the first push after connecting and again on change.",
+            "",
+            "WIDENING AN ENUM HERE IS NOT FREE. The generated validator refuses the",
+            "WHOLE message on any field it rejects, so a value an older frame does",
+            "not know would cost it `muted` and `reducedMotion` as well. A new",
+            "keyboard layout or confirm button needs a capability the frame",
+            "advertises before a parent may send it."
+          ],
+          "fields": {
+            "volume": {
+              "kind": "int",
+              "min": 0,
+              "max": 100,
+              "$comment": "Master volume as a percentage, 0..100. Default 100. A level, not a mute: `muted` above is the mute."
+            },
+            "batterySaver": {
+              "kind": "boolean",
+              "$comment": "The player asked games to spend less power: a lower frame rate, fewer effects, a lower resolution. Default false."
+            },
+            "keyboardLayout": {
+              "kind": "enum",
+              "values": ["wasd", "arrows"],
+              "$comment": "Which keys move by default: WASD or the arrow keys. Default `wasd`."
+            },
+            "gamepadConfirm": {
+              "kind": "enum",
+              "values": ["south", "east"],
+              "$comment": "Which face button confirms, by position: `south` (the bottom button, A on an Xbox pad) or `east` (the right button, B on an Xbox pad); the other one goes back. Default `south`."
+            },
+            "vibration": {
+              "kind": "boolean",
+              "$comment": "Whether the player wants vibration and controller rumble. Default true."
+            }
+          }
         }
       },
       "rateLimit": { "perMinute": 60 }
@@ -2422,11 +2483,12 @@
       "transport": "port",
       "$comment": [
         "What the game adds to the arcade's own menu — the one control the arcade",
-        "keeps over a game, in the frame's top-right corner, which is how a player",
-        "leaves, mutes, reports a problem, and reaches the game's settings.",
+        "keeps over a game, in a corner `gem.viewport.reserved` names, which is how",
+        "a player leaves, mutes and reports a problem.",
         "",
         "  settings: true   the game has a settings screen and will open it when",
-        "                   told to; the menu gains a Settings entry",
+        "                   told to; a parent MAY show a Settings entry for it",
+        "                   (the Gem Arcade no longer does: see below)",
         "  items            up to four entries of the game's own, in this order,",
         "                   below the arcade's entries and visibly apart from them",
         "",
@@ -2454,8 +2516,15 @@
         "entry does nothing but send `gem.menuSelect`.",
         "",
         "Gated by `gameMenu`: sent only to a parent that advertised it. To any",
-        "other, `gem.setMenu` returns false and the game shows a settings control",
-        "of its own instead."
+        "other, `gem.setMenu` returns false.",
+        "",
+        "THE GEM ARCADE NO LONGER SHOWS A SETTINGS ENTRY FOR `settings: true`.",
+        "A game draws its own settings button (top-right is the recommendation)",
+        "and the Arcade's menu holds the player's Arcade-wide settings instead,",
+        "which reach the game as `gem.prefs.recommended`. The field STAYS: removing",
+        "it is a `v` bump, every game that sends it keeps working, and another",
+        "embedder may still show the entry. A parent that ignores it sends no",
+        "`gem.menuSelect` for it."
       ],
       "fields": {
         "settings": { "kind": "boolean" },