colyseus 0.17.7 → 0.17.9

package/LICENSE

@@ -1,6 +1,4 @@
-Copyright (c) 2023 Endel Dreyer
-Copyright (c) 2021-2022 Lucid Sight
-Copyright (c) 2015-2021 Endel Dreyer
+Copyright (c) 2015-2026 Endel Dreyer
 
 MIT License:
 

package/README.md

@@ -7,19 +7,33 @@
   <a href="https://npmjs.com/package/colyseus">
     <img src="https://img.shields.io/npm/dm/colyseus.svg?style=for-the-badge&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAQAAAC1+jfqAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAAAmJLR0QAAKqNIzIAAAAJcEhZcwAADsQAAA7EAZUrDhsAAAAHdElNRQfjAgETESWYxR33AAAAtElEQVQoz4WQMQrCQBRE38Z0QoTcwF4Qg1h4BO0sxGOk80iCtViksrIQRRBTewWxMI1mbELYjYu+4rPMDPtn12ChMT3gavb4US5Jym0tcBIta3oDHv4Gwmr7nC4QAxBrCdzM2q6XqUnm9m9r59h7Rc0n2pFv24k4ttGMUXW+sGELTJjSr7QDKuqLS6UKFChVWWuFkZw9Z2AAvAirKT+JTlppIRnd6XgaP4goefI2Shj++OnjB3tBmHYK8z9zAAAAJXRFWHRkYXRlOmNyZWF0ZQAyMDE5LTAyLTAxVDE4OjE3OjM3KzAxOjAwGQQixQAAACV0RVh0ZGF0ZTptb2RpZnkAMjAxOS0wMi0wMVQxODoxNzozNyswMTowMGhZmnkAAAAZdEVYdFNvZnR3YXJlAHd3dy5pbmtzY2FwZS5vcmeb7jwaAAAAAElFTkSuQmCC">
   </a>
-  <a href="https://github.com/colyseus/colyseus/discussions" title="Discuss on Forum">
-    <img src="https://img.shields.io/badge/discuss-on%20forum-brightgreen.svg?style=for-the-badge&colorB=0069b8&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAQAAAC1+jfqAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAAAmJLR0QAAKqNIzIAAAAJcEhZcwAADsQAAA7EAZUrDhsAAAAHdElNRQfjAgETDROxCNUzAAABB0lEQVQoz4WRvyvEARjGP193CnWRH+dHQmGwKZtFGcSmxHAL400GN95ktIpV2dzlLzDJgsGgGNRdDAzoQueS/PgY3HXHyT3T+/Y87/s89UANBKXBdoZo5J6L4K1K5ZxHfnjnlQUf3bKvkgy57a0r9hS3cXfMO1kWJMza++tj3Ac7/LY343x1NA9cNmYMwnSS/SP8JVFuSJmr44iFqvtmpjhmhBCrOOazCesq6H4P3bPBjFoIBydOk2bUA17I080Es+wSZ51B4DIA2zgjSpYcEe44Js01G0XjRcCU+y4ZMrDeLmfc9EnVd5M/o0VMeu6nJZxWJivLmhyw1WHTvrr2b4+2OFqra+ALwouTMDcqmjMAAAAldEVYdGRhdGU6Y3JlYXRlADIwMTktMDItMDFUMTg6MTM6MTkrMDE6MDAC9f6fAAAAJXRFWHRkYXRlOm1vZGlmeQAyMDE5LTAyLTAxVDE4OjEzOjE5KzAxOjAwc6hGIwAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAAAASUVORK5CYII=" alt="Discussion forum" />
-  </a>
   <a href="http://chat.colyseus.io">
     <img src="https://img.shields.io/discord/525739117951320081.svg?style=for-the-badge&colorB=7581dc&logo=discord&logoColor=white">
   </a>
+  <a href="https://github.com/colyseus/colyseus/discussions" title="Discuss Forum">
+    <img src="https://img.shields.io/badge/discuss-forum-brightgreen.svg?style=for-the-badge&colorB=0069b8&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAQAAAC1+jfqAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAAAmJLR0QAAKqNIzIAAAAJcEhZcwAADsQAAA7EAZUrDhsAAAAHdElNRQfjAgETDROxCNUzAAABB0lEQVQoz4WRvyvEARjGP193CnWRH+dHQmGwKZtFGcSmxHAL400GN95ktIpV2dzlLzDJgsGgGNRdDAzoQueS/PgY3HXHyT3T+/Y87/s89UANBKXBdoZo5J6L4K1K5ZxHfnjnlQUf3bKvkgy57a0r9hS3cXfMO1kWJMza++tj3Ac7/LY343x1NA9cNmYMwnSS/SP8JVFuSJmr44iFqvtmpjhmhBCrOOazCesq6H4P3bPBjFoIBydOk2bUA17I080Es+wSZ51B4DIA2zgjSpYcEe44Js01G0XjRcCU+y4ZMrDeLmfc9EnVd5M/o0VMeu6nJZxWJivLmhyw1WHTvrr2b4+2OFqra+ALwouTMDcqmjMAAAAldEVYdGRhdGU6Y3JlYXRlADIwMTktMDItMDFUMTg6MTM6MTkrMDE6MDAC9f6fAAAAJXRFWHRkYXRlOm1vZGlmeQAyMDE5LTAyLTAxVDE4OjEzOjE5KzAxOjAwc6hGIwAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAAAASUVORK5CYII=" alt="Discussion forum" />
+  </a>
   <h3>
     Multiplayer Framework for Node.js. <br /><a href="https://docs.colyseus.io/">View documentation</a>
   </h3>
 </div>
 
