@colyseus/core 0.18.0 → 0.18.1

package/build/Room.mjs

@@ -1,9 +1,10 @@
 // packages/core/src/Room.ts
-import { unpack } from "msgpackr";
-import { decode, Encoder, Reflection, $changes } from "@colyseus/schema";
-import { InputDecoder } from "@colyseus/schema/input";
-import { InputAccessorImpl, InputBufferImpl, NO_OP_INPUT_ACCESSOR } from "./input/InputBuffer.mjs";
-import {} from "./input/InputBuffer.mjs";
+import { $changes } from "@colyseus/schema";
+import { validateSubSteps } from "./input/InputBuffer.mjs";
+import { RoomInput } from "./input/RoomInput.mjs";
+import { RoomMessages } from "./RoomMessages.mjs";
+import { Rewind } from "./Rewind.mjs";
+import {} from "./input/types.mjs";
 import { ClockTimer as Clock } from "@colyseus/timer";
 import { EventEmitter } from "events";
 import { logger } from "./Logger.mjs";
@@ -11,20 +12,19 @@ import { NoneSerializer } from "./serializer/NoneSerializer.mjs";
 import { SchemaSerializer } from "./serializer/SchemaSerializer.mjs";
 import { getMessageBytes } from "./Protocol.mjs";
 import { Deferred, generateId, wrapTryCatch } from "./utils/Utils.mjs";
-import { createNanoEvents } from "./utils/nanoevents.mjs";
 import { isDevMode } from "./utils/DevMode.mjs";
 import { debugAndPrintError, debugMatchMaking, debugMessage } from "./Debug.mjs";
 import { ServerError } from "./errors/ServerError.mjs";
 import { ClientState, ClientArray } from "./Transport.mjs";
