@genex-ai/multiplayer 0.17.1 → 0.17.8

package/dist/chunk-4R7C2TLH.js

@@ -0,0 +1,68 @@
+// src/bridge-core.ts
+import { getColyseusAuth, getColyseusUrls, initEmbed, waitForPlayer } from "@genex-ai/embed-sdk";
+var embedIdentity = {
+  ready(gameId) {
+    const cfg = globalThis.__GENEX__;
+    if (gameId && cfg && typeof cfg.apiUrl === "string" && Array.isArray(cfg.dashboardOrigins)) {
+      initEmbed({
+        slug: gameId,
+        apiUrl: cfg.apiUrl,
+        dashboardOrigins: cfg.dashboardOrigins.filter((o) => typeof o === "string")
+      });
+    }
+    return waitForPlayer();
+  },
+  auth: () => getColyseusAuth(),
+  urls: () => getColyseusUrls()
+};
+var MAX_QUEUED_EVENTS = 4096;
+function push(e, event) {
+  if (e.q.length >= MAX_QUEUED_EVENTS) {
+    if (e.overflowed) e.q.splice(1, 1);
+    else {
+      e.overflowed = true;
+      e.q.splice(0, 2, { type: "warning", message: "genex bridge: event queue full; drain it every frame (oldest events dropped)" });
+    }
+  }
+  e.q.push(event);
+}
+var warningEvent = (message) => ({ type: "warning", message: `genex bridge: ${message}` });
+function eventJson(event) {
+  try {
+    return JSON.stringify(event);
+  } catch (err) {
+    const name = typeof event.kind === "string" ? event.kind : event.type;
+    return JSON.stringify(warningEvent(`event ${JSON.stringify(name)} dropped: JSON cannot carry it (${errorMessage(err)})`));
+  }
+}
+function drainQueueJson(e) {
+  e.overflowed = false;
+  return `[${e.q.splice(0).map(eventJson).join(",")}]`;
+}
+var isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+var errorCode = (err) => {
+  const c = isObject(err) || err instanceof Error ? err.code : void 0;
+  return typeof c === "number" && Number.isFinite(c) ? c : 0;
+};
+var errorMessage = (err) => err instanceof Error ? err.message : typeof err === "string" ? err : "join failed";
+function parseJson(json, what) {
+  if (typeof json !== "string") throw new TypeError(`genex bridge: ${what} must be a JSON string`);
+  return JSON.parse(json);
+}
+function parseObject(json, what) {
+  const v = parseJson(json, what);
+  if (!isObject(v)) throw new TypeError(`genex bridge: ${what} must be a JSON object`);
+  return v;
+}
+
+export {
+  embedIdentity,
+  push,
+  warningEvent,
+  drainQueueJson,
+  isObject,
+  errorCode,
+  errorMessage,
+  parseJson,
+  parseObject
+};

package/dist/{chunk-C52XFIB6.js → chunk-CSQEEANB.js}

@@ -1,13 +1,26 @@
 // src/protocol.ts
 var PROTOCOL_VERSION = 3;
 var MIN_PROTOCOL_VERSION = 3;
