@indiegems/gem-web-sdk 12.0.0 → 13.1.0

package/schema/bridge.v1.json

@@ -563,7 +563,13 @@
         "`avatar3dIconUrl`) is re-sent the same way: whenever it changes, from",
         "either tab of the parent's picker, the whole message goes again. It is",
         "a separate worn choice from the portrait — wearing one never changes",
-        "the other — so a message may carry either, both or neither."
+        "the other — so a message may carry either, both or neither.",
+        "",
+        "`avatars3d` (one worn character per rig family) is re-sent the same",
+        "way, and also after a 3D character bought through",
+        "`gem.requestAvatar3dPurchase` is worn: the parent sends this message",
+        "BEFORE it answers `gem.purchaseResult`, so a game that redraws from",
+        "the player already shows the purchase when the answer lands."
       ],
       "fields": {
         "untrusted": {
@@ -672,6 +678,70 @@
           "optional": true,
           "$comment": "The worn 3D character's PORTRAIT RENDER (gem-api `avatar_3d_icon_url`) — a picture of the model, for a roster or a menu where loading the model is too much. NOT the 2D portrait (`avatarIconUrl`), which is a separate worn choice. Absent when no 3D character is worn. Same pin caveat as `avatarIconUrl`."
         },
+        "avatars3d": {
+          "kind": "array",
+          "maxItems": 8,
+          "optional": true,
+          "$comment": [
+            "Every 3D character the player WEARS, one per RIG FAMILY (gem-api",
+            "`avatars_3d`). A family is a rig contract — `small_human` and",
+            "`adult_human` today — and a player wears at most one character per",
+            "family, so a game that accepts several families reads the one it",
+            "draws by `family`.",
+            "",
+            "THE FLAT FIELDS STAY, AND THEY ARE ONE OF THESE. `avatar3dId`,",
+            "`avatar3dModelUrl` and `avatar3dIconUrl` carry the worn character of",
+            "the game's FIRST declared family that has one (`small_human` when the",
+            "game declares none), so an older frame keeps working unchanged. A",
+            "parent that sends this list sends the flat fields too, describing the",
+            "same item as the matching entry.",
+            "",
+            "ABSENT OR EMPTY means no 3D character is worn in any family — the",
+            "game's default look — or an older parent. Bounded at eight, the",
+            "most families a game may declare; a parent sends the families the",
+            "game declared, in the game's order, and drops an entry it cannot fit",
+            "in these bounds rather than losing the whole message to it.",
+            "",
+            "THE URLS ARE BOUNDED AT 256, NOT 2048 like the flat fields, because",
+            "of `maxMessageBytes`: eight entries of two 2048-character URLs would",
+            "declare about 98 KB on their own, past the 64 KB cap the whole",
+            "message is held to. An item CDN URL is about a hundred characters.",
+            "",
+            "Platform-assigned, so it sits on the trusted side of the `untrusted`",
+            "split. `id` and `family` are BOUNDED HERE AND SHAPE-CHECKED BY THE",
+            "FRAME, as `avatar3dId` is: the frame keeps an entry only when `id` is",
+            "a UUID and `family` is a lowercase code, and drops the entry — never",
+            "the message — otherwise. The URLs carry `avatarIconUrl`'s pin caveat:",
+            "THE CONSUMER MUST PIN THE ORIGIN before fetching either."
+          ],
+          "items": {
+            "kind": "object",
+            "fields": {
+              "family": {
+                "kind": "string",
+                "maxLength": 32,
+                "$comment": "The rig family (gem-api `family`), e.g. `small_human` or `adult_human`. A lowercase code, checked by the frame rather than by a format here, so one family name this frame does not recognise costs the entry and never the message."
+              },
+              "id": {
+                "kind": "string",
+                "maxLength": 64,
+                "$comment": "The worn character's item-definition id (gem-api `avatar_3d_id`), a UUID. Shape-checked by the frame like `avatar3dId`."
+              },
+              "modelUrl": {
+                "kind": "string",
+                "maxLength": 256,
+                "format": "url",
+                "$comment": "The character's binary glTF (gem-api `model_url`), immutable at its URL and built on the family's rig. Same pin caveat as `avatarIconUrl`."
+              },
+              "iconUrl": {
+                "kind": "string",
+                "maxLength": 256,
+                "format": "url",
+                "$comment": "A rendered portrait of the character (gem-api `icon_url`). Same pin caveat as `avatarIconUrl`."
+              }
+            }
+          }
+        },
         "badges": {
           "kind": "array",
           "maxItems": 2,
@@ -874,8 +944,8 @@
             "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`.",
+            "the game side all four are present whenever the object is. They are the",
+            "player's Arcade-wide defaults; a game says nothing back about them.",
             "",
             "THE GRAPHICS TWO ARE OPTIONAL INSIDE IT TOO (owner decision",
             "2026-10-11): `graphicsQuality` and `graphicsQualityAuto`, the quality",
@@ -2611,8 +2681,8 @@
         "moved (or is about to move) a progression mapped onto a platform currency,",
         "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.",
+        "button, in whichever corner of the frame it sits — 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",
@@ -2739,7 +2809,16 @@
       "direction": "frameToParent",
       "transport": "port",
       "$comment": [
-        "Which of the player's camera and controls settings this game leaves to",
+        "DEPRECATED, NEVER SENT BY THIS SDK (owner decision 2026-10-12). The",
+        "arcade's Settings show the player's own Arcade-wide defaults and nothing",
+        "a game says, so `gem.controls.declare` is gone and the SDK no longer",
+        "advertises `controls`. A parent ACCEPTS AND DROPS it from an older SDK",
+        "for the N-1 window (DESIGN §9): no `unsupported_capability`, no",
+        "`rate_limited`, no answer. A sender stopping is not a breaking change,",
+        "so `v` stays; the type is removed from this schema in a later, separate",
+        "change.",
+        "",
+        "What it was: 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",
@@ -2820,9 +2899,7 @@
         "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; a parent MAY show a Settings entry for it",
-        "                   (the Gem Arcade no longer does: see below)",
+        "  settings         DEPRECATED, always false from this SDK: 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",
         "",
@@ -2852,16 +2929,22 @@
         "Gated by `gameMenu`: sent only to a parent that advertised it. To any",
         "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."
+        "`settings` IS DEPRECATED (owner decision 2026-10-12). It said the game",
+        "had a settings screen the parent's menu could open. A game's settings",
+        "open from its own button, never from the parent's menu, which holds the",
+        "player's Arcade-wide settings instead (they reach the game as",
+        "`gem.prefs.recommended`). This SDK ALWAYS SENDS `false` and never claims",
+        "a settings screen; an older one may still send `true`. A parent IGNORES",
+        "it: it draws no Settings entry for a game and sends no `gem.menuSelect`",
+        "for one. The field stays REQUIRED on the wire for the N-1 window (a",
+        "parent validating against an earlier copy refuses a `gem.menu` without",
+        "it); removing it is a later, separate change."
       ],
       "fields": {
-        "settings": { "kind": "boolean" },
+        "settings": {
+          "kind": "boolean",
+          "$comment": "DEPRECATED (owner decision 2026-10-12): always false from this SDK, and ignored by a parent. Required on the wire for the N-1 window."
+        },
         "items": {
           "kind": "array",
           "maxItems": 4,
@@ -2891,11 +2974,15 @@
       "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.",
+        "The player chose one of the game's entries in the arcade's menu: one of",
+        "the items `gem.menu` declared.",
         "",
-        "  entry: settings        open your settings screen",
         "  entry: item, id        the item with this id",
+        "  entry: settings        DEPRECATED (owner decision 2026-10-12): it",
+        "                         opened the settings screen of a game that sent",
+        "                         `settings: true`. This SDK never does, and ignores",
+        "                         it; an older one still opens its settings on it.",
+        "                         A parent sends it to no game.",
         "",
         "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",
@@ -2921,6 +3008,53 @@
       "rateLimit": { "perMinute": 60 }
     },
 
+    {
+      "type": "gem.gemCorner",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "The corner of the frame the game would like the arcade's own control",
+        "over it to sit in - in the Gem Arcade, the Gem button that opens its",
+        "menu. With no message at all it sits top-left, which is also the",
+        "recommendation: a game asks for another corner only when its own HUD",
+        "needs that one.",
+        "",
+        "SCREEN STATE, NOT A TOGGLE, like `gem.menu`. Each message is the whole",
+        "answer and the latest one wins. The SDK holds it from before the bridge",
+        "is up and re-sends it after every handshake, so a parent that reconnects",
+        "puts the control where the game had asked.",
+        "",
+        "A REQUEST, APPLIED ON THE PARENT'S TERMS. The parent holds a move while",
+        "the player is using the control or one of its surfaces is open, keeps a",
+        "minimum dwell between moves and applies only the latest request after",
+        "one, and puts a player's own choice of corner, should it ever offer one,",
+        "above the game's. So a game never lays out around the corner it asked",
+        "for: it lays out around the rectangles `gem.viewport` sends in",
+        "`reserved`, which say where the control actually is.",
+        "",
+        "ONE ENUM, AND IT ONLY GROWS. A later anchor is a new value behind a",
+        "capability of its own, sent only to a parent that advertised that",
+        "capability, so `v` does not move; a parent that advertised only",
+        "`gemCorner` is only ever sent these four.",
+        "",
+        "A PRESENTATION REQUEST ONLY, and not an authorization control. The game",
+        "picks one of four places the parent defines, never a coordinate, a size,",
+        "a visibility or a look; the parent's dwell and holds, not this rate",
+        "limit, are what keep a game from making the control run away.",
+        "",
+        "Gated by `gemCorner`: sent only to a parent that advertised it. To any",
+        "other, `gem.setGemCorner` returns false."
+      ],
+      "fields": {
+        "corner": {
+          "kind": "enum",
+          "values": ["top-left", "top-right", "bottom-left", "bottom-right"],
+          "$comment": "Physical, not logical: `left` is the frame's left edge in every language, so a right-to-left locale never mirrors a game's choice."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
+
     {
       "type": "gem.requestShare",
       "direction": "frameToParent",
@@ -3430,6 +3564,94 @@
         "$comment": "Bounds a BUGGY game. NOT a security control: a hostile game posts on the port it holds rather than calling the SDK, so a frame-side limit is one the attacker enforces against itself. See METER IT IN MONEY, SERVER-SIDE above."
       }
     },
+    {
+      "type": "gem.requestAvatar3dPurchase",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask the parent to buy one of THIS GAME's 3D avatars (an Arcade item of",
+        "type `avatar_3d` the game owns and has put on sale) with platform",
+        "currency, on the player's behalf, and WEAR it. Gated by the",
+        "`avatar3dPurchases` capability. Answered by the existing",
+        "`gem.purchaseResult`, whose `purchases` gate every SDK that can send",
+        "this also advertises.",
+        "",
+        "A SEPARATE MESSAGE, NOT A THIRD `purchaseKind`. `gem.requestPurchase`'s",
+        "`purchaseKind` is a closed enum, and `check-schema-freeze` refuses a",
+        "new value there because an N-1 parent would refuse the whole message.",
+        "And the two buy different things: that one grants a game-scope item",
+        "through the game's purchase catalog; this one grants a PLATFORM item",
+        "the player owns across the Arcade, priced on the item's own offer",
+        "(gem-api `GET /v1/games/{game_id}/avatars-3d`), and puts it on.",
+        "",
+        "EVERY OBLIGATION ON `gem.requestPurchase` APPLIES HERE, UNCHANGED:",
+        "payable currencies only, resolved exactly; price it yourself from",
+        "platform records, under the player's session (the offer's price in",
+        "`currencySlug`); the confirmation is the parent's own sheet, on user",
+        "activation only; back off after a cancel; one prompt at a time, quiet",
+        "after paint; one purchase per ask; meter it in money, server-side;",
+        "treat every field as untrusted text. A shortfall is never a sale.",
+        "",
+        "AND THREE OF ITS OWN:",
+        "",
+        "  WEAR IT, THEN SAY SO, THEN ANSWER. On success the purchase wears the",
+        "  avatar in its family's slot (gem-api's purchase does both in one",
+        "  transaction). Re-send `gem.player`, with the new character in",
+        "  `avatars3d` and in the flat `avatar3d*` fields where its family is the",
+        "  game's first, BEFORE `gem.purchaseResult` `ok`, so a game that",
+        "  redraws from the player never shows the old look after an `ok`.",
+        "",
+        "  ALREADY OWNED IS A DECLINE, NOT A SALE. A player who owns the item is",
+        "  answered `declined` / `already_owned` before any sheet; a parent may",
+        "  instead offer to wear it in its own chrome, which is a wear, not a",
+        "  purchase, and answers `declined` / `already_owned` all the same.",
+        "",
+        "  `purchaseId` IS OPTIONAL HERE. The SDK confirms an `ok` against the",
+        "  platform by asking whether the player now OWNS the item (gem-api",
+        "  `GET /v1/games/{game_id}/avatars-3d/{item_id}/owned`, with the game's",
+        "  own token), not by reading a receipt, so a parent may omit it. When",
+        "  sent it follows `gem.purchaseResult.purchaseId`'s rules: an opaque",
+        "  token minted for the disclosure, never an order id.",
+        "",
+        "REASONS. `gem.purchaseResult.reason`'s allow-list holds, with these",
+        "rows for this ask's own refusals:",
+        "",
+        "  CONDITION                                   OUTCOME      REASON",
+        "  the player already owns the item            declined     already_owned",
+        "  gem-api 404 not_found, item_not_purchasable, declined     not_purchasable",
+        "    or not_yet_writable (sales are off); the",
+        "    item is retired, not this game's, not an",
+        "    avatar, or not on sale",
+        "  the offer has no price in that currency     declined     no_price_in_currency",
+        "  gem-api 402 insufficient_balance or         declined     insufficient_funds",
+        "    wallet_negative",
+        "  gem-api 409 price_mismatch                  declined     price_mismatch",
+        "",
+        "and everything else as `gem.purchaseResult.reason` says — `error` for",
+        "anything not listed there or here."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Opaque and frame-chosen. Echo-only, exactly as on gem.requestPurchase: not unique across tabs or reloads, never a key on the money path, and not safe to write into a log line unescaped."
+        },
+        "itemId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "The avatar's item-definition id (gem-api `item_id` on an offer), a UUID. Matched by the parent against the offers it read itself; never interpolated into a path unchecked."
+        },
+        "currencySlug": {
+          "kind": "string",
+          "maxLength": 32,
+          "$comment": "Which platform currency to pay in, by its exact slug: GEMS or ARCADE_TICKETS. The offer must carry a price in it (`no_price_in_currency` otherwise). Frame-chosen and unconstrained here, exactly as on gem.requestPurchase, so the parent resolves it against platform records."
+        }
+      },
+      "rateLimit": {
+        "perMinute": 12,
+        "$comment": "gem.requestPurchase's limit and its argument: it bounds a BUGGY game, not a hostile one."
+      }
+    },
     {
       "type": "gem.purchaseResult",
       "direction": "parentToFrame",
@@ -3437,6 +3659,11 @@
       "$comment": [
         "The answer to one gem.requestPurchase. Gated by the `purchases` capability.",
         "",
+        "ALSO the answer to one gem.requestAvatar3dPurchase,",
+        "with the same fields and the same three outcomes; that message lists the",
+        "reasons of its own and says why `purchaseId` may be absent on its `ok`.",
+        "The `already_owned` reason is sent only there.",
+        "",
         "THREE OUTCOMES, AND A REASON ON THE TWO THAT ARE NOT `ok`. `outcome` says",
         "what the game should DO;",
         "`reason` says WHY, so a developer can fix a config mistake instead of",

package/schema/capabilities.public.json

@@ -27,6 +27,12 @@
         "gem.purchaseResult"
       ]
     },
+    "avatar3dPurchases": {
+      "implemented": true,
+      "gates": [
+        "gem.requestAvatar3dPurchase"
+      ]
+    },
     "friendChallenges": {
       "implemented": true,
       "gates": [
@@ -230,6 +236,12 @@
       "gates": [
         "gem.controlsDeclare"
       ]
+    },
+    "gemCorner": {
+      "implemented": true,
+      "gates": [
+        "gem.gemCorner"
+      ]
     }
   }
 }