@colyseus/core 0.18.24 → 0.18.26

package/src/RoomMessages.ts

@@ -7,8 +7,9 @@ import { createNanoEvents } from './utils/nanoevents.ts';
 import { standardValidate, type StandardSchemaV1 } from './utils/StandardSchema.ts';
 import { isDevMode } from './utils/DevMode.ts';
 import { debugMessage, debugAndPrintError } from './Debug.ts';
+import { logger } from './Logger.ts';
 import { OnMessageException } from './errors/RoomExceptions.ts';
-import type { Client, ClientPrivate } from './Transport.ts';
+import { ClientState, type Client, type ClientPrivate } from './Transport.ts';
 import type { Room } from './Room.ts';
 
 /** Normalize a thrown value into the `{ name, message, code? }` shape echoed in a
@@ -74,7 +75,7 @@ const SEND_CONTEXT: MessageContext = Object.freeze({
  * ROOM_DATA_BYTES). Room's `_onMessage` keeps the protocol/lifecycle frames
  * (JOIN/PING/LEAVE/input) and calls one of these per frame, preserving the
  * original dispatch order. Reads back into its Room only for `onUncaughtException`
- * (handler wrapping) and `roomId`/`roomName` (logging).
+ * (handler wrapping), `onUnhandledMessage` and `roomId`/`roomName` (logging).
  *
  * @internal
  */
@@ -263,6 +264,10 @@ export class RoomMessages {
     const handler = this.events.events[messageType as string]?.[0];
 
     if (handler === undefined) {
+      // no warning without the hook: the client already gets an explicit error
+      if (this.room.onUnhandledMessage !== undefined) {
+        this.#reportUnhandled(client, messageType, message);
+      }
       this.#replyToRequest(client, requestId, ResponseStatus.ERROR, {
         name: "no_handler",
         message: `room "${this.room.roomName}" has no onMessage("${messageType}") handler to answer this request.`,
@@ -351,13 +356,45 @@ export class RoomMessages {
   }
 
   /** No handler for the type: error the client in dev, drop it in production. */
-  #noHandler(client: Client, messageType: string | number, _message: unknown): void {
+  #noHandler(client: Client, messageType: string | number, message: unknown): void {
     const errorMessage = `room onMessage for "${messageType}" not registered.`;
-    debugMessage(`${errorMessage} (roomId: ${this.room.roomId})`);
+
+    if (this.room.onUnhandledMessage !== undefined) {
+      this.#reportUnhandled(client, messageType, message);
+
+    } else {
+      logger.warn(`room "${this.room.roomName}" (roomId: ${this.room.roomId}): client '${client.sessionId}' sent "${messageType}", which has no onMessage() handler. ${(isDevMode)
+        ? "Replied with an INVALID_PAYLOAD error (outside devMode, the client is disconnected)."
+        : "Disconnecting the client."}`);
+    }
+
     if (isDevMode) {
       client.error(ErrorCode.INVALID_PAYLOAD, errorMessage);
     } else {
+      // frames already received still arrive after leave(); Room#_onMessage skips them
+      client.state = ClientState.LEAVING;
       client.leave(CloseCode.WITH_ERROR, errorMessage);
     }
   }
+
+  /** Call `room.onUnhandledMessage`. A throw or rejection goes to
+   *  `onUncaughtException` when set, or is logged; it never stops the default. */
+  #reportUnhandled(client: Client, messageType: string | number, message: unknown): void {
+    const report = (e: any) => {
+      if (this.room.onUncaughtException !== undefined) {
+        this.room.onUncaughtException(new OnMessageException<Room<any>, any>(e, e?.message, client, message, messageType), 'onMessage');
+      } else {
+        debugAndPrintError(e);
+      }
+    };
+
+    try {
+      const result = this.room.onUnhandledMessage!(client, messageType, message) as any;
+      if (typeof result?.catch === 'function') {
+        result.catch(report);
+      }
+    } catch (e: any) {
+      report(e);
+    }
+  }
 }

package/src/index.ts