+var AUTHORITY_PROTOCOL_VERSION = 4;
+var AUTHORITY_MIN_PROTOCOL_VERSION = 4;
+var RELAY_WINDOW = Object.freeze({ min: MIN_PROTOCOL_VERSION, max: PROTOCOL_VERSION });
+var AUTHORITY_WINDOW = Object.freeze({
+  min: AUTHORITY_MIN_PROTOCOL_VERSION,
+  max: AUTHORITY_PROTOCOL_VERSION
+});
+function inProtocolWindow(sent, window) {
+  return typeof sent === "number" && Number.isInteger(sent) && sent >= window.min && sent <= window.max;
+}
 var RoomType = {
   /** The plain relay room: joinOrCreate, fullest-first placement. */
   PLAY: "play",
   /** The matchmaking search pool. No game session — it only hands out seat reservations. */
   QUEUE: "queue",
   /** A capped match arena: seat reservation (matchmade), create (private lobby) or joinById (invite). */
-  MATCH: "match"
+  MATCH: "match",
+  /** A server-authoritative room (§17): the server runs the game's room module, clients send input.
+   *  Served by the authority cluster, never by a relay. */
+  AUTHORITY: "authority"
 };
 var JoinOption = {
   /** The game's slug. Must equal the embed token's `slug` claim. */
@@ -19,7 +32,100 @@ var JoinOption = {
   /** {@link PROTOCOL_VERSION}. Required. */
   PROTOCOL: "protocol"
 };
+var AuthorityJoinOption = {
+  /** The capabilities this client implements: at most {@link AuthorityCaps.MAX_CAPS} strings of at
+   *  most {@link AuthorityCaps.MAX_CAP_CHARS} characters; absent = []. Any other value is refused
+   *  with 400 by every authority room. */
+  CAPS: "caps",
+  /** The client's SDK and version, `<sdk>/<version>` (§17.1): counted so a protocol bump can see whom it would
+   *  strand. Telemetry only: anything malformed is counted as unknown, never refused. */
+  SDK: "sdk",
+  /** The pool this join asks for (§17.2 *Choosing a room*): rooms are found by it beside the game and
+   *  the region. Absent or empty = the game's one pool, as a client that names no room has always had.
+   *  Malformed (authority/room-key.ts `matchKeyOf`) is refused with 400. */
+  MATCH_KEY: "matchKey",
+  /** `true` on a `create` makes a private room: no matchmaking reaches it, only its code. Any other
+   *  type is refused with 400. */
+  PRIVATE: "private",
+  /** The room this seat lost (§17.13 *Drain and rejoin*): a room code. Rooms are found by it too, so a
+   *  lost room's seats meet in one successor, which alone reads the room's hand-off. Absent or empty =
+   *  no successor. Malformed is refused with 400. */
+  SUCCESSOR_OF: "successorOf",
+  /** `true` keeps a successor closed to the game's pool: the lost room was private. Any other type is
+   *  refused with 400. */
+  SUCCESSOR_CLOSED: "successorClosed"
+};
+var AUTHORITY_SDK_LABEL = "ts/0.17.8";
+var AuthorityCaps = {
+  /** Decodes and draws §17.10's physics bodies. A physics room refuses a join without it (426). An
+   *  SDK sends it only once its drawing passes `physics-draw.json` and, for an engine SDK, its own
+   *  probe on the pinned core (§17.10 *Conformance*). */
+  PHYSICS: "physics@1",
+  /** Also predicts a predicting room's bodies (§17.11): it builds the room's world from `physDesc`,
+   *  adopts and replays keyframes, and draws its predicted bodies. A client sends it beside
+   *  `physics@1`, never alone; a room serves the same state to both, so the cap only says what the
+   *  client does. An SDK sends it only once it passes `physics-predict.json` (§17.11 *Conformance*). */
+  PHYSICS_PREDICT: "physics@2",
+  /** Reconciles a predicting room's repeated inputs (§17.11 *Input pacing*): it predicts its own
+   *  entity from the state as stepped through `ackSeq + inRep`, not `ackSeq`. A predicting room repeats
+   *  a starved seat's last input only for a client that sends it; without it a starved tick steps
+   *  nothing, as before. An SDK sends it only once it passes `input-repeat.json`. */
+  INPUT_REPEAT: "repeat@1",
+  /** Collides with, rides and draws a room's declared lifts (§17.11 *Lifts*). A room that declares
+   *  lifts refuses a join without it (426, `lifts@1 required`): a client that does not pose them
+   *  would fall through them in its prediction. An SDK sends it only once it passes `lifts.json`. */
+  LIFTS: "lifts@1",
+  /** Writes into each input the server tick its prediction steps it at (`AuthorityInput.tick`, modulo
+   *  2^16; §17.11 *The input's tick*): the server then judges a re-timed input (a tick that steps two of
+   *  a seat's inputs or none) at the tick it was meant for — a firstperson view on a spinning lift
+   *  carried by the lift's turn between the two, lag compensation's lift frames. Without it the field
+   *  is ignored, as before. */
+  INPUT_TICK: "tick@1",
+  /** Moves the seat's inputs and motion state to the fast channel (§17.12): redundant input datagrams
+   *  and ack-delta snapshots over UDP or WebTransport, the WebSocket kept for everything else. Sent
+   *  beside `tick@1`. An SDK sends it only once it passes `fast-transport.json` and its transport
+   *  tests; a room that does not offer the channel ignores it. */
+  FAST: "fast@1",
+  /** The seat can come back to the fast channel after a fallback (§17.12 *Return to the channel*): it asks
+   *  for a fresh binding, proves the path and swaps. Sent beside `fast@1`; a host that does not know it
+   *  ignores it, and a client asks only a host whose binding says `rev` 2. */
+  FAST_RETURN: "fast-return@1",
+  MAX_CAPS: 16,
+  MAX_CAP_CHARS: 32
+};
+function capsOf(value) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value) || value.length > AuthorityCaps.MAX_CAPS) return null;
+  const ok = value.every((cap) => typeof cap === "string" && cap.length <= AuthorityCaps.MAX_CAP_CHARS);
+  return ok ? [...value] : null;
+}
+var AUTHORITY_PHYSICS_UNITS = 6;
+var SIXTIETHS_PER_SECOND = 60;
+var AUTHORITY_PHYSICS_TICK_WEIGHT = { 20: 1, 30: 1, 60: 1, 120: 2 };
+function authorityRoomUnits(physics, tickHz) {
+  return physics ? AUTHORITY_PHYSICS_UNITS * AUTHORITY_PHYSICS_TICK_WEIGHT[tickHz] : 1;
+}
+function authorityPhysicsBudgetSixtieths(tickHz) {
+  return SIXTIETHS_PER_SECOND / tickHz * AUTHORITY_PHYSICS_TICK_WEIGHT[tickHz];
+}
+var MS_PER_SECOND = 1e3;
+function authorityTickBudgetMs(tickHz) {
+  return authorityPhysicsBudgetSixtieths(tickHz) * MS_PER_SECOND / SIXTIETHS_PER_SECOND;
+}
+var AUTHORITY_ENCODER_BUFFER_BYTES = 1048576;
 var SERVER_OWNED_JOIN_OPTIONS = ["clients", "preset", "winCondition", "config", "matchmade"];
