@colyseus/core 0.17.43 → 0.18.0

package/src/Room.ts

@@ -1,5 +1,15 @@
-import { unpack } from '@colyseus/msgpackr';
-import { decode, type Iterator, $changes } from '@colyseus/schema';
+import { unpack } from 'msgpackr';
+import { decode, Encoder, Reflection, type Iterator, $changes } from '@colyseus/schema';
+import { InputDecoder } from '@colyseus/schema/input';
+import { type InputAccessor, type InputAPI, type InputOptions, type NumericFieldsOf, InputAccessorImpl, InputBufferImpl, NO_OP_INPUT_ACCESSOR } from './input/InputBuffer.ts';
+export { type InputAccessor, type InputAPI, type InputOptions, type NumericFieldsOf } from './input/InputBuffer.ts';
+
+/**
+ * Module-level cache of `Reflection.encode` output keyed by input
+ * constructor — pays the encoding cost once per Room class regardless of
+ * room instance count. WeakMap so unused classes can be GC'd.
+ */
+const _inputReflectionCache = new WeakMap<Function, Uint8Array>();
 import { ClockTimer as Clock } from '@colyseus/timer';
 
 import { EventEmitter } from 'events';
@@ -28,16 +38,43 @@ import * as matchMaker from './MatchMaker.ts';
 import {
   CloseCode,
   ErrorCode,
+  HandshakeSection,
   Protocol,
+  ResponseStatus,
   type MessageHandlerWithFormat as SharedMessageHandlerWithFormat,
   type MessageHandler as SharedMessageHandler,
   type Messages as SharedMessages,
 } from '@colyseus/shared-types';
 
+import {
+  RoomPlugin,
+  setupRoomPlugins,
+  type PluginLayout,
+} from './RoomPlugin.ts';
+export {
+  RoomPlugin,
+  definePlugins,
+  attachToTestRoom,
+  type RoomPluginOrder,
+} from './RoomPlugin.ts';
+
 const DEFAULT_PATCH_RATE = 1000 / 20; // 20fps (50ms)
 const DEFAULT_SIMULATION_INTERVAL = 1000 / 60; // 60fps (16.66ms)
 const noneSerializer = new NoneSerializer();
 
+// Shape an Error (or thrown value) into a plain, msgpack-friendly object for a
+// ROOM_RESPONSE error payload. Only `name`/`message`/`code` cross the wire —
+// stacks stay on the server.
+function toResponseError(e: any): { name: string; message: string; code?: any } {
+  if (e instanceof Error) {
+    const code = (e as any).code;
+    return (code !== undefined)
+      ? { name: e.name, message: e.message, code }
+      : { name: e.name, message: e.message };
+  }
+  return { name: "Error", message: String(e) };
+}
+
 export const DEFAULT_SEAT_RESERVATION_TIME = Number(process.env.COLYSEUS_SEAT_RESERVATION_TIME || 15);
 
 export type SimulationCallback = (deltaTime: number) => void;
@@ -46,12 +83,23 @@ export interface RoomOptions {
   state?: object;
   metadata?: any;
   client?: Client;
+  /**
+   * Schema class for client→server input packets. When set, the Room
+   * allocates one instance per joining client and binds an InputDecoder.
+   * Must be a flat Schema (primitive fields only — see InputEncoder docs).
+   *
+   * Typed loosely (no `Schema` constraint) to avoid type-identity clashes
+   * when the user's app loads a different copy of `@colyseus/schema` than
+   * `@colyseus/core` does. Runtime validation happens via the encoder.
+   */
+  input?: any;
 }
 
 // Helper types to extract individual properties from RoomOptions
 export type ExtractRoomState<T> = T extends { state?: infer S extends object } ? S : any;
 export type ExtractRoomMetadata<T> = T extends { metadata?: infer M } ? M : any;
 export type ExtractRoomClient<T> = T extends { client?: infer C extends Client } ? C : Client;
