@colyseus/core 0.17.44 → 0.18.1

package/build/Room.cjs

@@ -33,12 +33,18 @@ __export(Room_exports, {
   DEFAULT_SEAT_RESERVATION_TIME: () => DEFAULT_SEAT_RESERVATION_TIME,
   Room: () => Room,
   RoomInternalState: () => RoomInternalState,
-  room: () => room,
+  RoomPlugin: () => import_RoomPlugin2.RoomPlugin,
+  attachToTestRoom: () => import_RoomPlugin2.attachToTestRoom,
+  definePlugins: () => import_RoomPlugin2.definePlugins,
   validate: () => validate
 });
 module.exports = __toCommonJS(Room_exports);
-var import_msgpackr = require("@colyseus/msgpackr");
 var import_schema = require("@colyseus/schema");
+var import_InputBuffer = require("./input/InputBuffer.cjs");
+var import_RoomInput = require("./input/RoomInput.cjs");
+var import_RoomMessages = require("./RoomMessages.cjs");
+var import_Rewind = require("./Rewind.cjs");
+var import_types = require("./input/types.cjs");
 var import_timer = require("@colyseus/timer");
 var import_events = require("events");
 var import_Logger = require("./Logger.cjs");
@@ -46,7 +52,6 @@ var import_NoneSerializer = require("./serializer/NoneSerializer.cjs");
 var import_SchemaSerializer = require("./serializer/SchemaSerializer.cjs");
 var import_Protocol = require("./Protocol.cjs");
 var import_Utils = require("./utils/Utils.cjs");
-var import_nanoevents = require("./utils/nanoevents.cjs");
 var import_DevMode = require("./utils/DevMode.cjs");
 var import_Debug = require("./Debug.cjs");
 var import_ServerError = require("./errors/ServerError.cjs");
@@ -55,9 +60,12 @@ var import_RoomExceptions = require("./errors/RoomExceptions.cjs");
 var import_StandardSchema = require("./utils/StandardSchema.cjs");
 var matchMaker = __toESM(require("./MatchMaker.cjs"), 1);
 var import_shared_types = require("@colyseus/shared-types");
+var import_RoomPlugin = require("./RoomPlugin.cjs");
+var import_RoomPlugin2 = require("./RoomPlugin.cjs");
 var DEFAULT_PATCH_RATE = 1e3 / 20;
 var DEFAULT_SIMULATION_INTERVAL = 1e3 / 60;
 var noneSerializer = new import_NoneSerializer.NoneSerializer();
