@colyseus/core 0.17.44 → 0.18.1

package/build/Room.d.ts

@@ -1,3 +1,6 @@
+import type { InputAPI, DefineInputOptions, IdleDeclared } from './input/types.ts';
+import { Rewind, type RewindOptions } from './Rewind.ts';
+export { type InputAccessor, type InputAPI, type NormalizedInputOptions, type ConsumeOptions, type IdleInput, type IdleContext, type SanitizeInput, type NumericFieldsOf, type DefineInputOptions, type IdleDeclared } from './input/types.ts';
 import { ClockTimer as Clock } from '@colyseus/timer';
 import type { Presence } from './presence/Presence.ts';
 import type { Serializer } from './serializer/Serializer.ts';
@@ -5,13 +8,58 @@ import { type Type, Deferred } from './utils/Utils.ts';
 import { type AuthContext, type Client, ClientArray, type ISendOptions, type MessageArgs } from './Transport.ts';
 import { type RoomMethodName, type RoomException } from './errors/RoomExceptions.ts';
 import { type StandardSchemaV1 } from './utils/StandardSchema.ts';
-import { type MessageHandlerWithFormat as SharedMessageHandlerWithFormat, type MessageHandler as SharedMessageHandler, type Messages as SharedMessages } from '@colyseus/shared-types';
+import { type MessageHandlerWithFormat as SharedMessageHandlerWithFormat, type MessageHandler as SharedMessageHandler, type Messages as SharedMessages, type MessageContext } from '@colyseus/shared-types';
+import { RoomPlugin, type PluginLayout } from './RoomPlugin.ts';
+export { RoomPlugin, definePlugins, attachToTestRoom, type RoomPluginOrder, } from './RoomPlugin.ts';
 export declare const DEFAULT_SEAT_RESERVATION_TIME: number;
 export type SimulationCallback = (deltaTime: number) => void;
