@colyseus/core 0.18.1 → 0.18.2

package/src/errors/RoomExceptions.ts

@@ -27,11 +27,11 @@ export type RoomException<R extends Room = Room> =
   TimedEventException;
 
 export class OnCreateException<R extends Room = Room> extends Error {
-  options: Parameters<R['onCreate']>[0];
+  options: Parameters<NonNullable<R['onCreate']>>[0];
   constructor(
     cause: Error,
     message: string,
-    options:  Parameters<R['onCreate']>[0],
+    options:  Parameters<NonNullable<R['onCreate']>>[0],
   ) {
     super(message, { cause });
     this.name = 'OnCreateException';
@@ -56,15 +56,15 @@ export class OnAuthException<R extends Room = Room> extends Error {
 }
 
 export class OnJoinException<R extends Room = Room> extends Error {
-  client: Parameters<R['onJoin']>[0];
-  options: Parameters<R['onJoin']>[1];
-  auth: Parameters<R['onJoin']>[2];
+  client: Parameters<NonNullable<R['onJoin']>>[0];
+  options: Parameters<NonNullable<R['onJoin']>>[1];
+  auth: Parameters<NonNullable<R['onJoin']>>[2];
   constructor(
     cause: Error,
     message: string,
-    client: Parameters<R['onJoin']>[0],
-    options: Parameters<R['onJoin']>[1],
-    auth: Parameters<R['onJoin']>[2],
+    client: Parameters<NonNullable<R['onJoin']>>[0],
+    options: Parameters<NonNullable<R['onJoin']>>[1],
+    auth: Parameters<NonNullable<R['onJoin']>>[2],
   ) {
     super(message, { cause });
     this.name = 'OnJoinException';
@@ -75,13 +75,13 @@ export class OnJoinException<R extends Room = Room> extends Error {
 }
 
 export class OnLeaveException<R extends Room = Room> extends Error {
-  client: Parameters<R['onLeave']>[0];
-  consented: Parameters<R['onLeave']>[1];
+  client: Parameters<NonNullable<R['onLeave']>>[0];
+  consented: Parameters<NonNullable<R['onLeave']>>[1];
   constructor(
     cause: Error,
     message: string,
-    client: Parameters<R['onLeave']>[0],
-    consented: Parameters<R['onLeave']>[1],
+    client: Parameters<NonNullable<R['onLeave']>>[0],
+    consented: Parameters<NonNullable<R['onLeave']>>[1],
   ) {
     super(message, { cause });
     this.name = 'OnLeaveException';
@@ -91,13 +91,13 @@ export class OnLeaveException<R extends Room = Room> extends Error {
 }
 
 export class OnDropException<R extends Room = Room> extends Error {
-  client: Parameters<R['onDrop']>[0];
-  code: Parameters<R['onDrop']>[1];
+  client: Parameters<NonNullable<R['onDrop']>>[0];
+  code: Parameters<NonNullable<R['onDrop']>>[1];
   constructor(
     cause: Error,
     message: string,
-    client: Parameters<R['onDrop']>[0],
-    code: Parameters<R['onDrop']>[1],
+    client: Parameters<NonNullable<R['onDrop']>>[0],
+    code: Parameters<NonNullable<R['onDrop']>>[1],
   ) {
     super(message, { cause });
     this.name = 'OnDropException';
@@ -107,11 +107,11 @@ export class OnDropException<R extends Room = Room> extends Error {
 }
 
 export class OnReconnectException<R extends Room = Room> extends Error {
-  client: Parameters<R['onReconnect']>[0];
+  client: Parameters<NonNullable<R['onReconnect']>>[0];
   constructor(
     cause: Error,
     message: string,
-    client: Parameters<R['onReconnect']>[0],
+    client: Parameters<NonNullable<R['onReconnect']>>[0],
   ) {
     super(message, { cause });
     this.name = 'OnReconnectException';

package/src/input/InputBuffer.ts

@@ -38,6 +38,10 @@ export function compileSanitizer<I>(spec: SanitizeInput<I>): (input: I) => void
     const inst = input as Record<string, number>;
     for (let i = 0; i < names.length; i++) {
       const v = inst[names[i]];
+      // Never-received field: no input to sanitize — clamping would INVENT
+      // one (delta-encoding clients legitimately never transmit fields they
+      // 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];
     }
@@ -59,6 +63,33 @@ function fieldNamesOf(ctor: new () => any): string[] {
   return names;
 }
 
+/**
+ * @internal Seed every declared field that has no construction default with
+ * its wire-neutral zero value (0 / false / ""; quantized: 0 clamped into the
+ * descriptor's range). The input contract is "the server holds the last
+ * received value" — before anything is received, that value is the ZERO of
+ * the field's type, never `undefined`: a sim would NaN-propagate it and a
+ * range sanitizer would clamp it into a phantom input. Clients only transmit
+ * fields they assign, so an untouched field stays absent on the wire forever.
+ */
+export function seedInputZeroValues(instance: any, ctor: new () => any): void {
+  const md = (ctor as any)[$METADATA] as
+    Record<number, { name?: string, type?: unknown }> | undefined;
+  if (!md) { return; }
+  for (let i = 0; ; i++) {
+    const f = md[i];
+    if (!f || typeof f.name !== "string") break;
+    if (instance[f.name] !== undefined) { continue; }   // .default() wins
+    const type = f.type;
+    if (typeof type === "string") {
+      instance[f.name] = type === "string" ? "" : type === "boolean" ? false : 0;
+    } else if (type !== null && typeof type === "object" && "quantized" in (type as object)) {
+      const q = (type as { quantized: { min: number, max: number } }).quantized;
+      instance[f.name] = q.min > 0 ? q.min : q.max < 0 ? q.max : 0;
+    }
+  }
+}
+
 /** Reclaim the consumed prefix once the read cursor passes this many items —
  *  bounds the parallel arrays' slack to O(THRESHOLD) between compactions while
  *  keeping per-consume work O(1) (no `shift()` re-index on every input). */
@@ -184,6 +215,7 @@ export class InputBufferImpl<I = any> {
     if (this._idle === undefined) {
       // Lazy mint (cold): the fresh instance doubles as the defaults source.
       this._idle = new this._ctor!();
+      seedInputZeroValues(this._idle, this._ctor!);
       this._fieldNames = fieldNamesOf(this._ctor!);
       const fresh = this._idle as Record<string, unknown>;
       this._defaults = this._fieldNames.map((n) => fresh[n]);

package/src/input/RoomInput.ts

@@ -4,7 +4,7 @@ import { HandshakeSection, InputFlags, ProtocolModifier } from '@colyseus/shared
 
 import {
   InputAccessorImpl, InputBufferImpl, NO_OP_INPUT_ACCESSOR,
-  compileSanitizer, validateSubSteps,
+  compileSanitizer, seedInputZeroValues, validateSubSteps,
 } from './InputBuffer.ts';
 import type {
   InputAccessor, InputAPI, NormalizedInputOptions,
@@ -152,6 +152,11 @@ export class RoomInput {
    *  via `bufferMaxSize > 0`, for rollback/lockstep), and the accessor. */
   allocate(client: Client & ClientPrivate): void {
     client._input = new this.options.ctor();
+    // Wire-neutral zero values for fields with no construction default: a
+    // client only transmits fields it assigns, and `undefined` here would
+    // NaN-propagate into the sim (or get floor-clamped by a range sanitizer
+    // into a PHANTOM held input).
+    seedInputZeroValues(client._input, this.options.ctor);
     client._inputDecoder = new InputDecoder(client._input);
     client._reckonBaseline = 0; // mirrors the SDK's delta-coded stamp baseline (reset together on (re)connect)
     const maxSize = this.options.bufferMaxSize;

package/src/presence/LocalPresence.ts

@@ -8,7 +8,7 @@ import { hasDevModeCache, isDevMode, getDevModeCache, writeDevModeCache } from '
 type Callback = (...args: any[]) => void;
 
 export class LocalPresence implements Presence {
-    public subscriptions = new EventEmitter();
+    public subscriptions: EventEmitter = new EventEmitter();
 
     public data: {[roomName: string]: string[]} = {};
     public hash: {[roomName: string]: {[key: string]: string}} = {};

package/src/router/index.ts

@@ -41,7 +41,7 @@ export function bindRouterToTransport(transport: Transport, router: Router, useE
   // add default "/" route, if not provided.
   const hasRootRoute = (
     // check if express app has a root route
-    (expressApp && expressRootRoute(expressApp) !== undefined) ||
+    (expressApp && hasExpressRootRoute(expressApp)) ||
 
     // check if router has a root route
     Object.values(router.endpoints).some(endpoint => endpoint.path === "/")
@@ -105,20 +105,33 @@ export function bindRouterToTransport(transport: Transport, router: Router, useE
   });
 }
 
-function expressRootRoute(expressApp: express.Application) {
-  //
-  // express v5 uses `app.router`, express v4 uses `app._router`
-  // check for `app._router` first, then `app.router`
-  //
-  // (express v4 will show a warning if `app.router` is used)
-  //
-  const stack = (expressApp as any)?._router?.stack ?? (expressApp as any)?.router?.stack;
-
-  if (!stack) {
-    return false;
+/**
+ * Whether the express app already handles the root route, in which case
+ * Colyseus must not register its own default "/" endpoint over it.
+ */
+function hasExpressRootRoute(expressApp: express.Application) {
+  return expressRouterStack(expressApp).some((layer: any) =>
+    layer.match('/') && !['query', 'expressInit'].includes(layer.name));
+}
+
+/**
+ * The app's router stack, or an empty stack if it has no routes yet.
+ *
+ * express v5 exposes the router as `app.router`; v4 exposes it as `app._router`
+ * and only creates it once the first route/middleware is registered.
+ */
+function expressRouterStack(expressApp: express.Application): any[] {
+  const app = expressApp as any;
+
+  if (app?._router?.stack) {
+    return app._router.stack;
   }
 
-  return stack.find((layer: any) => layer.match('/') && !['query', 'expressInit'].includes(layer.name));
+  try {
+    return app?.router?.stack ?? [];
+  } catch (e) {
+    return []; // express v4 throws on `app.router` — no routes registered
+  }
 }
 
 export function createRouter<

package/src/serializer/SchemaSerializer.ts

@@ -174,10 +174,10 @@ export class SchemaSerializer<T extends Schema> implements Serializer<T> {
         }
       }
 
-      // Heartbeat: clients that advertised CLIENT_TIMING still need
-      // periodic timing samples to keep their clock offset / RTT estimate
-      // fresh during quiet ticks. Emit a TIMED-prefixed ROOM_STATE_PATCH
-      // with an empty schema body — 1 byte protocol + 12 bytes prefix.
+      // Heartbeat: `defineInput()` rooms still need periodic timing samples
+      // to keep client clock offset / RTT estimates fresh during quiet
+      // ticks. Emit a TIMED-prefixed ROOM_STATE_PATCH with an empty schema
+      // body — 1 byte protocol + 8 bytes prefix.
       // No-op for rooms without `defineInput()` (timing is undefined).
       if (timing) {
         const heartbeatBody = Buffer.from([Protocol.ROOM_STATE_PATCH]);

package/src/serializer/Serializer.ts

@@ -2,12 +2,12 @@ import type { Client } from '../Transport.ts';
 
 /**
  * Per-tick timing context, populated by the Room when
- * {@link Room.defineInput} was called. The serializer uses it to emit a
- * {@link ProtocolModifier.TIMED} prefix for clients that advertised
- * the {@link HandshakeSection.CLIENT_TIMING} capability.
+ * {@link Room.defineInput} was called. Its presence makes the serializer emit
+ * a {@link ProtocolModifier.TIMED} prefix on every state/patch frame — the
+ * gate is per-room (defineInput), not a per-client capability.
  */
 export interface PatchTimingContext {
-  /** `performance.now()` at the moment the patch is being applied. */
+  /** Server clock as ms since room start (`clock.elapsedTime`) at patch time. */
   sNow: number;
 }