+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 };
@@ -122,21 +130,19 @@ var Room = class _Room {
     this._reservedSeatTimeouts = {};
     this._reconnections = {};
     this._reconnectionAttempts = {};
-    this.onMessageEvents = (0, import_nanoevents.createNanoEvents)();
-    this.onMessageValidators = {};
-    this.onMessageFallbacks = {
-      "__no_message_handler": (client, messageType, _) => {
-        const errorMessage = `room onMessage for "${messageType}" not registered.`;
-        (0, import_Debug.debugMessage)(`${errorMessage} (roomId: ${this.roomId})`);
-        if (import_DevMode.isDevMode) {
-          client.error(import_shared_types.ErrorCode.INVALID_PAYLOAD, errorMessage);
-        } else {
-          client.leave(import_shared_types.CloseCode.WITH_ERROR, errorMessage);
-        }
-      }
-    };
+    /** @internal Message-routing layer: handler registry + user-message decode/dispatch. */
+    this.#_messages = new import_RoomMessages.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;
@@ -192,6 +198,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()
@@ -256,6 +273,9 @@ var Room = class _Room {
     if (this.#_state) {
       this.state = this.#_state;
     }
+    if (this.plugins !== void 0) {
+      (0, import_RoomPlugin.setupRoomPlugins)(this);
+    }
     if (this.messages !== void 0) {
       if (this.messages["_"]) {
         this.onMessage("*", this.messages["_"].bind(this));
@@ -312,6 +332,44 @@ var Room = class _Room {
     }
     this.#_roomId = roomId;
   }
+  /**
+   * 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.
+   */
+  defineInput(type, opts) {
+    this._inputController ??= new import_RoomInput.RoomInput(this);
+    return this._inputController.define(type, opts);
+  }
   /**
    * This method is called before onJoin() - this is where you should authenticate the client
    * @param client - The client that is authenticating.
@@ -371,7 +429,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;
   }
@@ -389,22 +447,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 = (0, import_Utils.wrapTryCatch)(onTickCallback, this.onUncaughtException.bind(this), import_RoomExceptions.SimulationIntervalException, "setSimulationInterval");
+        onTickCallback = (0, import_Utils.wrapTryCatch)(onTickCallback, this.onUncaughtException.bind(this), import_RoomExceptions.TimestepException, "setTimestep");
       }
       this._simulationInterval = setInterval(() => {
         this.clock.tick();
@@ -412,6 +475,158 @@ var Room = class _Room {
       }, delay);
     }
   }
+  /**
+   * @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.
+   *
+   * `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, tickRate = Math.round(1e3 / DEFAULT_SIMULATION_INTERVAL), opts) {
+    if (this._simulationInterval) {
+      clearInterval(this._simulationInterval);
+    }
+    const stepMs = 1e3 / tickRate;
+    const stepSeconds = 1 / tickRate;
+    const subSteps = (0, import_InputBuffer.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 = (0, import_Utils.wrapTryCatch)(step, this.onUncaughtException.bind(this), import_RoomExceptions.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();
+  }
+  /**
+   * 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) {
+    this.#rewind = import_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;
+  }
   /**
    * @deprecated Use `.patchRate=` instead.
    */
@@ -428,19 +643,7 @@ var Room = class _Room {
     this._serializer = serializer;
   }
   async setMetadata(meta, persist = true) {
-    if (!this._listing.metadata) {
-      this._listing.metadata = meta;
-    } else {
-      for (const field in meta) {
-        if (!meta.hasOwnProperty(field)) {
-          continue;
-        }
-        this._listing.metadata[field] = meta[field];
-      }
-      if ("markModified" in this._listing) {
-        this._listing.markModified("metadata");
-      }
-    }
+    this._listing.metadata = meta;
     if (persist && this._internalState === RoomInternalState.CREATED) {
       await matchMaker.driver.persist(this._listing);
       this._events.emit("metadata-change");
@@ -481,7 +684,8 @@ var Room = class _Room {
    *
    * @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 }
    * });
@@ -595,22 +799,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);
   }
   /**
@@ -626,33 +820,118 @@ 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 ? (0, import_Utils.wrapTryCatch)(callback, this.onUncaughtException.bind(this), import_RoomExceptions.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)
+  // through `remoteRoomCall(roomId, methodName)`. Marked `@internal` because
+  // they're framework-tooling primitives, not part of the game-code surface.
+  // ---------------------------------------------------------------------------
+  /**
+   * 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() {
+    const elapsed = this.clock.elapsedTime;
+    return {
+      roomId: this.roomId,
+      name: this.roomName,
+      clients: this.clients.length,
+      maxClients: this.maxClients,
+      locked: this.#_locked,
+      elapsedTime: elapsed,
+      metadata: this.metadata ?? null,
+      // Cast through `unknown`: `ExtractRoomClient<T>` vs `Client & ClientPrivate`
+      // don't structurally overlap (the user's `client` generic may carry a
+      // narrower userData/auth shape), but the runtime objects we walk here
+      // always have the private join-time field. The narrow per-property
+      // `(c as any)` reads below keep the cast scoped.
+      //
+      // userId / userEmail read straight off `client.auth` — the JWT
+      // payload @colyseus/auth's default onAuth decodes carries both
+      // when the user has them on file. Saves the admin a per-client
+      // database round-trip; falls back to null when the client signed
+      // in anonymously (or with a custom onAuth that returns a shape
+      // without those fields).
+      clientList: this.clients.map((c) => {
+        const auth = c.auth;
+        return {
+          sessionId: c.sessionId,
+          userId: c.userId ?? auth?.id ?? null,
+          userEmail: auth?.email ?? null,
+          elapsedTime: elapsed - (c._joinedAt ?? elapsed)
+        };
+      }),
+      state: this.state ?? null,
+      stateSize: this.#_inspectorStateSize()
+    };
+  }
+  /**
+   * 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, closeCode = import_shared_types.CloseCode.CONSENTED, reason) {
+    for (const client of this.clients) {
+      if (client.sessionId === sessionId) {
+        this.#_forciblyCloseClient(client, closeCode, reason);
+        return;
+      }
+    }
+  }
+  /**
+   * Best-effort byte size of the current full state. Falls back to `0`
+   * when the room has no serializer or the serializer can't produce a
+   * payload (raw rooms, very-early-onCreate, etc.). The serializer
+   * detection mirrors `@colyseus/monitor`'s — we read whichever buffer
+   * is available across schema v2 and v3.
+   */
+  #_inspectorStateSize() {
+    const ser = this._serializer;
+    if (!ser) {
+      return 0;
+    }
+    const hasState = ser.encoder || ser.state;
+    if (!hasState) {
+      return 0;
+    }
+    try {
+      const full = ser.getFullState?.();
+      if (!full) {
+        return 0;
+      }
+      return full.byteLength ?? full.length ?? 0;
+    } catch {
+      return 0;
     }
   }
   /**
@@ -692,6 +971,7 @@ var Room = class _Room {
   async _onJoin(client, authContext, connectionOptions) {
     const sessionId = client.sessionId;
     client.reconnectionToken = (0, import_Utils.generateId)();
+    this._inputController?.allocate(client);
     if (this._reservedSeatTimeouts[sessionId]) {
       clearTimeout(this._reservedSeatTimeouts[sessionId]);
       delete this._reservedSeatTimeouts[sessionId];
@@ -700,7 +980,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) {
       (0, import_Debug.debugMatchMaking)("attempting to reconnect client with a stale previous connection - sessionId: '%s', roomId: '%s'", client.sessionId, this.roomId);
       this._reconnectionAttempts[connectionOptions.reconnectionToken] = new import_Utils.Deferred();
       const reconnectionAttemptTimeout = setTimeout(() => {
@@ -721,13 +1001,14 @@ var Room = class _Room {
     }
     this._reservedSeats[sessionId][2] = true;
     (0, import_Debug.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 = import_Transport.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) {
@@ -767,6 +1048,7 @@ var Room = class _Room {
           throw new import_ServerError.ServerError(import_shared_types.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
@@ -794,6 +1076,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));
+      const extraSections = this._inputController?.handshakeSections();
       client.raw(import_Protocol.getMessageBytes[import_shared_types.Protocol.JOIN_ROOM](
         client.reconnectionToken,
         this._serializer.id,
@@ -801,7 +1084,8 @@ var Room = class _Room {
          * if skipHandshake is true, we don't need to send the handshake
          * (in case client already has handshake data)
          */
