@colyseus/core 0.18.16 → 0.18.18

package/src/Room.ts

@@ -65,6 +65,9 @@ const noneSerializer = new NoneSerializer();
  *  next patch. Frozen + shared (read-only) → zero per-call allocation. */
 const AFTER_PATCH_OPTS = Object.freeze({ afterNextPatch: true });
 
+/** Room properties backed by `Room.prototype` accessors. */
+const ROOM_ACCESSORS = ['state', 'maxClients', 'autoDispose', 'patchRate', 'unreliablePatchRate'] as const;
+
 export const DEFAULT_SEAT_RESERVATION_TIME = Number(process.env.COLYSEUS_SEAT_RESERVATION_TIME || 15);
 
 export type SimulationCallback = (deltaTime: number) => void;
@@ -258,25 +261,25 @@ export class Room<T extends RoomOptions = RoomOptions> {
    * it is locked automatically. Unless the room was explicitly locked by you via `lock()` method,
    * the room will be unlocked as soon as a client disconnects from it.
    */
-  public maxClients: number = Infinity;
+  declare public maxClients: number;
   #_maxClientsReached: boolean = false;
-  #_maxClients: number;
+  #_maxClients: number = Infinity;
 
   /**
    * Automatically dispose the room when last client disconnects.
    *
    * @default true
    */
-  public autoDispose: boolean = true;
-  #_autoDispose: boolean;
+  declare public autoDispose: boolean;
+  #_autoDispose: boolean = true;
 
   /**
    * Frequency to send the room state to connected clients, in milliseconds.
    *
    * @default 50ms (20fps)
    */
-  public patchRate: number | null = DEFAULT_PATCH_RATE;
-  #_patchRate: number;
+  declare public patchRate: number | null;
+  #_patchRate: number = DEFAULT_PATCH_RATE;
   #_patchInterval: NodeJS.Timeout;
 
   /**
@@ -305,7 +308,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
    * @default null — flush alongside every {@link broadcastPatch}, and only when
    * the state actually declares an `@unreliable` field.
    */
-  public unreliablePatchRate: number | null = null;
+  declare public unreliablePatchRate: number | null;
   #_unreliablePatchRate: number | null = null;
   #_unreliablePatchInterval: NodeJS.Timeout;
 
@@ -329,9 +332,12 @@ export class Room<T extends RoomOptions = RoomOptions> {
   /**
    * The state instance you provided to `setState()`.
    */
-  public state: ExtractRoomState<T>;
+  declare public state: ExtractRoomState<T>;
   #_state: ExtractRoomState<T>;
 
+  /** Until `__init()`, the prototype accessor setters only store the value. */
+  #_ready: boolean = false;
+
   /**
    * The presence instance. Check Presence API for more details.
    *
@@ -455,21 +461,30 @@ export class Room<T extends RoomOptions = RoomOptions> {
   }
 
   /**
-   * This method is called by the MatchMaker before onCreate()
-   * @internal
+   * These accessors are defined once, on the prototype, to keep rooms in V8's
+   * fast-properties mode.
+   *
+   * V8 reads a property of an ordinary object at a fixed offset. A few
+   * operations switch the object to "dictionary mode" instead, where every
+   * read is a hash lookup, and it stays there:
+   *  - `delete obj.prop`, unless `prop` was the last property added;
+   *  - redefining an existing data property as an accessor;
+   *  - `Object.defineProperty(instance, ...)` with fresh getter/setter
+   *    closures per instance (every room after the first).
+   *
+   * Room and Client properties are read on every message and broadcast, so
+   * never `delete` their properties (assign `undefined`) and never define
+   * accessors per instance. Check with `node --allow-natives-syntax` and
+   * `%HasFastProperties(room)`.
    */
-  private __init() {
-    this.#_state = this.state;
-    this.#_autoDispose = this.autoDispose;
-    this.#_patchRate = this.patchRate;
-    this.#_unreliablePatchRate = this.unreliablePatchRate;
-    this.#_maxClients = this.maxClients;
-
-    Object.defineProperties(this, {
+  static {
+    Object.defineProperties(this.prototype, {
       state: {
         enumerable: true,
-        get: () => this.#_state,
-        set: (newState: ExtractRoomState<T>) => {
+        configurable: true,
+        get(this: Room<any>) { return this.#_state; },
+        set(this: Room<any>, newState: any) {
+          if (!this.#_ready) { this.#_state = newState; return; }
           if (newState?.constructor[Symbol.metadata] !== undefined || newState[$changes] !== undefined) {
             this.setSerializer(new SchemaSerializer());
           } else if ('_definition' in newState) {
@@ -485,16 +500,20 @@ export class Room<T extends RoomOptions = RoomOptions> {
 
       maxClients: {
         enumerable: true,
-        get: () => this.#_maxClients,
-        set: (value: number) => {
+        configurable: true,
+        get(this: Room<any>) { return this.#_maxClients; },
+        set(this: Room<any>, value: number) {
+          if (!this.#_ready) { this.#_maxClients = value; return; }
           this.setMatchmaking({ maxClients: value });
         },
       },
 
       autoDispose: {
         enumerable: true,
-        get: () => this.#_autoDispose,
-        set: (value: boolean) => {
+        configurable: true,
+        get(this: Room<any>) { return this.#_autoDispose; },
+        set(this: Room<any>, value: boolean) {
+          if (!this.#_ready) { this.#_autoDispose = value; return; }
           if (
             value !== this.#_autoDispose &&
             this._internalState !== RoomInternalState.DISPOSING
@@ -507,9 +526,11 @@ export class Room<T extends RoomOptions = RoomOptions> {
 
       patchRate: {
         enumerable: true,
-        get: () => this.#_patchRate,
-        set: (milliseconds: number) => {
+        configurable: true,
+        get(this: Room<any>) { return this.#_patchRate; },
+        set(this: Room<any>, milliseconds: number) {
           this.#_patchRate = milliseconds;
+          if (!this.#_ready) { return; }
           // clear previous interval in case called setPatchRate more than once
           if (this.#_patchInterval) {
             clearInterval(this.#_patchInterval);
@@ -526,13 +547,33 @@ export class Room<T extends RoomOptions = RoomOptions> {
 
       unreliablePatchRate: {
         enumerable: true,
-        get: () => this.#_unreliablePatchRate,
-        set: (milliseconds: number | null) => {
+        configurable: true,
+        get(this: Room<any>) { return this.#_unreliablePatchRate; },
+        set(this: Room<any>, milliseconds: number | null) {
           this.#_unreliablePatchRate = milliseconds;
+          if (!this.#_ready) { return; }
           this._armUnreliablePatches();
         },
       },
     });
+  }
+
+  /**
+   * This method is called by the MatchMaker before onCreate()
+   * @internal
+   */
+  private __init() {
+    // Native class fields (plain JS, type-stripped TS, `useDefineForClassFields`) shadow
+    // the prototype accessors: re-install them here, at the cost of this room's fast mode.
+    for (let i = 0; i < ROOM_ACCESSORS.length; i++) {
+      const key = ROOM_ACCESSORS[i];
+      if (!Object.hasOwn(this, key)) { continue; }
+      const value = this[key];
+      Object.defineProperty(this, key, Object.getOwnPropertyDescriptor(Room.prototype, key));
+      (this as any)[key] = value; // not ready yet: only stores
+    }
+
+    this.#_ready = true;
 
     // set patch interval, now with the setter
     this.patchRate = this.#_patchRate;
@@ -2187,7 +2228,8 @@ export class Room<T extends RoomOptions = RoomOptions> {
   async #_dispose(): Promise<any> {
     this._internalState = RoomInternalState.DISPOSING;
 
-    // If the room is still CREATING, the roomId is not yet set.
+    // no row to remove: roomId is unset if onCreate() failed, and cleared when the
+    // row belongs to another process (see `recordRoom`)
     if (this._listing?.roomId !== undefined) {
       await matchMaker.driver.remove(this._listing.roomId);
     }
@@ -2284,7 +2326,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
       if (client._enqueuedMessages.length > 0) {
         client._enqueuedMessages.forEach((enqueued) => client.raw(enqueued));
       }
-      delete client._enqueuedMessages;
+      client._enqueuedMessages = undefined; // not `delete`: keeps the client in V8 fast mode (see Room's static block)
 
     } else if (code === Protocol.PING) {
       client.raw(getMessageBytes[Protocol.PING]());

package/src/matchmaker/LocalDriver/LocalDriver.ts

@@ -8,8 +8,11 @@ export type { IRoomCache, SortOptions, MatchMakerDriver };
 export class LocalDriver implements MatchMakerDriver {
   public rooms: IRoomCache[] = [];
 
+  // the roomIds in `rooms`: keeps has() and insert() O(1) however many rooms there are
+  private roomIds = new Set<string>();
+
   public has(roomId: string) {
-    return this.rooms.some((room) => room.roomId === roomId);
+    return this.roomIds.has(roomId);
   }
 
   public query(conditions: Partial<IRoomCache>, sortOptions?: SortOptions) {
@@ -70,15 +73,18 @@ export class LocalDriver implements MatchMakerDriver {
     return true;
   }
 
-  public persist(room: IRoomCache, create: boolean = false) {
-    // if (this.rooms.indexOf(room) !== -1) {
-    //   // already in the list
-    //   return true;
-    // }
+  public async insert(room: IRoomCache) {
+    if (this.has(room.roomId)) { return false; }
 
+    this.roomIds.add(room.roomId);
+    this.rooms.push(room);
+    return true;
+  }
+
+  public persist(room: IRoomCache, create: boolean = false) {
     if (!create) { return false; }
 
-    // add to the list
+    this.roomIds.add(room.roomId);
     this.rooms.push(room);
 
     return true;
@@ -88,6 +94,7 @@ export class LocalDriver implements MatchMakerDriver {
     const roomIndex = this.rooms.findIndex((room) => room.roomId === roomId);
     if (roomIndex !== -1) {
       this.rooms.splice(roomIndex, 1);
+      this.roomIds.delete(roomId);
       return true;
     }
     return false;
@@ -95,6 +102,7 @@ export class LocalDriver implements MatchMakerDriver {
 
   public clear() {
     this.rooms = [];
+    this.roomIds.clear();
   }
 
   public shutdown() {

package/src/matchmaker/driver.ts

@@ -186,6 +186,18 @@ export interface MatchMakerDriver {
    */
   persist(room: IRoomCache, create?: boolean): Promise<boolean> | boolean;
 
+  /**
+   * Record a room, unless its `roomId` is already recorded. Must be atomic, and
+   * must return false rather than throwing when the `roomId` is taken.
+   *
+   * Matchmaking uses this to settle which process owns a room when one create
+   * request is answered twice. Drivers that don't implement it fall back to
+   * `persist(room, true)`, where the second write silently wins.
+   *
+   * TODO: required on 1.0, replacing `persist()`'s `create` flag.
+   */
+  insert?(room: IRoomCache): Promise<boolean>;
+
   /**
    * Empty the room cache. Used for testing purposes only.
    * May be asynchronous — callers must await it.

package/src/presence/LocalPresence.ts

@@ -107,6 +107,8 @@ export class LocalPresence implements Presence {
     }
 
     public del(key: string) {
+        clearTimeout(this.timeouts[key]); // a pending expiry would wipe whatever is set next
+        delete this.timeouts[key];
         delete this.keys[key];
         delete this.data[key];
         delete this.hash[key];

package/src/utils/DevMode.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import { type Schema, MapSchema, ArraySchema, SetSchema, CollectionSchema, $childType, $changes } from '@colyseus/schema';
 import { logger } from '../Logger.ts';
 import { debugAndPrintError, debugDevMode } from '../Debug.ts';
-import { getLocalRoomById, handleCreateRoom, presence, remoteRoomCall } from '../MatchMaker.ts';
+import { getLocalRoomById, handleCreateRoom, MatchMakerState, presence, remoteRoomCall, state } from '../MatchMaker.ts';
 import type { Room } from '../Room.ts';
 
 const DEVMODE_CACHE_FILE_PATH = path.resolve(".devmode.json");
@@ -49,6 +49,9 @@ export async function reloadFromCache() {
       recreatedRoom = getLocalRoomById(recreatedRoomListing.roomId);
 
     } catch (e: any) {
+      // shutdown interrupted the restore: keep the remaining entries for the next boot
+      if (state === MatchMakerState.SHUTTING_DOWN) { break; }
+
       // unrestorable entry (e.g. room type renamed/removed) — drop it
       // instead of wedging the boot
       debugAndPrintError(`❌ couldn't restore room '${roomId}':\n${e.stack}`);

package/src/utils/Utils.ts

@@ -44,6 +44,12 @@ export type RemoteRoomCallReturn<
 export const REMOTE_ROOM_SHORT_TIMEOUT = Number(process.env.COLYSEUS_PRESENCE_SHORT_TIMEOUT || 2000);
 export const MAX_CONCURRENT_CREATE_ROOM_WAIT_TIME = Number(process.env.COLYSEUS_MAX_CONCURRENT_CREATE_ROOM_WAIT_TIME || 0.5);
 
+// a peer that removes this process's room listings leaves a receipt. this
+// process looks for it every INTERVAL (ms) and restores them. the TTL (seconds)
+// only bounds what dead processes leave behind.
+export const SWEPT_CHECK_INTERVAL = Number(process.env.COLYSEUS_SWEPT_CHECK_INTERVAL || 5000);
+export const SWEPT_RECEIPT_TTL = Number(process.env.COLYSEUS_SWEPT_RECEIPT_TTL || 600);
+
 /**
  * The well-known `Symbol.metadata` (TC39 decorator metadata), falling back to the
  * registered symbol on runtimes that don't expose it globally yet. `@colyseus/schema`