@genex-ai/multiplayer 0.16.1 → 0.17.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { PlayerState, RoomState } from './schema.js';
+import { ObjectControlOperation as ObjectControlOperation$1, ObjectControlReason as ObjectControlReason$1 } from './protocol.js';
+export { ObjectState, PlayerState, RoomState } from './schema.js';
 import '@colyseus/schema';
 
 /** One remote participant in the voice mesh. */
@@ -70,6 +71,16 @@ type ConnectOptions = {
     auth?: AuthSource;
     /** Extra join options passed to the room. */
     options?: Record<string, unknown>;
+} & SessionOptions;
+/** How remote posed players are smoothed (EXPERIMENTAL, see {@link SessionOptions.smoothing}). */
+type PredictSmoothing = {
+    engine: 'predict';
+    /** Colyseus `Predict` mode. Default `'lerp'`. */
+    mode?: 'lerp' | 'damped';
+    /** `lerp` render delay in ms (Predict's default 100). */
+    delay?: number;
+    /** Predict's output spring / damped chase rate in ms (Predict's defaults when omitted). */
+    smoothMs?: number;
 };
 type PlayerView<TState> = {
     id: string;
@@ -81,6 +92,14 @@ type PlayerView<TState> = {
     avatarUrl: string;
     /** Transport is live now. False while this reserved seat is inside reconnect grace. */
     connected: boolean;
+    /** This player's stable id IN THIS GAME: the same across reloads, devices and rooms of the
+     * game, different in every other game, never the account id. Key anything that outlives a
+     * session (scores, colours, saves, "is this me") by it — `id` is a session id and changes on
+     * every reload. Opaque, ≤64 chars: never parse it. Relay-stamped from the verified token. */
+    uid: string;
+    /** Team index the relay assigned, or `-1` for no team: the `open` preset's `teams: N` (kept by
+     * `uid` for the room's life, never reshuffled) or the `teams` preset's current round. */
+    team: number;
     /** RENDER ONLY — for remote players this is **auto-smoothed** (interpolated) and delayed;
      * for yourself it's live. Numeric fields are lerped; everything else snaps. Use `stateRaw`
      * for every gameplay read (hits, reach, pickups, flags, physics adoption). */
@@ -103,8 +122,12 @@ type ObjectView<TState> = {
     /** The latest raw snapshot (never smoothed/delayed) — for hit-tests / logic. */
     stateRaw: TState;
 };
-type ObjectControlOperation = 'claim' | 'release' | 'remove';
-type ObjectControlReason = 'accepted' | 'already-owner' | 'held' | 'rate-limited' | 'not-owner' | 'capacity' | 'invalid' | 'missing' | 'host-authority' | 'not-host' | 'unsupported' | 'timeout' | 'aborted' | 'disconnected';
+type ObjectControlOperation = ObjectControlOperation$1;
+/** The relay's reasons (PROTOCOL.md §7.2), plus the ones this client settles a request with
+ *  itself: `timeout`, `aborted` (your signal, or `leave()`), `disconnected` (the session ended). */
+type ObjectControlReason = ObjectControlReason$1
+/** @deprecated Never produced since protocol 3 — every relay answers control requests. */
+ | 'unsupported' | 'timeout' | 'aborted' | 'disconnected';
 type ObjectControlResult = {
     requestId: string;
     operation: ObjectControlOperation;
@@ -185,7 +208,8 @@ type Session<TState extends Record<string, unknown>> = {
     /** True if you are the elected room host — the earliest signed-in player still present
      * (guests host only while no account is in the room); can migrate on join as well as leave.
      * Settles within the first state patch after connect — read it in your loop or react to
-     * `on('host')`, not once. */
+     * `on('host')`, not once. False while the session is reconnecting (until the fresh snapshot
+     * says who the host is now) and after it ends, so a write behind `isHost` is never stale. */
     readonly isHost: boolean;
     /** Session id of the current room host, or `undefined` until the first host patch lands. */
     readonly host: string | undefined;
@@ -228,27 +252,35 @@ type Session<TState extends Record<string, unknown>> = {
         limit?: number;
     }) => void): () => void;
     /**
-     * The connection dropped unexpectedly and auto-reconnect is underway (attempts run
-     * ~0.5s→8s backoff inside the server's grace window). Show a "reconnecting…" overlay;
-     * keep your loop running — the world resumes seamlessly on `reconnected`.
+     * The connection dropped unexpectedly and auto-reconnect is underway (one event per
+     * attempt; the attempts back off ~0.25s→4s and all land inside the relay's 30s seat grace).
+     * Show a "reconnecting…" overlay; keep your loop running — the world resumes seamlessly on
+     * `reconnected`. Host ticks pause until then.
      */
     on(event: 'reconnecting', cb: (info: {
         attempt: number;
         code: number;
     }) => void): () => void;
-    /** Auto-reconnect succeeded: same session id, same seat — nothing was torn down. */
+    /** Auto-reconnect succeeded: same session id, same seat — nothing was torn down. Fires once
+     *  the room's state is current again (host, owners, players), so it is safe to read here. */
     on(event: 'reconnected', cb: () => void): () => void;
     /**
      * The connection is gone for good: the server closed it on purpose (restart, revoked
-     * session, match eviction) or every reconnect attempt failed. The session is dead —
-     * to play again, read a FRESH `getColyseusAuth()` and `connect()` anew.
+     * session 4401, a newer tab took the seat 4409, match eviction) or every reconnect attempt
+     * failed (4003). The session is dead — to play again, read a FRESH `getColyseusAuth()` and
+     * `connect()` anew (but not automatically after 4409: the player is playing elsewhere).
      */
     on(event: 'disconnect', cb: (code: number) => void): () => void;
+    /** The host opened or closed this room to new matchmaking placements (`setRoomOpen`). */
+    on(event: 'room:open', cb: (info: {
+        open: boolean;
+    }) => void): () => void;
     /** A custom event another client sent via `send(type, ...)`. */
     on(event: string & {}, cb: (payload: unknown) => void): () => void;
     /** Fire-and-forget event to all OTHER clients (not stored in state). Event names used
-     * by the relay itself (`state`, `shared`, `claim`, `obj`, `release`, `destroy`, and the
-     * `match:`/`__` prefixes) are refused with a console warning — pick another name. */
+     * by the relay itself (`state`, `shared`, `claim`, `release`, `destroy`, `obj`, `queue`,
+     * `seat`, and the `__`/`match:`/`server:`/`rate:` prefixes) and names over 128 characters
+     * are refused with a console warning — pick another name. */
     send(type: string, payload?: unknown): void;
     /** Text chat for this room. See {@link ChatApi}. */
     chat: ChatApi;
@@ -263,12 +295,56 @@ type Session<TState extends Record<string, unknown>> = {
      * keeps playing, and a reconnecting player still gets back in (reconnection uses a
      * reserved seat, not matchmaking).
      *
-     * Ignored (with no error) when called by a non-host — read `isHost` first. All
-     * clients are told either way, so you can render "closed" from the `room:open` event.
+     * Ignored (with no error) when called by a non-host — read `isHost` first. When the host
+     * calls it every client is told, so you can render "closed" from the `room:open` event.
      */
     setRoomOpen(open: boolean): void;
     /** Leave the room (deliberate — no auto-reconnect, no `disconnect` event). */
     leave(): void;
+    /**
+     * EXPERIMENTAL — the relay's server clock (PROTOCOL.md §16): milliseconds since the room was
+     * created, estimated from this client's heartbeat acks. `undefined` against a relay that does not
+     * publish its clock. For server-stamped deadlines prefer {@link timeUntil}; never use this to drive
+     * rendering (remote players stay on their senders' clocks).
+     */
+    serverNow(): number | undefined;
+    /** EXPERIMENTAL — smoothed round-trip time to the relay in ms, from heartbeat acks. `undefined`
+     *  until the first ack, and always against a relay that does not publish its clock. It includes
+     *  the relay's hold until its next patch (0 to ~33 ms), so read it as an upper bound. */
+    readonly rtt: number | undefined;
+    /** EXPERIMENTAL — true once enough heartbeats were acked (~3 s) that `serverNow()` is within a few ms of the room clock. */
+    readonly clockSynced: boolean;
+    /**
+     * Milliseconds from now until a relay deadline stamped in epoch ms (a match's `startsAt` /
+     * `endsBy`; negative once it passed). Uses the server clock once it is synced — immune to a wrong
+     * clock on the player's device — and falls back to `deadline − Date.now()` otherwise.
+     */
+    timeUntil(epochMs: number): number;
+};
+/** Session behaviour options shared by `connect()`, `matchmake()`, `createPrivate()` and
+ *  `joinPrivate()`. Every one is EXPERIMENTAL and off by default: each is an A/B arm of the
+ *  netcode bench (PROTOCOL.md §15) and stays opt-in until it wins its gate. */
+type SessionOptions = {
+    /**
+     * EXPERIMENTAL — typed pose (PROTOCOL.md §6.6). Default `false`. When `true`, the reserved keys
+     * `x y z yaw vx vy vz anim` of `me.set()` / `me.snap()` are published as typed relay fields
+     * (float32 deltas instead of a re-sent JSON blob) and everything else as `data`, which is then sent
+     * only when it changes. If you omit `vx/vy/vz` they are derived from successive positions.
+     *
+     * Opt in for EVERY client of the game at once. Receivers then interpolate only the pose — `yaw`
+     * along the shortest arc (radians), `anim` switches when the rendered pose reaches it — and SNAP
+     * everything else in your state: a rotation you sync as a quaternion is no longer smoothed, so put
+     * the heading in `yaw`. A remote posed player's `state` always carries all eight pose keys.
+     */
+    pose?: boolean;
+    /**
+     * EXPERIMENTAL — remote smoothing engine for POSED players. Default `'genex'`: the SDK's own
+     * sender-clock interpolation (PROTOCOL.md §10.1), which every other stream keeps whatever this says.
+     * `'predict'` (or a {@link PredictSmoothing}) hands posed players' `x y z vx vy vz` and `yaw` to
+     * Colyseus `Predict` instead — receive-time stamps, a fixed delay, no dead reckoning past the newest
+     * sample, and `anim`/`data` applied on arrival. It exists so the bench can A/B the two engines.
+     */
+    smoothing?: 'genex' | 'predict' | PredictSmoothing;
 };
 /** One chat line, as the relay stamped it. Only `text` came from the sender's client —
  *  `from` and `name` are filled in server-side from the verified session, so a player
@@ -397,6 +473,16 @@ type MatchmakingView = {
     /** Winner of the round shown while `status === 'ended'` (competitor id; null on a draw). */
     winnerId: string | null;
     message: string;
+    /** The relay's epoch-ms `startsAt` — when the countdown (or the result screen before the next
+     *  round) ends — else null. */
+    startsAt: number | null;
+    /** Round time limit: the relay's epoch-ms `endsBy` (presets with a round limit), else null. */
+    endsBy: number | null;
+    /** Milliseconds until `startsAt` as of this read (≥ 0), or null. Measured on the relay's server
+     *  clock once it is synced, so a wrong clock on the player's device cannot skew a countdown. */
+    startsInMs: number | null;
+    /** Milliseconds until `endsBy` as of this read (≥ 0), or null. Same clock as `startsInMs`. */
+    endsInMs: number | null;
 };
 type Matchmaking<TState extends Record<string, unknown>> = {
     /** The live game session, or null while searching for a match. */
@@ -406,11 +492,17 @@ type Matchmaking<TState extends Record<string, unknown>> = {
     /**
      * searching: (re)entered the queue. queue: your position changed ({position,size}).
      * matched: `session` is now live. matchStart: a round began ({roundId}).
-     * matchEnded: {winnerId,loserId,draw,scores}. spectate: you're watching, not playing.
+     * matchEnded: {winnerId,losers,draw,scores}. spectate: you're watching, not playing.
      * error: joining the queue failed even after the SDK's automatic retries (persistent —
      * e.g. auth is broken or the server is unreachable); fix the cause, then call `retry()`.
+     * A relay that refuses this SDK's protocol (code 426) fails at once, without retries: the
+     * game needs an SDK update.
+     * disconnect: the match seat ended with 4409 (this player opened the game in another tab or
+     * device) or 4401 (signed out). The handle stops and does NOT requeue; `session` is null. Tell
+     * the player, and call `retry()` only if they choose to play here again. Every other terminal
+     * drop requeues automatically.
      */
-    on(event: 'searching' | 'queue' | 'matched' | 'matchStart' | 'matchEnded' | 'spectate' | 'error', cb: (payload?: unknown) => void): () => void;
+    on(event: 'searching' | 'queue' | 'matched' | 'matchStart' | 'matchEnded' | 'spectate' | 'error' | 'disconnect', cb: (payload?: unknown) => void): () => void;
     /** Report your OWN elimination (the `lastStanding` win condition). */
     eliminated(): void;
     /** Report a score delta for yourself (the `firstToScore` / `highScoreInTime` conditions). */
@@ -439,7 +531,7 @@ type MatchmakeOptions = {
      * token; a static object is read only once and will be rejected once it expires.
      */
     auth?: AuthSource;
-};
+} & SessionOptions;
 /**
  * Join a game's matchmaking. Returns immediately in the SEARCHING state (`session` is null); the
  * matchmaker seats you into a match room, at which point `session` becomes a live Session and a
@@ -469,4 +561,4 @@ declare function createPrivate<TState extends Record<string, unknown> = never>(o
  */
 declare function joinPrivate<TState extends Record<string, unknown> = never>(code: string, opts: MatchmakeOptions): Promise<Matchmaking<TState>>;
 
-export { type AuthSource, type ChatApi, type ChatMessage, type ColyseusAuth, type ConnectOptions, type MatchStatus, type MatchmakeOptions, type Matchmaking, type MatchmakingView, type ObjectControlOperation, type ObjectControlOptions, type ObjectControlReason, type ObjectControlResult, type ObjectView, type PlayerView, type PrivateMatch, type Session, type VoiceApi, type VoiceJoinOptions, type VoiceParticipant, connect, createPrivate, joinPrivate, matchmake };
+export { type AuthSource, type ChatApi, type ChatMessage, type ColyseusAuth, type ConnectOptions, type MatchStatus, type MatchmakeOptions, type Matchmaking, type MatchmakingView, type ObjectControlOperation, type ObjectControlOptions, type ObjectControlReason, type ObjectControlResult, type ObjectView, type PlayerView, type PredictSmoothing, type PrivateMatch, type Session, type SessionOptions, type VoiceApi, type VoiceJoinOptions, type VoiceParticipant, connect, createPrivate, joinPrivate, matchmake };