-        connectionOptions?.skipHandshake ? void 0 : this._serializer.handshake && this._serializer.handshake()
+        connectionOptions?.skipHandshake ? void 0 : this._serializer.handshake && this._serializer.handshake(),
+        extraSections
       ));
     }
   }
@@ -868,7 +1152,7 @@ var Room = class _Room {
     }).finally(() => {
       cleanup();
     });
-    if (this._reconnectionAttempts[reconnectionToken]) {
+    if (this._reconnectionAttempts[reconnectionToken] !== void 0) {
       (0, import_Debug.debugMatchMaking)("resolving reconnection attempt for client - sessionId: '%s', roomId: '%s'", sessionId, this.roomId);
       this._reconnectionAttempts[reconnectionToken].resolve(true);
     }
@@ -888,30 +1172,64 @@ var Room = class _Room {
     (0, import_Debug.debugMessage)("broadcast: %O (roomId: %s)", message, this.roomId);
     const encodedMessage = message instanceof Uint8Array ? import_Protocol.getMessageBytes.raw(import_shared_types.Protocol.ROOM_DATA_BYTES, type, void 0, message) : import_Protocol.getMessageBytes.raw(import_shared_types.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);
+      }
+    }
+  }
+  /** 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()) {
@@ -945,6 +1263,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();
         }
@@ -986,11 +1305,12 @@ 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());
   }
   _onMessage(client, buffer) {
@@ -1009,49 +1329,18 @@ var Room = class _Room {
       return this.#_forciblyCloseClient(client, import_shared_types.CloseCode.WITH_ERROR);
     }
     const it = { offset: 1 };
-    const code = buffer[0];
+    const code = buffer[0] & import_shared_types.PROTOCOL_CODE_MASK;
+    const modifiers = buffer[0] & import_shared_types.PROTOCOL_MODIFIER_MASK;
     if (code === import_shared_types.Protocol.ROOM_DATA) {
-      const messageType = import_schema.decode.stringCheck(buffer, it) ? import_schema.decode.string(buffer, it) : import_schema.decode.number(buffer, it);
-      let message;
-      try {
-        message = buffer.byteLength > it.offset ? (0, import_msgpackr.unpack)(buffer.subarray(it.offset, buffer.byteLength)) : void 0;
-        (0, import_Debug.debugMessage)("received: '%s' -> %j (roomId: %s)", messageType, message, this.roomId);
-        if (this.onMessageValidators[messageType] !== void 0) {
-          message = (0, import_StandardSchema.standardValidate)(this.onMessageValidators[messageType], message);
-        }
-      } catch (e) {
-        (0, import_Debug.debugAndPrintError)(e);
-        client.leave(import_shared_types.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 === import_shared_types.Protocol.ROOM_REQUEST) {
+      this.#_messages.onRequest(client, buffer, it);
     } else if (code === import_shared_types.Protocol.ROOM_DATA_BYTES) {
-      const messageType = import_schema.decode.stringCheck(buffer, it) ? import_schema.decode.string(buffer, it) : import_schema.decode.number(buffer, it);
-      let message = buffer.subarray(it.offset, buffer.byteLength);
-      (0, import_Debug.debugMessage)("received: '%s' -> %j (roomId: %s)", messageType, message, this.roomId);
-      const bytesMessageType = `_$b${messageType}`;
-      try {
-        if (this.onMessageValidators[bytesMessageType] !== void 0) {
-          message = (0, import_StandardSchema.standardValidate)(this.onMessageValidators[bytesMessageType], message);
-        }
-      } catch (e) {
-        (0, import_Debug.debugAndPrintError)(e);
-        client.leave(import_shared_types.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 === import_shared_types.Protocol.ROOM_INPUT_RELIABLE) {
+      this._inputController?.decodeReliable(client, buffer, it, modifiers);
+    } else if (code === import_shared_types.Protocol.ROOM_INPUT_UNRELIABLE) {
+      this._inputController?.decodeUnreliable(client, buffer, modifiers);
     } else if (code === import_shared_types.Protocol.JOIN_ROOM && client.state === import_Transport.ClientState.JOINING) {
       client.state = import_Transport.ClientState.JOINED;
       client._joinedAt = this.clock.elapsedTime;
@@ -1068,10 +1357,10 @@ var Room = class _Room {
       this.#_forciblyCloseClient(client, import_shared_types.CloseCode.CONSENTED);
     }
   }
-  #_forciblyCloseClient(client, closeCode) {
+  #_forciblyCloseClient(client, closeCode, reason) {
     client.ref.removeAllListeners("message");
     client.ref.removeListener("close", client.ref["onleave"]);
-    this._onLeave(client, closeCode).then(() => client.leave(closeCode));
+    this._onLeave(client, closeCode).then(() => client.leave(closeCode, reason));
   }
   async _onLeave(client, code) {
     const method = code === import_shared_types.CloseCode.CONSENTED || client.state === import_Transport.ClientState.RECONNECTING ? this.onLeave : this.onDrop || this.onLeave;
@@ -1079,6 +1368,7 @@ var Room = class _Room {
     if (!this.clients.delete(client)) {
       return;
     }
+    this._inputController?.freeze(client);
     if (method) {
       (0, import_Debug.debugMatchMaking)(`${method.name}, sessionId: '%s' (close code: %d, roomId: %s)`, client.sessionId, code, this.roomId);
       try {
@@ -1105,6 +1395,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);
     }
   }
@@ -1168,28 +1459,13 @@ 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 _;
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_SEAT_RESERVATION_TIME,
   Room,
   RoomInternalState,
-  room,
+  RoomPlugin,
+  attachToTestRoom,
+  definePlugins,
   validate
 });