@genex-ai/multiplayer 0.16.2 → 0.17.0

package/dist/chunk-C52XFIB6.js

@@ -0,0 +1,312 @@
+// src/protocol.ts
+var PROTOCOL_VERSION = 3;
+var MIN_PROTOCOL_VERSION = 3;
+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"
+};
+var JoinOption = {
+  /** The game's slug. Must equal the embed token's `slug` claim. */
+  GAME_ID: "gameId",
+  /** A fresh `embed:play` JWT. Required — there is no anonymous join. */
+  EMBED_TOKEN: "embedToken",
+  /** Display-name fallback when the token carries none. */
+  NAME: "name",
+  /** {@link PROTOCOL_VERSION}. Required. */
+  PROTOCOL: "protocol"
+};
+var SERVER_OWNED_JOIN_OPTIONS = ["clients", "preset", "winCondition", "config", "matchmade"];
+var JoinError = {
+  /** A server-owned option was sent. */
+  BAD_OPTION: 400,
+  /** No token, an invalid/expired token, or a revoked session. */
+  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
+};
+var STAGING_ROOM_PREFIX = "preview--";
+var roomKeyFor = (slug, channel) => channel === "staging" ? `${STAGING_ROOM_PREFIX}${slug}` : slug;
+var slugOfRoomKey = (key) => key.startsWith(STAGING_ROOM_PREFIX) ? key.slice(STAGING_ROOM_PREFIX.length) : key;
+var ClientMessage = {
+  STATE: "state",
+  STATE_SNAP: "__state:snap",
+  SHARED: "shared",
+  CLAIM: "claim",
+  RELEASE: "release",
+  DESTROY: "destroy",
+  OBJECT: "obj",
+  OBJECT_SNAP: "__object:snap",
+  INPUT: "__input",
+  ROOM_OPEN: "__room:open",
+  CHAT: "__chat",
+  CHAT_HISTORY_REQUEST: "__chat:history:request",
+  VOICE_ICE_REQUEST: "__voice:ice:request",
+  VOICE_JOIN: "__voice:join",
+  VOICE_LEAVE: "__voice:leave",
+  VOICE_SIGNAL: "__voice:signal",
+  // match rooms only — self-reports, accepted only from an active seat
+  MATCH_ELIMINATED: "match:eliminated",
+  MATCH_SCORE: "match:score",
+  MATCH_FINISH: "match:finish",
+  // optional typed pose (§6.6) — appended in protocol 3
+  POSE: "__pose",
+  POSE_SNAP: "__pose:snap"
+};
+var ServerMessage = {
+  OBJECT_RESULT: "__object:result",
+  INPUT: "__input",
+  ROOM_OPEN: "__room:open",
+  CHAT: "__chat",
+  CHAT_HISTORY: "__chat:history",
+  VOICE_ICE: "__voice:ice",
+  VOICE_SIGNAL: "__voice:signal",
+  VOICE_REJECTED: "__voice:rejected",
+  RATE_DROP: "rate:drop",
+  SERVER_RESTART: "server:restart",
+  // match rooms only
+  MATCH_START: "match:start",
+  MATCH_ENDED: "match:ended",
+  MATCH_REQUEUE: "match:requeue",
+  // queue room only
+  QUEUE: "queue",
+  SEAT: "seat"
+};
+var RESERVED_EVENT_PREFIXES = ["__", "match:", "server:", "rate:"];
+var RESERVED_EVENT_TYPES = ["state", "shared", "claim", "release", "destroy", "obj", "queue", "seat"];
+function isReservedEventType(type) {
+  return RESERVED_EVENT_TYPES.includes(type) || RESERVED_EVENT_PREFIXES.some((prefix) => type.startsWith(prefix));
+}
+var RESERVED_SHARED_PREFIX = "__";
+var SEND_TIME_KEY = "__t";
+var RATE_LANES = {
+  state: { rate: 30, burst: 60, softZone: 0 },
+  control: { rate: 40, burst: 80, softZone: 0 },
+  input: { rate: 60, burst: 120, softZone: 0 },
+  bulk: { rate: 120, burst: 240, softZone: 60 },
+  chat: { rate: 2, burst: 5, softZone: 0 },
+  voice: { rate: 25, burst: 60, softZone: 0 },
+  /** `__pose` / `__pose:snap` (§6.6). Its own reserved lane, outside the global bucket like
+   *  `state`: a posed player publishes pose AND (low-rate) `data`, and neither may starve the other. */
+  pose: { rate: 30, burst: 60, softZone: 0 }
+};
+var GLOBAL_RATE = { rate: 180, burst: 360 };
+var MAX_MESSAGES_PER_SECOND = 1200;
+var MESSAGE_LANE = {
+  [ClientMessage.STATE]: "state",
+  [ClientMessage.STATE_SNAP]: "state",
+  [ClientMessage.SHARED]: "bulk",
+  [ClientMessage.CLAIM]: "control",
+  [ClientMessage.RELEASE]: "control",
+  [ClientMessage.DESTROY]: "control",
+  [ClientMessage.OBJECT]: "bulk",
+  [ClientMessage.OBJECT_SNAP]: "bulk",
+  [ClientMessage.INPUT]: "input",
+  [ClientMessage.ROOM_OPEN]: "control",
+  [ClientMessage.CHAT]: "chat",
+  [ClientMessage.CHAT_HISTORY_REQUEST]: "control",
+  [ClientMessage.VOICE_ICE_REQUEST]: "voice",
+  [ClientMessage.VOICE_JOIN]: "voice",
+  [ClientMessage.VOICE_LEAVE]: "voice",
+  [ClientMessage.VOICE_SIGNAL]: "voice",
+  [ClientMessage.MATCH_ELIMINATED]: "bulk",
+  [ClientMessage.MATCH_SCORE]: "bulk",
+  [ClientMessage.MATCH_FINISH]: "bulk",
+  [ClientMessage.POSE]: "pose",
+  [ClientMessage.POSE_SNAP]: "pose"
+};
+var CloseCode = {
+  // reconnectable (the seat is held for the grace window)
+  GOING_AWAY: 1001,
+  NO_STATUS: 1005,
+  ABNORMAL: 1006,
+  /** Colyseus: the server is going down, come back. The one ≥4000 code that is not terminal. */
+  MAY_TRY_RECONNECT: 4010,
+  // terminal
+  NORMAL: 1e3,
+  /** A deliberate leave (Colyseus CONSENTED) — and the code a match room boots a requeued player
+   *  with when it ignored `match:requeue` (Genex MATCH_BOOT). Same number, same meaning: seat gone. */
+  CONSENTED: 4e3,
+  MATCH_BOOT: 4e3,
+  SERVER_SHUTDOWN: 4001,
+  /** Colyseus: protocol error, or the socket exceeded MAX_MESSAGES_PER_SECOND. */
+  WITH_ERROR: 4002,
+  /** Colyseus SDK: every reconnection attempt failed (the grace expired). */
+  FAILED_TO_RECONNECT: 4003,
+  /** 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
+};
+var Limits = {
+  ROOM_MAX_CLIENTS: 64,
+  MAX_NAME_CHARS: 64,
+  MAX_AVATAR_URL_CHARS: 512,
+  MAX_UID_CHARS: 64,
+  /** `state` / `__state:snap` payload (the JSON text). */
+  MAX_STATE_BYTES: 16 * 1024,
+  MAX_SHARED_KEY_CHARS: 256,
+  MAX_SHARED_VALUE_BYTES: 64 * 1024,
+  /** Distinct game keys a room's `shared` map may ever hold (keys are never deleted). */
+  MAX_SHARED_KEYS: 256,
+  MAX_OBJECT_ID_CHARS: 128,
+  /** An object's `d` as stored (JSON text). */
+  MAX_OBJECT_STATE_BYTES: 64 * 1024,
+  /** Live objects per room (an id counts from its first accepted claim until `destroy`). */
+  MAX_OBJECTS: 128,
+  MAX_REQUEST_ID_CHARS: 96,
+  /** Game events and `__input`: the payload's JSON encoding. */
+  MAX_EVENT_BYTES: 16 * 1024,
+  MAX_EVENT_TYPE_CHARS: 128,
+  /** JSON payload shape bounds: nesting depth and total node count. */
+  MAX_JSON_DEPTH: 32,
+  MAX_JSON_NODES: 4096,
+  /** Code points per chat line after normalization. */
+  MAX_CHAT_CHARS: 500,
+  CHAT_HISTORY_MAX: 50,
+  CHAT_HISTORY_MAX_BYTES: 8 * 1024,
+  MAX_VOICE_PARTICIPANTS: 6,
+  MAX_VOICE_SIGNAL_BYTES: 8 * 1024,
+  /** `match:score` delta is clamped to ±this. */
+  MAX_SCORE_DELTA: 1e3,
+  /** Results kept per session for request-id replay, and how long. */
+  CONTROL_RESULTS_PER_SESSION: 128,
+  CONTROL_RESULT_TTL_MS: 6e4,
+  /** Open preset `teams` knob range (0 = no teams). */
+  MAX_TEAMS: 8,
+  /** `__pose` `anim` string (§6.6). */
+  MAX_ANIM_CHARS: 64,
+  /** Every `__pose` number must be finite with |v| ≤ this (float32 holds it without overflowing to
+   *  Infinity; past ~1e7 a float32 position is coarser than a metre anyway). */
+  MAX_POSE_ABS: 1e9
+};
+var RelayTiming = {
+  /** State patch cadence: every accumulated change goes out on this tick. */
+  PATCH_INTERVAL_MS: 1e3 / 30,
+  /** Seat grace after an abnormal drop (1006 etc.). */
+  RECONNECT_GRACE_S: 30,
+  /** Seat grace after a 1001 close (reload/navigate) — long enough to rejoin and supersede. */
+  GOING_AWAY_GRACE_S: 5,
+  /** A dropped host keeps host for this long before the relay fails over. */
+  HOST_FAILOVER_GRACE_MS: 1500,
+  /** A freshly changed owner cannot be displaced by an ordinary claim for this long. */
+  MIN_OWNERSHIP_HOLD_MS: 300,
+  /** After `server:restart`, clients are dropped this much later. */
+  SHUTDOWN_DRAIN_MS: 3e3,
+  /** A requeued match player that has not left is booted (MATCH_BOOT) after this. */
+  REQUEUE_GRACE_MS: 5e3,
+  /** A seat reservation must be consumed within this. */
+  SEAT_RESERVATION_S: 15,
+  /** The queue room's matchmaking pass. */
+  QUEUE_TICK_MS: 1e3,
+  /** Embed tokens are re-checked for revocation on this cadence (REVOKED close on hit). */
+  REVOCATION_SWEEP_MS: 3e4
+};
+var ClientReconnection = {
+  enabled: true,
+  minUptime: 0,
+  delay: 125,
+  minDelay: 100,
+  maxDelay: 4e3,
+  maxRetries: 9,
+  maxEnqueuedMessages: 0,
+  /** After the SDK reports reconnected, wait at most this for the first state decode (§8). */
+  firstStateTimeoutMs: 2e3
+};
+var POSE_KEYS = ["x", "y", "z", "yaw", "vx", "vy", "vz", "anim"];
+var Interpolation = {
+  /** Render delay target = RATIO × median publish interval of that sender… */
+  RATIO: 1.5,
+  /** …but at least JITTER_SAFETY × (p90 − min) of that sender's (arrival − sendTime)… */
+  JITTER_SAFETY: 1.25,
+  /** …clamped to [MIN_MS, MAX_MS], and DEFAULT_MS before anything is measured. */
+  MIN_MS: 90,
+  MAX_MS: 300,
+  DEFAULT_MS: 100,
+  /** Per-sample fraction the delay moves toward its target (no pops). */
+  EASE: 0.1,
+  /**
+   * The min-filtered clock-offset window, kept PER SENDER: it holds at least the last CLOCK_WINDOW
+   * samples AND at least CLOCK_WINDOW_MS of them, whichever reaches further back, so a sender that
+   * owns many streams never shrinks the time the window covers. The jitter term reads each stream's
+   * own last CLOCK_WINDOW samples.
+   */
+  CLOCK_WINDOW: 80,
+  CLOCK_WINDOW_MS: 5e3,
+  /** Hard cap on one sender's window (memory bound for a sender publishing very many streams). */
+  CLOCK_WINDOW_MAX: 4096,
+  /** Publish-gap history for the median; gaps outside (MIN_GAP_MS, MAX_GAP_MS) are ignored. */
+  INTERVAL_WINDOW: 30,
+  MIN_GAP_MS: 5,
+  MAX_GAP_MS: 2e3,
+  /** Snapshot history kept per stream (never fewer than 2). */
+  HISTORY_MS: 1500,
+  /** Past the newest snapshot: dead-reckon position at most this far, rotation this far. */
+  MAX_EXTRAP_MS: 250,
+  ROT_EXTRAP_MS: 150,
+  /** Output smoothing time constants (alpha = 1 − e^(−dt/τ), dt clamped to 250 ms). */
+  SMOOTH_TAU_POS_MS: 30,
+  SMOOTH_TAU_ROT_MS: 70,
+  /** A head snapshot this far in the future of the newest is a foreign-clock poison: drop it. */
+  POISON_GUARD_MS: 2e3,
+  /** A reconnect gap longer than this discards every stream's history (one deliberate rebase). */
+  REBASE_AFTER_GAP_MS: 1e3,
+  /** Host tick dt is clamped to this (a backgrounded tab must not tunnel the simulation). */
+  MAX_HOST_TICK_DT_MS: 250
+};
+var ClockSync = {
+  /** The heartbeat rate a client SHOULD send at, from a wall-clock timer (never the render loop). */
+  HEARTBEAT_HZ: 10,
+  /** A client that sends heartbeats MUST stay within [MIN_HEARTBEAT_HZ, MAX_HEARTBEAT_HZ] while its
+   *  page is foregrounded. Below MIN the offset and RTT refresh too slowly; above MAX buys nothing,
+   *  and the relay's small buffer (RELAY_BUFFER) folds the excess away. */
+  MIN_HEARTBEAT_HZ: 5,
+  MAX_HEARTBEAT_HZ: 20,
+  /** Each interval is the nominal one × (1 ± up to this), clamped to the band above. A fixed interval
+   *  that divides the patch interval phase-locks to the patch tick (every RTT sample then carries the
+   *  same hold); the dither walks the phase so near-zero holds keep turning up. */
+  HEARTBEAT_DITHER: 0.15,
+  /** Relay `defineInput({ bufferMaxSize })`. Overflow counts as consumed, so a burst still acks. */
+  RELAY_BUFFER: 4,
+  /** Acked heartbeats (RTT-valid samples) before a client treats `serverNow` as synced and uses it
+   *  for deadlines (≈3 s at 10 Hz). The room clock seeds its offset from the first TIMED frame, which
+   *  is biased by the one-way latency, and then moves by an EMA (α = 0.1) per RTT sample, so after k
+   *  samples 0.9^k of that bias remains: ≈35% at 10, ≈4% at 30 (≈6 ms at 150 ms one way). 30 is also
+   *  where the room clock's RTT gate stops being bypassed (its warmup). */
+  WARMUP_ACKS: 30
+};
+
+export {
+  PROTOCOL_VERSION,
+  MIN_PROTOCOL_VERSION,
+  RoomType,
+  JoinOption,
+  SERVER_OWNED_JOIN_OPTIONS,
+  JoinError,
+  STAGING_ROOM_PREFIX,
+  roomKeyFor,
+  slugOfRoomKey,
+  ClientMessage,
+  ServerMessage,
+  RESERVED_EVENT_PREFIXES,
+  RESERVED_EVENT_TYPES,
+  isReservedEventType,
+  RESERVED_SHARED_PREFIX,
+  SEND_TIME_KEY,
+  RATE_LANES,
+  GLOBAL_RATE,
+  MAX_MESSAGES_PER_SECOND,
+  MESSAGE_LANE,
+  CloseCode,
+  Limits,
+  RelayTiming,
+  ClientReconnection,
+  POSE_KEYS,
+  Interpolation,
+  ClockSync
+};