@indiegems/gem-web-sdk 11.1.2 → 13.0.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` is the first — 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`. 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",
@@ -1514,6 +1584,90 @@
       },
       "rateLimit": { "perMinute": 30 }
     },
+    {
+      "type": "gem.ticketEvent",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "A matchmaking ticket this player is on changed state. Gated by the",
+        "`ticketEvents` capability; the mapping lives in schema/capabilities.json",
+        "and nowhere else.",
+        "",
+        "gem-api's `matchmaking_ticket_queued`, `_matched`, `_expired`,",
+        "`_cancelled` and `_failed`, which it sends to EVERY player a ticket",
+        "seats: its owner and, for a party's ticket, every member. A party",
+        "queues as one ticket and it is the leader's, so a member's frame is on a",
+        "ticket it never created and cannot read — only the owner may. This is",
+        "the only thing that can tell that frame its party is queued, and how",
+        "the wait ended.",
+        "",
+        "A HINT, LIKE EVERY RELAY, and for a member a hint with nothing behind",
+        "it to re-read. So the frame gives it exactly the authority of a",
+        "display: a member's view of the ticket can be shown and cannot be",
+        "cancelled or kept alive, and nothing is entered on the strength of it.",
+        "A `matched` makes the frame look for the seat over its OWN token, which",
+        "is where a room is believed. For the ticket's OWNER the event is a cue",
+        "to ask the platform at once, exactly as a relayed match start is.",
+        "",
+        "ITS OWN TYPE, for the reason gem.seatedEvent gives: an unknown TYPE is",
+        "ignored by any frame, and the capability keeps the parent from sending",
+        "it to a frame that would not understand it.",
+        "",
+        "NOTHING ABOUT ANYBODY CROSSES. The push names no player and no other",
+        "ticket, and neither does this. The templates gem-api lists on `queued`",
+        "stop at the parent: the frame's game chose them, or its leader's did.",
+        "",
+        "`event` IS CLOSED, and it is the ticket's status. A status gem-api adds",
+        "later is not relayed until this enum names it — the parent drops what",
+        "it cannot name rather than send a value the frame would refuse.",
+        "",
+        "PARENT TO FRAME ONLY. A frame-authored ticket event would let a game",
+        "tell the parent, and through it nobody, that a queue it does not own",
+        "moved."
+      ],
+      "fields": {
+        "event": {
+          "kind": "enum",
+          "values": ["queued", "matched", "expired", "cancelled", "failed"],
+          "$comment": "The ticket's status after the change. `queued` is its creation; every other value is final."
+        },
+        "ticketId": { "kind": "string", "maxLength": 64 },
+        "partySize": {
+          "kind": "int",
+          "min": 1,
+          "max": 64,
+          "optional": true,
+          "$comment": "How many players the ticket seats. Sent with `queued`."
+        },
+        "queuedAt": {
+          "kind": "int",
+          "min": 0,
+          "max": 4102444800,
+          "optional": true,
+          "$comment": "When the ticket was queued, in Unix seconds. Sent with `queued`."
+        },
+        "expiresAt": {
+          "kind": "int",
+          "min": 0,
+          "max": 4102444800,
+          "optional": true,
+          "$comment": "When the ticket gives up if it is still waiting, in Unix seconds. Sent with `queued`. A frame that has seen no ending once this long has passed stops showing the ticket as waiting: the pushes are not retried, and a member has no other way to learn the ticket is over."
+        },
+        "reason": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": "Why a ticket ended without a match: `timed_out`, `heartbeat_lapsed`, `requested`, `party_changed`, `handoff_failed`. Open, so a reason added later reaches the game."
+        },
+        "roomId": {
+          "kind": "string",
+          "maxLength": 64,
+          "optional": true,
+          "$comment": "The room a `matched` ticket's players were seated in. A place to look, not a seat: the frame reads the room over its own token and checks this player is a member."
+        }
+      },
+      "rateLimit": { "perMinute": 60 }
+    },
 
     {
       "type": "gem.signalEvent",
@@ -2655,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",
@@ -2736,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",
         "",
@@ -2768,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,
@@ -2807,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",
@@ -3346,6 +3517,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",
@@ -3353,6 +3612,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": [
@@ -93,6 +99,12 @@
         "gem.autoStartFailedEvent"
       ]
     },
+    "ticketEvents": {
+      "implemented": true,
+      "gates": [
+        "gem.ticketEvent"
+      ]
+    },
     "partySeating": {
       "implemented": true,
       "gates": [