@colyseus/core 0.18.0 → 0.18.1

package/build/Room.d.ts

@@ -1,5 +1,6 @@
-import { type InputAPI, type NumericFieldsOf } from './input/InputBuffer.ts';
-export { type InputAccessor, type InputAPI, type InputOptions, type NumericFieldsOf } from './input/InputBuffer.ts';
+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';
@@ -7,11 +8,44 @@ 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;
@@ -65,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;
@@ -227,11 +261,9 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
      * @internal
      */
     static __pluginLayout?: PluginLayout | null;
-    private onMessageEvents;
-    private onMessageValidators;
-    private onMessageFallbacks;
+    private get onMessageEvents();
+    private get onMessageValidators();
     private _serializer;
-    private _afterNextPatchQueue;
     private _simulationInterval;
     private _internalState;
     private _lockedExplicitly;
@@ -304,63 +336,71 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
      */
     onLeave?(client: ExtractRoomClient<T>, code?: number): void | Promise<any>;
     /**
-     * Per-client input accessor. Set by `defineInput()`. Call `room.input(sessionId)`
-     * each tick to read the latest decoded input and/or the buffered snapshot ring
-     * for that client.
+     * 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 }> {
-     *   input = this.defineInput(MoveInput);
+     *   inputs = this.defineInput(MoveInput);
      *
      *   onCreate() {
-     *     this.setSimulationInterval(() => {
-     *       for (const c of this.clients) {
-     *         const input = this.input(c.sessionId);
-     *         if (input.latest) this.apply(c, input.latest);
-     *         // for rollback / lockstep:
-     *         //   const snapshot = input.at(this.clock.ticks);
-     *         //   for (const snapshot of input.drain()) ...
-     *       }
-     *     }, 1000 / 30);
+     *     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);
      *   }
      * }
      * ```
      */
-    input?: InputAPI<ExtractRoomInput<T>>;
+    inputs?: InputAPI<ExtractRoomInput<T>>;
     /**
-     * Input configuration. Set via {@link defineInput} only.
-     * @internal
+     * @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 inputOptions?;
+    private _inputController?;
     /**
      * Declare the input schema and configuration in a single line. Returns the
-     * callable accessor that gets assigned to `this.input` — call
-     * `this.input(sessionId)` per tick to consume.
+     * input API that gets assigned to `this.inputs` — call
+     * `this.inputs.get(sessionId)` per tick to consume.
      *
      * ```typescript
      * class FpsRoom extends Room<{ input: MoveInput }> {
-     *   input = this.defineInput(MoveInput, {
+     *   inputs = this.defineInput(MoveInput, {
      *     seqField: "tick",       // typed: only numeric fields of MoveInput
      *     bufferMaxSize: 64,
      *   });
      *
-     *   // …or without options — defaults to seqField: "seq", bufferMaxSize: 32:
-     *   // input = this.defineInput(MoveInput);
+     *   // …or without options — no seq dedupe, bufferMaxSize: 32:
+     *   // inputs = this.defineInput(MoveInput);
      * }
      * ```
      *
      * **Defaults** when `opts` (or individual fields) are omitted:
-     * - `seqField`: `"seq"` — framework dedupes by `input.seq` if the schema has
-     *   such a field. Schemas without it gracefully skip dedupe.
+     * - `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
-     *   `room.input(sessionId).drain() / .peek() / .at()`. Set to `0` to disable
-     *   buffering (the `.latest` read still works).
+     *   `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>(type: C, opts?: {
-        seqField?: NumericFieldsOf<InstanceType<C>>;
-        bufferMaxSize?: number;
-    }): InputAPI<InstanceType<C>>;
+    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.
      */
@@ -373,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)
      */
@@ -429,48 +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;
     /**
-     * Run a fixed-rate simulation tagged with a monotonic server tick number.
-     * Combine with `room.input(sessionId).at(tick)` to retrieve each client's
-     * input *for a specific tick* — the building block for lockstep / rollback
-     * netcode.
-     *
-     * Replaces any previous {@link setSimulationInterval}. The current tick is
-     * exposed via {@link tick}.
+     * 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
-     * ```typescript
-     * class LockstepRoom extends Room<{ input: MoveInput }> {
-     *   input = this.defineInput(MoveInput, { seqField: "tick", bufferMaxSize: 64 });
-     *
-     *   onCreate() {
-     *     this.setTickedSimulation((tick, dt) => {
-     *       for (const c of this.clients) {
-     *         const snapshot = this.input(c.sessionId).at(tick);
-     *         if (snapshot) this.apply(c, snapshot);
-     *         // else: predict, freeze, etc. — game-level decision
-     *       }
-     *     }, 1000 / 60);
-     *   }
+     * ```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 });
      * }
      * ```
      */
-    setTickedSimulation(onTickCallback: (tick: number, deltaTime: number) => void, delay?: number, startTick?: number): void;
-    /**
-     * Current server tick. Incremented by {@link setTickedSimulation} after each
-     * tick callback returns. Returns 0 when no ticked simulation is running.
+    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).
      */
-    get tick(): number;
+    allowRewindState(opts?: RewindOptions): Rewind;
     /**
      * @deprecated Use `.patchRate=` instead.
      */
@@ -581,8 +686,8 @@ 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;
     /**
@@ -653,19 +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>;