+/**
+ * Per-step context passed to a {@link Room.setFixedTimestep} callback. Carries
+ * ONLY the fixed simulation step — never wall-clock/measured time — so feeding a
+ * jittery delta into deterministic sim math is unrepresentable. The same fixed
+ * `dt` is advertised to clients so prediction integrates identically. (The
+ * client's step context additionally carries an `isReplay` flag for rollback
+ * re-simulation; the server is authoritative and never replays, so it has none.)
+ */
+export interface StepContext {
+    /** Fixed step in SECONDS (`1/tickRate`) — the dt to integrate one step with. */
+    readonly dt: number;
+    /** Fixed step in MILLISECONDS (`1000/tickRate`). */
+    readonly dtMs: number;
+    /** Monotonic index of the fixed step being simulated. */
+    readonly tick: number;
+    /**
+     * Physics sub-steps per fixed step (≥ 1; `1` unless declared via
+     * `setFixedTimestep(..., { subSteps })`). Run your engine `subSteps` times at
+     * {@link subDt} inside each step — `for (let i = 0; i < ctx.subSteps; i++)
+     * world.step(ctx.subDt)` — to integrate physics at `tickRate * subSteps` Hz
+     * while inputs flow at `tickRate`. The same numbers are cascaded to predicting
+     * clients (their step context carries identical `subSteps`/`subDt`), so the
+     * sub-stepped trajectory replays bit-identically.
+     */
+    readonly subSteps: number;
+    /** Physics sub-step in SECONDS (`dt / subSteps`); equals {@link dt} when
+     *  `subSteps` is 1, so the loop above is valid for every room. */
+    readonly subDt: number;
+    /** Physics sub-step in MILLISECONDS (`dtMs / subSteps`). */
+    readonly subDtMs: number;
+}
+/** Fixed-timestep simulation callback. @see Room.setFixedTimestep */
+export type FixedTimestepCallback = (ctx: StepContext) => void;
 export interface RoomOptions {
     state?: object;
     metadata?: any;
     client?: Client;
+    /**
+     * Schema class for client→server input packets. When set, the Room
+     * allocates one instance per joining client and binds an InputDecoder.
+     * Must be a flat Schema (primitive fields only — see InputEncoder docs).
+     *
+     * Typed loosely (no `Schema` constraint) to avoid type-identity clashes
+     * when the user's app loads a different copy of `@colyseus/schema` than
+     * `@colyseus/core` does. Runtime validation happens via the encoder.
+     */
+    input?: any;
 }
 export type ExtractRoomState<T> = T extends {
     state?: infer S extends object;
@@ -22,6 +70,9 @@ export type ExtractRoomMetadata<T> = T extends {
 export type ExtractRoomClient<T> = T extends {
     client?: infer C extends Client;
 } ? C : Client;
+export type ExtractRoomInput<T> = T extends {
+    input?: infer I;
+} ? I : never;
 export interface IBroadcastOptions extends ISendOptions {
     except?: Client | Client[];
 }
@@ -48,7 +99,7 @@ export type Messages<This extends Room> = SharedMessages<This, Client>;
  * }
  * ```
  */
-export declare function validate<T extends StandardSchemaV1, This = any>(format: T, handler: (this: This, client: Client, message: StandardSchemaV1.InferOutput<T>) => void): MessageHandlerWithFormat<T, This>;
+export declare function validate<T extends StandardSchemaV1, This = any>(format: T, handler: (this: This, client: Client, message: StandardSchemaV1.InferOutput<T>, ctx: MessageContext) => unknown): MessageHandlerWithFormat<T, This>;
 export declare const RoomInternalState: {
     readonly CREATING: 0;
     readonly CREATED: 1;
@@ -172,11 +223,47 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
     private _reconnections;
     private _reconnectionAttempts;
     messages?: Messages<any>;
-    private onMessageEvents;
-    private onMessageValidators;
-    private onMessageFallbacks;
+    /**
+     * Room plugins, keyed by an operator-chosen handle. Each plugin
+     * contributes any subset of: declarative message handlers (merged
+     * into `this.messages`), lifecycle hooks (composed with the room's
+     * own), and public methods callable via `this.plugins.<key>.X()`.
+     *
+     * The framework walks this record once per Room subclass to compute
+     * the lifecycle/message layout and install hook wrappers on the
+     * class prototype; subsequent constructs reuse the cached layout
+     * and just inject `.room` + merge messages.
+     *
+     * Use `definePlugins({...})` so TypeScript preserves each plugin's
+     * literal instance type. Frozen after `__init`.
+     */
+    plugins?: any;
+    /**
+     * Auto-included plugin instances pulled in via `static
+     * dependencies` declarations on user-registered plugins. Kept
+     * separate from `this.plugins` so the user's typed view doesn't
+     * gain framework-managed keys. Sentinel-keyed (`__dep:<ClassName>`)
+     * so the hook wrappers can route lookups to the right map.
+     *
+     * @internal
+     */
+    _autoPlugins?: Record<string, RoomPlugin<any>>;
+    /**
+     * Layout cache populated on the FIRST construction of each Room
+     * subclass. Holds the precomputed hook participation order + message
+     * key → plugin key mapping. Stored on the constructor (a static field)
+     * so all instances of the same class share it.
+     *
+     * `null` is a sentinel meaning "no plugins on this class" — distinct
+     * from `undefined` ("not yet computed") so we don't re-walk an empty
+     * plugin record on every construct.
+     *
+     * @internal
+     */
+    static __pluginLayout?: PluginLayout | null;
+    private get onMessageEvents();
+    private get onMessageValidators();
     private _serializer;
-    private _afterNextPatchQueue;
     private _simulationInterval;
     private _internalState;
     private _lockedExplicitly;
@@ -248,6 +335,72 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
      * @param code - The close code of the leave event.
      */
     onLeave?(client: ExtractRoomClient<T>, code?: number): void | Promise<any>;
+    /**
+     * Per-client input accessor. Assign it `= this.defineInput(...)`, then call
+     * `this.inputs.get(sessionId)` each tick to read that client's buffered input
+     * *stream* — iterate it directly, or call `.next()` / `.drain()` / `.latest`.
+     *
+     * (In the `Room<{ input: I }>` generic, `input` is the input *type* of one
+     * frame; `this.inputs` is the per-client accessor over the stream of them.)
+     *
+     * @example
+     * ```typescript
+     * class FpsRoom extends Room<{ input: MoveInput }> {
+     *   inputs = this.defineInput(MoveInput);
+     *
+     *   onCreate() {
+     *     this.setFixedTimestep((ctx) => {
+     *       for (const [sid, p] of this.state.players)
+     *         for (const input of this.inputs.get(sid))   // consume one-by-one
+     *           applyInput(p, input, ctx.dt);
+     *     }, 30);
+     *   }
+     * }
+     * ```
+     */
+    inputs?: InputAPI<ExtractRoomInput<T>>;
+    /**
+     * @internal The per-room input subsystem (options, accessor registry, wire
+     * stamp mode, encode/decode/handshake). Created lazily on the first
+     * {@link defineInput} call — rooms without inputs allocate none of it, and its
+     * presence is what enables client-timed state messages. See {@link RoomInput}.
+     */
+    private _inputController?;
+    /**
+     * Declare the input schema and configuration in a single line. Returns the
+     * input API that gets assigned to `this.inputs` — call
+     * `this.inputs.get(sessionId)` per tick to consume.
+     *
+     * ```typescript
+     * class FpsRoom extends Room<{ input: MoveInput }> {
+     *   inputs = this.defineInput(MoveInput, {
+     *     seqField: "tick",       // typed: only numeric fields of MoveInput
+     *     bufferMaxSize: 64,
+     *   });
+     *
+     *   // …or without options — no seq dedupe, bufferMaxSize: 32:
+     *   // inputs = this.defineInput(MoveInput);
+     * }
+     * ```
+     *
+     * **Defaults** when `opts` (or individual fields) are omitted:
+     * - `seqField`: unset — dedupe and `this.inputs.get(sessionId).at(value)` lookup are
+     *   OPT-IN (lockstep / rollback). Name a monotonic numeric field here to enable
+     *   them; redundant frames (`input[seqField]` ≤ the last seen) are then dropped.
+     *   Leave unset for reliable, in-order channels where every frame is unique.
+     * - `bufferMaxSize`: `32` — enables per-client snapshot buffering for
+     *   `this.inputs.get(sessionId)` iteration / `.consume() / .drain() / .next() /
+     *   .take() / .peek() / .at()`. Set to `0` to disable buffering (the `.latest`
+     *   read still works).
+     *
+     * **Consuming the buffer** — `for (const inp of this.inputs.get(sessionId))` (sugar
+     * for `.consume()`) is the per-entity loop: it consumes one at a time, so
+     * lag-comp `renderTime` tracks each input. `next()` (take exactly one, ack +1)
+     * suits a shared physics world stepped once for everyone; `drain()` returns the
+     * whole pending set as an array. See {@link InputAccessor} for the full
+     * per-entity-vs-shared-world guidance and why the choice affects the reconcile ack.
+     */
+    protected defineInput<C extends new () => any, O extends DefineInputOptions<InstanceType<C>> = DefineInputOptions<InstanceType<C>>>(type: C, opts?: O): InputAPI<InstanceType<C>, IdleDeclared<O, InstanceType<C>>>;
     /**
      * This method is called when the room is disposed.
      */
@@ -260,7 +413,7 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
      * - `onMessage`
      * - `onAuth` / `onJoin` / `onLeave` / `onCreate` / `onDispose`
      * - `clock.setTimeout` / `clock.setInterval`
-     * - `setSimulationInterval`
+     * - `setTimestep` / `setFixedTimestep`
      *
      * (Experimental: this feature is subject to change in the future - we're currently getting feedback to improve it)
      */
@@ -316,16 +469,113 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
     hasReservedSeat(sessionId: string, reconnectionToken?: string): boolean;
     checkReconnectionToken(reconnectionToken: string): string;
     /**
-     * (Optional) Set a simulation interval that can change the state of the game.
-     * The simulation interval is your game loop.
+     * Set the room's game loop. `onTickCallback` runs every `delay` ms and receives
+     * the MEASURED wall-clock delta since the previous tick (a VARIABLE timestep).
+     * For deterministic, prediction-friendly simulation prefer
+     * {@link Room.setFixedTimestep}, which advances a fixed step via an accumulator.
      *
      * @default 16.6ms (60fps)
      *
-     * @param onTickCallback - You can implement your physics or world updates here!
-     *  This is a good place to update the room state.
-     * @param delay - Interval delay on executing `onTickCallback` in milliseconds.
+     * @param onTickCallback - Your physics / world update — a good place to mutate
+     *  room state. Receives the measured delta (`this.clock.deltaTime`).
+     * @param delay - Interval between ticks in milliseconds.
+     */
+    setTimestep(onTickCallback?: SimulationCallback, delay?: number): void;
+    /**
+     * @deprecated Renamed to {@link Room.setTimestep} (which pairs with
+     * {@link Room.setFixedTimestep}). Kept for backwards compatibility — forwards
+     * to `setTimestep` unchanged.
      */
     setSimulationInterval(onTickCallback?: SimulationCallback, delay?: number): void;
+    /**
+     * Fixed-timestep game loop with a framework-owned accumulator — the right
+     * default for prediction/rollback. Unlike {@link setTimestep} (which
+     * hands you the *measured* wall-clock delta), this runs `step` a whole number
+     * of times per real frame so each step advances by the SAME fixed
+     * `dt = 1/tickRate`; the measured delta only decides HOW MANY steps run. The
+     * fixed dt is delivered via {@link StepContext}, so the jittery wall-clock
+     * delta can't leak into deterministic simulation.
+     *
+     * `tickRate` is also the SINGLE SOURCE of the simulation rate: it's advertised
+     * to predicting clients via the join handshake (they predict at the matching
+     * `dt`), so don't also pass `tickRate` to {@link defineInput}.
+     *
+     * **`tickRate` couples three rates** — by design, one input == one fixed step
+     * == one server tick, so lowering `tickRate` to save bandwidth also lowers
+     * the simulation rate. To keep high-fidelity physics on a lower network rate,
+     * pass `{ subSteps: N }`: one input still drives one fixed step, but you
+     * integrate `N` engine sub-steps of `ctx.subDt` (= `ctx.dt / N`) inside it —
+     * physics at `tickRate * N` Hz, inputs at `tickRate`/sec. The same
+     * `subSteps`/`subDt` are cascaded to predicting clients (via the join
+     * handshake, onto their reconciler's step context), so client replay
+     * reproduces the sub-stepped trajectory exactly. Render interpolation already
+     * smooths above the step rate — most games don't need this; reach for it when
+     * the *simulation* needs the extra Hz (fast projectiles, stacking, tunneling).
+     *
+     * On a hitch the accumulator runs at most a few catch-up steps then drops the
+     * backlog (no spiral of death). Lag-comp is recorded once per real frame.
+     *
+     * **Consuming input inside the step** — how you consume each client's buffer
+     * depends on who integrates (see {@link InputAccessor}):
+     * - *Per-entity* (each body integrates itself): `for (const cmd of
+     *   this.inputs.get(sid)) applyInput(player, cmd, ctx.dt)` — N inputs =
+     *   N sub-integrations, ack lands on the newest applied, and `renderTime`
+     *   tracks each input (lag comp stays exact per step).
+     * - *Shared world* (one solver step advances every body): consume exactly one
+     *   input per entity per step with `this.inputs.get(sid).next()` (or `take(n)` +
+     *   sub-step), then `world.step()` once. Draining all and applying only the
+     *   latest would jump the reconcile ack past inputs you never simulated.
+     *
+     * @param step - Called once per fixed step with a {@link StepContext}.
+     * @param tickRate - Simulation rate in **Hz**. Defaults to 60.
+     * @param opts - `subSteps`: physics sub-steps per fixed step (integer ≥ 1,
+     *   default 1) — see above.
+     *
+     * @example
+     * ```ts
+     * onCreate() {
+     *   // 30 inputs/sec on the wire, physics integrated at 60 Hz:
+     *   this.setFixedTimestep((ctx) => {
+     *     this.applyInputs(ctx);      // consume ONE input per client per step
+     *     for (let i = 0; i < ctx.subSteps; i++) this.world.step(ctx.subDt);
+     *   }, 30, { subSteps: 2 });
+     * }
+     * ```
+     */
+    setFixedTimestep(step: FixedTimestepCallback, tickRate?: number, opts?: {
+        subSteps?: number;
+    }): void;
+    /** @internal The rewind attachments' timeline mode (snapshot/reckon), or
+     *  `undefined` when no rewind is configured. {@link RoomInput} reads it to
+     *  derive the wire input stamp mode (snapshot → renderTime, reckon → reckonTime). */
+    _timelineMode(): {
+        snapshot?: boolean;
+        reckon?: boolean;
+    } | undefined;
+    /**
+     * Enable server-side lag compensation: returns a {@link Rewind} that records the
+     * position history of the entities you attach and automatically snapshots them
+     * on each broadcast (the patchRate cadence). Attach the collections to rewind,
+     * then read past positions (at a client's renderTime) in your hit tests.
+     *
+     * @example
+     * ```ts
+     * const rewind = this.allowRewindState({ maxRewindMs: 500 });
+     * rewind.attachAll(this.state.enemies, { fields: ["x", "y"] });
+     * // in a hit test — rewind to where the SHOOTER saw the world:
+     * const seen = rewind.lastSeenBy(shooterSessionId);   // needs this.defineInput(...)
+     * const seenX = seen.value(enemy, "x"), seenY = seen.value(enemy, "y");
+     * ```
+     *
+     * Per-client stamps auto-enable from the `attachAll` `mode` of the groups you
+     * rewind — no `renderTime` flag. The default auto-record fires on each
+     * broadcast, snapshotting exactly what the client receives — so the rewind
+     * reproduces the client's interpolation and hits stay exact even when the
+     * broadcast rate differs from the sim rate (`patchRate ≠ timestep`). Call
+     * `rewind.record()` yourself during a tick to take over that cadence (you then
+     * own correctness against your own broadcast rate).
+     */
+    allowRewindState(opts?: RewindOptions): Rewind;
     /**
      * @deprecated Use `.patchRate=` instead.
      */
@@ -335,7 +585,7 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
      */
     setState(newState: ExtractRoomState<T>): void;
     setSerializer(serializer: Serializer<ExtractRoomState<T>>): void;
-    setMetadata(meta: Partial<ExtractRoomMetadata<T>>, persist?: boolean): Promise<void>;
+    setMetadata(meta: ExtractRoomMetadata<T>, persist?: boolean): Promise<void>;
     setPrivate(bool?: boolean, persist?: boolean): Promise<void>;
     /**
      * Update multiple matchmaking/listing properties at once with a single persist operation.
@@ -364,7 +614,8 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
      *
      * @example
      * ```typescript
-     * // Partial metadata update (merges with existing)
+     * // Merging with existing metadata: spread `this.metadata` yourself.
+     * // `metadata` is always REPLACED (not merged) by setMatchmaking()/setMetadata().
      * await this.setMatchmaking({
      *   metadata: { ...this.metadata, round: this.metadata.round + 1 }
      * });
@@ -435,10 +686,48 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
      * ```
      */
     onMessage<T = any, C extends Client = ExtractRoomClient<T>>(messageType: '*', callback: (client: C, type: string | number, message: T) => void): any;
-    onMessage<T = any, C extends Client = ExtractRoomClient<T>>(messageType: string | number, callback: (client: C, message: T) => void): any;
-    onMessage<T = any, C extends Client = ExtractRoomClient<T>>(messageType: string | number, validationSchema: StandardSchemaV1<T>, callback: (client: C, message: T) => void): any;
+    onMessage<T = any, C extends Client = ExtractRoomClient<T>>(messageType: string | number, callback: (client: C, message: T, ctx: MessageContext) => unknown): any;
+    onMessage<T = any, C extends Client = ExtractRoomClient<T>>(messageType: string | number, validationSchema: StandardSchemaV1<T>, callback: (client: C, message: T, ctx: MessageContext) => unknown): any;
     onMessageBytes<T = any, C extends Client = ExtractRoomClient<T>>(messageType: string | number, callback: (client: C, message: T) => void): any;
     onMessageBytes<T = any, C extends Client = ExtractRoomClient<T>>(messageType: string | number, validationSchema: StandardSchemaV1<T>, callback: (client: C, message: T) => void): any;
+    /**
+     * Snapshot the room's live state for an inspector / admin UI. Includes:
+     *
+     *   roomId, name, maxClients, locked, elapsedTime (ms),
+     *   metadata, clients (sessionId + per-client elapsed + userId when set),
+     *   state (the schema/json the SDK would see),
+     *   stateSize (bytes of the encoded full state, or 0 when no serializer).
+     *
+     * The payload is intentionally plain JSON — `remoteRoomCall` serializes
+     * the return value across process boundaries.
+     *
+     * @internal Operator-only. Game code should not call this.
+     */
+    getInspectorView(): {
+        roomId: string;
+        name: string;
+        clients: number;
+        maxClients: number;
+        locked: boolean;
+        elapsedTime: number;
+        metadata: any;
+        clientList: Array<{
+            sessionId: string;
+            userId: string | null;
+            userEmail: string | null;
+            elapsedTime: number;
+        }>;
+        state: any;
+        stateSize: number;
+    };
+    /**
+     * Force-disconnect a single client by sessionId. No-op when the client
+     * isn't connected (idempotent — the caller doesn't need to race-check).
+     *
+     * @internal Operator-only. Game code disconnects clients by calling
+     *   `.leave()` on the Client object directly.
+     */
+    kickClient(sessionId: string, closeCode?: number, reason?: string): void;
     /**
      * Disconnect all connected clients, and then dispose the room.
      *
@@ -469,20 +758,18 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
     allowReconnection(previousClient: Client, seconds: number | "manual"): Deferred<Client>;
     private resetAutoDisposeTimeout;
     private broadcastMessageType;
+    /** Drain `#afterPatchBroadcasts` right after the patch — each as ONE shared
+     *  buffer fanned out to its (non-excepted) recipients. `enqueueRaw` handles
+     *  JOINED (send now) vs still-joining (buffer until JOIN) per client. */
+    private _flushAfterPatchBroadcasts;
     private sendFullState;
-    private _dequeueAfterPatchMessages;
+    /** Send each client's staged `afterNextPatch` frames as standalone frames right
+     *  after the patch, then reset the tracker. Iterates only the clients that staged
+     *  frames this cycle (`#pendingFrameClients`), never the full client list; empty
+     *  (→ O(1)) on a tick where nothing was staged. */
+    private _flushPendingClientFrames;
     private _reserveSeat;
     private _reserveMultipleSeats;
     private _onMessage;
     private _onLeave;
 }
-/**
- * (WIP) Alternative, method-based room definition.
- * We should be able to define
- */
-type RoomLifecycleMethods = 'messages' | 'onCreate' | 'onJoin' | 'onLeave' | 'onDispose' | 'onCacheRoom' | 'onRestoreRoom' | 'onDrop' | 'onReconnect' | 'onUncaughtException' | 'onAuth' | 'onBeforeShutdown' | 'onBeforePatch';
-type DefineRoomOptions<T extends RoomOptions = RoomOptions> = Partial<Pick<Room<T>, RoomLifecycleMethods>> & {
-    state?: ExtractRoomState<T> | (() => ExtractRoomState<T>);
-} & ThisType<Exclude<Room<T>, RoomLifecycleMethods>> & ThisType<Room<T>>;
-export declare function room<T>(options: DefineRoomOptions<T>): typeof Room<T>;
-export {};