@@ -20,7 +20,7 @@ export {
 // Core classes
 export { Server, defineRoom, defineServer, registerRoomDefinitions, unregisterRoomDefinitions, applySimulatedLatency, parseLatencyEnv, type RoomDefinitions, type ServerOptions, type SDKTypes } from './Server.ts';
 export { Room, RoomInternalState, validate, type RoomOptions, type DefineInputOptions, type SimulationCallback, type FixedTimestepCallback, type StepContext, type MessageHandlerWithFormat, type Messages, type ExtractRoomState, type ExtractRoomMetadata, type ExtractRoomClient } from './Room.ts';
-export { InputBufferImpl, compileSanitizer } from './input/InputBuffer.ts';
+export { InputBufferImpl, compileSanitizer, compileSnapshot } from './input/InputBuffer.ts';
 export { type InputAccessor, type InputAPI, type NormalizedInputOptions, type ConsumeOptions, type IdleInput, type IdleContext, type SanitizeInput, type NumericFieldsOf } from './input/types.ts';
 export { Rewind, RewindView, type RewindOptions, type RewindMode } from './Rewind.ts';
 export {

package/src/input/InputBuffer.ts

@@ -1,3 +1,5 @@
+import { $values } from '@colyseus/schema';
+
 import type { ClientPrivate } from '../Transport.ts';
 import { $METADATA } from '../utils/Utils.ts';
 
@@ -43,7 +45,9 @@ export function compileSanitizer<I>(spec: SanitizeInput<I>): (input: I) => void
       // never assigned; the range floor turned "no input" into "held stick").
       if (v === undefined) { continue; }
       // NaN-safe: NaN fails both comparisons → clamp floor.
-      inst[names[i]] = v >= mins[i] ? (v <= maxs[i] ? v : maxs[i]) : mins[i];
+      const clamped = v >= mins[i] ? (v <= maxs[i] ? v : maxs[i]) : mins[i];
+      // Honest frames clamp nothing: a keyed write through the setter costs more than the walk.
+      if (clamped !== v) { inst[names[i]] = clamped; }
     }
   };
 }
@@ -63,6 +67,59 @@ function fieldNamesOf(ctor: new () => any): string[] {
   return names;
 }
 