+var AUTHORITY_SERVER_OWNED_JOIN_OPTIONS = [
+  ...SERVER_OWNED_JOIN_OPTIONS,
+  "moduleSha",
+  "tickHz",
+  "maxPlayers",
+  "lagComp",
+  "seed",
+  "units",
+  "leaseId",
+  "region",
+  "createdBy"
+];
 var JoinError = {
   /** A server-owned option was sent. */
   BAD_OPTION: 400,
@@ -27,8 +133,21 @@ var JoinError = {
   AUTH_REQUIRED: 401,
   /** Token for another game ('wrong game'), or the room's guest cap is full. */
   FORBIDDEN: 403,
-  /** `protocol` missing or outside [MIN_PROTOCOL_VERSION, PROTOCOL_VERSION]. Update the client. */
-  PROTOCOL_UNSUPPORTED: 426
+  /** A join by code entered through another region than the room's (§17.2 *Choosing a room*): the
+   *  client tries its next region. */
+  WRONG_REGION: 421,
+  /** `protocol` missing or outside the room type's window ({@link RELAY_WINDOW},
+   *  {@link AUTHORITY_WINDOW}). Update the client. */
+  PROTOCOL_UNSUPPORTED: 426,
+  // ---- authority rooms only (§17.2); a relay room never answers these ----
+  /** The game's owner is not entitled to server-authoritative rooms. Terminal: do not retry. */
+  NOT_ENTITLED: 402,
+  /** The owner's room quota, concurrency cap or credits refused a NEW room. Live rooms never close for it. */
+  ROOM_QUOTA: 429,
+  /** The game has no published room module on this channel, or it could not be loaded. */
+  MODULE_UNAVAILABLE: 424,
+  /** No authority server can take the room right now, or admission could not be checked. Retry later. */
+  AUTHORITY_CAPACITY: 503
 };
 var STAGING_ROOM_PREFIX = "preview--";
 var roomKeyFor = (slug, channel) => channel === "staging" ? `${STAGING_ROOM_PREFIX}${slug}` : slug;
@@ -97,6 +216,14 @@ var RATE_LANES = {
 };
 var GLOBAL_RATE = { rate: 180, burst: 360 };
 var MAX_MESSAGES_PER_SECOND = 1200;
+var AUTHORITY_MAX_MESSAGES_PER_SECOND = 2400;
+var AUTHORITY_MAX_FRAME_BYTES = 4 * 1024;
+var SeatCloseReason = {
+  /** Its socket passed {@link AUTHORITY_MAX_MESSAGES_PER_SECOND} (4002). */
+  MessageFlood: "message_flood",
+  /** Its input had not changed for the room's idle limit (4408). */
+  SeatIdle: "seat_idle"
+};
 var MESSAGE_LANE = {
   [ClientMessage.STATE]: "state",
   [ClientMessage.STATE_SNAP]: "state",
@@ -141,8 +268,48 @@ var CloseCode = {
   /** The player's session was revoked (signed out from the dashboard). Do not rejoin with it. */
   REVOKED: 4401,
   /** A newer session of the same player took the seat (second tab, or the page reloaded). */
-  SUPERSEDED: 4409
+  SUPERSEDED: 4409,
+  /** Authority rooms: the seat's input had not changed for the room's idle limit (§17.6 *Room lifetime*). */
+  IDLE: 4408,
+  // ---- authority rooms only (§17.6), terminal ----
+  /** The operator or the platform halted the room (kill switch, takedown, disabled game). */
+  MODULE_HALTED: 4500,
+  /** The game's room module broke its limits or threw; the room is gone. */
+  MODULE_FAULT: 4501
+};
+var AuthorityCloseCode = {
+  /** A call ran past its hard timeout (an infinite loop, a long microtask). */
+  ModuleTimeout: "module_timeout",
+  /** The module hit its memory limit, or the heap poll caught it near the limit. */
+  ModuleMemory: "module_memory",
+  /** The module threw (or failed to load) too many times. */
+  ModuleError: "module_error",
+  /** The module's output broke the wire limits too many times. */
+  ModuleOutputInvalid: "module_output_invalid",
+  /** The module stayed under the hard timeout but over the mean CPU budget for a whole window. */
+  ModuleBudget: "module_budget",
+  /** The operator or the platform stopped the room (kill switch, takedown, disabled game). */
+  Halted: "halted",
+  /** isolated-vm's wall-clock backstop stopped a call while the guest's own CPU stayed under its limit: the
+   *  host stalled (contention, a GC pause, descheduled). The guest was cut off mid-call, so it is
+   *  never called again; the room ends, but the module is not at fault. */
+  HostStall: "host_stall",
+  /** The room's physics passed the physics meter for the third strike (§17.10). */
+  PhysicsBudget: "physics_budget",
+  /** The room reached its age limit (§17.6 *Room lifetime*), announced like a drain. Not a fault. */
+  RoomAge: "room_age",
+  /** The room sent more than its ceiling for a whole window (§17.6 *The downlink budget*): its module writes
+   *  too much state or too many events for its seats. Lower what it writes; no strike comes first. */
+  ModuleBandwidth: "module_bandwidth",
+  /** The physics core answered `internal` (C§11.3): every physics room on that instance ends. Never
+   *  the module's fault. */
+  PhysicsInternal: "physics_internal"
 };
+function authorityCloseCodeOf(reason) {
+  const known = Object.values(AuthorityCloseCode);
+  return known.includes(reason) ? reason : null;
+}
+var AUTHORITY_ROOM_ENDED_TEXT = "This match ended because of a problem with the game. Please try again.";
 var Limits = {
   ROOM_MAX_CLIENTS: 64,
   MAX_NAME_CHARS: 64,
@@ -207,6 +374,29 @@ var RelayTiming = {
   /** Embed tokens are re-checked for revocation on this cadence (REVOKED close on hit). */
   REVOCATION_SWEEP_MS: 3e4
 };
+var AuthorityTiming = {
+  /** Fixed simulation step rate when the module does not choose one. */
+  TICK_HZ: 30,
+  /** How far behind the server clock clients render other entities (the interpolation buffer). */
+  RENDER_DELAY_MS: 100,
+  /** The furthest back lag compensation rewinds for one input's `seen` snapshot. */
+  MAX_REWIND_MS: 500,
+  /** Inputs buffered per seat before the oldest are folded away. */
+  INPUT_BUFFER: 32,
+  /** State patch cadence. The spike measured its feel gates at 50 ms; 33 is an owner call. */
+  PATCH_INTERVAL_MS: 50,
+  /** A predicting room repeats a starved seat's last input for at most this long of repeats not yet
+   *  paid back (§17.11 *Input pacing*), then the seat holds: a vanished player stops instead of
+   *  driving into a wall. Rocket League's client resends its last 10 frames of input in every packet
+   *  (83 ms at 120 Hz), the gap its server's repeat bridges; 100 ms is that rounded up to whole ticks
+   *  at every tick rate (12 at 120 Hz, 6 at 60, 3 at 30). */
+  INPUT_REPEAT_MAX_MS: 100,
+  /** One starve run is repeated for at most this long; past it the seat holds as before (§17.11 *Input
+   *  pacing*): a stick steady before a starve is less and less likely to stay so through it, and on
+   *  car-ball (5 runs a profile) 4 repeats a run at 120 Hz kept its corrections over 20 u at the base's
+   *  under loss where 12 doubled them. 4 ticks at 120 Hz, 2 at 60, 1 at 30. */
+  INPUT_REPEAT_RUN_MS: 33
+};
 var ClientReconnection = {
   enabled: true,
   minUptime: 0,
@@ -284,9 +474,25 @@ var ClockSync = {
 export {
   PROTOCOL_VERSION,
   MIN_PROTOCOL_VERSION,
+  AUTHORITY_PROTOCOL_VERSION,
+  AUTHORITY_MIN_PROTOCOL_VERSION,
+  RELAY_WINDOW,
+  AUTHORITY_WINDOW,
+  inProtocolWindow,
   RoomType,
   JoinOption,
+  AuthorityJoinOption,
+  AUTHORITY_SDK_LABEL,
+  AuthorityCaps,
+  capsOf,
+  AUTHORITY_PHYSICS_UNITS,
+  AUTHORITY_PHYSICS_TICK_WEIGHT,
+  authorityRoomUnits,
+  authorityPhysicsBudgetSixtieths,
+  authorityTickBudgetMs,
+  AUTHORITY_ENCODER_BUFFER_BYTES,
   SERVER_OWNED_JOIN_OPTIONS,
+  AUTHORITY_SERVER_OWNED_JOIN_OPTIONS,
   JoinError,
   STAGING_ROOM_PREFIX,
   roomKeyFor,
@@ -301,10 +507,17 @@ export {
   RATE_LANES,
   GLOBAL_RATE,
   MAX_MESSAGES_PER_SECOND,
+  AUTHORITY_MAX_MESSAGES_PER_SECOND,
+  AUTHORITY_MAX_FRAME_BYTES,
+  SeatCloseReason,
   MESSAGE_LANE,
   CloseCode,
+  AuthorityCloseCode,
+  authorityCloseCodeOf,
+  AUTHORITY_ROOM_ENDED_TEXT,
   Limits,
   RelayTiming,
+  AuthorityTiming,
   ClientReconnection,
   POSE_KEYS,
   Interpolation,

package/dist/chunk-FPWP22Y7.js

@@ -0,0 +1,143 @@
+import {
+  ClientReconnection,
+  JoinError,
+  PROTOCOL_VERSION
+} from "./chunk-CSQEEANB.js";
+
+// src/join.ts
+import { Client as Client2 } from "@colyseus/sdk";
+
+// src/relay-select.ts
+import { Client } from "@colyseus/sdk";
+var RELAY_SELECT_DEFAULTS = {
+  SAMPLES: 3,
+  // Well past Colyseus's 1.5 s, which a loading web export's main thread was measured exceeding.
+  TIMEOUT_MS: 4e3,
+  // A far relay's sample lands within a few hundred ms of a near one's; a dead relay must not hold
+  // a working join for the full timeout.
+  GRACE_MS: 1e3
+};
+async function selectRelayUrl(urls, options = {}) {
+  const first = urls[0];
+  if (first === void 0) throw new Error("genex multiplayer: `urls` must contain at least one relay URL");
+  if (urls.length === 1) return first;
+  const probe = options.probe ?? defaultProbe;
+  const samples = Math.max(1, options.samples ?? RELAY_SELECT_DEFAULTS.SAMPLES);
+  const timeoutMs = options.timeoutMs ?? RELAY_SELECT_DEFAULTS.TIMEOUT_MS;
+  const graceMs = options.graceMs ?? RELAY_SELECT_DEFAULTS.GRACE_MS;
+  const best = urls.map(() => void 0);
+  await new Promise((resolve) => {
+    let pending = urls.length * samples;
+    let grace;
+    const ceiling = setTimeout(done, timeoutMs);
+    function done() {
+      clearTimeout(ceiling);
+      clearTimeout(grace);
+      resolve();
+    }
+    const settle = () => {
+      if (--pending === 0) done();
+    };
+    urls.forEach((url, i) => {
+      for (let n = 0; n < samples; n++) {
+        let sample;
+        try {
+          sample = probe(url, timeoutMs);
+        } catch (err) {
+          sample = Promise.reject(err);
+        }
+        sample.then(
+          (ms) => {
+            if (Number.isFinite(ms) && ms >= 0) {
+              best[i] = Math.min(best[i] ?? Infinity, ms);
+              grace ??= setTimeout(done, graceMs);
+            }
+            settle();
+          },
+          settle
+        );
+      }
+    });
+  });
+  let pick = -1;
+  best.forEach((ms, i) => {
+    if (ms !== void 0 && (pick < 0 || ms < best[pick])) pick = i;
+  });
+  if (pick < 0) {
+    console.warn(`genex multiplayer: no relay answered the latency probe \u2014 connecting to ${first}`);
+    return first;
+  }
+  return urls[pick];
+}
+var defaultProbe = (url, timeoutMs) => new Client(url).getLatency({ pingCount: 1, timeout: timeoutMs });
+
+// src/join.ts
+var resolveAuth = (auth) => typeof auth === "function" ? auth() : auth;
+async function relayClient(opts) {
+  if (opts.url) return new Client2(opts.url);
+  return new Client2(await selectRelayUrl(opts.urls));
+}
+function joinOptions(gameId, name, auth) {
+  return {
+    gameId,
+    name,
+    embedToken: resolveAuth(auth)?.embedToken,
+    protocol: PROTOCOL_VERSION
+  };
+}
+var isProtocolRefusal = (err) => !!err && typeof err === "object" && err.code === JoinError.PROTOCOL_UNSUPPORTED;
+var warnProtocolRefusal = () => console.error(
+  `[multiplayer] the relay refused protocol ${PROTOCOL_VERSION} (code 426) \u2014 this game was built with a @genex-ai/multiplayer that this relay no longer serves. Update the package and republish.`
+);
+var explainJoinRefusal = (err) => {
+  if (isProtocolRefusal(err)) warnProtocolRefusal();
+  throw err;
+};
+
+// src/room-lifecycle.ts
+function useSdkReconnection(room) {
+  const r = room.reconnection;
+  r.enabled = ClientReconnection.enabled;
+  r.minUptime = ClientReconnection.minUptime;
+  r.delay = ClientReconnection.delay;
+  r.minDelay = ClientReconnection.minDelay;
+  r.maxDelay = ClientReconnection.maxDelay;
+  r.maxRetries = ClientReconnection.maxRetries;
+  r.maxEnqueuedMessages = ClientReconnection.maxEnqueuedMessages;
+  r.enqueuedMessages.length = 0;
+  return room;
+}
+function withoutReconnection(room) {
+  room.reconnection.enabled = false;
+  return room;
+}
+function waitForFirstState(room, timeoutMs) {
+  return new Promise((resolve) => {
+    const onState = () => {
+      clearTimeout(timer);
+      resolve(true);
+    };
+    const timer = setTimeout(() => {
+      room.onStateChange.remove(onState);
+      resolve(false);
+    }, timeoutMs);
+    room.onStateChange.once(onState);
+  });
+}
+function seedsInterpolation(id, selfId, sendTime) {
+  return id !== selfId && sendTime != null;
+}
+
+export {
+  RELAY_SELECT_DEFAULTS,
+  defaultProbe,
+  relayClient,
+  joinOptions,
+  isProtocolRefusal,
+  warnProtocolRefusal,
+  explainJoinRefusal,
+  useSdkReconnection,
+  withoutReconnection,
+  waitForFirstState,
+  seedsInterpolation
+};