@indiegems/gem-web-sdk 11.1.1 → 12.0.0

package/schema/bridge.v1.json

@@ -1514,6 +1514,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",

package/schema/capabilities.public.json

@@ -93,6 +93,12 @@
         "gem.autoStartFailedEvent"
       ]
     },
+    "ticketEvents": {
+      "implemented": true,
+      "gates": [
+        "gem.ticketEvent"
+      ]
+    },
     "partySeating": {
       "implemented": true,
       "gates": [