-import { OnAuthException, OnCreateException, OnDisposeException, OnDropException, OnJoinException, OnLeaveException, OnMessageException, OnReconnectException, SimulationIntervalException, TimedEventException } from "./errors/RoomExceptions.mjs";
-import { standardValidate } from "./utils/StandardSchema.mjs";
+import { OnAuthException, OnCreateException, OnDisposeException, OnDropException, OnJoinException, OnLeaveException, OnReconnectException, TimestepException, TimedEventException } from "./errors/RoomExceptions.mjs";
+import "./utils/StandardSchema.mjs";
 import * as matchMaker from "./MatchMaker.mjs";
 import {
   CloseCode,
   ErrorCode,
-  HandshakeSection,
   Protocol,
-  ResponseStatus
+  PROTOCOL_CODE_MASK,
+  PROTOCOL_MODIFIER_MASK
 } from "@colyseus/shared-types";
 import {
   setupRoomPlugins
@@ -34,17 +34,10 @@ import {
   definePlugins,
   attachToTestRoom
 } from "./RoomPlugin.mjs";
-var _inputReflectionCache = /* @__PURE__ */ new WeakMap();
 var DEFAULT_PATCH_RATE = 1e3 / 20;
 var DEFAULT_SIMULATION_INTERVAL = 1e3 / 60;
 var noneSerializer = new NoneSerializer();
-function toResponseError(e) {
-  if (e instanceof Error) {
-    const code = e.code;
-    return code !== void 0 ? { name: e.name, message: e.message, code } : { name: e.name, message: e.message };
-  }
-  return { name: "Error", message: String(e) };
-}
+var AFTER_PATCH_OPTS = Object.freeze({ afterNextPatch: true });
 var DEFAULT_SEAT_RESERVATION_TIME = Number(process.env.COLYSEUS_SEAT_RESERVATION_TIME || 15);
 function validate(format, handler) {
   return { format, handler };
@@ -109,25 +102,22 @@ var Room = class _Room {
     this._reservedSeatTimeouts = {};
     this._reconnections = {};
     this._reconnectionAttempts = {};
-    this.onMessageEvents = createNanoEvents();
-    this.onMessageValidators = {};
-    this.onMessageFallbacks = {
-      "__no_message_handler": (client, messageType, _) => {
-        const errorMessage = `room onMessage for "${messageType}" not registered.`;
-        debugMessage(`${errorMessage} (roomId: ${this.roomId})`);
-        if (isDevMode) {
-          client.error(ErrorCode.INVALID_PAYLOAD, errorMessage);
-        } else {
-          client.leave(CloseCode.WITH_ERROR, errorMessage);
-        }
-      }
-    };
+    /** @internal Message-routing layer: handler registry + user-message decode/dispatch. */
+    this.#_messages = new RoomMessages(this);
     this._serializer = noneSerializer;
-    this._afterNextPatchQueue = [];
+    /** Clients that staged `afterNextPatch` frames since the last patch, so the
+     *  post-patch flush iterates only these — never the full client list. Shared by
+     *  reference onto each client at join. Reset each `broadcastPatch`. */
+    this.#pendingFrameClients = [];
+    /** `broadcast(..., { afterNextPatch })` in NON-timed rooms, sent as a SHARED
+     *  frame right after the next patch (one encode, N sends). Non-timed patches are
+     *  themselves a shared buffer, so a per-client copy would force N× allocation in
+     *  large rooms — sharing avoids that. TIMED rooms instead stage the broadcast onto
+     *  each client's `_pendingFrames`. Drained each `broadcastPatch`. */
+    this.#afterPatchBroadcasts = [];
     this._internalState = RoomInternalState.CREATING;
     this._lockedExplicitly = false;
     this.#_locked = false;
-    this.#_tick = 0;
     this._events.once("dispose", () => {
       this.#_dispose().catch((e) => debugAndPrintError(`onDispose error: ${e && e.stack || e.message || e || "promise rejected"} (roomId: ${this.roomId})`)).finally(() => this._events.emit("disconnect"));
     });
@@ -180,6 +170,17 @@ var Room = class _Room {
   #_patchRate;
   #_patchInterval;
   #_state;
+  #_messages;
+  // Re-expose the registry for @colyseus/playground introspection and
+  // @colyseus/testing handler-swapping (both reach in via bracket access).
+  get onMessageEvents() {
+    return this.#_messages.events;
+  }
+  get onMessageValidators() {
+    return this.#_messages.validators;
+  }
+  #pendingFrameClients;
+  #afterPatchBroadcasts;
   #_locked;
   /**
    * This method is called by the MatchMaker before onCreate()
@@ -305,41 +306,41 @@ var Room = class _Room {
   }
   /**
    * 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.
    */
   defineInput(type, opts) {
-    this.inputOptions = {
-      ctor: type,
-      seqField: opts?.seqField ?? "seq",
-      bufferMaxSize: opts?.bufferMaxSize ?? 32
-    };
-    if (!_inputReflectionCache.has(type)) {
-      _inputReflectionCache.set(type, Reflection.encode(new Encoder(new type())));
-    }
-    return ((sessionId) => {
-      const c = this.clients.getById(sessionId);
-      return c?._inputAccessor ?? NO_OP_INPUT_ACCESSOR;
-    });
+    this._inputController ??= new RoomInput(this);
+    return this._inputController.define(type, opts);
   }
   /**
    * This method is called before onJoin() - this is where you should authenticate the client
@@ -400,7 +401,7 @@ var Room = class _Room {
         reservedSeat[3] && this._reconnections[reconnectionToken]?.[0] === sessionId
       );
     } else if (typeof reconnectionToken === "string") {
-      return this.clients.getById(sessionId)?.reconnectionToken === reconnectionToken;
+      return this.clients.get(sessionId)?.reconnectionToken === reconnectionToken;
     }
     return false;
   }
@@ -418,22 +419,27 @@ var Room = class _Room {
     return void 0;
   }
   /**
-   * (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.
    */
-  setSimulationInterval(onTickCallback, delay = DEFAULT_SIMULATION_INTERVAL) {
+  setTimestep(onTickCallback, delay = DEFAULT_SIMULATION_INTERVAL) {
     if (this._simulationInterval) {
       clearInterval(this._simulationInterval);
     }
+    if (onTickCallback && this._inputController && this._inputController.options.tickRate === void 0) {
+      this._inputController.options.tickRate = Math.round(1e3 / delay);
+    }
     if (onTickCallback) {
       if (this.onUncaughtException !== void 0) {
-        onTickCallback = wrapTryCatch(onTickCallback, this.onUncaughtException.bind(this), SimulationIntervalException, "setSimulationInterval");
+        onTickCallback = wrapTryCatch(onTickCallback, this.onUncaughtException.bind(this), TimestepException, "setTimestep");
       }
       this._simulationInterval = setInterval(() => {
         this.clock.tick();
@@ -442,46 +448,157 @@ var Room = class _Room {
     }
   }
   /**
-   * 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.
+   * @deprecated Renamed to {@link Room.setTimestep} (which pairs with
+   * {@link Room.setFixedTimestep}). Kept for backwards compatibility — forwards
+   * to `setTimestep` unchanged.
+   */
+  setSimulationInterval(onTickCallback, delay = DEFAULT_SIMULATION_INTERVAL) {
+    this.setTimestep(onTickCallback, delay);
+  }
+  /**
+   * 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.
    *
-   * Replaces any previous {@link setSimulationInterval}. The current tick is
-   * exposed via {@link tick}.
+   * `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}.
    *
-   * @example
-   * ```typescript
-   * class LockstepRoom extends Room<{ input: MoveInput }> {
-   *   input = this.defineInput(MoveInput, { seqField: "tick", bufferMaxSize: 64 });
+   * **`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).
    *
-   *   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);
-   *   }
+   * 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 });
    * }
    * ```
    */
-  setTickedSimulation(onTickCallback, delay = DEFAULT_SIMULATION_INTERVAL, startTick = 0) {
-    this.#_tick = startTick;
-    this.setSimulationInterval((dt) => {
-      onTickCallback(this.#_tick, dt);
-      this.#_tick++;
-    }, delay);
+  setFixedTimestep(step, tickRate = Math.round(1e3 / DEFAULT_SIMULATION_INTERVAL), opts) {
+    if (this._simulationInterval) {
+      clearInterval(this._simulationInterval);
+    }
+    const stepMs = 1e3 / tickRate;
+    const stepSeconds = 1 / tickRate;
+    const subSteps = validateSubSteps(opts?.subSteps, "setFixedTimestep") ?? this._inputController?.options.subSteps ?? 1;
+    if (this._inputController) {
+      this._inputController.options.tickRate = tickRate;
+      this._inputController.options.subSteps = subSteps;
+    }
+    let cb = step;
+    if (this.onUncaughtException !== void 0) {
+      cb = wrapTryCatch(step, this.onUncaughtException.bind(this), TimestepException, "setFixedTimestep");
+    }
+    let acc = 0;
+    let tick = 0;
+    const ctx = {
+      dt: stepSeconds,
+      dtMs: stepMs,
+      tick: 0,
+      subSteps,
+      subDt: stepSeconds / subSteps,
+      subDtMs: stepMs / subSteps
+    };
+    const MAX_CATCHUP_STEPS = 5;
+    this._simulationInterval = setInterval(() => {
+      this.clock.tick();
+      acc += this.clock.deltaTime;
+      let ran = 0;
+      while (acc >= stepMs && ran < MAX_CATCHUP_STEPS) {
+        acc -= stepMs;
+        ctx.tick = tick++;
+        cb(ctx);
+        ran++;
+      }
+      if (ran === MAX_CATCHUP_STEPS) {
+        acc = 0;
+      }
+    }, stepMs);
+  }
+  /** Server-side lag compensation, lazily created. @see allowRewindState */
+  #rewind;
+  /** @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() {
+    return this.#rewind?.timelineMode();
   }
   /**
-   * Current server tick. Incremented by {@link setTickedSimulation} after each
-   * tick callback returns. Returns 0 when no ticked simulation is running.
+   * 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() {
-    return this.#_tick;
+  allowRewindState(opts) {
+    this.#rewind = Rewind.get(this, opts);
+    this.#rewind.bindRenderTime((sessionId) => {
+      const api = this._inputController?.api;
+      if (api === void 0) {
+        throw new Error(
+          "rewind.lastSeenBy() found no input API. Declare `inputs = this.defineInput(YourInput)`, or use rewind.at(time) with a render time you track yourself."
+        );
+      }
+      return api.get(sessionId).renderTime;
+    });
+    this.#rewind.bindReckonTime(
+      (sessionId) => this._inputController?.rawReckonTime(sessionId) ?? 0
+    );
+    this.#rewind.bindNow(() => this.clock.elapsedTime);
+    return this.#rewind;
   }
-  #_tick;
   /**
    * @deprecated Use `.patchRate=` instead.
    */
@@ -654,22 +771,12 @@ var Room = class _Room {
    */
   broadcast(type, ...args) {
     const [message, options] = args;
-    if (options && options.afterNextPatch) {
-      delete options.afterNextPatch;
-      this._afterNextPatchQueue.push(["broadcast", [type, ...args]]);
-      return;
-    }
     this.broadcastMessageType(type, message, options);
   }
   /**
    * Broadcast bytes (UInt8Arrays) to a particular room
    */
   broadcastBytes(type, message, options) {
-    if (options && options.afterNextPatch) {
-      delete options.afterNextPatch;
-      this._afterNextPatchQueue.push(["broadcastBytes", arguments]);
-      return;
-    }
     this.broadcastMessageType(type, message, options);
   }
   /**
@@ -685,34 +792,25 @@ var Room = class _Room {
     if (!this.state) {
       return false;
     }
-    const hasChanges = this._serializer.applyPatches(this.clients, this.state);
-    this._dequeueAfterPatchMessages();
+    const sNow = this.clock.elapsedTime;
+    const hasChanges = this._serializer.applyPatches(
+      this.clients,
+      this.state,
+      this._inputController !== void 0 ? { sNow } : void 0
+    );
+    this._flushPendingClientFrames();
+    this._flushAfterPatchBroadcasts();
+    const rw = this.#rewind;
+    if (rw !== void 0 && rw.lastRecordedAt !== sNow) {
+      rw.record(sNow, this.#_patchRate || void 0);
+    }
     return hasChanges;
   }
   onMessage(_messageType, _validationSchema, _callback) {
-    const messageType = _messageType.toString();
-    const validationSchema = typeof _callback === "function" ? _validationSchema : void 0;
-    const callback = validationSchema === void 0 ? _validationSchema : _callback;
-    const removeListener = this.onMessageEvents.on(messageType, this.onUncaughtException !== void 0 ? wrapTryCatch(callback, this.onUncaughtException.bind(this), OnMessageException, "onMessage", false, _messageType) : callback);
-    if (validationSchema !== void 0) {
-      this.onMessageValidators[messageType] = validationSchema;
-    }
-    return () => {
-      removeListener();
-      if (this.onMessageEvents.events[messageType].length === 0) {
-        delete this.onMessageValidators[messageType];
-      }
-    };
+    return this.#_messages.on(_messageType, _validationSchema, _callback);
   }
   onMessageBytes(_messageType, _validationSchema, _callback) {
-    const messageType = `_$b${_messageType}`;
-    const validationSchema = typeof _callback === "function" ? _validationSchema : void 0;
-    const callback = validationSchema === void 0 ? _validationSchema : _callback;
-    if (validationSchema !== void 0) {
-      return this.onMessage(messageType, validationSchema, callback);
-    } else {
-      return this.onMessage(messageType, callback);
-    }
+    return this.#_messages.on(`_$b${_messageType}`, _validationSchema, _callback);
   }
   // ---------------------------------------------------------------------------
   // Operator API — used by @colyseus/admin (and monitor in due course)
@@ -845,15 +943,7 @@ var Room = class _Room {
   async _onJoin(client, authContext, connectionOptions) {
     const sessionId = client.sessionId;
     client.reconnectionToken = generateId();
-    if (this.inputOptions !== void 0) {
-      client._input = new this.inputOptions.ctor();
-      client._inputDecoder = new InputDecoder(client._input);
-      const maxSize = this.inputOptions.bufferMaxSize;
-      if (maxSize > 0) {
-        client._inputBuffer = new InputBufferImpl(maxSize, this.inputOptions.seqField);
-      }
-      client._inputAccessor = new InputAccessorImpl(client);
-    }
+    this._inputController?.allocate(client);
     if (this._reservedSeatTimeouts[sessionId]) {
       clearTimeout(this._reservedSeatTimeouts[sessionId]);
       delete this._reservedSeatTimeouts[sessionId];
@@ -862,7 +952,7 @@ var Room = class _Room {
       clearTimeout(this._autoDisposeTimeout);
       this._autoDisposeTimeout = void 0;
     }
-    if (this._reservedSeats[sessionId] === void 0 && connectionOptions?.reconnectionToken && this.clients.getById(sessionId)?.reconnectionToken === connectionOptions.reconnectionToken) {
+    if (this._reservedSeats[sessionId] === void 0 && connectionOptions?.reconnectionToken && this.clients.get(sessionId)?.reconnectionToken === connectionOptions.reconnectionToken) {
       debugMatchMaking("attempting to reconnect client with a stale previous connection - sessionId: '%s', roomId: '%s'", client.sessionId, this.roomId);
       this._reconnectionAttempts[connectionOptions.reconnectionToken] = new Deferred();
       const reconnectionAttemptTimeout = setTimeout(() => {
@@ -883,13 +973,14 @@ var Room = class _Room {
     }
     this._reservedSeats[sessionId][2] = true;
     debugMatchMaking("consuming seat reservation, sessionId: '%s' (roomId: %s)", client.sessionId, this.roomId);
-    client._afterNextPatchQueue = this._afterNextPatchQueue;
+    client._pendingFrameClients = this.#pendingFrameClients;
     client.ref["onleave"] = (_) => client.state = ClientState.LEAVING;
     client.ref.once("close", client.ref["onleave"]);
     if (isWaitingReconnection) {
       const reconnectionToken = connectionOptions?.reconnectionToken;
       if (reconnectionToken && this._reconnections[reconnectionToken]?.[0] === sessionId) {
         this.clients.push(client);
+        this._inputController?.register(sessionId, client);
         await this._reconnections[reconnectionToken]?.[1].resolve(client);
         try {
           if (this.onReconnect) {
@@ -929,6 +1020,7 @@ var Room = class _Room {
           throw new ServerError(CloseCode.WITH_ERROR, "already disconnected");
         }
         this.clients.push(client);
+        this._inputController?.register(sessionId, client);
         Object.defineProperty(this._reservedSeats, sessionId, {
           value: this._reservedSeats[sessionId],
           enumerable: false
@@ -956,13 +1048,7 @@ var Room = class _Room {
       client.ref["onleave"] = this._onLeave.bind(this, client);
       client.ref.once("close", client.ref["onleave"]);
       client.ref.on("message", this._onMessage.bind(this, client));
-      let extraSections;
-      if (!connectionOptions?.skipHandshake && this.inputOptions !== void 0) {
-        const inputBytes = _inputReflectionCache.get(this.inputOptions.ctor);
-        if (inputBytes !== void 0) {
-          extraSections = [{ tag: HandshakeSection.INPUT_REFLECTION, bytes: inputBytes }];
-        }
-      }
+      const extraSections = this._inputController?.handshakeSections();
       client.raw(getMessageBytes[Protocol.JOIN_ROOM](
         client.reconnectionToken,
         this._serializer.id,
@@ -1058,36 +1144,64 @@ var Room = class _Room {
     debugMessage("broadcast: %O (roomId: %s)", message, this.roomId);
     const encodedMessage = message instanceof Uint8Array ? getMessageBytes.raw(Protocol.ROOM_DATA_BYTES, type, void 0, message) : getMessageBytes.raw(Protocol.ROOM_DATA, type, message);
     const except = typeof options.except !== "undefined" ? Array.isArray(options.except) ? options.except : [options.except] : void 0;
+    if (options.afterNextPatch && this._inputController === void 0) {
+      this.#afterPatchBroadcasts.push({ bytes: encodedMessage, except });
+      return;
+    }
+    const sendOpts = options.afterNextPatch ? AFTER_PATCH_OPTS : void 0;
     let numClients = this.clients.length;
     while (numClients--) {
       const client = this.clients[numClients];
       if (!except || !except.includes(client)) {
-        client.enqueueRaw(encodedMessage);
+        client.enqueueRaw(encodedMessage, sendOpts);
       }
     }
   }
-  // Encode and enqueue a ROOM_RESPONSE for a client request. If the client has
-  // already left, `enqueueRaw` is a no-op — no response is needed.
-  #replyToRequest(client, requestId, status, payload) {
-    debugMessage("response #%d: status=%d -> %j (roomId: %s)", requestId, status, payload, this.roomId);
-    client.enqueueRaw(getMessageBytes[Protocol.ROOM_RESPONSE](requestId, status, payload));
+  /** 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. */
+  _flushAfterPatchBroadcasts() {
+    const queued = this.#afterPatchBroadcasts;
+    if (queued.length === 0) {
+      return;
+    }
+    for (let i = 0; i < queued.length; i++) {
+      const { bytes, except } = queued[i];
+      let numClients = this.clients.length;
+      while (numClients--) {
+        const client = this.clients[numClients];
+        if (!except || !except.includes(client)) {
+          client.enqueueRaw(bytes);
+        }
+      }
+    }
+    queued.length = 0;
   }
   sendFullState(client) {
-    client.raw(this._serializer.getFullState(client));
+    client.raw(this._serializer.getFullState(
+      client,
+      this._inputController !== void 0 ? { sNow: this.clock.elapsedTime } : void 0
+    ));
   }
-  _dequeueAfterPatchMessages() {
-    const length = this._afterNextPatchQueue.length;
-    if (length > 0) {
-      for (let i = 0; i < length; i++) {
-        const [target, args] = this._afterNextPatchQueue[i];
-        if (target === "broadcast") {
-          this.broadcast.apply(this, args);
-        } else {
-          target.raw.apply(target, args);
+  /** 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. */
+  _flushPendingClientFrames() {
+    const dirty = this.#pendingFrameClients;
+    if (dirty.length === 0) {
+      return;
+    }
+    for (let i = 0; i < dirty.length; i++) {
+      const frames = dirty[i]._pendingFrames;
+      if (frames !== void 0 && frames.length > 0) {
+        for (let j = 0; j < frames.length; j++) {
+          dirty[i].raw(frames[j]);
         }
+        frames.length = 0;
       }
-      this._afterNextPatchQueue.splice(0, length);
     }
+    dirty.length = 0;
   }
   async _reserveSeat(sessionId, joinOptions = true, authData = void 0, seconds = this.seatReservationTimeout, allowReconnection = false, devModeReconnectionToken) {
     if (!allowReconnection && this.hasReachedMaxClients()) {
@@ -1121,6 +1235,7 @@ var Room = class _Room {
         delete this._reconnections[devModeReconnectionToken];
         delete this._reservedSeats[sessionId];
         delete this._reservedSeatTimeouts[sessionId];
+        this._inputController?.release(sessionId);
         if (!allowReconnection) {
           await this.#_decrementClientCount();
         }
@@ -1162,33 +1277,14 @@ var Room = class _Room {
       this._simulationInterval = void 0;
     }
     if (this._autoDisposeTimeout) {
-      clearInterval(this._autoDisposeTimeout);
+      clearTimeout(this._autoDisposeTimeout);
       this._autoDisposeTimeout = void 0;
     }
     this.clock.clear();
     this.clock.stop();
+    this._inputController?.dispose();
     return await (userReturnData || Promise.resolve());
   }
-  /**
-   * After the decoder has mutated `client._input`, push a clone into the
-   * per-client buffer (when buffering is enabled). Honors
-   * `inputOptions.seqField` for dedupe of redundant frames.
-   */
-  #captureInput(client) {
-    const buf = client._inputBuffer;
-    if (!buf) {
-      return;
-    }
-    const inst = client._input;
-    const seqField = this.inputOptions?.seqField;
-    if (seqField !== void 0) {
-      const value = inst[seqField];
-      if (typeof value === "number" && !buf.accept(value)) {
-        return;
-      }
-    }
-    buf.push(inst.clone());
-  }
   _onMessage(client, buffer) {
     if (client.state === ClientState.LEAVING) {
       return;
@@ -1205,98 +1301,18 @@ var Room = class _Room {
       return this.#_forciblyCloseClient(client, CloseCode.WITH_ERROR);
     }
     const it = { offset: 1 };
-    const code = buffer[0];
+    const code = buffer[0] & PROTOCOL_CODE_MASK;
+    const modifiers = buffer[0] & PROTOCOL_MODIFIER_MASK;
     if (code === Protocol.ROOM_DATA) {
-      const messageType = decode.stringCheck(buffer, it) ? decode.string(buffer, it) : decode.number(buffer, it);
-      let message;
-      try {
-        message = buffer.byteLength > it.offset ? unpack(buffer.subarray(it.offset, buffer.byteLength)) : void 0;
-        debugMessage("received: '%s' -> %j (roomId: %s)", messageType, message, this.roomId);
-        if (this.onMessageValidators[messageType] !== void 0) {
-          message = standardValidate(this.onMessageValidators[messageType], message);
-        }
-      } catch (e) {
-        debugAndPrintError(e);
-        client.leave(CloseCode.WITH_ERROR);
-        return;
-      }
-      if (this.onMessageEvents.events[messageType]) {
-        this.onMessageEvents.emit(messageType, client, message);
-      } else if (this.onMessageEvents.events["*"]) {
-        this.onMessageEvents.emit("*", client, messageType, message);
-      } else {
-        this.onMessageFallbacks["__no_message_handler"](client, messageType, message);
-      }
+      this.#_messages.onData(client, buffer, it);
     } else if (code === Protocol.ROOM_REQUEST) {
-      const requestId = decode.number(buffer, it);
-      const messageType = decode.stringCheck(buffer, it) ? decode.string(buffer, it) : decode.number(buffer, it);
-      let message;
-      try {
-        message = buffer.byteLength > it.offset ? unpack(buffer.subarray(it.offset, buffer.byteLength)) : void 0;
-        debugMessage("request #%d: '%s' -> %j (roomId: %s)", requestId, messageType, message, this.roomId);
-        if (this.onMessageValidators[messageType] !== void 0) {
-          message = standardValidate(this.onMessageValidators[messageType], message);
-        }
-      } catch (e) {
-        debugAndPrintError(e);
-        this.#replyToRequest(client, requestId, ResponseStatus.ERROR, toResponseError(e));
-        return;
-      }
-      const handler = this.onMessageEvents.events[messageType]?.[0];
-      if (handler === void 0) {
-        this.#replyToRequest(client, requestId, ResponseStatus.ERROR, {
-          name: "no_handler",
-          message: `room "${this.roomName}" has no onMessage("${messageType}") handler to answer this request.`
-        });
-        return;
-      }
-      Promise.resolve().then(() => handler(client, message)).then(
-        (response) => this.#replyToRequest(client, requestId, ResponseStatus.OK, response),
-        (e) => {
-          debugAndPrintError(e);
-          this.#replyToRequest(client, requestId, ResponseStatus.ERROR, toResponseError(e));
-        }
-      );
+      this.#_messages.onRequest(client, buffer, it);
     } else if (code === Protocol.ROOM_DATA_BYTES) {
-      const messageType = decode.stringCheck(buffer, it) ? decode.string(buffer, it) : decode.number(buffer, it);
-      let message = buffer.subarray(it.offset, buffer.byteLength);
-      debugMessage("received: '%s' -> %j (roomId: %s)", messageType, message, this.roomId);
-      const bytesMessageType = `_$b${messageType}`;
-      try {
-        if (this.onMessageValidators[bytesMessageType] !== void 0) {
-          message = standardValidate(this.onMessageValidators[bytesMessageType], message);
-        }
-      } catch (e) {
-        debugAndPrintError(e);
-        client.leave(CloseCode.WITH_ERROR);
-        return;
-      }
-      if (this.onMessageEvents.events[bytesMessageType]) {
-        this.onMessageEvents.emit(bytesMessageType, client, message);
-      } else if (this.onMessageEvents.events["*"]) {
-        this.onMessageEvents.emit("*", client, messageType, message);
-      } else {
-        this.onMessageFallbacks["__no_message_handler"](client, messageType, message);
-      }
+      this.#_messages.onDataBytes(client, buffer, it);
     } else if (code === Protocol.ROOM_INPUT_RELIABLE) {
-      if (client._inputDecoder) {
-        try {
-          client._inputDecoder.decode(buffer.subarray(1));
-        } catch (e) {
-          debugAndPrintError(e);
-          return;
-        }
-        this.#captureInput(client);
-      }
+      this._inputController?.decodeReliable(client, buffer, it, modifiers);
     } else if (code === Protocol.ROOM_INPUT_UNRELIABLE) {
-      if (client._inputDecoder) {
-        try {
-          client._inputDecoder.decodeAll(buffer.subarray(1), () => this.#captureInput(client));
-        } catch (e) {
-          debugAndPrintError(e);
-          return;
-        }
-      }
+      this._inputController?.decodeUnreliable(client, buffer, modifiers);
     } else if (code === Protocol.JOIN_ROOM && client.state === ClientState.JOINING) {
       client.state = ClientState.JOINED;
       client._joinedAt = this.clock.elapsedTime;
@@ -1324,6 +1340,7 @@ var Room = class _Room {
     if (!this.clients.delete(client)) {
       return;
     }
+    this._inputController?.freeze(client);
     if (method) {
       debugMatchMaking(`${method.name}, sessionId: '%s' (close code: %d, roomId: %s)`, client.sessionId, code, this.roomId);
       try {
@@ -1350,6 +1367,7 @@ var Room = class _Room {
     }
     const willDispose = await this.#_decrementClientCount();
     if (this._reservedSeats[client.sessionId] === void 0) {
+      this._inputController?.release(client.sessionId);
       this._events.emit("leave", client, willDispose);
     }
   }
@@ -1413,23 +1431,6 @@ var Room = class _Room {
     }
   }
 };
-function room(options) {
-  class _ extends Room {
-    constructor() {
-      super();
-      this.messages = options.messages;
-      if (options.state && typeof options.state === "function") {
-        this.state = options.state();
-      }
-    }
-  }
-  for (const key in options) {
-    if (typeof options[key] === "function") {
-      _.prototype[key] = options[key];
-    }
-  }
-  return _;
-}
 export {
   DEFAULT_SEAT_RESERVATION_TIME,
   Room,
@@ -1437,6 +1438,5 @@ export {
   RoomPlugin2 as RoomPlugin,
   attachToTestRoom,
   definePlugins,
-  room,
   validate
 };