@indiegems/gem-web-sdk 10.2.0 → 10.3.1

package/schema/bridge.v1.json

@@ -811,10 +811,18 @@
             "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.",
+            "fields above without it, and the SDK reports `null`. The first 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.",
+            "",
+            "THE CAMERA AND CONTROLS FOUR ARE OPTIONAL INSIDE IT (owner decision",
+            "2026-10-11): `lookSensitivity`, `gamepadLookSensitivity`, `invertLookY`",
+            "and `touchMovement`, Roblox's per-device camera settings. A parent built",
+            "against an older SDK sends the object without them, and the SDK fills",
+            "each missing one with its default (100, 100, false, `floating`), so on",
+            "the game side all four are present whenever the object is. A game says",
+            "which of them it leaves to the player with `gem.controlsDeclare`.",
             "",
             "`muted`, `reducedMotion` and `showFrameStats` stay where they are, at",
             "the top of this message, and keep their meaning: they are the Arcade's",
@@ -829,8 +837,8 @@
             "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."
+            "keyboard layout, confirm button or touch-movement mode needs a",
+            "capability the frame advertises before a parent may send it."
           ],
           "fields": {
             "volume": {
@@ -856,6 +864,42 @@
             "vibration": {
               "kind": "boolean",
               "$comment": "Whether the player wants vibration and controller rumble. Default true."
+            },
+            "lookSensitivity": {
+              "kind": "int",
+              "min": 20,
+              "max": 400,
+              "optional": true,
+              "$comment": "Look speed for touch, mouse and pen, as a percentage of the base speeds (Roblox's MouseSensitivity): 100 is 1x, 20..400. Default 100 when absent. The Arcade's slider has eleven positions (20, 36, 52, 68, 84, 100, 160, 220, 280, 340, 400) but any integer in range is valid."
+            },
+            "gamepadLookSensitivity": {
+              "kind": "int",
+              "min": 20,
+              "max": 400,
+              "optional": true,
+              "$comment": "Look speed for a gamepad stick, as a percentage of the base speed (Roblox's GamepadCameraSensitivity): 100 is 1x, 20..400. Default 100 when absent."
+            },
+            "invertLookY": {
+              "kind": "boolean",
+              "optional": true,
+              "$comment": "Up/down look inverted: pushing up or dragging up looks DOWN (Roblox's CameraYInverted). Flips pitch only, never yaw. Default false when absent."
+            },
+            "touchMovement": {
+              "kind": "string",
+              "maxLength": 16,
+              "format": "code",
+              "optional": true,
+              "$comment": [
+                "On a touch screen, the movement thumbstick: `floating` appears where",
+                "the thumb lands (Roblox's Dynamic Thumbstick), `fixed` stays in one",
+                "place (Roblox's Thumbstick). Stored on every device, meaningful on",
+                "touch. Default `floating` when absent.",
+                "",
+                "A CODE, NOT AN ENUM, so the vocabulary can grow without costing an",
+                "older frame the whole message (see WIDENING above): a parent sends",
+                "only `floating` or `fixed` today, and the SDK maps any other value to",
+                "the default, `floating`, so a game only ever sees those two."
+              ]
             }
           }
         }
@@ -2393,9 +2437,10 @@
       "$comment": [
         "A platform-currency reward is on its way — the game's SERVER has just",
         "moved (or is about to move) a progression mapped onto a platform currency,",
-        "and the game would like the arcade's wallet to show it landing: a pending",
-        "state now and, when the platform confirms the grant, the currency flying",
-        "from `origin` into the wallet.",
+        "and the game would like the arcade to show it landing: the currency flying",
+        "from `origin` into the arcade's chrome — in the Gem Arcade, into its Gem",
+        "button at the frame's top-left — and the total moving when the platform",
+        "confirms the grant.",
         "",
         "A PRESENTATION CUE, NOT A CLAIM. Nothing here is trusted as a number. The",
         "amount that lands and the player's new total reach the parent from gem-api",
@@ -2408,7 +2453,8 @@
         "`origin` is where the flight starts, in CSS px of the frame's own",
         "coordinate space — the same space `gem.viewport` speaks — measured from",
         "the frame's top-left corner; the parent translates it into its own page.",
-        "Absent, the arcade animates at the wallet alone. Integers, like",
+        "Absent, the Gem Arcade flies the confirmed grant from the middle of the",
+        "frame, as it does a grant no cue announced. Integers, like",
         "`gem.viewport`'s insets: a fractional pixel is not a placement, and the",
         "SDK rounds and clamps on the way out. 16384 is a bound, not a size.",
         "",
@@ -2428,10 +2474,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`): the",
-        "arcade's wallet shows Gems and Tickets side by side and flies a payout",
-        "into the one `currencySlug` names. `origin` is the centre of the game's icon for",
-        "that currency — its gem, or its ticket."
+        "celebration of its own. The same holds for Tickets (`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."
       ],
       "fields": {
         "currencySlug": { "kind": "string", "maxLength": 32 },
@@ -2487,6 +2532,12 @@
         "docks its wallets beside the frame rather than over it, this changes",
         "nothing.",
         "",
+        "THE GEM ARCADE DRAWS NO WALLET OVER A GAME (since 2026-10-11): the player",
+        "sees their balances in its Gem menu and payouts fly into its Gem button, so",
+        "it advertises this message, accepts it, and changes nothing on screen — no",
+        "wallet is shown, popped up or reserved whatever the game says. The rules",
+        "above are for a parent that does draw wallets over the frame.",
+        "",
         "A PRESENTATION REQUEST ONLY. Not an authorization control, and it carries no",
         "numbers: the parent takes every figure it shows from the platform. A game",
         "never draws a platform balance itself and never implements a pending state.",
@@ -2511,6 +2562,83 @@
       "rateLimit": { "perMinute": 60 }
     },
 