+export type ExtractRoomInput<T> = T extends { input?: infer I } ? I : never;
 
 export interface IBroadcastOptions extends ISendOptions {
   except?: Client | Client[];
@@ -254,6 +302,47 @@ export class Room<T extends RoomOptions = RoomOptions> {
 
   public messages?: Messages<any>;
 
+  /**
+   * Room plugins, keyed by an operator-chosen handle. Each plugin
+   * contributes any subset of: declarative message handlers (merged
+   * into `this.messages`), lifecycle hooks (composed with the room's
+   * own), and public methods callable via `this.plugins.<key>.X()`.
+   *
+   * The framework walks this record once per Room subclass to compute
+   * the lifecycle/message layout and install hook wrappers on the
+   * class prototype; subsequent constructs reuse the cached layout
+   * and just inject `.room` + merge messages.
+   *
+   * Use `definePlugins({...})` so TypeScript preserves each plugin's
+   * literal instance type. Frozen after `__init`.
+   */
+  public plugins?: any;
+
+  /**
+   * Auto-included plugin instances pulled in via `static
+   * dependencies` declarations on user-registered plugins. Kept
+   * separate from `this.plugins` so the user's typed view doesn't
+   * gain framework-managed keys. Sentinel-keyed (`__dep:<ClassName>`)
+   * so the hook wrappers can route lookups to the right map.
+   *
+   * @internal
+   */
+  public _autoPlugins?: Record<string, RoomPlugin<any>>;
+
+  /**
+   * Layout cache populated on the FIRST construction of each Room
+   * subclass. Holds the precomputed hook participation order + message
+   * key → plugin key mapping. Stored on the constructor (a static field)
+   * so all instances of the same class share it.
+   *
+   * `null` is a sentinel meaning "no plugins on this class" — distinct
+   * from `undefined` ("not yet computed") so we don't re-walk an empty
+   * plugin record on every construct.
+   *
+   * @internal
+   */
+  static __pluginLayout?: PluginLayout | null;
+
   private onMessageEvents = createNanoEvents();
   private onMessageValidators: {[message: string]: StandardSchemaV1} = {};
 
@@ -379,6 +468,15 @@ export class Room<T extends RoomOptions = RoomOptions> {
       this.state = this.#_state;
     }
 
+    // Wire room plugins from the instance-level `this.plugins` record.
+    // The heavy lifting (conflict detection, hook participation, hook
+    // wrapping on the prototype) runs once per class — see
+    // `setupRoomPlugins` in `./RoomPlugin.ts`. Per-instance: set
+    // `plugin.room = this`, instantiate auto-deps, merge messages.
+    if (this.plugins !== undefined) {
+      setupRoomPlugins(this);
+    }
+
     // Bind messages to the room
     if (this.messages !== undefined) {
 
@@ -405,6 +503,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
     this.clock.start();
   }
 
+
   /**
    * The name of the room you provided as first argument for `gameServer.define()`.
    *
@@ -489,6 +588,86 @@ export class Room<T extends RoomOptions = RoomOptions> {
    */
   public 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.
+   *
+   * @example
+   * ```typescript
+   * class FpsRoom extends Room<{ input: MoveInput }> {
+   *   input = 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);
+   *   }
+   * }
+   * ```
+   */
+  public input?: InputAPI<ExtractRoomInput<T>>;
+
+  /**
+   * Input configuration. Set via {@link defineInput} only.
+   * @internal
+   */
+  private inputOptions?: InputOptions;
+
+  /**
+   * 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.
+   *
+   * ```typescript
+   * class FpsRoom extends Room<{ input: MoveInput }> {
+   *   input = 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);
+   * }
+   * ```
+   *
+   * **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.
+   * - `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).
+   */
+  protected defineInput<C extends new () => any>(
+    type: C,
+    opts?: {
+      seqField?: NumericFieldsOf<InstanceType<C>>;
+      bufferMaxSize?: number;
+    },
+  ): InputAPI<InstanceType<C>> {
+    this.inputOptions = {
+      ctor: type,
+      seqField: opts?.seqField ?? "seq",
+      bufferMaxSize: opts?.bufferMaxSize ?? 32,
+    };
+    if (!_inputReflectionCache.has(type)) {
+      // Reflection.encode walks the schema's TypeContext via a one-shot
+      // Encoder around a throwaway instance; the bytes are SDK-deserializable
+      // back into a constructor through Reflection.decode.
+      _inputReflectionCache.set(type, Reflection.encode(new Encoder(new type())));
+    }
+    return ((sessionId: string): InputAccessor<InstanceType<C>> => {
+      const c = this.clients.getById(sessionId) as unknown as ClientPrivate | undefined;
+      return (c?._inputAccessor as InputAccessor<InstanceType<C>>) ?? NO_OP_INPUT_ACCESSOR;
+    });
+  }
+
   /**
    * This method is called when the room is disposed.
    */
@@ -653,6 +832,51 @@ export class Room<T extends RoomOptions = RoomOptions> {
     }
   }
 
+  /**
+   * 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}.
+   *
+   * @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);
+   *   }
+   * }
+   * ```
+   */
+  public setTickedSimulation(
+    onTickCallback: (tick: number, deltaTime: number) => void,
+    delay: number = DEFAULT_SIMULATION_INTERVAL,
+    startTick: number = 0,
+  ): void {
+    this.#_tick = startTick;
+    this.setSimulationInterval((dt) => {
+      onTickCallback(this.#_tick, dt);
+      this.#_tick++;
+    }, delay);
+  }
+
+  /**
+   * Current server tick. Incremented by {@link setTickedSimulation} after each
+   * tick callback returns. Returns 0 when no ticked simulation is running.
+   */
+  public get tick(): number { return this.#_tick; }
+  #_tick: number = 0;
+
   /**
    * @deprecated Use `.patchRate=` instead.
    */
@@ -671,21 +895,8 @@ export class Room<T extends RoomOptions = RoomOptions> {
     this._serializer = serializer;
   }
 
-  public async setMetadata(meta: Partial<ExtractRoomMetadata<T>>, persist: boolean = true) {
-    if (!this._listing.metadata) {
-      this._listing.metadata = meta as ExtractRoomMetadata<T>;
-
-    } else {
-      for (const field in meta) {
-        if (!meta.hasOwnProperty(field)) { continue; }
-        this._listing.metadata[field] = meta[field];
-      }
-
-      // `MongooseDriver` workaround: persit metadata mutations
-      if ('markModified' in this._listing) {
-        (this._listing as any).markModified('metadata');
-      }
-    }
+  public async setMetadata(meta: ExtractRoomMetadata<T>, persist: boolean = true) {
+    this._listing.metadata = meta;
 
     if (persist && this._internalState === RoomInternalState.CREATED) {
       await matchMaker.driver.persist(this._listing);
@@ -735,7 +946,8 @@ export class Room<T extends RoomOptions = RoomOptions> {
    *
    * @example
    * ```typescript
-   * // Partial metadata update (merges with existing)
+   * // Merging with existing metadata: spread `this.metadata` yourself.
+   * // `metadata` is always REPLACED (not merged) by setMatchmaking()/setMetadata().
    * await this.setMatchmaking({
    *   metadata: { ...this.metadata, round: this.metadata.round + 1 }
    * });
@@ -1042,6 +1254,117 @@ export class Room<T extends RoomOptions = RoomOptions> {
     }
   }
 
+  // ---------------------------------------------------------------------------
+  // 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.
+   */
+  public getInspectorView(): {
+    roomId: string;
+    name: string;
+    clients: number;
+    maxClients: number;
+    locked: boolean;
+    elapsedTime: number;
+    metadata: any;
+    clientList: Array<{
+      sessionId: string;
+      userId: string | null;
+      userEmail: string | null;
+      elapsedTime: number;
+    }>;
+    state: any;
+    stateSize: number;
+  } {
+    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 as unknown as ReadonlyArray<Client & ClientPrivate>).map((c) => {
+        const auth = (c as any).auth;
+        return {
+          sessionId: c.sessionId,
+          userId: ((c as any).userId ?? auth?.id) ?? null,
+          userEmail: auth?.email ?? null,
+          elapsedTime: elapsed - ((c as any)._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.
+   */
+  public kickClient(sessionId: string, closeCode: number = CloseCode.CONSENTED, reason?: string): void {
+    // Same `unknown` indirection as in `getInspectorView` above —
+    // ExtractRoomClient<T> doesn't structurally include ClientPrivate.
+    for (const client of this.clients as unknown as ReadonlyArray<Client & ClientPrivate>) {
+      if (client.sessionId === sessionId) {
+        this.#_forciblyCloseClient(client as ExtractRoomClient<T> & ClientPrivate, 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(): number {
+    const ser = this._serializer as any;
+    if (!ser) { return 0; }
+    const hasState = ser.encoder || ser.state;
+    if (!hasState) { return 0; }
+    try {
+      const full = ser.getFullState?.();
+      if (!full) { return 0; }
+      // Buffer / Uint8Array have `byteLength`; raw arrays have `length`.
+      return (full as any).byteLength ?? (full as any).length ?? 0;
+    } catch {
+      return 0;
+    }
+  }
+
   /**
    * Disconnect all connected clients, and then dispose the room.
    *
@@ -1103,6 +1426,19 @@ export class Room<T extends RoomOptions = RoomOptions> {
     // (each new reconnection receives a new reconnection token)
     client.reconnectionToken = generateId();
 
+    // Allocate per-client input instance + decoder if the Room called `defineInput()`.
+    // Done early so onJoin can reference room.input(sessionId).latest.
+    if (this.inputOptions !== undefined) {
+      client._input = new this.inputOptions.ctor();
+      client._inputDecoder = new InputDecoder(client._input);
+      // Buffer is opt-in via bufferMaxSize > 0 (rollback / lockstep).
+      const maxSize = this.inputOptions.bufferMaxSize;
+      if (maxSize > 0) {
+        client._inputBuffer = new InputBufferImpl(maxSize, this.inputOptions.seqField);
+      }
+      client._inputAccessor = new InputAccessorImpl(client);
+    }
+
     if (this._reservedSeatTimeouts[sessionId]) {
       clearTimeout(this._reservedSeatTimeouts[sessionId]);
       delete this._reservedSeatTimeouts[sessionId];
@@ -1289,6 +1625,17 @@ export class Room<T extends RoomOptions = RoomOptions> {
       // allow client to send messages after onJoin has succeeded.
       client.ref.on('message', this._onMessage.bind(this, client));
 
+      // Append input reflection as a tagged section when the room declared
+      // input. The SDK uses these bytes to materialize a constructor for
+      // `conn.input()` calls that don't pass an explicit `type`.
+      let extraSections: Array<{ tag: number; bytes: Uint8Array }> | undefined;
+      if (!connectionOptions?.skipHandshake && this.inputOptions !== undefined) {
+        const inputBytes = _inputReflectionCache.get(this.inputOptions.ctor);
+        if (inputBytes !== undefined) {
+          extraSections = [{ tag: HandshakeSection.INPUT_REFLECTION, bytes: inputBytes }];
+        }
+      }
+
       // confirm room id that matches the room name requested to join
       client.raw(getMessageBytes[Protocol.JOIN_ROOM](
         client.reconnectionToken,
@@ -1300,6 +1647,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
         (connectionOptions?.skipHandshake)
           ? undefined
           : this._serializer.handshake && this._serializer.handshake(),
+        extraSections,
       ));
     }
   }
@@ -1404,7 +1752,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
     // switching Wi-Fi), as the original connection may still be open while a
     // new reconnection attempt is being made.
     //
-    if (this._reconnectionAttempts[reconnectionToken]) {
+    if (this._reconnectionAttempts[reconnectionToken] !== undefined) {
       debugMatchMaking('resolving reconnection attempt for client - sessionId: \'%s\', roomId: \'%s\'', sessionId, this.roomId);
       this._reconnectionAttempts[reconnectionToken].resolve(true);
     }
@@ -1448,6 +1796,13 @@ export class Room<T extends RoomOptions = RoomOptions> {
     }
   }
 
+  // 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: Client, requestId: number, status: ResponseStatus, payload?: any) {
+    debugMessage("response #%d: status=%d -> %j (roomId: %s)", requestId, status, payload, this.roomId);
+    client.enqueueRaw(getMessageBytes[Protocol.ROOM_RESPONSE](requestId, status, payload));
+  }
+
   private sendFullState(client: Client): void {
     client.raw(this._serializer.getFullState(client));
   }
@@ -1595,6 +1950,23 @@ export class Room<T extends RoomOptions = RoomOptions> {
     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: ClientPrivate) {
+    const buf = client._inputBuffer;
+    if (!buf) { return; } // no consumer registered — skip the clone allocation
+    const inst = client._input!;
+    const seqField = this.inputOptions?.seqField;
+    if (seqField !== undefined) {
+      const value = (inst as any)[seqField] as number;
+      if (typeof value === 'number' && !buf.accept(value)) { return; }
+    }
+    buf.push(inst.clone() as any);
+  }
+
   private _onMessage(client: ExtractRoomClient<T> & ClientPrivate, buffer: Buffer) {
     // skip if client is on LEAVING state.
     if (client.state === ClientState.LEAVING) { return; }
@@ -1650,6 +2022,67 @@ export class Room<T extends RoomOptions = RoomOptions> {
         this.onMessageFallbacks['__no_message_handler'](client, messageType, message);
       }
 
+    } else if (code === Protocol.ROOM_REQUEST) {
+      // A request reuses the same `onMessage(type, ...)` handlers as a plain
+      // ROOM_DATA message — the only difference is the client opted in to a
+      // reply (by passing a callback / using `room.request()`), so the wire
+      // carries a `requestId` we must echo back. The handler's return value
+      // (awaited) becomes the response payload.
+      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))
+          : undefined;
+        debugMessage("request #%d: '%s' -> %j (roomId: %s)", requestId, messageType, message, this.roomId);
+
+        // custom message validation (shared with the ROOM_DATA path)
+        if (this.onMessageValidators[messageType] !== undefined) {
+          message = standardValidate(this.onMessageValidators[messageType], message);
+        }
+
+      } catch (e: any) {
+        // Reply with an error so the client's pending request settles instead
+        // of timing out. (A plain ROOM_DATA would drop the client here, but a
+        // request has a caller waiting on the other end.)
+        debugAndPrintError(e);
+        this.#replyToRequest(client, requestId, ResponseStatus.ERROR, toResponseError(e));
+        return;
+      }
+
+      // A request is answered by the FIRST handler registered for its type.
+      // `onMessageEvents.emit` would run every handler and discard returns, so
+      // we invoke directly to capture the value. Wildcard ('*') handlers are
+      // not eligible — their (client, type, message) shape has no response
+      // contract — so a type with only a wildcard handler gets `no_handler`.
+      const handler = this.onMessageEvents.events[messageType as string]?.[0];
+
+      if (handler === undefined) {
+        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(...)` normalizes sync throws and async
+      // rejections into the same rejection path. When `onUncaughtException`
+      // is configured the handler is wrapped (see `onMessage`) and swallows
+      // its own errors, so the request resolves with `undefined` and the
+      // exception is reported there instead of as an ERROR response.
+      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));
+        },
+      );
+
     } else if (code === Protocol.ROOM_DATA_BYTES) {
       const messageType = (decode.stringCheck(buffer, it))
         ? decode.string(buffer, it)
@@ -1681,6 +2114,27 @@ export class Room<T extends RoomOptions = RoomOptions> {
         this.onMessageFallbacks['__no_message_handler'](client, messageType, message);
       }
 
+    } else if (code === Protocol.ROOM_INPUT_RELIABLE) {
+      if (client._inputDecoder) {
+        try {
+          client._inputDecoder.decode(buffer.subarray(1));
+        } catch (e: any) {
+          debugAndPrintError(e);
+          return;
+        }
+        this.#captureInput(client);
+      }
+
+    } else if (code === Protocol.ROOM_INPUT_UNRELIABLE) {
+      if (client._inputDecoder) {
+        try {
+          client._inputDecoder.decodeAll(buffer.subarray(1), () => this.#captureInput(client));
+        } catch (e: any) {
+          debugAndPrintError(e);
+          return;
+        }
+      }
+
     } else if (code === Protocol.JOIN_ROOM && client.state === ClientState.JOINING) {
       // join room has been acknowledged by the client
       client.state = ClientState.JOINED;
@@ -1705,7 +2159,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
     }
   }
 
-  #_forciblyCloseClient(client: ExtractRoomClient<T> & ClientPrivate, closeCode: number) {
+  #_forciblyCloseClient(client: ExtractRoomClient<T> & ClientPrivate, closeCode: number, reason?: string) {
     // stop receiving messages from this client
     client.ref.removeAllListeners('message');
 
@@ -1713,7 +2167,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
     client.ref.removeListener('close', client.ref['onleave']);
 
     // only effectively close connection when "onLeave" is fulfilled
-    this._onLeave(client, closeCode).then(() => client.leave(closeCode));
+    this._onLeave(client, closeCode).then(() => (client as any).leave(closeCode, reason));
   }
 
   private async _onLeave(client: ExtractRoomClient<T>, code?: number): Promise<any> {
@@ -1771,7 +2225,6 @@ export class Room<T extends RoomOptions = RoomOptions> {
     if (this._reservedSeats[client.sessionId] === undefined) {
       this._events.emit('leave', client, willDispose);
     }
-
   }
 
   async #_incrementClientCount() {