@colyseus/core 0.17.39 → 0.17.41

package/src/Room.ts

@@ -23,7 +23,7 @@ import { ClientState, type AuthContext, type Client, type ClientPrivate, ClientA
 import { type RoomMethodName, OnAuthException, OnCreateException, OnDisposeException, OnDropException, OnJoinException, OnLeaveException, OnMessageException, OnReconnectException, type RoomException, SimulationIntervalException, TimedEventException } from './errors/RoomExceptions.ts';
 
 import { standardValidate, type StandardSchemaV1 } from './utils/StandardSchema.ts';
-import { matchMaker } from '@colyseus/core';
+import * as matchMaker from './MatchMaker.ts';
 
 import {
   CloseCode,
@@ -551,7 +551,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
       (isDevMode)
         ? CloseCode.MAY_TRY_RECONNECT
         : CloseCode.SERVER_SHUTDOWN
-    );
+    ).catch(() => {});
   }
 
   /**
@@ -1066,9 +1066,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
       this._events.once('disconnect', () => resolve()));
 
     // reject pending reconnections
-    for (const [_, reconnection] of Object.values(this._reconnections)) {
-      reconnection.reject(new Error("disconnecting"));
-    }
+    this._rejectPendingReconnections("disconnecting");
 
     let numClients = this.clients.length;
     if (numClients > 0) {
@@ -1085,6 +1083,15 @@ export class Room<T extends RoomOptions = RoomOptions> {
     return delayedDisconnection;
   }
 
+  private _rejectPendingReconnections(message: string) {
+    for (const [_, reconnection] of Object.values(this._reconnections)) {
+      reconnection.reject(new ServerError(CloseCode.NORMAL_CLOSURE, message));
+      // Suppress unhandled rejection — expected during shutdown/devMode
+      // restart, handled downstream by _onLeave's .catch() handler.
+      reconnection.catch(() => {});
+    }
+  }
+
   private async _onJoin(
     client: ExtractRoomClient<T> & ClientPrivate,
     authContext: AuthContext,
@@ -1323,7 +1330,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
     //
     if ((previousClient as unknown as ClientPrivate)._enqueuedMessages !== undefined) {
       // @ts-ignore
-      return Promise.reject(new Error("not joined"));
+      return Promise.reject(new ServerError("not joined"));
     }
 
     if (seconds === undefined) { // TODO: remove this check
@@ -1497,13 +1504,26 @@ export class Room<T extends RoomOptions = RoomOptions> {
       this.resetAutoDisposeTimeout(seconds);
     }
 
-    //
-    // TODO: isDevMode workaround to allow players to reconnect on devMode
-    //
     if (devModeReconnectionToken) {
-      // Set up reconnection token mapping
       const reconnection = new Deferred<Client & ClientPrivate>();
       this._reconnections[devModeReconnectionToken] = [sessionId, reconnection];
+
+      // If the client doesn't reconnect within the timeout, call onLeave
+      // so the room can clean up stale state (e.g. delete player data).
+      clearTimeout(this._reservedSeatTimeouts[sessionId]);
+      this._reservedSeatTimeouts[sessionId] = setTimeout(async () => {
+        if (!this._reconnections[devModeReconnectionToken]) { return; }
+
+        delete this._reconnections[devModeReconnectionToken];
+        delete this._reservedSeats[sessionId];
+        delete this._reservedSeatTimeouts[sessionId];
+
+        if (!allowReconnection) {
+          await this.#_decrementClientCount();
+        }
+
+        this.onLeave?.({ sessionId } as any, CloseCode.MAY_TRY_RECONNECT);
+      }, seconds * 1000);
     }
 
     return true;
@@ -1717,7 +1737,10 @@ export class Room<T extends RoomOptions = RoomOptions> {
         await method.call(this, client, code);
 
       } catch (e: any) {
-        debugAndPrintError(`${method.name} error: ${(e && e.message || e || 'promise rejected')} (roomId: ${this.roomId})`);
+        const serverError = (!(e instanceof ServerError))
+          ? new ServerError(CloseCode.WITH_ERROR, `${method.name} error`, { cause: e })
+          : e;
+        debugAndPrintError(serverError);
 
       } finally {
         this.#_onLeaveConcurrent--;

package/src/Server.ts

@@ -370,6 +370,40 @@ export class Server<
     () => Promise.resolve()
 }
 
+export type RoomDefinitions = Record<string, RegisteredHandler | Type<Room>>;
+
+function isRegisteredHandler(value: RegisteredHandler | Type<Room>): value is RegisteredHandler {
+  return value instanceof RegisteredHandler || (
+    typeof(value) === "object" &&
+    value !== null &&
+    'klass' in (value as object)
+  );
+}
+
+export function registerRoomDefinitions<T extends RoomDefinitions>(rooms: T): string[] {
+  const roomNames: string[] = [];
+
+  for (const [name, value] of Object.entries(rooms)) {
+    if (isRegisteredHandler(value)) {
+      value.name = name;
+      matchMaker.addRoomType(value);
+
+    } else {
+      matchMaker.defineRoomType(name, value);
+    }
+
+    roomNames.push(name);
+  }
+
+  return roomNames;
+}
+
+export function unregisterRoomDefinitions(roomNames: Iterable<string>) {
+  for (const roomName of roomNames) {
+    matchMaker.removeRoomType(roomName);
+  }
+}
+
 export type DefineServerOptions<
   T extends Record<string, RegisteredHandler>,
   R extends Router
@@ -385,14 +419,21 @@ export function defineServer<
   options: DefineServerOptions<T, R>,
 ): Server<T, R> {
   const { rooms, routes, ...serverOptions } = options;
-  const server = new Server<T, R>(serverOptions);
 
+  if (isDevMode) {
+    // In dev mode, the Vite plugin manages Server/matchMaker lifecycle.
+    // Return a config-only object — no Server instance, no matchMaker.setup().
+    return {
+      options: serverOptions,
+      router: routes,
+      '~rooms': rooms,
+    } as unknown as Server<T, R>;
+  }
+
+  const server = new Server<T, R>(serverOptions);
   server.router = routes;
 
-  for (const [name, handler] of Object.entries(rooms)) {
-    handler.name = name;
-    matchMaker.addRoomType(handler);
-  }
+  registerRoomDefinitions(rooms);
 
   return server;
 }
@@ -402,4 +443,4 @@ export function defineRoom<T extends Type<Room>>(
   defaultOptions?: Parameters<NonNullable<InstanceType<T>['onCreate']>>[0],
 ): RegisteredHandler<InstanceType<T>> {
   return new RegisteredHandler(roomKlass, defaultOptions) as unknown as RegisteredHandler<InstanceType<T>>;
-}
+}

package/src/errors/ServerError.ts

@@ -3,8 +3,8 @@ import { ErrorCode } from '@colyseus/shared-types';
 export class ServerError extends Error {
   public code: number;
 
-  constructor(code: number = ErrorCode.MATCHMAKE_UNHANDLED, message?: string) {
-    super(message);
+  constructor(code: number = ErrorCode.MATCHMAKE_UNHANDLED, message?: string, options?: ErrorOptions) {
+    super(message, options);
 
     // Maintains proper stack trace for where our error was thrown (only available on V8)
     if (Error.captureStackTrace) {

package/src/index.ts

@@ -11,7 +11,7 @@ export {
 } from '@colyseus/shared-types';
 
 // Core classes
-export { Server, defineRoom, defineServer, type ServerOptions, type SDKTypes } from './Server.ts';
+export { Server, defineRoom, defineServer, registerRoomDefinitions, unregisterRoomDefinitions, type RoomDefinitions, type ServerOptions, type SDKTypes } from './Server.ts';
 export { Room, room, RoomInternalState, validate, type RoomOptions, type MessageHandlerWithFormat, type Messages, type ExtractRoomState, type ExtractRoomMetadata, type ExtractRoomClient } from './Room.ts';
 export { getMessageBytes } from './Protocol.ts';
 export { RegisteredHandler } from './matchmaker/RegisteredHandler.ts';
@@ -34,6 +34,7 @@ export {
 import * as matchMaker from './MatchMaker.ts';
 export { matchMaker };
 export { updateLobby, subscribeLobby } from './matchmaker/Lobby.ts';
+export { createNodeMatchmakingMiddleware } from './router/node.ts';
 
 // Driver
 export * from './matchmaker/LocalDriver/LocalDriver.ts';
@@ -53,7 +54,7 @@ export { SchemaSerializer } from './serializer/SchemaSerializer.ts';
 // Utilities
 export { Clock, Delayed };
 export { generateId, Deferred, spliceOne, getBearerToken, dynamicImport } from './utils/Utils.ts';
-export { isDevMode } from './utils/DevMode.ts';
+export { isDevMode, setDevMode } from './utils/DevMode.ts';
 
 // IPC
 export { subscribeIPC, requestFromIPC } from './IPC.ts';

package/src/router/index.ts

@@ -68,7 +68,7 @@ export function bindRouterToTransport(transport: Transport, router: Router, useE
     next = async (req: IncomingMessage, res: ServerResponse) => {
       // check if the route is defined in the router
       // if so, use the router handler, otherwise fallback to express
-      if (router.findRoute(req.method, req.url) !== undefined) {
+      if (router.findRoute(req.method, req.url.split('?')[0]) !== undefined) {
         const protocol = req.headers["x-forwarded-proto"] || ((req.socket as any).encrypted ? "https" : "http");
         const base = `${protocol}://${req.headers[":authority"] || req.headers.host}`;
         const response = await router.handler(getRequest({ base, request: req }));

package/src/router/node.ts

@@ -0,0 +1,88 @@
+/**
+ * Raw Node.js adapter for Colyseus matchmaking routes used by `colyseus/vite`.
+ *
+ * This file exists specifically so the Vite plugin can share Vite's dev HTTP
+ * server while still exposing the Colyseus `/matchmake/*` endpoints.
+ *
+ * Keep the matchmaking behavior itself in `router/default_routes.ts` and use
+ * this file only as the thin raw Node/Express adapter around it.
+ */
+import type http from 'http';
+import { URL } from 'url';
+import * as matchMaker from '../MatchMaker.ts';
+import { setResponse } from '@colyseus/better-call/node';
+import { postMatchmakeMethod } from './default_routes.ts';
+
+function readBody(req: http.IncomingMessage): Promise<any> {
+  return new Promise((resolve, reject) => {
+    let data = '';
+
+    req.on('data', (chunk: Buffer | string) => {
+      data += chunk.toString();
+    });
+    req.on('end', () => resolve(data ? JSON.parse(data) : {}));
+    req.on('error', reject);
+  });
+}
+
+function getCorsHeaders(req: http.IncomingMessage, headers?: Headers): Record<string, string> {
+  return {
+    ...matchMaker.controller.DEFAULT_CORS_HEADERS,
+    ...matchMaker.controller.getCorsHeaders(headers),
+  };
+}
+
+export function createNodeMatchmakingMiddleware() {
+  return async (
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    next: () => void,
+  ) => {
+    const url = new URL(req.url || '/', 'http://localhost');
+    const isMatchmakeRoute = url.pathname.startsWith(`/${matchMaker.controller.matchmakeRoute}/`);
+
+    if (!isMatchmakeRoute) {
+      next();
+      return;
+    }
+
+    const headers = new Headers(req.headers as Record<string, string>);
+    const corsHeaders = getCorsHeaders(req, headers);
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, corsHeaders);
+      res.end();
+      return;
+    }
+
+    if (req.method !== 'POST') {
+      next();
+      return;
+    }
+
+    const match = url.pathname.match(/^\/matchmake\/(\w+)\/(.+)/);
+    if (!match) {
+      next();
+      return;
+    }
+
+    const [, method, roomName] = match;
+
+    try {
+      const response = await postMatchmakeMethod({
+        params: { method, roomName },
+        body: await readBody(req),
+        headers: req.headers as Record<string, string>,
+        request: { headers } as any,
+        asResponse: true,
+      });
+
+      await setResponse(res, response);
+
+    } catch {
+      // Endpoint-level failures are returned as Response when `asResponse` is true.
+      // Any thrown error here is unexpected, so let the next middleware decide.
+      next();
+    }
+  };
+}

