@indiegems/gem-web-sdk 7.8.1 → 7.9.1

package/schema/bridge.v1.json

@@ -893,7 +893,7 @@
         "",
         "AMENDED, DELIBERATELY: this message once carried insets only. It now also",
         "carries `reserved`, rectangles of the frame covered by the parent's own",
-        "controls floating over the game (a Back tab in a corner, the wallet chips",
+        "controls floating over the game (a menu button in a corner, the wallet chips",
         "shown in another). An inset can only describe a full-width or full-height band,",
         "and a corner tab expressed as a top inset would take the whole top strip",
         "from a full-bleed game to clear a control a few dozen pixels wide. A",
@@ -2387,7 +2387,7 @@
         "to it: a reward cue, a pending grant, a landing, a spend, a daily-maximum",
         "note, a score change. The game's state never cancels those. Only wallets",
         "shown BECAUSE OF THIS STATE reserve space: they extend `gem.viewport`'s",
-        "`reserved`, and hiding them shrinks it back to the parent's own Back tab. An",
+        "`reserved`, and hiding them shrinks it back to the parent's own menu button. An",
         "event pop floats over the game and never moves its layout. Where the parent",
         "docks its wallets beside the frame rather than over it, this changes",
         "nothing.",
@@ -2416,6 +2416,108 @@
       "rateLimit": { "perMinute": 60 }
     },
 
+    {
+      "type": "gem.menu",
+      "direction": "frameToParent",
+      "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.",
+        "",
+        "  settings: true   the game has a settings screen and will open it when",
+        "                   told to; the menu gains a Settings entry",
+        "  items            up to four entries of the game's own, in this order,",
+        "                   below the arcade's entries and visibly apart from them",
+        "",
+        "With no message at all, the menu holds the arcade's own entries and",
+        "nothing of the game's. The arcade's entries are the arcade's: a game can",
+        "neither remove nor reorder them, and Return to the Arcade is always there.",
+        "",
+        "SCREEN STATE, NOT A TOGGLE, like `gem.walletDisplay`. Each message is the",
+        "whole answer and the latest one wins; nothing accumulates. The SDK re-sends",
+        "the latest state after every handshake, so a parent that reconnects never",
+        "shows a menu missing what the game had declared.",
+        "",
+        "`id` is the game's own name for an entry and is what comes back in",
+        "`gem.menuSelect`; unique within one message, and the parent keeps the first",
+        "of a repeated id. `label` is what the player reads, ALREADY IN THE PLAYER'S",
+        "LANGUAGE (`gem.prefs.locale`): the parent does not translate it.",
+        "",
+        "A LABEL IS UNTRUSTED TEXT IN THE PARENT'S CHROME. A parent renders it as",
+        "text and never as markup, in the game's group and never among its own",
+        "entries, truncated to fit, and may decline to show an entry at all. A game",
+        "cannot make the menu say something the arcade says: that is what the",
+        "separate group is for.",
+        "",
+        "A PRESENTATION REQUEST ONLY. Not an authorization control; choosing an",
+        "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."
+      ],
+      "fields": {
+        "settings": { "kind": "boolean" },
+        "items": {
+          "kind": "array",
+          "maxItems": 4,
+          "optional": true,
+          "items": {
+            "kind": "object",
+            "fields": {
+              "id": {
+                "kind": "string",
+                "maxLength": 32,
+                "$comment": "The game's own name for the entry, 1..32 characters, echoed in `gem.menuSelect`. The SDK drops an entry whose id is empty or over-long rather than cutting it into a different id."
+              },
+              "label": {
+                "kind": "string",
+                "maxLength": 40,
+                "$comment": "What the player reads, 1..40 characters, already translated. The SDK drops an entry with an empty label and cuts an over-long one."
+              }
+            }
+          }
+        }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
+
+    {
+      "type": "gem.menuSelect",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The player chose one of the game's entries in the arcade's menu: its",
+        "Settings entry, or one of the items `gem.menu` declared.",
+        "",
+        "  entry: settings        open your settings screen",
+        "  entry: item, id        the item with this id",
+        "",
+        "Sent only for what the frame's LATEST `gem.menu` declared, and only to a",
+        "frame that advertised `gameMenu`. The parent closes its menu first, so the",
+        "`gem.pause` it sent when the menu opened is lifted before this arrives:",
+        "the game is running, in front, and the next thing on screen is the game's",
+        "own. A frame that hears an id it no longer declares ignores it — the menu",
+        "may have been open across a change.",
+        "",
+        "The arcade's own entries never come through here. Leaving, the mute and",
+        "fullscreen reach the game as they always did (`gem.pause`,",
+        "`gem.willTerminate`, `gem.prefs`), and a problem report reaches it not at",
+        "all."
+      ],
+      "fields": {
+        "entry": { "kind": "enum", "values": ["settings", "item"] },
+        "id": {
+          "kind": "string",
+          "maxLength": 32,
+          "optional": true,
+          "$comment": "Present when `entry` is `item`: the id from `gem.menu`."
+        }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
+
     {
       "type": "gem.requestShare",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -190,6 +190,13 @@
       "gates": [
         "gem.requestShare"
       ]
+    },
+    "gameMenu": {
+      "implemented": true,
+      "gates": [
+        "gem.menu",
+        "gem.menuSelect"
+      ]
     }
   }
 }