+/** One per input schema, so every room's frames share a hidden class. */
+const _snapshots = new WeakMap<new () => any, (input: any) => any>();
+
+/**
+ * @internal Compile how a decoded input is copied into the buffer. `clone()`
+ * builds a Schema and its ChangeTree per input, for a frame that's never
+ * encoded, so a schema of plain values gets a lighter frame: its own array of
+ * values behind the ctor's prototype. Methods, getters, `instanceof`, `clone()`
+ * and `toJSON()` all hold, and a field write lands on the copy, untracked. A
+ * nested schema or collection keeps `clone()`, whose copy is deep.
+ *
+ * Fields are read by name, as `clone()` reads them, never by copying `$values`:
+ * native class fields (`useDefineForClassFields`) shadow the schema's accessors,
+ * so the decoder's values sit on the instance and `$values` stays empty.
+ */
+export function compileSnapshot<I>(ctor: new () => I): (input: I) => I {
+  let snapshot = _snapshots.get(ctor);
+  if (snapshot !== undefined) { return snapshot; }
+
+  const md = (ctor as any)[$METADATA] as Record<number, { type?: unknown }> | undefined;
+  const names = fieldNamesOf(ctor);
+  const plain = md !== undefined && names.every((_, i) => {
+    const type = md[i].type;
+    return typeof type === "string" || (type !== null && typeof type === "object" && "quantized" in type);
+  });
+
+  if (plain) {
+    const fields: PropertyDescriptorMap = {};
+    names.forEach((name, i) => {
+      fields[name] = {
+        get(this: any) { return this[$values][i]; },
+        set(this: any, value: unknown) { this[$values][i] = value; },
+        enumerable: true,
+        configurable: true,
+      };
+    });
+    // A function, not a class: `constructor` must stay the schema's (clone/toJSON read its metadata).
+    function Frame(this: any, values: unknown[]) { this[$values] = values; }
+    Frame.prototype = Object.create(ctor.prototype, fields);
+    const count = names.length;
+    snapshot = (input) => {
+      const values = new Array(count);
+      for (let i = 0; i < count; i++) { values[i] = input[names[i]]; }
+      return new (Frame as any)(values);
+    };
+  } else {
+    snapshot = (input) => input.clone();
+  }
+
+  _snapshots.set(ctor, snapshot!);
+  return snapshot!;
+}
+
 /**
  * @internal Seed every declared field that has no construction default with
  * its wire-neutral zero value (0 / false / ""; quantized: 0 clamped into the

package/src/input/RoomInput.ts

@@ -4,7 +4,7 @@ import { HandshakeSection, InputFlags, ProtocolModifier } from '@colyseus/shared
 
 import {
   InputAccessorImpl, InputBufferImpl, NO_OP_INPUT_ACCESSOR,
-  compileSanitizer, seedInputZeroValues, validateSubSteps,
+  compileSanitizer, compileSnapshot, seedInputZeroValues, validateSubSteps,
 } from './InputBuffer.ts';
 import type {
   InputAccessor, InputAPI, NormalizedInputOptions,
@@ -148,6 +148,7 @@ export class RoomInput {
       idle: opts?.idle,
       // Compiled once (map → dense min/max walk); applied per decoded frame.
       sanitize: opts?.sanitize !== undefined ? compileSanitizer(opts.sanitize) : undefined,
+      snapshot: compileSnapshot(type),
       tickRate,
       subSteps: validateSubSteps(opts?.subSteps, 'defineInput'),
     };
@@ -220,15 +221,15 @@ export class RoomInput {
 
   /**
    * Sanitize the freshly-decoded `client._input`, then (when buffering is on)
-   * push a clone into the per-client buffer. Honors the framework seq
+   * push a snapshot into the per-client buffer. Honors the framework seq
    * (unreliable) / a user `inputOptions.seqField` (reliable) to dedupe the
    * redundancy ring.
    */
   capture(client: ClientPrivate, renderTime: number = 0, reckonTime: number = 0, seq?: number): void {
-    // Sanitize before anything reads it (latest, the clone below, the idle ctx).
+    // Sanitize before anything reads it (latest, the snapshot below, the idle ctx).
     this.options.sanitize?.(client._input);
     const buf = client._inputBuffer;
-    if (!buf) { return; } // no consumer registered — skip the clone allocation
+    if (!buf) { return; } // no consumer registered — skip the snapshot allocation
     const inst = client._input!;
     if (seq !== undefined) {
       // Unreliable: dedup the ring by the framework wire seq (user seqField is for .at() only).
@@ -241,7 +242,7 @@ export class RoomInput {
         if (typeof value === 'number' && !buf.accept(value)) { return; }
       }
     }
-    buf.push(inst.clone() as any, renderTime, reckonTime, seq);
+    buf.push(this.options.snapshot(inst), renderTime, reckonTime, seq);
   }
 
   /** Decode a `ROOM_INPUT_RELIABLE` frame: an optional TIMED stamp prefix (shape

package/src/input/types.ts

@@ -193,7 +193,7 @@ export interface NormalizedInputOptions {
   seqField?: string;
 
   /**
-   * > 0 enables per-client buffering of cloned snapshots — required for
+   * > 0 enables per-client buffering of input snapshots — required for
    * `room.inputs.get(sessionId).drain() / .peek() / .at()` to return populated
    * data. Oldest drops on overflow. Set to `0` to disable (`.latest` still
    * works).
@@ -229,6 +229,12 @@ export interface NormalizedInputOptions {
    * `latest` / the buffer / the idle ctx.
    */
   sanitize?: (instance: any) => void;
+
+  /**
+   * COMPILED copy of a decoded frame for the buffer (see `compileSnapshot`).
+   * Reads and writes like the schema, without its change tracking.
+   */
+  snapshot: (instance: any) => any;
 }
 
 /**