-Colyseus is an Authoritative Multiplayer Framework for Node.js, with clients
-available for the Web, Unity3d, Defold, Haxe, and Cocos. ([See official clients](#%EF%B8%8F-official-client-integration))
+Colyseus is an Authoritative Multiplayer Framework for Node.js, with SDKs
+available for all major platforms and engines.
+
+## Client SDKs
+
+| Platform | Install | Documentation | Demo |
+|----------|---------|---------------|------|
+| TypeScript | `npm install @colyseus/sdk` | [Getting Started](https://docs.colyseus.io/getting-started/typescript) | [PlayCanvas](https://github.com/endel/tank-battle-multiplayer/tree/master/web-playcanvas) |
+| React | `npm install @colyseus/react` | [Getting Started](https://docs.colyseus.io/getting-started/react) | [R3F Lobby](https://github.com/endel/r3f-lobby-car-prototype) |
+| Unity | [Download](https://github.com/colyseus/colyseus-unity3d/releases/latest/download/Colyseus_Plugin.unitypackage) | [Getting Started](https://docs.colyseus.io/getting-started/unity) | [Tank Battle](https://github.com/endel/tank-battle-multiplayer/tree/master/unity) |
+| Godot | [Download](https://github.com/colyseus/native-sdk/releases?q=godot+sdk&expanded=true) | [Getting Started](https://docs.colyseus.io/getting-started/godot) | [Tank Battle](https://github.com/endel/tank-battle-multiplayer/tree/master/godot) |
+| GameMaker | [Download](https://github.com/colyseus/native-sdk/releases?q=gamemaker+sdk&expanded=true) | [Getting Started](https://docs.colyseus.io/getting-started/gamemaker) | [Tank Battle](https://github.com/endel/tank-battle-multiplayer/tree/master/gamemaker) |
+| Defold | See documentation → | [Getting Started](https://docs.colyseus.io/getting-started/defold) | [Tank Battle](https://github.com/endel/tank-battle-multiplayer/tree/master/defold) |
+| Construct | [Download](https://www.construct.net/en/make-games/addons/111/colyseus-multiplayer-sdk) | [Getting Started](https://docs.colyseus.io/getting-started/construct3) | [Raw Demo](https://github.com/colyseus/construct3-demo) |
+| Haxe | `haxelib install colyseus` | [Getting Started](https://docs.colyseus.io/getting-started/haxe) | [Tank Battle](https://github.com/endel/tank-battle-multiplayer/tree/master/haxe) |
+| C / Static Libraries | [Download](https://github.com/colyseus/native-sdk/releases?q=%22Colyseus+Native+SDK+-+Static+Library%22&expanded=true) | [GitHub](https://github.com/colyseus/native-sdk) | [raylib](https://github.com/colyseus/native-sdk/tree/main/platforms/raylib) |
 
 The project focuses on providing synchronizable data structures for realtime and
 turn-based games, matchmaking, and ease of usage both on the server-side and
@@ -28,23 +42,24 @@ client-side.
 The mission of the framework is to be a standard netcode & matchmaking solution
 for any kind of project you can think of!
 
-## Key features:
+## Why developers choose Colyseus:
 
-- WebSocket-based communication
-- Simple API in the server-side and client-side.
-- Automatic state synchronization from server-to-client (delta compressed)
-- Matchmaking clients into game rooms/sessions
-- Scale vertically or horizontally
+- ⚡️ **Real-time state sync that just works** → Define your state on the server and it automatically synchronizes to all clients, delta-compressed and binary-encoded.
+- ⚔️ **Built-in matchmaking** → Room-based architecture with filtering, queuing, and reconnection support out of the box.
+- 📈 **Scalable** → Go from 10 to 10,000+ CCU by scaling vertically or horizontally with Redis and load balancers.
+- 🛡️ **Cheat-proof by design** → Authoritative server model ensures game logic runs on the server, not the client.
+- 🛠️ **Use the tools you already know** → Built on Node.js and TypeScript with a simple, familiar API on both server and client.
+- 💙 **Free forever** → MIT licensed, even for commercial games.
 
-See [public roadmap](https://github.com/colyseus/colyseus/wiki/Public-Roadmap) for future plans.
+See [public roadmap](https://docs.colyseus.io/roadmap) for version 1.0.
 
 # 🚀 Quickstart
 
-Create a bare-bones Colyseus server by using `npm create colyseus-app@latest`:
+Set up your own Colyseus server project for your game using `npm create colyseus-app@latest`:
 
 ```
-npm create colyseus-app@latest my-colyseus-server
-cd my-colyseus-server
+npm create colyseus-app@latest ./my-server
+cd my-server
 npm start
 ```
 
@@ -87,7 +102,7 @@ Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds
     <td align="center"><a href="https://github.com/TinyDobbins"><img src="https://avatars2.githubusercontent.com/u/20824844?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Nikita Borisov</b></sub></a><br /><a href="https://github.com/colyseus/colyseus/issues?q=author%3ATinyDobbins" title="Bug reports">🐛</a> <a href="https://github.com/colyseus/colyseus/commits?author=TinyDobbins" title="Code">💻</a> <a href="#business-TinyDobbins" title="Business development">💼</a> <a href="#ideas-TinyDobbins" title="Ideas, Planning, & Feedback">🤔</a></td>
     <td align="center"><a href="https://acemobe.com/"><img src="https://avatars2.githubusercontent.com/u/232101?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Phil Harvey</b></sub></a><br /><a href="https://github.com/colyseus/colyseus/commits?author=filharvey" title="Documentation">📖</a></td>
     <td align="center"><a href="https://github.com/serjek"><img src="https://avatars2.githubusercontent.com/u/18265157?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Sergey</b></sub></a><br /><a href="https://github.com/colyseus/colyseus/issues?q=author%3Aserjek" title="Bug reports">🐛</a> <a href="https://github.com/colyseus/colyseus/commits?author=serjek" title="Code">💻</a></td>
-    <td align="center"><a href="https://oyed.io"><img src="https://avatars0.githubusercontent.com/u/853683?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Tom</b></sub></a><br /><a href="#question-oyed" title="Answering Questions">💬</a> <a href="https://github.com/colyseus/colyseus/issues?q=author%3Aoyed" title="Bug reports">🐛</a> <a href="#ideas-oyed" title="Ideas, Planning, & Feedback">🤔</a></td>
+    <td align="center"><a href="https://devlsh.com"><img src="https://avatars0.githubusercontent.com/u/853683?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Sophie</b></sub></a><br /><a href="#question-devlsh" title="Answering Questions">💬</a> <a href="https://github.com/colyseus/colyseus/issues?q=author%3Adevlsh" title="Bug reports">🐛</a> <a href="#ideas-devlsh" title="Ideas, Planning, & Feedback">🤔</a></td>
     <td align="center"><a href="https://github.com/supertommy"><img src="https://avatars0.githubusercontent.com/u/2236153?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Tommy Leung</b></sub></a><br /><a href="#mentoring-supertommy" title="Mentoring">🧑‍🏫</a></td>
     <td align="center"><a href="https://github.com/digimbyte"><img src="https://avatars2.githubusercontent.com/u/6645396?v=4?s=100" width="100px;" alt=""/><br /><sub><b>digimbyte</b></sub></a><br /><a href="https://github.com/colyseus/colyseus/commits?author=digimbyte" title="Documentation">📖</a></td>
   </tr>

package/build/vite.cjs

@@ -0,0 +1,277 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// bundles/colyseus/src/vite.ts
+var vite_exports = {};
+__export(vite_exports, {
+  colyseus: () => colyseus,
+  createColyseusViteServerEntry: () => createColyseusViteServerEntry,
+  reloadColyseusViteRooms: () => reloadColyseusViteRooms
+});
+module.exports = __toCommonJS(vite_exports);
+var matchMaker = __toESM(require("@colyseus/core/MatchMaker"), 1);
+var import_core = require("@colyseus/core");
+var import_Transport = require("@colyseus/core/Transport");
+var VIRTUAL_SERVER_ENTRY = "virtual:colyseus-server-entry";
+var RESOLVED_VIRTUAL_SERVER_ENTRY = "\0" + VIRTUAL_SERVER_ENTRY;
+function getServerExport(mod) {
+  return mod.server || mod.default?.server;
+}
+function getRoomsExport(mod) {
+  return mod.rooms || mod.default?.rooms;
+}
+function createColyseusViteServerEntry(options) {
+  const port = options.port ?? 2567;
+  const lines = [
+    `import { Server, registerRoomDefinitions } from "colyseus";`
+  ];
+  if (options.serveClient) {
+    lines.push(
+      `import express from "express";`,
+      `import { fileURLToPath } from "url";`,
+      `import { dirname, join } from "path";`,
+      ``,
+      `const __dirname = dirname(fileURLToPath(import.meta.url));`,
+      `const clientDir = join(__dirname, "../client");`
+    );
+  }
+  lines.push(
+    ``,
+    `const entry = await import(${JSON.stringify(options.serverEntry)});`,
+    `const server = entry.server ?? entry.default?.server;`,
+    `const rooms = entry.rooms ?? entry.default?.rooms;`,
+    ``,
+    `if (server) {`
+  );
+  if (options.serveClient) {
+    lines.push(
+      `  await server["_onTransportReady"];`,
+      `  if (server.transport.getExpressApp) {`,
+      `    const app = server.transport.getExpressApp();`,
+      `    app.use(express.static(clientDir));`,
+      `    app.get("*all", (req, res) => res.sendFile(join(clientDir, "index.html")));`,
+      `  }`
+    );
+  }
+  lines.push(
+    `  server.listen(${port});`,
+    `} else if (rooms) {`,
+    `  const gameServer = new Server();`,
+    `  registerRoomDefinitions(rooms);`,
+    `  gameServer.listen(${port});`,
+    `} else {`,
+    `  throw new Error('[colyseus] Server entry should export \`server = defineServer(...)\` or \`rooms\`.');`,
+    `}`
+  );
+  return lines.join("\n");
+}
+async function reloadColyseusViteRooms(importModule, serverEntry, currentRoomNames = []) {
+  const mod = await importModule(serverEntry);
+  (0, import_core.unregisterRoomDefinitions)(currentRoomNames);
+  const server = getServerExport(mod);
+  const rooms = getRoomsExport(mod) || server?.["~rooms"];
+  if (!rooms) {
+    return {
+      roomNames: [],
+      hasRooms: false,
+      server
+    };
+  }
+  return {
+    roomNames: (0, import_core.registerRoomDefinitions)(rooms),
+    hasRooms: true,
+    server
+  };
+}
+function colyseus(options) {
+  let viteServer;
+  let currentRoomNames = [];
+  let currentAppHandler = null;
+  let expressApp = null;
+  let isStarted = false;
+  return [
+    {
+      name: "colyseus:config",
+      config() {
+        return {
+          builder: {},
+          build: { outDir: "dist/client" },
+          environments: {
+            colyseus: {
+              consumer: "server",
+              resolve: {
+                // Externalize all dependencies so they share the same module
+                // instances (and matchMaker singleton) with the plugin process.
+                // Without this, Vite re-evaluates workspace/linked packages in
+                // the runner, creating isolated singletons — breaking monitor, etc.
+                external: true
+              },
+              build: {
+                outDir: "dist/server",
+                ssr: true,
+                rollupOptions: {
+                  input: VIRTUAL_SERVER_ENTRY,
+                  output: { entryFileNames: "server.mjs" }
+                }
+              }
+            }
+          }
+        };
+      },
+      resolveId(id) {
+        if (id === VIRTUAL_SERVER_ENTRY) {
+          return RESOLVED_VIRTUAL_SERVER_ENTRY;
+        }
+      },
+      load(id) {
+        if (id === RESOLVED_VIRTUAL_SERVER_ENTRY) {
+          return createColyseusViteServerEntry(options);
+        }
+      }
+    },
+    {
+      name: "colyseus:dev-server",
+      configureServer(server) {
+        viteServer = server;
+        server.middlewares.use((0, import_core.createNodeMatchmakingMiddleware)());
+        server.middlewares.use((req, res, next) => {
+          if (!currentAppHandler) {
+            return next();
+          }
+          currentAppHandler(req, res, next);
+        });
+        return async () => {
+          if (!server.httpServer) {
+            throw new Error("[colyseus] Vite HTTP server not available.");
+          }
+          await loadServerModule();
+          console.log("[colyseus] Server ready on Vite's HTTP server");
+        };
+      }
+    },
+    {
+      name: "colyseus:hmr",
+      hotUpdate({ file, modules }) {
+        if (this.environment?.name === "colyseus" && modules.length > 0) {
+          loadServerModule().then(() => {
+            if (!options.quiet) {
+              console.log(`[colyseus] Server code reloaded (${file})`);
+            }
+          }).catch((e) => {
+            console.error("[colyseus] Failed to reload server module:", e);
+          });
+        }
+      }
+    }
+  ];
+  async function loadServerModule() {
+    const env = viteServer.environments.colyseus;
+    if (!env) {
+      console.error("[colyseus] Environment not found");
+      return;
+    }
+    try {
+      if (isStarted && env.runner.evaluatedModules) {
+        env.runner.evaluatedModules.clear();
+      }
+      if (!isStarted) {
+        (0, import_core.setDevMode)(true);
+        await matchMaker.setup();
+        const wsModule = await (options.loadWsTransport ? options.loadWsTransport() : (0, import_core.dynamicImport)("@colyseus/ws-transport"));
+        const transport = new wsModule.WebSocketTransport({ noServer: true });
+        if (typeof transport.attachToServer !== "function") {
+          throw new Error("[colyseus] Vite dev mode requires a transport with attachToServer().");
+        }
+        transport.attachToServer(viteServer.httpServer, {
+          filter(req) {
+            return /^\/[a-zA-Z0-9_-]+\/[a-zA-Z0-9_-]+\/?$/.test(
+              new URL(req.url || "", "http://localhost").pathname
+            );
+          }
+        });
+        (0, import_Transport.setTransport)(transport);
+      }
+      const mod = await env.runner.import(options.serverEntry);
+      const config = getServerExport(mod);
+      const rooms = getRoomsExport(mod) || config?.["~rooms"];
+      const router = config?.router;
+      if (!expressApp && config?.options?.express) {
+        try {
+          const express = (await (0, import_core.dynamicImport)("express")).default;
+          expressApp = express();
+          config.options.express(expressApp);
+        } catch (e) {
+          console.warn("[colyseus] Express not available. Install express to use the express option.");
+        }
+      }
+      if (router || expressApp) {
+        const routerHandler = router ? (0, import_core.toNodeHandler)(router.handler) : null;
+        currentAppHandler = (req, res, next) => {
+          if (router?.findRoute(req.method, req.url?.split("?")[0]) !== void 0) {
+            routerHandler(req, res);
+          } else if (expressApp) {
+            expressApp(req, res, next);
+          } else {
+            next();
+          }
+        };
+      } else {
+        currentAppHandler = null;
+      }
+      (0, import_core.unregisterRoomDefinitions)(currentRoomNames);
+      if (rooms) {
+        currentRoomNames = (0, import_core.registerRoomDefinitions)(rooms);
+      } else {
+        currentRoomNames = [];
+        console.warn(
+          "[colyseus] Server entry should export `server = defineServer(...)` or `rooms`."
+        );
+      }
+      if (!isStarted) {
+        await matchMaker.accept();
+        isStarted = true;
+      } else {
+        await matchMaker.hotReload();
+      }
+      if (!options.quiet) {
+        for (const roomName of currentRoomNames) {
+          console.log(`[colyseus] Room defined: "${roomName}"`);
+        }
+      }
+    } catch (e) {
+      console.error("[colyseus] Failed to load server module:", e);
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  colyseus,
+  createColyseusViteServerEntry,
+  reloadColyseusViteRooms
+});

package/build/vite.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/vite.ts"],
+  "sourcesContent": ["/**\n * Colyseus Vite Plugin\n *\n * Integrates a Colyseus game server into Vite's dev server and build pipeline.\n *\n * ## Architecture\n *\n * Colyseus packages are externalized in the runner environment so they share\n * the same module instances \u2014 and therefore the same matchMaker singleton \u2014\n * as the plugin process. This lets user code (monitor, playground, custom\n * middleware) access the real matchMaker with actual room data.\n *\n * In dev mode, defineServer() returns a config-only object (no Server\n * instance). The plugin manages the matchMaker lifecycle, transport, and\n * HMR directly.\n *\n * On HMR:\n * 1. Re-import user module (defineServer returns fresh config)\n * 2. Swap router handler + re-register room definitions\n * 3. matchMaker.hotReload() \u2014 cache rooms, dispose, restore\n */\nimport * as matchMaker from '@colyseus/core/MatchMaker';\nimport {\n  setDevMode,\n  createNodeMatchmakingMiddleware,\n  dynamicImport,\n  registerRoomDefinitions,\n  unregisterRoomDefinitions,\n  toNodeHandler,\n  type RoomDefinitions,\n  type ServerOptions,\n  type Transport,\n  type Router,\n} from '@colyseus/core';\nimport { setTransport } from '@colyseus/core/Transport';\nimport type { Plugin } from 'vite';\n\n// \u2500\u2500\u2500 Virtual module IDs \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nconst VIRTUAL_SERVER_ENTRY = 'virtual:colyseus-server-entry';\nconst RESOLVED_VIRTUAL_SERVER_ENTRY = '\\0' + VIRTUAL_SERVER_ENTRY;\n\n// \u2500\u2500\u2500 Options \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface ColyseusViteOptions {\n  serverEntry: string;\n  port?: number;\n  quiet?: boolean;\n  /**\n   * Serve the built client files via express.static() in the production\n   * server entry. Adds a SPA fallback that serves index.html for\n   * unmatched GET requests.\n   *\n   * Has no effect in dev mode (Vite serves the frontend).\n   */\n  serveClient?: boolean;\n  loadWsTransport?: () => Promise<{\n    WebSocketTransport: new (options?: any) => Transport & {\n      attachToServer(server: any, options?: { filter?: (req: any) => boolean }): any;\n    };\n  }>;\n}\n\n// \u2500\u2500\u2500 Internal types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\ntype ServerConfig = {\n  options?: ServerOptions;\n  router?: Router;\n  '~rooms'?: RoomDefinitions;\n};\n\ntype ServerModule = {\n  server?: ServerConfig;\n  rooms?: RoomDefinitions;\n  default?: {\n    server?: ServerConfig;\n    rooms?: RoomDefinitions;\n  };\n};\n\n// \u2500\u2500\u2500 Helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nfunction getServerExport(mod: ServerModule): ServerConfig | undefined {\n  return mod.server || mod.default?.server;\n}\n\nfunction getRoomsExport(mod: ServerModule): RoomDefinitions | undefined {\n  return mod.rooms || mod.default?.rooms;\n}\n\n// \u2500\u2500\u2500 Virtual module generators \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Production build entry \u2014 standalone server that imports the user's\n * server entry and calls `server.listen()`.\n */\nexport function createColyseusViteServerEntry(options: ColyseusViteOptions) {\n  const port = options.port ?? 2567;\n\n  const lines: string[] = [\n    `import { Server, registerRoomDefinitions } from \"colyseus\";`,\n  ];\n\n  if (options.serveClient) {\n    lines.push(\n      `import express from \"express\";`,\n      `import { fileURLToPath } from \"url\";`,\n      `import { dirname, join } from \"path\";`,\n      ``,\n      `const __dirname = dirname(fileURLToPath(import.meta.url));`,\n      `const clientDir = join(__dirname, \"../client\");`,\n    );\n  }\n\n  lines.push(\n    ``,\n    `const entry = await import(${JSON.stringify(options.serverEntry)});`,\n    `const server = entry.server ?? entry.default?.server;`,\n    `const rooms = entry.rooms ?? entry.default?.rooms;`,\n    ``,\n    `if (server) {`,\n  );\n\n  if (options.serveClient) {\n    lines.push(\n      `  await server[\"_onTransportReady\"];`,\n      `  if (server.transport.getExpressApp) {`,\n      `    const app = server.transport.getExpressApp();`,\n      `    app.use(express.static(clientDir));`,\n      `    app.get(\"*all\", (req, res) => res.sendFile(join(clientDir, \"index.html\")));`,\n      `  }`,\n    );\n  }\n\n  lines.push(\n    `  server.listen(${port});`,\n    `} else if (rooms) {`,\n    `  const gameServer = new Server();`,\n    `  registerRoomDefinitions(rooms);`,\n    `  gameServer.listen(${port});`,\n    `} else {`,\n    `  throw new Error('[colyseus] Server entry should export \\`server = defineServer(...)\\` or \\`rooms\\`.');`,\n    `}`,\n  );\n\n  return lines.join('\\n');\n}\n\n// \u2500\u2500\u2500 Exported helpers (for testing) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport async function reloadColyseusViteRooms(\n  importModule: (specifier: string) => Promise<any>,\n  serverEntry: string,\n  currentRoomNames: string[] = [],\n) {\n  const mod = await importModule(serverEntry);\n\n  unregisterRoomDefinitions(currentRoomNames);\n\n  const server = getServerExport(mod);\n  const rooms: RoomDefinitions | undefined = getRoomsExport(mod)\n    || server?.['~rooms'];\n\n  if (!rooms) {\n    return {\n      roomNames: [],\n      hasRooms: false,\n      server,\n    };\n  }\n\n  return {\n    roomNames: registerRoomDefinitions(rooms),\n    hasRooms: true,\n    server,\n  };\n}\n\n// \u2500\u2500\u2500 Plugin \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function colyseus(options: ColyseusViteOptions): Plugin[] {\n  let viteServer: any;\n  let currentRoomNames: string[] = [];\n  let currentAppHandler: ((req: any, res: any, next: any) => void) | null = null;\n  let expressApp: any = null;\n  let isStarted = false;\n\n  return [\n    {\n      name: 'colyseus:config',\n      config() {\n        return {\n          builder: {},\n          build: { outDir: 'dist/client' },\n          environments: {\n            colyseus: {\n              consumer: 'server' as const,\n              resolve: {\n                // Externalize all dependencies so they share the same module\n                // instances (and matchMaker singleton) with the plugin process.\n                // Without this, Vite re-evaluates workspace/linked packages in\n                // the runner, creating isolated singletons \u2014 breaking monitor, etc.\n                external: true,\n              },\n              build: {\n                outDir: 'dist/server',\n                ssr: true,\n                rollupOptions: {\n                  input: VIRTUAL_SERVER_ENTRY,\n                  output: { entryFileNames: 'server.mjs' },\n                },\n              },\n            },\n          },\n        };\n      },\n      resolveId(id: string) {\n        if (id === VIRTUAL_SERVER_ENTRY) { return RESOLVED_VIRTUAL_SERVER_ENTRY; }\n      },\n      load(id: string) {\n        if (id === RESOLVED_VIRTUAL_SERVER_ENTRY) {\n          return createColyseusViteServerEntry(options);\n        }\n      },\n    },\n\n    {\n      name: 'colyseus:dev-server',\n      configureServer(server: any) {\n        viteServer = server;\n        server.middlewares.use(createNodeMatchmakingMiddleware());\n\n        // Dynamic application middleware \u2014 handler is swapped on each HMR reload.\n        server.middlewares.use((req: any, res: any, next: any) => {\n          if (!currentAppHandler) { return next(); }\n          currentAppHandler(req, res, next);\n        });\n\n        return async () => {\n          if (!server.httpServer) {\n            throw new Error('[colyseus] Vite HTTP server not available.');\n          }\n          await loadServerModule();\n          console.log(\"[colyseus] Server ready on Vite's HTTP server\");\n        };\n      },\n    },\n\n    {\n      name: 'colyseus:hmr',\n      hotUpdate({ file, modules }) {\n        if (this.environment?.name === 'colyseus' && modules.length > 0) {\n          loadServerModule().then(() => {\n            if (!options.quiet) {\n              console.log(`[colyseus] Server code reloaded (${file})`);\n            }\n          }).catch((e) => {\n            console.error('[colyseus] Failed to reload server module:', e);\n          });\n        }\n      },\n    },\n  ];\n\n  /**\n   * Import (or re-import) the user's server entry and configure the\n   * matchMaker, transport, rooms, and middleware.\n   *\n   * On initial load: sets up matchMaker, creates transport, registers rooms.\n   * On HMR reload: re-imports user code, swaps rooms/router, hot-reloads\n   * running rooms (cache \u2192 dispose \u2192 restore).\n   */\n  async function loadServerModule() {\n    const env = viteServer.environments.colyseus;\n    if (!env) {\n      console.error('[colyseus] Environment not found');\n      return;\n    }\n\n    try {\n      // Clear the runner's evaluated module cache so re-import picks up\n      // fresh user code. External packages (@colyseus/*) are cached by\n      // Node's module system \u2014 they keep their singleton state.\n      if (isStarted && env.runner.evaluatedModules) {\n        env.runner.evaluatedModules.clear();\n      }\n\n      // \u2500\u2500 Step 1: Set up matchMaker + transport (initial load only) \u2500\u2500\n      if (!isStarted) {\n        setDevMode(true);\n        await matchMaker.setup();\n\n        const wsModule = await (options.loadWsTransport\n          ? options.loadWsTransport()\n          : dynamicImport<typeof import('@colyseus/ws-transport')>('@colyseus/ws-transport'));\n\n        const transport = new wsModule.WebSocketTransport({ noServer: true });\n\n        if (typeof (transport as any).attachToServer !== 'function') {\n          throw new Error('[colyseus] Vite dev mode requires a transport with attachToServer().');\n        }\n\n        (transport as any).attachToServer(viteServer.httpServer, {\n          filter(req: any) {\n            return /^\\/[a-zA-Z0-9_-]+\\/[a-zA-Z0-9_-]+\\/?$/.test(\n              new URL(req.url || '', 'http://localhost').pathname,\n            );\n          },\n        });\n        setTransport(transport);\n      }\n\n      // \u2500\u2500 Step 2: Import user module \u2500\u2500\n      // In dev mode, defineServer() returns a config object (no Server\n      // instance, no matchMaker.setup() call) because isDevMode is true.\n      const mod = await env.runner.import(options.serverEntry);\n\n      const config = getServerExport(mod);\n      const rooms: RoomDefinitions | undefined = getRoomsExport(mod)\n        || config?.['~rooms'];\n\n      // \u2500\u2500 Step 3: Build application middleware (router + express) \u2500\u2500\n      const router = config?.router;\n\n      // Set up express once \u2014 persistent across HMR reloads.\n      if (!expressApp && config?.options?.express) {\n        try {\n          const express = (await dynamicImport<any>('express')).default;\n          expressApp = express();\n          config.options.express(expressApp);\n        } catch (e) {\n          console.warn('[colyseus] Express not available. Install express to use the express option.');\n        }\n      }\n\n      // Build combined handler: router (hot-swappable) + express (persistent).\n      if (router || expressApp) {\n        const routerHandler = router ? toNodeHandler(router.handler) : null;\n        currentAppHandler = (req: any, res: any, next: any) => {\n          if (router?.findRoute(req.method, req.url?.split('?')[0]) !== undefined) {\n            routerHandler!(req, res);\n          } else if (expressApp) {\n            expressApp(req, res, next);\n          } else {\n            next();\n          }\n        };\n      } else {\n        currentAppHandler = null;\n      }\n\n      // \u2500\u2500 Step 4: Register room definitions \u2500\u2500\n      // Must happen BEFORE hotReload() because reloadFromCache() needs\n      // the new handlers to recreate room instances.\n      unregisterRoomDefinitions(currentRoomNames);\n      if (rooms) {\n        currentRoomNames = registerRoomDefinitions(rooms);\n      } else {\n        currentRoomNames = [];\n        console.warn(\n          '[colyseus] Server entry should export `server = defineServer(...)` or `rooms`.',\n        );\n      }\n\n      // \u2500\u2500 Step 5: Accept connections or hot-reload rooms \u2500\u2500\n      if (!isStarted) {\n        await matchMaker.accept();\n        isStarted = true;\n      } else {\n        await matchMaker.hotReload();\n      }\n\n      if (!options.quiet) {\n        for (const roomName of currentRoomNames) {\n          console.log(`[colyseus] Room defined: \"${roomName}\"`);\n        }\n      }\n\n    } catch (e) {\n      console.error('[colyseus] Failed to load server module:', e);\n    }\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/build/vite.d.ts

@@ -0,0 +1,39 @@
+import { type RoomDefinitions, type ServerOptions, type Transport, type Router } from '@colyseus/core';
+import type { Plugin } from 'vite';
+export interface ColyseusViteOptions {
+    serverEntry: string;
+    port?: number;
+    quiet?: boolean;
+    /**
+     * Serve the built client files via express.static() in the production
+     * server entry. Adds a SPA fallback that serves index.html for
+     * unmatched GET requests.
+     *
+     * Has no effect in dev mode (Vite serves the frontend).
+     */
+    serveClient?: boolean;
+    loadWsTransport?: () => Promise<{
+        WebSocketTransport: new (options?: any) => Transport & {
+            attachToServer(server: any, options?: {
+                filter?: (req: any) => boolean;
+            }): any;
+        };
+    }>;
+}
+type ServerConfig = {
+    options?: ServerOptions;
+    router?: Router;
+    '~rooms'?: RoomDefinitions;
+};
+/**
+ * Production build entry — standalone server that imports the user's
+ * server entry and calls `server.listen()`.
+ */
+export declare function createColyseusViteServerEntry(options: ColyseusViteOptions): string;
+export declare function reloadColyseusViteRooms(importModule: (specifier: string) => Promise<any>, serverEntry: string, currentRoomNames?: string[]): Promise<{
+    roomNames: string[];
+    hasRooms: boolean;
+    server: ServerConfig;
+}>;
+export declare function colyseus(options: ColyseusViteOptions): Plugin[];
+export {};

package/build/vite.mjs

@@ -0,0 +1,247 @@
+// bundles/colyseus/src/vite.ts
+import * as matchMaker from "@colyseus/core/MatchMaker";
+import {
+  setDevMode,
+  createNodeMatchmakingMiddleware,
+  dynamicImport,
+  registerRoomDefinitions,
+  unregisterRoomDefinitions,
+  toNodeHandler
+} from "@colyseus/core";
+import { setTransport } from "@colyseus/core/Transport";
+var VIRTUAL_SERVER_ENTRY = "virtual:colyseus-server-entry";
+var RESOLVED_VIRTUAL_SERVER_ENTRY = "\0" + VIRTUAL_SERVER_ENTRY;
+function getServerExport(mod) {
+  return mod.server || mod.default?.server;
+}
+function getRoomsExport(mod) {
+  return mod.rooms || mod.default?.rooms;
+}
+function createColyseusViteServerEntry(options) {
+  const port = options.port ?? 2567;
+  const lines = [
+    `import { Server, registerRoomDefinitions } from "colyseus";`
+  ];
+  if (options.serveClient) {
+    lines.push(
+      `import express from "express";`,
+      `import { fileURLToPath } from "url";`,
+      `import { dirname, join } from "path";`,
+      ``,
+      `const __dirname = dirname(fileURLToPath(import.meta.url));`,
+      `const clientDir = join(__dirname, "../client");`
+    );
+  }
+  lines.push(
+    ``,
+    `const entry = await import(${JSON.stringify(options.serverEntry)});`,
+    `const server = entry.server ?? entry.default?.server;`,
+    `const rooms = entry.rooms ?? entry.default?.rooms;`,
+    ``,
+    `if (server) {`
+  );
+  if (options.serveClient) {
+    lines.push(
+      `  await server["_onTransportReady"];`,
+      `  if (server.transport.getExpressApp) {`,
+      `    const app = server.transport.getExpressApp();`,
+      `    app.use(express.static(clientDir));`,
+      `    app.get("*all", (req, res) => res.sendFile(join(clientDir, "index.html")));`,
+      `  }`
+    );
+  }
+  lines.push(
+    `  server.listen(${port});`,
+    `} else if (rooms) {`,
+    `  const gameServer = new Server();`,
+    `  registerRoomDefinitions(rooms);`,
+    `  gameServer.listen(${port});`,
+    `} else {`,
+    `  throw new Error('[colyseus] Server entry should export \`server = defineServer(...)\` or \`rooms\`.');`,
+    `}`
+  );
+  return lines.join("\n");
+}
+async function reloadColyseusViteRooms(importModule, serverEntry, currentRoomNames = []) {
+  const mod = await importModule(serverEntry);
+  unregisterRoomDefinitions(currentRoomNames);
+  const server = getServerExport(mod);
+  const rooms = getRoomsExport(mod) || server?.["~rooms"];
+  if (!rooms) {
+    return {
+      roomNames: [],
+      hasRooms: false,
+      server
+    };
+  }
+  return {
+    roomNames: registerRoomDefinitions(rooms),
+    hasRooms: true,
+    server
+  };
+}
+function colyseus(options) {
+  let viteServer;
+  let currentRoomNames = [];
+  let currentAppHandler = null;
+  let expressApp = null;
+  let isStarted = false;
+  return [
+    {
+      name: "colyseus:config",
+      config() {
+        return {
+          builder: {},
+          build: { outDir: "dist/client" },
+          environments: {
+            colyseus: {
+              consumer: "server",
+              resolve: {
+                // Externalize all dependencies so they share the same module
+                // instances (and matchMaker singleton) with the plugin process.
+                // Without this, Vite re-evaluates workspace/linked packages in
+                // the runner, creating isolated singletons — breaking monitor, etc.
+                external: true
+              },
+              build: {
+                outDir: "dist/server",
+                ssr: true,
+                rollupOptions: {
+                  input: VIRTUAL_SERVER_ENTRY,
+                  output: { entryFileNames: "server.mjs" }
+                }
+              }
+            }
+          }
+        };
+      },
+      resolveId(id) {
+        if (id === VIRTUAL_SERVER_ENTRY) {
+          return RESOLVED_VIRTUAL_SERVER_ENTRY;
+        }
+      },
+      load(id) {
+        if (id === RESOLVED_VIRTUAL_SERVER_ENTRY) {
+          return createColyseusViteServerEntry(options);
+        }
+      }
+    },
+    {
+      name: "colyseus:dev-server",
+      configureServer(server) {
+        viteServer = server;
+        server.middlewares.use(createNodeMatchmakingMiddleware());
+        server.middlewares.use((req, res, next) => {
+          if (!currentAppHandler) {
+            return next();
+          }
+          currentAppHandler(req, res, next);
+        });
+        return async () => {
+          if (!server.httpServer) {
+            throw new Error("[colyseus] Vite HTTP server not available.");
+          }
+          await loadServerModule();
+          console.log("[colyseus] Server ready on Vite's HTTP server");
+        };
+      }
+    },
+    {
+      name: "colyseus:hmr",
+      hotUpdate({ file, modules }) {
+        if (this.environment?.name === "colyseus" && modules.length > 0) {
+          loadServerModule().then(() => {
+            if (!options.quiet) {
+              console.log(`[colyseus] Server code reloaded (${file})`);
+            }
+          }).catch((e) => {
+            console.error("[colyseus] Failed to reload server module:", e);
+          });
+        }
+      }
+    }
+  ];
+  async function loadServerModule() {
+    const env = viteServer.environments.colyseus;
+    if (!env) {
+      console.error("[colyseus] Environment not found");
+      return;
+    }
+    try {
+      if (isStarted && env.runner.evaluatedModules) {
+        env.runner.evaluatedModules.clear();
+      }
+      if (!isStarted) {
+        setDevMode(true);
+        await matchMaker.setup();
+        const wsModule = await (options.loadWsTransport ? options.loadWsTransport() : dynamicImport("@colyseus/ws-transport"));
+        const transport = new wsModule.WebSocketTransport({ noServer: true });
+        if (typeof transport.attachToServer !== "function") {
+          throw new Error("[colyseus] Vite dev mode requires a transport with attachToServer().");
+        }
+        transport.attachToServer(viteServer.httpServer, {
+          filter(req) {
+            return /^\/[a-zA-Z0-9_-]+\/[a-zA-Z0-9_-]+\/?$/.test(
+              new URL(req.url || "", "http://localhost").pathname
+            );
+          }
+        });
+        setTransport(transport);
+      }
+      const mod = await env.runner.import(options.serverEntry);
+      const config = getServerExport(mod);
+      const rooms = getRoomsExport(mod) || config?.["~rooms"];
+      const router = config?.router;
+      if (!expressApp && config?.options?.express) {
+        try {
+          const express = (await dynamicImport("express")).default;
+          expressApp = express();
+          config.options.express(expressApp);
+        } catch (e) {
+          console.warn("[colyseus] Express not available. Install express to use the express option.");
+        }
+      }
+      if (router || expressApp) {
+        const routerHandler = router ? toNodeHandler(router.handler) : null;
+        currentAppHandler = (req, res, next) => {
+          if (router?.findRoute(req.method, req.url?.split("?")[0]) !== void 0) {
+            routerHandler(req, res);
+          } else if (expressApp) {
+            expressApp(req, res, next);
+          } else {
+            next();
+          }
+        };
+      } else {
+        currentAppHandler = null;
+      }
+      unregisterRoomDefinitions(currentRoomNames);
+      if (rooms) {
+        currentRoomNames = registerRoomDefinitions(rooms);
+      } else {
+        currentRoomNames = [];
+        console.warn(
+          "[colyseus] Server entry should export `server = defineServer(...)` or `rooms`."
+        );
+      }
+      if (!isStarted) {
+        await matchMaker.accept();
+        isStarted = true;
+      } else {
+        await matchMaker.hotReload();
+      }
+      if (!options.quiet) {
+        for (const roomName of currentRoomNames) {
+          console.log(`[colyseus] Room defined: "${roomName}"`);
+        }
+      }
+    } catch (e) {
+      console.error("[colyseus] Failed to load server module:", e);
+    }
+  }
+}
+export {
+  colyseus,
+  createColyseusViteServerEntry,
+  reloadColyseusViteRooms
+};

package/build/vite.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/vite.ts"],
+  "sourcesContent": ["/**\n * Colyseus Vite Plugin\n *\n * Integrates a Colyseus game server into Vite's dev server and build pipeline.\n *\n * ## Architecture\n *\n * Colyseus packages are externalized in the runner environment so they share\n * the same module instances \u2014 and therefore the same matchMaker singleton \u2014\n * as the plugin process. This lets user code (monitor, playground, custom\n * middleware) access the real matchMaker with actual room data.\n *\n * In dev mode, defineServer() returns a config-only object (no Server\n * instance). The plugin manages the matchMaker lifecycle, transport, and\n * HMR directly.\n *\n * On HMR:\n * 1. Re-import user module (defineServer returns fresh config)\n * 2. Swap router handler + re-register room definitions\n * 3. matchMaker.hotReload() \u2014 cache rooms, dispose, restore\n */\nimport * as matchMaker from '@colyseus/core/MatchMaker';\nimport {\n  setDevMode,\n  createNodeMatchmakingMiddleware,\n  dynamicImport,\n  registerRoomDefinitions,\n  unregisterRoomDefinitions,\n  toNodeHandler,\n  type RoomDefinitions,\n  type ServerOptions,\n  type Transport,\n  type Router,\n} from '@colyseus/core';\nimport { setTransport } from '@colyseus/core/Transport';\nimport type { Plugin } from 'vite';\n\n// \u2500\u2500\u2500 Virtual module IDs \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nconst VIRTUAL_SERVER_ENTRY = 'virtual:colyseus-server-entry';\nconst RESOLVED_VIRTUAL_SERVER_ENTRY = '\\0' + VIRTUAL_SERVER_ENTRY;\n\n// \u2500\u2500\u2500 Options \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport interface ColyseusViteOptions {\n  serverEntry: string;\n  port?: number;\n  quiet?: boolean;\n  /**\n   * Serve the built client files via express.static() in the production\n   * server entry. Adds a SPA fallback that serves index.html for\n   * unmatched GET requests.\n   *\n   * Has no effect in dev mode (Vite serves the frontend).\n   */\n  serveClient?: boolean;\n  loadWsTransport?: () => Promise<{\n    WebSocketTransport: new (options?: any) => Transport & {\n      attachToServer(server: any, options?: { filter?: (req: any) => boolean }): any;\n    };\n  }>;\n}\n\n// \u2500\u2500\u2500 Internal types \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\ntype ServerConfig = {\n  options?: ServerOptions;\n  router?: Router;\n  '~rooms'?: RoomDefinitions;\n};\n\ntype ServerModule = {\n  server?: ServerConfig;\n  rooms?: RoomDefinitions;\n  default?: {\n    server?: ServerConfig;\n    rooms?: RoomDefinitions;\n  };\n};\n\n// \u2500\u2500\u2500 Helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nfunction getServerExport(mod: ServerModule): ServerConfig | undefined {\n  return mod.server || mod.default?.server;\n}\n\nfunction getRoomsExport(mod: ServerModule): RoomDefinitions | undefined {\n  return mod.rooms || mod.default?.rooms;\n}\n\n// \u2500\u2500\u2500 Virtual module generators \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Production build entry \u2014 standalone server that imports the user's\n * server entry and calls `server.listen()`.\n */\nexport function createColyseusViteServerEntry(options: ColyseusViteOptions) {\n  const port = options.port ?? 2567;\n\n  const lines: string[] = [\n    `import { Server, registerRoomDefinitions } from \"colyseus\";`,\n  ];\n\n  if (options.serveClient) {\n    lines.push(\n      `import express from \"express\";`,\n      `import { fileURLToPath } from \"url\";`,\n      `import { dirname, join } from \"path\";`,\n      ``,\n      `const __dirname = dirname(fileURLToPath(import.meta.url));`,\n      `const clientDir = join(__dirname, \"../client\");`,\n    );\n  }\n\n  lines.push(\n    ``,\n    `const entry = await import(${JSON.stringify(options.serverEntry)});`,\n    `const server = entry.server ?? entry.default?.server;`,\n    `const rooms = entry.rooms ?? entry.default?.rooms;`,\n    ``,\n    `if (server) {`,\n  );\n\n  if (options.serveClient) {\n    lines.push(\n      `  await server[\"_onTransportReady\"];`,\n      `  if (server.transport.getExpressApp) {`,\n      `    const app = server.transport.getExpressApp();`,\n      `    app.use(express.static(clientDir));`,\n      `    app.get(\"*all\", (req, res) => res.sendFile(join(clientDir, \"index.html\")));`,\n      `  }`,\n    );\n  }\n\n  lines.push(\n    `  server.listen(${port});`,\n    `} else if (rooms) {`,\n    `  const gameServer = new Server();`,\n    `  registerRoomDefinitions(rooms);`,\n    `  gameServer.listen(${port});`,\n    `} else {`,\n    `  throw new Error('[colyseus] Server entry should export \\`server = defineServer(...)\\` or \\`rooms\\`.');`,\n    `}`,\n  );\n\n  return lines.join('\\n');\n}\n\n// \u2500\u2500\u2500 Exported helpers (for testing) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport async function reloadColyseusViteRooms(\n  importModule: (specifier: string) => Promise<any>,\n  serverEntry: string,\n  currentRoomNames: string[] = [],\n) {\n  const mod = await importModule(serverEntry);\n\n  unregisterRoomDefinitions(currentRoomNames);\n\n  const server = getServerExport(mod);\n  const rooms: RoomDefinitions | undefined = getRoomsExport(mod)\n    || server?.['~rooms'];\n\n  if (!rooms) {\n    return {\n      roomNames: [],\n      hasRooms: false,\n      server,\n    };\n  }\n\n  return {\n    roomNames: registerRoomDefinitions(rooms),\n    hasRooms: true,\n    server,\n  };\n}\n\n// \u2500\u2500\u2500 Plugin \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nexport function colyseus(options: ColyseusViteOptions): Plugin[] {\n  let viteServer: any;\n  let currentRoomNames: string[] = [];\n  let currentAppHandler: ((req: any, res: any, next: any) => void) | null = null;\n  let expressApp: any = null;\n  let isStarted = false;\n\n  return [\n    {\n      name: 'colyseus:config',\n      config() {\n        return {\n          builder: {},\n          build: { outDir: 'dist/client' },\n          environments: {\n            colyseus: {\n              consumer: 'server' as const,\n              resolve: {\n                // Externalize all dependencies so they share the same module\n                // instances (and matchMaker singleton) with the plugin process.\n                // Without this, Vite re-evaluates workspace/linked packages in\n                // the runner, creating isolated singletons \u2014 breaking monitor, etc.\n                external: true,\n              },\n              build: {\n                outDir: 'dist/server',\n                ssr: true,\n                rollupOptions: {\n                  input: VIRTUAL_SERVER_ENTRY,\n                  output: { entryFileNames: 'server.mjs' },\n                },\n              },\n            },\n          },\n        };\n      },\n      resolveId(id: string) {\n        if (id === VIRTUAL_SERVER_ENTRY) { return RESOLVED_VIRTUAL_SERVER_ENTRY; }\n      },\n      load(id: string) {\n        if (id === RESOLVED_VIRTUAL_SERVER_ENTRY) {\n          return createColyseusViteServerEntry(options);\n        }\n      },\n    },\n\n    {\n      name: 'colyseus:dev-server',\n      configureServer(server: any) {\n        viteServer = server;\n        server.middlewares.use(createNodeMatchmakingMiddleware());\n\n        // Dynamic application middleware \u2014 handler is swapped on each HMR reload.\n        server.middlewares.use((req: any, res: any, next: any) => {\n          if (!currentAppHandler) { return next(); }\n          currentAppHandler(req, res, next);\n        });\n\n        return async () => {\n          if (!server.httpServer) {\n            throw new Error('[colyseus] Vite HTTP server not available.');\n          }\n          await loadServerModule();\n          console.log(\"[colyseus] Server ready on Vite's HTTP server\");\n        };\n      },\n    },\n\n    {\n      name: 'colyseus:hmr',\n      hotUpdate({ file, modules }) {\n        if (this.environment?.name === 'colyseus' && modules.length > 0) {\n          loadServerModule().then(() => {\n            if (!options.quiet) {\n              console.log(`[colyseus] Server code reloaded (${file})`);\n            }\n          }).catch((e) => {\n            console.error('[colyseus] Failed to reload server module:', e);\n          });\n        }\n      },\n    },\n  ];\n\n  /**\n   * Import (or re-import) the user's server entry and configure the\n   * matchMaker, transport, rooms, and middleware.\n   *\n   * On initial load: sets up matchMaker, creates transport, registers rooms.\n   * On HMR reload: re-imports user code, swaps rooms/router, hot-reloads\n   * running rooms (cache \u2192 dispose \u2192 restore).\n   */\n  async function loadServerModule() {\n    const env = viteServer.environments.colyseus;\n    if (!env) {\n      console.error('[colyseus] Environment not found');\n      return;\n    }\n\n    try {\n      // Clear the runner's evaluated module cache so re-import picks up\n      // fresh user code. External packages (@colyseus/*) are cached by\n      // Node's module system \u2014 they keep their singleton state.\n      if (isStarted && env.runner.evaluatedModules) {\n        env.runner.evaluatedModules.clear();\n      }\n\n      // \u2500\u2500 Step 1: Set up matchMaker + transport (initial load only) \u2500\u2500\n      if (!isStarted) {\n        setDevMode(true);\n        await matchMaker.setup();\n\n        const wsModule = await (options.loadWsTransport\n          ? options.loadWsTransport()\n          : dynamicImport<typeof import('@colyseus/ws-transport')>('@colyseus/ws-transport'));\n\n        const transport = new wsModule.WebSocketTransport({ noServer: true });\n\n        if (typeof (transport as any).attachToServer !== 'function') {\n          throw new Error('[colyseus] Vite dev mode requires a transport with attachToServer().');\n        }\n\n        (transport as any).attachToServer(viteServer.httpServer, {\n          filter(req: any) {\n            return /^\\/[a-zA-Z0-9_-]+\\/[a-zA-Z0-9_-]+\\/?$/.test(\n              new URL(req.url || '', 'http://localhost').pathname,\n            );\n          },\n        });\n        setTransport(transport);\n      }\n\n      // \u2500\u2500 Step 2: Import user module \u2500\u2500\n      // In dev mode, defineServer() returns a config object (no Server\n      // instance, no matchMaker.setup() call) because isDevMode is true.\n      const mod = await env.runner.import(options.serverEntry);\n\n      const config = getServerExport(mod);\n      const rooms: RoomDefinitions | undefined = getRoomsExport(mod)\n        || config?.['~rooms'];\n\n      // \u2500\u2500 Step 3: Build application middleware (router + express) \u2500\u2500\n      const router = config?.router;\n\n      // Set up express once \u2014 persistent across HMR reloads.\n      if (!expressApp && config?.options?.express) {\n        try {\n          const express = (await dynamicImport<any>('express')).default;\n          expressApp = express();\n          config.options.express(expressApp);\n        } catch (e) {\n          console.warn('[colyseus] Express not available. Install express to use the express option.');\n        }\n      }\n\n      // Build combined handler: router (hot-swappable) + express (persistent).\n      if (router || expressApp) {\n        const routerHandler = router ? toNodeHandler(router.handler) : null;\n        currentAppHandler = (req: any, res: any, next: any) => {\n          if (router?.findRoute(req.method, req.url?.split('?')[0]) !== undefined) {\n            routerHandler!(req, res);\n          } else if (expressApp) {\n            expressApp(req, res, next);\n          } else {\n            next();\n          }\n        };\n      } else {\n        currentAppHandler = null;\n      }\n\n      // \u2500\u2500 Step 4: Register room definitions \u2500\u2500\n      // Must happen BEFORE hotReload() because reloadFromCache() needs\n      // the new handlers to recreate room instances.\n      unregisterRoomDefinitions(currentRoomNames);\n      if (rooms) {\n        currentRoomNames = registerRoomDefinitions(rooms);\n      } else {\n        currentRoomNames = [];\n        console.warn(\n          '[colyseus] Server entry should export `server = defineServer(...)` or `rooms`.',\n        );\n      }\n\n      // \u2500\u2500 Step 5: Accept connections or hot-reload rooms \u2500\u2500\n      if (!isStarted) {\n        await matchMaker.accept();\n        isStarted = true;\n      } else {\n        await matchMaker.hotReload();\n      }\n\n      if (!options.quiet) {\n        for (const roomName of currentRoomNames) {\n          console.log(`[colyseus] Room defined: \"${roomName}\"`);\n        }\n      }\n\n    } catch (e) {\n      console.error('[colyseus] Failed to load server module:', e);\n    }\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "colyseus",
-  "version": "0.17.7",
+  "version": "0.17.9",
   "description": "Multiplayer Framework for Node.js",
   "type": "module",
   "input": "./src/index.ts",
@@ -12,6 +12,11 @@
       "types": "./build/index.d.ts",
       "import": "./build/index.mjs",
       "require": "./build/index.cjs"
+    },
+    "./vite": {
+      "types": "./build/vite.d.ts",
+      "import": "./build/vite.mjs",
+      "require": "./build/vite.cjs"
     }
   },
   "author": "Endel Dreyer",
@@ -37,36 +42,43 @@
     "node": ">= 20.x"
   },
   "dependencies": {
-    "@colyseus/core": "^0.17.18",
-    "@colyseus/auth": "^0.17.5",
-    "@colyseus/playground": "^0.17.7",
-    "@colyseus/tools": "^0.17.15",
-    "@colyseus/monitor": "^0.17.6",
-    "@colyseus/ws-transport": "^0.17.7",
-    "@colyseus/redis-driver": "^0.17.5",
-    "@colyseus/redis-presence": "^0.17.5"
+    "@colyseus/monitor": "^0.17.8",
+    "@colyseus/core": "^0.17.41",
+    "@colyseus/playground": "^0.17.12",
+    "@colyseus/auth": "^0.17.9",
+    "@colyseus/redis-driver": "^0.17.7",
+    "@colyseus/redis-presence": "^0.17.7",
+    "@colyseus/ws-transport": "^0.17.13",
+    "@colyseus/tools": "^0.17.19"
   },
   "devDependencies": {
     "@colyseus/msgpackr": "*",
-    "@colyseus/schema": "^4.0.4",
+    "@colyseus/schema": "^4.0.7",
     "@types/ws": "^8.5.14",
+    "ioredis": "^5.9.3",
     "ws": "^8.18.0",
     "zod": "^4.1.12",
-    "@colyseus/core": "^0.17.18",
-    "@colyseus/sdk": "^0.17.20",
-    "@colyseus/better-call": "^1.2.0",
-    "@colyseus/tools": "^0.17.15",
-    "@colyseus/uwebsockets-transport": "^0.17.8",
-    "@colyseus/drizzle-driver": "^0.17.6"
+    "@colyseus/better-call": "^1.3.1",
+    "@colyseus/drizzle-driver": "^0.17.7",
+    "@colyseus/sdk": "^0.17.39",
+    "@colyseus/tools": "^0.17.19",
+    "@colyseus/core": "^0.17.41",
+    "@colyseus/uwebsockets-transport": "^0.17.20"
   },
   "peerDependencies": {
     "@colyseus/auth": "0.17.x",
     "@colyseus/core": "0.17.x",
     "@colyseus/redis-driver": "0.17.x",
     "@colyseus/redis-presence": "0.17.x",
-    "@colyseus/schema": "^4.0.4",
+    "@colyseus/schema": "^4.0.7",
     "@colyseus/uwebsockets-transport": "0.17.x",
-    "@colyseus/ws-transport": "0.17.x"
+    "@colyseus/ws-transport": "0.17.x",
+    "vite": ">=6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
   },
   "gitHead": "25ba61e283429bb4fa02db0454f804ea218259eb",
   "scripts": {

package/src/vite.ts

@@ -0,0 +1,383 @@
+/**
+ * Colyseus Vite Plugin
+ *
+ * Integrates a Colyseus game server into Vite's dev server and build pipeline.
+ *
+ * ## Architecture
+ *
+ * Colyseus packages are externalized in the runner environment so they share
+ * the same module instances — and therefore the same matchMaker singleton —
+ * as the plugin process. This lets user code (monitor, playground, custom
+ * middleware) access the real matchMaker with actual room data.
+ *
+ * In dev mode, defineServer() returns a config-only object (no Server
+ * instance). The plugin manages the matchMaker lifecycle, transport, and
+ * HMR directly.
+ *
+ * On HMR:
+ * 1. Re-import user module (defineServer returns fresh config)
+ * 2. Swap router handler + re-register room definitions
+ * 3. matchMaker.hotReload() — cache rooms, dispose, restore
+ */
+import * as matchMaker from '@colyseus/core/MatchMaker';
+import {
+  setDevMode,
+  createNodeMatchmakingMiddleware,
+  dynamicImport,
+  registerRoomDefinitions,
+  unregisterRoomDefinitions,
+  toNodeHandler,
+  type RoomDefinitions,
+  type ServerOptions,
+  type Transport,
+  type Router,
+} from '@colyseus/core';
+import { setTransport } from '@colyseus/core/Transport';
+import type { Plugin } from 'vite';
+
+// ─── Virtual module IDs ───────────────────────────────────────────────
+
+const VIRTUAL_SERVER_ENTRY = 'virtual:colyseus-server-entry';
+const RESOLVED_VIRTUAL_SERVER_ENTRY = '\0' + VIRTUAL_SERVER_ENTRY;
+
+// ─── Options ──────────────────────────────────────────────────────────
+
+export interface ColyseusViteOptions {
+  serverEntry: string;
+  port?: number;
+  quiet?: boolean;
+  /**
+   * Serve the built client files via express.static() in the production
+   * server entry. Adds a SPA fallback that serves index.html for
+   * unmatched GET requests.
+   *
+   * Has no effect in dev mode (Vite serves the frontend).
+   */
+  serveClient?: boolean;
+  loadWsTransport?: () => Promise<{
+    WebSocketTransport: new (options?: any) => Transport & {
+      attachToServer(server: any, options?: { filter?: (req: any) => boolean }): any;
+    };
+  }>;
+}
+
+// ─── Internal types ───────────────────────────────────────────────────
+
+type ServerConfig = {
+  options?: ServerOptions;
+  router?: Router;
+  '~rooms'?: RoomDefinitions;
+};
+
+type ServerModule = {
+  server?: ServerConfig;
+  rooms?: RoomDefinitions;
+  default?: {
+    server?: ServerConfig;
+    rooms?: RoomDefinitions;
+  };
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────────
+
+function getServerExport(mod: ServerModule): ServerConfig | undefined {
+  return mod.server || mod.default?.server;
+}
+
+function getRoomsExport(mod: ServerModule): RoomDefinitions | undefined {
+  return mod.rooms || mod.default?.rooms;
+}
+
+// ─── Virtual module generators ────────────────────────────────────────
+
+/**
+ * Production build entry — standalone server that imports the user's
+ * server entry and calls `server.listen()`.
+ */
+export function createColyseusViteServerEntry(options: ColyseusViteOptions) {
+  const port = options.port ?? 2567;
+
+  const lines: string[] = [
+    `import { Server, registerRoomDefinitions } from "colyseus";`,
+  ];
+
+  if (options.serveClient) {
+    lines.push(
+      `import express from "express";`,
+      `import { fileURLToPath } from "url";`,
+      `import { dirname, join } from "path";`,
+      ``,
+      `const __dirname = dirname(fileURLToPath(import.meta.url));`,
+      `const clientDir = join(__dirname, "../client");`,
+    );
+  }
+
+  lines.push(
+    ``,
+    `const entry = await import(${JSON.stringify(options.serverEntry)});`,
+    `const server = entry.server ?? entry.default?.server;`,
+    `const rooms = entry.rooms ?? entry.default?.rooms;`,
+    ``,
+    `if (server) {`,
+  );
+
+  if (options.serveClient) {
+    lines.push(
+      `  await server["_onTransportReady"];`,
+      `  if (server.transport.getExpressApp) {`,
+      `    const app = server.transport.getExpressApp();`,
+      `    app.use(express.static(clientDir));`,
+      `    app.get("*all", (req, res) => res.sendFile(join(clientDir, "index.html")));`,
+      `  }`,
+    );
+  }
+
+  lines.push(
+    `  server.listen(${port});`,
+    `} else if (rooms) {`,
+    `  const gameServer = new Server();`,
+    `  registerRoomDefinitions(rooms);`,
+    `  gameServer.listen(${port});`,
+    `} else {`,
+    `  throw new Error('[colyseus] Server entry should export \`server = defineServer(...)\` or \`rooms\`.');`,
+    `}`,
+  );
+
+  return lines.join('\n');
+}
+
+// ─── Exported helpers (for testing) ───────────────────────────────────
+
+export async function reloadColyseusViteRooms(
+  importModule: (specifier: string) => Promise<any>,
+  serverEntry: string,
+  currentRoomNames: string[] = [],
+) {
+  const mod = await importModule(serverEntry);
+
+  unregisterRoomDefinitions(currentRoomNames);
+
+  const server = getServerExport(mod);
+  const rooms: RoomDefinitions | undefined = getRoomsExport(mod)
+    || server?.['~rooms'];
+
+  if (!rooms) {
+    return {
+      roomNames: [],
+      hasRooms: false,
+      server,
+    };
+  }
+
+  return {
+    roomNames: registerRoomDefinitions(rooms),
+    hasRooms: true,
+    server,
+  };
+}
+
+// ─── Plugin ───────────────────────────────────────────────────────────
+
+export function colyseus(options: ColyseusViteOptions): Plugin[] {
+  let viteServer: any;
+  let currentRoomNames: string[] = [];
+  let currentAppHandler: ((req: any, res: any, next: any) => void) | null = null;
+  let expressApp: any = null;
+  let isStarted = false;
+
+  return [
+    {
+      name: 'colyseus:config',
+      config() {
+        return {
+          builder: {},
+          build: { outDir: 'dist/client' },
+          environments: {
+            colyseus: {
+              consumer: 'server' as const,
+              resolve: {
+                // Externalize all dependencies so they share the same module
+                // instances (and matchMaker singleton) with the plugin process.
+                // Without this, Vite re-evaluates workspace/linked packages in
+                // the runner, creating isolated singletons — breaking monitor, etc.
+                external: true,
+              },
+              build: {
+                outDir: 'dist/server',
+                ssr: true,
+                rollupOptions: {
+                  input: VIRTUAL_SERVER_ENTRY,
+                  output: { entryFileNames: 'server.mjs' },
+                },
+              },
+            },
+          },
+        };
+      },
+      resolveId(id: string) {
+        if (id === VIRTUAL_SERVER_ENTRY) { return RESOLVED_VIRTUAL_SERVER_ENTRY; }
+      },
+      load(id: string) {
+        if (id === RESOLVED_VIRTUAL_SERVER_ENTRY) {
+          return createColyseusViteServerEntry(options);
+        }
+      },
+    },
+
+    {
+      name: 'colyseus:dev-server',
+      configureServer(server: any) {
+        viteServer = server;
+        server.middlewares.use(createNodeMatchmakingMiddleware());
+
+        // Dynamic application middleware — handler is swapped on each HMR reload.
+        server.middlewares.use((req: any, res: any, next: any) => {
+          if (!currentAppHandler) { return next(); }
+          currentAppHandler(req, res, next);
+        });
+
+        return async () => {
+          if (!server.httpServer) {
+            throw new Error('[colyseus] Vite HTTP server not available.');
+          }
+          await loadServerModule();
+          console.log("[colyseus] Server ready on Vite's HTTP server");
+        };
+      },
+    },
+
+    {
+      name: 'colyseus:hmr',
+      hotUpdate({ file, modules }) {
+        if (this.environment?.name === 'colyseus' && modules.length > 0) {
+          loadServerModule().then(() => {
+            if (!options.quiet) {
+              console.log(`[colyseus] Server code reloaded (${file})`);
+            }
+          }).catch((e) => {
+            console.error('[colyseus] Failed to reload server module:', e);
+          });
+        }
+      },
+    },
+  ];
+
+  /**
+   * Import (or re-import) the user's server entry and configure the
+   * matchMaker, transport, rooms, and middleware.
+   *
+   * On initial load: sets up matchMaker, creates transport, registers rooms.
+   * On HMR reload: re-imports user code, swaps rooms/router, hot-reloads
+   * running rooms (cache → dispose → restore).
+   */
+  async function loadServerModule() {
+    const env = viteServer.environments.colyseus;
+    if (!env) {
+      console.error('[colyseus] Environment not found');
+      return;
+    }
+
+    try {
+      // Clear the runner's evaluated module cache so re-import picks up
+      // fresh user code. External packages (@colyseus/*) are cached by
+      // Node's module system — they keep their singleton state.
+      if (isStarted && env.runner.evaluatedModules) {
+        env.runner.evaluatedModules.clear();
+      }
+
+      // ── Step 1: Set up matchMaker + transport (initial load only) ──
+      if (!isStarted) {
+        setDevMode(true);
+        await matchMaker.setup();
+
+        const wsModule = await (options.loadWsTransport
+          ? options.loadWsTransport()
+          : dynamicImport<typeof import('@colyseus/ws-transport')>('@colyseus/ws-transport'));
+
+        const transport = new wsModule.WebSocketTransport({ noServer: true });
+
+        if (typeof (transport as any).attachToServer !== 'function') {
+          throw new Error('[colyseus] Vite dev mode requires a transport with attachToServer().');
+        }
+
+        (transport as any).attachToServer(viteServer.httpServer, {
+          filter(req: any) {
+            return /^\/[a-zA-Z0-9_-]+\/[a-zA-Z0-9_-]+\/?$/.test(
+              new URL(req.url || '', 'http://localhost').pathname,
+            );
+          },
+        });
+        setTransport(transport);
+      }
+
+      // ── Step 2: Import user module ──
+      // In dev mode, defineServer() returns a config object (no Server
+      // instance, no matchMaker.setup() call) because isDevMode is true.
+      const mod = await env.runner.import(options.serverEntry);
+
+      const config = getServerExport(mod);
+      const rooms: RoomDefinitions | undefined = getRoomsExport(mod)
+        || config?.['~rooms'];
+
+      // ── Step 3: Build application middleware (router + express) ──
+      const router = config?.router;
+
+      // Set up express once — persistent across HMR reloads.
+      if (!expressApp && config?.options?.express) {
+        try {
+          const express = (await dynamicImport<any>('express')).default;
+          expressApp = express();
+          config.options.express(expressApp);
+        } catch (e) {
+          console.warn('[colyseus] Express not available. Install express to use the express option.');
+        }
+      }
+
+      // Build combined handler: router (hot-swappable) + express (persistent).
+      if (router || expressApp) {
+        const routerHandler = router ? toNodeHandler(router.handler) : null;
+        currentAppHandler = (req: any, res: any, next: any) => {
+          if (router?.findRoute(req.method, req.url?.split('?')[0]) !== undefined) {
+            routerHandler!(req, res);
+          } else if (expressApp) {
+            expressApp(req, res, next);
+          } else {
+            next();
+          }
+        };
+      } else {
+        currentAppHandler = null;
+      }
+
+      // ── Step 4: Register room definitions ──
+      // Must happen BEFORE hotReload() because reloadFromCache() needs
+      // the new handlers to recreate room instances.
+      unregisterRoomDefinitions(currentRoomNames);
+      if (rooms) {
+        currentRoomNames = registerRoomDefinitions(rooms);
+      } else {
+        currentRoomNames = [];
+        console.warn(
+          '[colyseus] Server entry should export `server = defineServer(...)` or `rooms`.',
+        );
+      }
+
+      // ── Step 5: Accept connections or hot-reload rooms ──
+      if (!isStarted) {
+        await matchMaker.accept();
+        isStarted = true;
+      } else {
+        await matchMaker.hotReload();
+      }
+
+      if (!options.quiet) {
+        for (const roomName of currentRoomNames) {
+          console.log(`[colyseus] Room defined: "${roomName}"`);
+        }
+      }
+
+    } catch (e) {
+      console.error('[colyseus] Failed to load server module:', e);
+    }
+  }
+}