package/src/utils/DevMode.ts

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import { type Schema, MapSchema, ArraySchema, SetSchema, CollectionSchema, $childType } from '@colyseus/schema';
+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';
@@ -44,19 +44,33 @@ export async function reloadFromCache() {
         logger.debug(`📋 room '${roomId}' state =>`, rawState);
 
         (recreatedRoom.state as Schema).restore(rawState);
+
+        // Restore the encoder's nextUniqueId so refIds increase
+        // monotonically across HMR cycles. Without this, restore()
+        // always produces the same refIds (0,1,2,3...) and onJoin()
+        // always assigns the same next refIds (4,5...), causing the
+        // client decoder to reuse stale instances on the 2nd+ cycle.
+        if (roomHistory.nextRefId !== undefined) {
+          const encoderRoot = recreatedRoom.state[$changes]?.root;
+          if (encoderRoot && roomHistory.nextRefId > encoderRoot['nextUniqueId']) {
+            encoderRoot['nextUniqueId'] = roomHistory.nextRefId;
+          }
+        }
       } catch (e: any) {
         debugAndPrintError(`❌ couldn't restore room '${roomId}' state:\n${e.stack}`);
       }
     }
 
-    // Reserve seats for clients from cached history
+    // Reserve seats for clients from cached history.
+    // Skip entries without a reconnectionToken — these are stale
+    // seats from allowReconnection() where the client already left
+    // (e.g. page refresh). Restoring them would block room disposal.
     if (roomHistory.clients) {
       for (const clientData of roomHistory.clients) {
-        // TODO: need to restore each client's StateView as well
-        // reserve seat for 20 seconds
         const { sessionId, reconnectionToken } = clientData;
-        console.log("reserving seat for client", { sessionId, reconnectionToken });
-        await remoteRoomCall(recreatedRoomListing.roomId, '_reserveSeat', [sessionId, {}, {}, 20, false, reconnectionToken]);
+        if (!reconnectionToken) { continue; }
+        // TODO: need to restore each client's StateView as well
+        await remoteRoomCall(recreatedRoomListing.roomId, '_reserveSeat', [sessionId, {}, {}, recreatedRoom.seatReservationTimeout, false, reconnectionToken]);
       }
     }
 
@@ -86,6 +100,15 @@ export async function cacheRoomHistory(rooms: { [roomId: string]: Room }) {
 
         if (room.state) {
           roomHistory["state"] = JSON.stringify(room.state);
+
+          // Cache the encoder's nextUniqueId so it can be restored.
+          // This ensures refIds increase monotonically across HMR cycles,
+          // preventing the client decoder from reusing stale refs that
+          // happen to have the same refId as newly created instances.
+          const encoderRoot = room.state[$changes]?.root;
+          if (encoderRoot) {
+            roomHistory["nextRefId"] = encoderRoot['nextUniqueId'];
+          }
         }
 
         // cache active clients with their reconnection tokens

package/src/utils/Utils.ts

@@ -190,8 +190,8 @@ export function dynamicImport<T = any>(moduleName: string): Promise<T> {
     }
   } else {
     // ESM context - use import()
-    const promise = import(moduleName);
+    const promise = import(/* @vite-ignore */ moduleName);
     promise.catch(() => {}); // prevent unhandled rejection warnings
     return promise;
   }
-}
+}