+    {
+      "type": "gem.controlsDeclare",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Which of the player's camera and controls settings this game leaves to",
+        "the player and which it decides itself — Roblox's UserChoice versus",
+        "`StarterPlayer.Dev*`, declared at runtime (owner decision 2026-10-11).",
+        "The settings are the four camera and controls fields of",
+        "`gem.prefs.recommended`; the parent's Settings panel shows each row",
+        "according to this.",
+        "",
+        "  'player'  the game applies the Arcade's value (or the player's own",
+        "            in-game choice, which wins); a normal row",
+        "  'game'    the game decides this itself; the parent shows the row",
+        "            disabled, \"Set by this game\"",
+        "  absent    the game does not use this setting at all",
+        "",
+        "SCREEN STATE, NOT A TOGGLE, like `gem.walletDisplay`. Each message is the",
+        "whole answer and the latest one wins; nothing accumulates. The SDK holds",
+        "the latest declaration and re-sends it after every handshake, deduped per",
+        "connection, so a parent that reconnects never shows a stale panel. With no",
+        "message at all, the parent treats every setting as unused by this game.",
+        "A declaration is per game session: the parent forgets it when the game is",
+        "left.",
+        "",
+        "EACH VALUE IS A CODE, NOT AN ENUM, and an unknown KEY is ignored, so the",
+        "vocabulary can grow without an older parent refusing the whole message:",
+        "the SDK drops any key or value it does not know before sending, and a",
+        "parent ignores any it does not know on receipt — treating that setting",
+        "as absent.",
+        "",
+        "A PRESENTATION REQUEST ONLY. Not an authorization control: it changes",
+        "which rows of the parent's own panel are editable, and nothing the game",
+        "receives.",
+        "",
+        "Gated by `controls`: sent only to a parent that advertised it."
+      ],
+      "fields": {
+        "uses": {
+          "kind": "object",
+          "$comment": "One optional entry per setting, each `player` or `game`. An empty object is a valid declaration: the game uses none of them.",
+          "fields": {
+            "lookSensitivity": {
+              "kind": "string",
+              "maxLength": 16,
+              "format": "code",
+              "optional": true,
+              "$comment": "`player` or `game` for `gem.prefs.recommended.lookSensitivity`."
+            },
+            "gamepadLookSensitivity": {
+              "kind": "string",
+              "maxLength": 16,
+              "format": "code",
+              "optional": true,
+              "$comment": "`player` or `game` for `gem.prefs.recommended.gamepadLookSensitivity`."
+            },
+            "invertLookY": {
+              "kind": "string",
+              "maxLength": 16,
+              "format": "code",
+              "optional": true,
+              "$comment": "`player` or `game` for `gem.prefs.recommended.invertLookY`."
+            },
+            "touchMovement": {
+              "kind": "string",
+              "maxLength": 16,
+              "format": "code",
+              "optional": true,
+              "$comment": "`player` or `game` for `gem.prefs.recommended.touchMovement`."
+            }
+          }
+        }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
+
     {
       "type": "gem.menu",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -218,6 +218,12 @@
         "gem.menu",
         "gem.menuSelect"
       ]
+    },
+    "controls": {
+      "implemented": true,
+      "gates": [
+        "gem.controlsDeclare"
+      ]
     }
   }
 }