@colyseus/core 0.17.40 → 0.17.42

package/src/Server.ts

@@ -40,7 +40,7 @@ export type ServerOptions = {
    *
    * For uWebSockets transport, this uses the uwebsockets-express module.
    */
-  express?: (app: express.Application) => void,
+  express?: (app: express.Application) => Promise<void> | void,
 
   /**
    * Custom function to determine which process should handle room creation.
@@ -141,7 +141,7 @@ export class Server<
     // Initialize Express if callback is provided
     if (options.express && this.transport.getExpressApp) {
       const expressApp = await this.transport.getExpressApp();
-      options.express(expressApp);
+      await options.express(expressApp);
     }
 
     // Resolve the promise when the transport is ready
@@ -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/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/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;
   }
-}
+}