colyseus 0.17.9 → 0.18.0

package/build/plugins/unique-session.d.ts

@@ -0,0 +1,174 @@
+/**
+ * UniqueSessionPlugin — enforces "one (or N) concurrent session(s) of
+ * this room type per user." Use to prevent a player from opening
+ * two tabs of the same game mode, or from re-queueing into another
+ * instance while their old session is still active.
+ *
+ * Usage:
+ *
+ *   import { UniqueSessionPlugin } from 'colyseus/plugins/unique-session';
+ *
+ *   class GameRoom extends Room {
+ *     plugins = definePlugins({
+ *       unique: new UniqueSessionPlugin({ max: 1, onDuplicate: 'reject' }),
+ *     });
+ *   }
+ *
+ * The plugin reads the per-user reverse index that
+ * `TrackUserSessionsPlugin` maintains in Presence. Same source the
+ * admin's by-user inspector and the `closeUserSessions` helper use —
+ * no new bookkeeping. (For a generic lookup from your own code,
+ * prefer `TrackUserSessionsPlugin.listUserSessions(userId)`.)
+ *
+ * Anonymous clients (no `userId`) are NEVER rejected: with no stable
+ * identity we have nothing to enforce against. Document this so
+ * apps that anonymously match-make don't expect a guarantee they
+ * can't get.
+ *
+ * Race window: two near-simultaneous joins from the same user can
+ * both pass the check before either has written to the hash
+ * (`trackRoomJoin` fires AFTER the plugin/room onJoin chain). For
+ * the singleton/two-tabs UX this is acceptable; if your game needs
+ * strict serialization, layer an atomic `hsetnx` reservation on
+ * top — out of scope for v1.
+ *
+ * Stale-entry handling: entries are reconciled two ways. Entries
+ * pointing at another room get dropped if `matchMaker.query` doesn't
+ * know that room anymore (crashed process). Entries pointing at THIS
+ * room get cross-checked against `this.room.clients` — if the
+ * sessionId isn't live locally, the entry is treated as stale (e.g.
+ * a fast disconnect that missed `onLeave`) and dropped, so a
+ * legitimate fresh join isn't blocked by ghost data.
+ *
+ * Auto-includes `TrackUserSessionsPlugin` via `static dependencies`
+ * so the per-user reverse index this plugin reads from is always
+ * populated — apps don't have to register the tracker plugin
+ * themselves.
+ */
+import { RoomPlugin, type Client, type Room, type IRoomCache, type PluginDependencies } from '@colyseus/core';
+import { type UserSessionInfo } from '@colyseus/core/internal';
+/**
+ * Per-existing-session context passed to the `conflictsWith`
+ * predicate. The full matchmaker `IRoomCache` (including `metadata`)
+ * is attached for cross-room entries — populated from the same
+ * batch lookup the plugin already runs, so no extra wire ops.
+ *
+ * For entries that point at the CURRENT room (same `Room` instance
+ * the plugin is attached to), `room` is `undefined` — read from
+ * the second arg (`currentRoom`) instead, which is the live `Room`.
+ */
+export interface UniqueSessionConflict {
+    /** The existing session's id. */
+    sessionId: string;
+    /** Unix ms timestamp recorded when the existing session joined. */
+    joinedAt: number;
+    /** Matchmaker's cached `IRoomCache` for the existing session's
+     *  room — `metadata`, `clients`, `locked`, etc. Undefined when the
+     *  existing session is in the same room instance as the joining
+     *  client; use `currentRoom` for that case. */
+    room?: IRoomCache;
+}
+export interface UniqueSessionOptions {
+    /**
+     * Max concurrent sessions of this room type per user. Default `1`
+     * (strict singleton). Setting `> 1` lets users open e.g. two tabs
+     * but not ten — useful for testing/spectating workflows.
+     */
+    max?: number;
+    /**
+     * Behavior when the limit is exceeded:
+     *  - `'reject'` (default): refuse the new join with a `ServerError`.
+     *  - `'replace'`: kick the oldest existing session(s) so the new
+     *    join can proceed. Useful for refresh-style UX where a player
+     *    expects their newer tab to "win".
+     */
+    onDuplicate?: 'reject' | 'replace';
+    /**
+     * Error code attached to the `ServerError` thrown on reject. The
+     * SDK surfaces this as `MatchMakeError.code`. Default `4400`
+     * (matches the 4xxx custom range Colyseus uses elsewhere).
+     */
+    rejectCode?: number;
+    /**
+     * Message attached to the `ServerError` thrown on reject. Default
+     * `'already_in_room'`. The SDK exposes it as `e.message` so the
+     * client can branch on it.
+     */
+    rejectMessage?: string;
+    /**
+     * Per-existing-session filter applied after the plugin's own
+     * same-`roomName` matching + stale-entry reconcile, but before
+     * counting against `max`. Return `true` to count the existing
+     * session as a conflict, `false` to skip it.
+     *
+     * Receives:
+     *  - `existing` — `{ sessionId, joinedAt, room? }`. The `room`
+     *    field is the matchmaker's cached `IRoomCache` for the
+     *    existing session's room (carrying `metadata`, `clients`,
+     *    `locked`, etc.), populated for cross-room entries from the
+     *    same batch lookup the plugin already runs. It is `undefined`
+     *    when the existing session is in the SAME `Room` instance as
+     *    the joining client — for those, read state from `currentRoom`.
+     *  - `currentRoom` — the live `Room` instance the join is targeting
+     *    (i.e. `this.room` inside the plugin).
+     *
+     * Use this for metadata-based scoping (e.g. "only count
+     * same-game-mode sessions"), per-process exemptions (multi-region
+     * deploys), capacity-aware filtering ("don't count rooms that are
+     * already full"), etc.
+     */
+    conflictsWith?: (existing: UniqueSessionConflict, currentRoom: Room) => boolean;
+    /**
+     * Extract the user's stable id from `Client`. Return a non-empty
+     * string when the client carries an identity; return `undefined`
+     * (or empty string) for anonymous clients — the plugin skips the
+     * check in that case.
+     *
+     * Default reads `client.auth.id`, then `client.auth.userId` — the
+     * JWT payload shape `@colyseus/auth`'s default `onAuth` produces
+     * for both authenticated AND anonymously-registered sessions
+     * (anonymous users from `registerAnonymous` get an `id` too;
+     * `anonymousId` is a separate upgrade-token field).
+     *
+     * Custom auth flows that store the id elsewhere (e.g.
+     * `client.auth.profile.sub` for raw OIDC) override with a
+     * function that returns from that path.
+     */
+    resolveUserId?: (client: Client) => string | undefined;
+}
+/**
+ * Result of evaluating the user's existing sessions. Extracted from
+ * the `onJoin` body so the unit tests can drive it in isolation.
+ */
+interface ConflictResult {
+    /** Entries that should count against the limit. */
+    conflicts: UserSessionInfo[];
+    /** Session ids that point at rooms which no longer exist —
+     *  best-effort hdel'd so the next check doesn't re-pay the cost. */
+    staleSessions: string[];
+}
+export declare class UniqueSessionPlugin extends RoomPlugin {
+    readonly pluginName: "uniqueSession";
+    static dependencies: PluginDependencies;
+    private max;
+    private mode;
+    private rejectCode;
+    private rejectMessage;
+    private conflictsWith?;
+    private resolveUserId;
+    constructor(opts?: UniqueSessionOptions);
+    protected onJoin(client: Client): Promise<void>;
+    /**
+     * Read the user's session index, parse + reconcile entries against
+     * live rooms, return the conflict list. Exposed so unit tests can
+     * exercise the parsing/reconciliation logic without standing up
+     * the full plugin lifecycle.
+     *
+     * Wire-op cap: 2 per call — one HGETALL for the user's hash, plus
+     * one batch lookup for cross-room candidates (skipped when none).
+     * Self-room entries are resolved against `this.room.clients`
+     * locally and never touch the matchmaker.
+     */
+    evaluate(userId: string): Promise<ConflictResult>;
+}
+export {};

package/build/plugins/unique-session.mjs

@@ -0,0 +1,137 @@
+// bundles/colyseus/src/plugins/unique-session.ts
+import {
+  RoomPlugin,
+  ServerError,
+  matchMaker
+} from "@colyseus/core";
+import { userRoomsKey } from "@colyseus/core/internal";
+import { TrackUserSessionsPlugin } from "./track-user-sessions.mjs";
+function defaultResolveUserId(client) {
+  const auth = client.auth;
+  if (!auth) {
+    return void 0;
+  }
+  if (typeof auth.id === "string" && auth.id.length > 0) {
+    return auth.id;
+  }
+  if (typeof auth.userId === "string" && auth.userId.length > 0) {
+    return auth.userId;
+  }
+  return void 0;
+}
+var UniqueSessionPlugin = class extends RoomPlugin {
+  constructor(opts = {}) {
+    super();
+    this.pluginName = "uniqueSession";
+    this.max = opts.max ?? 1;
+    this.mode = opts.onDuplicate ?? "reject";
+    this.rejectCode = opts.rejectCode ?? 4400;
+    this.rejectMessage = opts.rejectMessage ?? "already_in_room";
+    this.conflictsWith = opts.conflictsWith;
+    this.resolveUserId = opts.resolveUserId ?? defaultResolveUserId;
+  }
+  static {
+    this.dependencies = [TrackUserSessionsPlugin];
+  }
+  async onJoin(client) {
+    const userId = this.resolveUserId(client);
+    if (!userId) {
+      return;
+    }
+    const { conflicts, staleSessions } = await this.evaluate(userId);
+    if (staleSessions.length > 0) {
+      const key = userRoomsKey(userId);
+      void Promise.all(
+        staleSessions.map((s) => matchMaker.presence.hdel(key, s))
+      ).catch(() => {
+      });
+    }
+    if (conflicts.length < this.max) {
+      return;
+    }
+    if (this.mode === "replace") {
+      const sorted = conflicts.slice().sort((a, b) => a.joinedAt - b.joinedAt);
+      const toKick = sorted.slice(0, conflicts.length - this.max + 1);
+      await Promise.all(
+        toKick.map(
+          (info) => matchMaker.remoteRoomCall(
+            info.roomId,
+            "kickClient",
+            [info.sessionId, 1e3, "replaced"]
+          ).catch(() => {
+          })
+        )
+      );
+      return;
+    }
+    throw new ServerError(this.rejectCode, this.rejectMessage);
+  }
+  /**
+   * Read the user's session index, parse + reconcile entries against
+   * live rooms, return the conflict list. Exposed so unit tests can
+   * exercise the parsing/reconciliation logic without standing up
+   * the full plugin lifecycle.
+   *
+   * Wire-op cap: 2 per call — one HGETALL for the user's hash, plus
+   * one batch lookup for cross-room candidates (skipped when none).
+   * Self-room entries are resolved against `this.room.clients`
+   * locally and never touch the matchmaker.
+   */
+  async evaluate(userId) {
+    const raw = await matchMaker.presence.hgetall(userRoomsKey(userId));
+    const fields = Object.keys(raw);
+    if (fields.length === 0) {
+      return { conflicts: [], staleSessions: [] };
+    }
+    const staleSessions = [];
+    const selfRoomConflicts = [];
+    const crossRoomEntries = [];
+    for (const sessionId of fields) {
+      let entry;
+      try {
+        entry = JSON.parse(raw[sessionId]);
+      } catch {
+        staleSessions.push(sessionId);
+        continue;
+      }
+      if (entry.roomName !== this.room.roomName) {
+        continue;
+      }
+      if (entry.roomId === this.room.roomId) {
+        const stillHere = this.room.clients?.some(
+          (c) => c.sessionId === sessionId
+        ) ?? false;
+        if (stillHere) {
+          selfRoomConflicts.push({ sessionId, ...entry });
+        } else {
+          staleSessions.push(sessionId);
+        }
+      } else {
+        crossRoomEntries.push({ sessionId, entry });
+      }
+    }
+    const live = crossRoomEntries.length > 0 ? await matchMaker.findRoomsByIds(crossRoomEntries.map((c) => c.entry.roomId)) : /* @__PURE__ */ new Map();
+    const conflicts = [...selfRoomConflicts];
+    for (const { sessionId, entry } of crossRoomEntries) {
+      const room = live.get(entry.roomId);
+      if (!room) {
+        staleSessions.push(sessionId);
+        continue;
+      }
+      const info = { sessionId, ...entry };
+      if (room.processId !== void 0) {
+        info.processId = room.processId;
+      }
+      conflicts.push(info);
+    }
+    const filtered = this.conflictsWith ? conflicts.filter((c) => this.conflictsWith({
+      sessionId: c.sessionId,
+      joinedAt: c.joinedAt,
+      room: live.get(c.roomId)
+    }, this.room)) : conflicts;
+    return { conflicts: filtered, staleSessions };
+  }
+};
+export {
+  UniqueSessionPlugin
+};

package/build/plugins/unique-session.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/plugins/unique-session.ts"],
+  "sourcesContent": ["/**\n * UniqueSessionPlugin \u2014 enforces \"one (or N) concurrent session(s) of\n * this room type per user.\" Use to prevent a player from opening\n * two tabs of the same game mode, or from re-queueing into another\n * instance while their old session is still active.\n *\n * Usage:\n *\n *   import { UniqueSessionPlugin } from 'colyseus/plugins/unique-session';\n *\n *   class GameRoom extends Room {\n *     plugins = definePlugins({\n *       unique: new UniqueSessionPlugin({ max: 1, onDuplicate: 'reject' }),\n *     });\n *   }\n *\n * The plugin reads the per-user reverse index that\n * `TrackUserSessionsPlugin` maintains in Presence. Same source the\n * admin's by-user inspector and the `closeUserSessions` helper use \u2014\n * no new bookkeeping. (For a generic lookup from your own code,\n * prefer `TrackUserSessionsPlugin.listUserSessions(userId)`.)\n *\n * Anonymous clients (no `userId`) are NEVER rejected: with no stable\n * identity we have nothing to enforce against. Document this so\n * apps that anonymously match-make don't expect a guarantee they\n * can't get.\n *\n * Race window: two near-simultaneous joins from the same user can\n * both pass the check before either has written to the hash\n * (`trackRoomJoin` fires AFTER the plugin/room onJoin chain). For\n * the singleton/two-tabs UX this is acceptable; if your game needs\n * strict serialization, layer an atomic `hsetnx` reservation on\n * top \u2014 out of scope for v1.\n *\n * Stale-entry handling: entries are reconciled two ways. Entries\n * pointing at another room get dropped if `matchMaker.query` doesn't\n * know that room anymore (crashed process). Entries pointing at THIS\n * room get cross-checked against `this.room.clients` \u2014 if the\n * sessionId isn't live locally, the entry is treated as stale (e.g.\n * a fast disconnect that missed `onLeave`) and dropped, so a\n * legitimate fresh join isn't blocked by ghost data.\n *\n * Auto-includes `TrackUserSessionsPlugin` via `static dependencies`\n * so the per-user reverse index this plugin reads from is always\n * populated \u2014 apps don't have to register the tracker plugin\n * themselves.\n */\nimport {\n  RoomPlugin, ServerError, matchMaker,\n  type Client, type Room, type IRoomCache, type PluginDependencies,\n} from '@colyseus/core';\nimport { userRoomsKey, type UserRoomEntry, type UserSessionInfo } from '@colyseus/core/internal';\nimport { TrackUserSessionsPlugin } from './track-user-sessions.ts';\n\n/**\n * Per-existing-session context passed to the `conflictsWith`\n * predicate. The full matchmaker `IRoomCache` (including `metadata`)\n * is attached for cross-room entries \u2014 populated from the same\n * batch lookup the plugin already runs, so no extra wire ops.\n *\n * For entries that point at the CURRENT room (same `Room` instance\n * the plugin is attached to), `room` is `undefined` \u2014 read from\n * the second arg (`currentRoom`) instead, which is the live `Room`.\n */\nexport interface UniqueSessionConflict {\n  /** The existing session's id. */\n  sessionId: string;\n  /** Unix ms timestamp recorded when the existing session joined. */\n  joinedAt: number;\n  /** Matchmaker's cached `IRoomCache` for the existing session's\n   *  room \u2014 `metadata`, `clients`, `locked`, etc. Undefined when the\n   *  existing session is in the same room instance as the joining\n   *  client; use `currentRoom` for that case. */\n  room?: IRoomCache;\n}\n\nexport interface UniqueSessionOptions {\n  /**\n   * Max concurrent sessions of this room type per user. Default `1`\n   * (strict singleton). Setting `> 1` lets users open e.g. two tabs\n   * but not ten \u2014 useful for testing/spectating workflows.\n   */\n  max?: number;\n\n  /**\n   * Behavior when the limit is exceeded:\n   *  - `'reject'` (default): refuse the new join with a `ServerError`.\n   *  - `'replace'`: kick the oldest existing session(s) so the new\n   *    join can proceed. Useful for refresh-style UX where a player\n   *    expects their newer tab to \"win\".\n   */\n  onDuplicate?: 'reject' | 'replace';\n\n  /**\n   * Error code attached to the `ServerError` thrown on reject. The\n   * SDK surfaces this as `MatchMakeError.code`. Default `4400`\n   * (matches the 4xxx custom range Colyseus uses elsewhere).\n   */\n  rejectCode?: number;\n\n  /**\n   * Message attached to the `ServerError` thrown on reject. Default\n   * `'already_in_room'`. The SDK exposes it as `e.message` so the\n   * client can branch on it.\n   */\n  rejectMessage?: string;\n\n  /**\n   * Per-existing-session filter applied after the plugin's own\n   * same-`roomName` matching + stale-entry reconcile, but before\n   * counting against `max`. Return `true` to count the existing\n   * session as a conflict, `false` to skip it.\n   *\n   * Receives:\n   *  - `existing` \u2014 `{ sessionId, joinedAt, room? }`. The `room`\n   *    field is the matchmaker's cached `IRoomCache` for the\n   *    existing session's room (carrying `metadata`, `clients`,\n   *    `locked`, etc.), populated for cross-room entries from the\n   *    same batch lookup the plugin already runs. It is `undefined`\n   *    when the existing session is in the SAME `Room` instance as\n   *    the joining client \u2014 for those, read state from `currentRoom`.\n   *  - `currentRoom` \u2014 the live `Room` instance the join is targeting\n   *    (i.e. `this.room` inside the plugin).\n   *\n   * Use this for metadata-based scoping (e.g. \"only count\n   * same-game-mode sessions\"), per-process exemptions (multi-region\n   * deploys), capacity-aware filtering (\"don't count rooms that are\n   * already full\"), etc.\n   */\n  conflictsWith?: (\n    existing: UniqueSessionConflict,\n    currentRoom: Room,\n  ) => boolean;\n\n  /**\n   * Extract the user's stable id from `Client`. Return a non-empty\n   * string when the client carries an identity; return `undefined`\n   * (or empty string) for anonymous clients \u2014 the plugin skips the\n   * check in that case.\n   *\n   * Default reads `client.auth.id`, then `client.auth.userId` \u2014 the\n   * JWT payload shape `@colyseus/auth`'s default `onAuth` produces\n   * for both authenticated AND anonymously-registered sessions\n   * (anonymous users from `registerAnonymous` get an `id` too;\n   * `anonymousId` is a separate upgrade-token field).\n   *\n   * Custom auth flows that store the id elsewhere (e.g.\n   * `client.auth.profile.sub` for raw OIDC) override with a\n   * function that returns from that path.\n   */\n  resolveUserId?: (client: Client) => string | undefined;\n}\n\n/** Default extractor \u2014 `auth.id`, then `auth.userId`. */\nfunction defaultResolveUserId(client: Client): string | undefined {\n  const auth = (client as any).auth;\n  if (!auth) { return undefined; }\n  if (typeof auth.id === 'string' && auth.id.length > 0) { return auth.id; }\n  if (typeof auth.userId === 'string' && auth.userId.length > 0) { return auth.userId; }\n  return undefined;\n}\n\n/**\n * Result of evaluating the user's existing sessions. Extracted from\n * the `onJoin` body so the unit tests can drive it in isolation.\n */\ninterface ConflictResult {\n  /** Entries that should count against the limit. */\n  conflicts: UserSessionInfo[];\n  /** Session ids that point at rooms which no longer exist \u2014\n   *  best-effort hdel'd so the next check doesn't re-pay the cost. */\n  staleSessions: string[];\n}\n\nexport class UniqueSessionPlugin extends RoomPlugin {\n  readonly pluginName = 'uniqueSession' as const;\n\n  static dependencies: PluginDependencies = [TrackUserSessionsPlugin];\n\n  private max: number;\n  private mode: 'reject' | 'replace';\n  private rejectCode: number;\n  private rejectMessage: string;\n  private conflictsWith?: (\n    existing: UniqueSessionConflict,\n    currentRoom: Room,\n  ) => boolean;\n  private resolveUserId: (client: Client) => string | undefined;\n\n  constructor(opts: UniqueSessionOptions = {}) {\n    super();\n    this.max = opts.max ?? 1;\n    this.mode = opts.onDuplicate ?? 'reject';\n    this.rejectCode = opts.rejectCode ?? 4400;\n    this.rejectMessage = opts.rejectMessage ?? 'already_in_room';\n    this.conflictsWith = opts.conflictsWith;\n    this.resolveUserId = opts.resolveUserId ?? defaultResolveUserId;\n  }\n\n  protected async onJoin(client: Client): Promise<void> {\n    const userId = this.resolveUserId(client);\n    // Anonymous clients have no stable identity \u2014 nothing to enforce\n    // against. Skipping (rather than rejecting) keeps anonymous\n    // matchmaking working unchanged.\n    if (!userId) { return; }\n\n    const { conflicts, staleSessions } = await this.evaluate(userId);\n\n    // Best-effort cleanup of stale entries \u2014 don't block the response\n    // on it (the user-visible answer doesn't depend on hdel landing).\n    if (staleSessions.length > 0) {\n      const key = userRoomsKey(userId);\n      void Promise.all(\n        staleSessions.map((s) => matchMaker.presence.hdel(key, s)),\n      ).catch(() => { /* ignore */ });\n    }\n\n    if (conflicts.length < this.max) { return; }\n\n    if (this.mode === 'replace') {\n      // Kick the *oldest* conflicts first so the newest existing\n      // session survives alongside the new one (or the new one wins\n      // outright when max=1). Sort by joinedAt ascending \u2014 earliest\n      // join time is oldest.\n      const sorted = conflicts.slice().sort((a, b) => a.joinedAt - b.joinedAt);\n      const toKick = sorted.slice(0, conflicts.length - this.max + 1);\n      await Promise.all(\n        toKick.map((info) =>\n          matchMaker.remoteRoomCall(\n            info.roomId,\n            'kickClient' as any,\n            [info.sessionId, 1000, 'replaced'],\n          ).catch(() => { /* room gone \u2014 that's fine, the conflict resolves either way */ }),\n        ),\n      );\n      return;\n    }\n\n    // 'reject' \u2014 throw so the framework refuses the join. The thrown\n    // ServerError surfaces to the SDK as `MatchMakeError`.\n    throw new ServerError(this.rejectCode, this.rejectMessage);\n  }\n\n  /**\n   * Read the user's session index, parse + reconcile entries against\n   * live rooms, return the conflict list. Exposed so unit tests can\n   * exercise the parsing/reconciliation logic without standing up\n   * the full plugin lifecycle.\n   *\n   * Wire-op cap: 2 per call \u2014 one HGETALL for the user's hash, plus\n   * one batch lookup for cross-room candidates (skipped when none).\n   * Self-room entries are resolved against `this.room.clients`\n   * locally and never touch the matchmaker.\n   */\n  async evaluate(userId: string): Promise<ConflictResult> {\n    // Wire op 1: read user's session hash.\n    const raw = await matchMaker.presence.hgetall(userRoomsKey(userId));\n    const fields = Object.keys(raw);\n    if (fields.length === 0) { return { conflicts: [], staleSessions: [] }; }\n\n    const staleSessions: string[] = [];\n    const selfRoomConflicts: UserSessionInfo[] = [];\n    const crossRoomEntries: Array<{ sessionId: string; entry: UserRoomEntry }> = [];\n\n    // Stage 1: classify entries in-memory. No matchmaker calls.\n    //   - corrupt JSON \u2192 stale\n    //   - wrong roomName \u2192 ignored\n    //   - this.room.roomId \u2192 resolved via local clients\n    //   - cross-room \u2192 deferred to the batch lookup below\n    for (const sessionId of fields) {\n      let entry: UserRoomEntry;\n      try { entry = JSON.parse(raw[sessionId]); }\n      catch {\n        staleSessions.push(sessionId);\n        continue;\n      }\n\n      if (entry.roomName !== this.room.roomName) { continue; }\n\n      if (entry.roomId === this.room.roomId) {\n        // Local clients are the authoritative source for \"is this\n        // sessionId still active in our room?\" \u2014 an entry without a\n        // live client is a leftover from a connection whose onLeave\n        // never ran (TCP reset, fast disconnect). Drop it so a\n        // legitimate fresh join isn't rejected by ghost data.\n        const stillHere = this.room.clients?.some(\n          (c: any) => c.sessionId === sessionId,\n        ) ?? false;\n        if (stillHere) {\n          selfRoomConflicts.push({ sessionId, ...entry });\n        } else {\n          staleSessions.push(sessionId);\n        }\n      } else {\n        crossRoomEntries.push({ sessionId, entry });\n      }\n    }\n\n    // Wire op 2 (skipped when no cross-room candidates): one batch\n    // lookup verifies that each cross-room candidate's roomId still\n    // exists in the matchmaker. Bounded at K cross-room entries for\n    // *this* user \u2014 never the cluster size.\n    const live = crossRoomEntries.length > 0\n      ? await matchMaker.findRoomsByIds(crossRoomEntries.map((c) => c.entry.roomId))\n      : new Map();\n\n    const conflicts: UserSessionInfo[] = [...selfRoomConflicts];\n    for (const { sessionId, entry } of crossRoomEntries) {\n      const room = live.get(entry.roomId);\n      if (!room) {\n        // Cross-room entry pointing at a roomId the matchmaker no\n        // longer knows about \u2014 index drift from a crashed process.\n        staleSessions.push(sessionId);\n        continue;\n      }\n      const info: UserSessionInfo = { sessionId, ...entry };\n      if (room.processId !== undefined) { info.processId = room.processId; }\n      conflicts.push(info);\n    }\n\n    // `live.get(c.roomId)` is undefined for self-room conflicts (we\n    // never put them in `live`) and the cross-room `IRoomCache` for\n    // the rest \u2014 exactly the predicate's contract.\n    const filtered = this.conflictsWith\n      ? conflicts.filter((c) => this.conflictsWith!({\n          sessionId: c.sessionId,\n          joinedAt: c.joinedAt,\n          room: live.get(c.roomId),\n        }, this.room))\n      : conflicts;\n    return { conflicts: filtered, staleSessions };\n  }\n\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/build/plugins/webrtc.cjs

@@ -0,0 +1,82 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// bundles/colyseus/src/plugins/webrtc.ts
+var webrtc_exports = {};
+__export(webrtc_exports, {
+  WebRTCPlugin: () => WebRTCPlugin
+});
+module.exports = __toCommonJS(webrtc_exports);
+var import_core = require("@colyseus/core");
+var WebRTCPlugin = class extends import_core.RoomPlugin {
+  constructor() {
+    super(...arguments);
+    this.pluginName = "webrtc";
+    /**
+     * Session IDs that have explicitly opted into the mesh via
+     * `webrtc:join`. Used by `onLeave` so we only emit `webrtc:peer-left`
+     * for clients the rest of the mesh actually knew about.
+     */
+    this.peers = /* @__PURE__ */ new Set();
+    this.messages = {
+      /**
+       * Client → server. Opt this client into the mesh: reply with the
+       * current peer list and notify the other peers that a new one has
+       * joined. Idempotent — re-joining sends the (possibly extended) list
+       * again but doesn't double-broadcast.
+       */
+      "webrtc:join": (client) => {
+        if (this.peers.has(client.sessionId)) {
+          client.send("webrtc:peers", [...this.peers].filter((id) => id !== client.sessionId));
+          return;
+        }
+        const existingPeers = [...this.peers];
+        this.peers.add(client.sessionId);
+        client.send("webrtc:peers", existingPeers);
+        this.room.broadcast("webrtc:peer-joined", client.sessionId, { except: client });
+      },
+      /** Client → server → target client. Relays an SDP offer. */
+      "webrtc:offer": (client, message) => {
+        const target = this.room.clients.getById(message.targetId);
+        target?.send("webrtc:offer", { peerId: client.sessionId, sdp: message.sdp });
+      },
+      /** Client → server → target client. Relays an SDP answer. */
+      "webrtc:answer": (client, message) => {
+        const target = this.room.clients.getById(message.targetId);
+        target?.send("webrtc:answer", { peerId: client.sessionId, sdp: message.sdp });
+      },
+      /** Client → server → target client. Relays an ICE candidate. */
+      "webrtc:ice-candidate": (client, message) => {
+        const target = this.room.clients.getById(message.targetId);
+        target?.send("webrtc:ice-candidate", { peerId: client.sessionId, candidate: message.candidate });
+      }
+    };
+  }
+  onLeave(client) {
+    if (!this.peers.has(client.sessionId)) {
+      return;
+    }
+    this.peers.delete(client.sessionId);
+    this.room.broadcast("webrtc:peer-left", client.sessionId, { except: client });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WebRTCPlugin
+});

package/build/plugins/webrtc.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/plugins/webrtc.ts"],
+  "sourcesContent": ["/**\n * WebRTC signaling plugin \u2014 wires the four standard signaling messages\n * (peers list + offer/answer/ICE relay) onto a room, plus a `peer-left`\n * broadcast when a connected peer disconnects.\n *\n * Ports the standalone `@colyseus/webrtc` package as a `RoomPlugin` so\n * the plumbing is automatic \u2014 no `messages = { ...signaling }` spread\n * and no manual `onPeerDisconnected(room, client)` call from `onLeave`.\n *\n * Usage:\n *\n *   import { WebRTCPlugin } from 'colyseus/plugins/webrtc';\n *\n *   class GameRoom extends Room {\n *     plugins = definePlugins({\n *       webrtc: new WebRTCPlugin(),\n *     });\n *   }\n *\n * The plugin tracks which clients have explicitly opted into the mesh\n * (sent `webrtc:join`) so `webrtc:peer-left` is only emitted for them \u2014\n * spectators and other non-WebRTC clients in the same room don't show\n * up in peer events.\n *\n * @see https://github.com/colyseus/webrtc for the original standalone\n *      package this plugin is derived from.\n */\nimport { RoomPlugin, type Client } from '@colyseus/core';\n\n/** WebRTC offer payload (peer \u2194 peer). */\nexport interface SignalingOffer {\n  targetId: string;\n  sdp: any; // RTCSessionDescriptionInit \u2014 browser type, intentionally `any` server-side\n}\n\n/** WebRTC answer payload (peer \u2194 peer). */\nexport interface SignalingAnswer {\n  targetId: string;\n  sdp: any;\n}\n\n/** WebRTC ICE candidate payload (peer \u2194 peer). */\nexport interface SignalingIceCandidate {\n  targetId: string;\n  candidate: any; // RTCIceCandidateInit \u2014 browser type\n}\n\nexport class WebRTCPlugin extends RoomPlugin {\n  readonly pluginName = 'webrtc' as const;\n\n  /**\n   * Session IDs that have explicitly opted into the mesh via\n   * `webrtc:join`. Used by `onLeave` so we only emit `webrtc:peer-left`\n   * for clients the rest of the mesh actually knew about.\n   */\n  private peers = new Set<string>();\n\n  protected messages = {\n    /**\n     * Client \u2192 server. Opt this client into the mesh: reply with the\n     * current peer list and notify the other peers that a new one has\n     * joined. Idempotent \u2014 re-joining sends the (possibly extended) list\n     * again but doesn't double-broadcast.\n     */\n    'webrtc:join': (client: Client) => {\n      if (this.peers.has(client.sessionId)) {\n        client.send('webrtc:peers', [...this.peers].filter((id) => id !== client.sessionId));\n        return;\n      }\n      const existingPeers = [...this.peers];\n      this.peers.add(client.sessionId);\n      client.send('webrtc:peers', existingPeers);\n      this.room.broadcast('webrtc:peer-joined', client.sessionId, { except: client });\n    },\n\n    /** Client \u2192 server \u2192 target client. Relays an SDP offer. */\n    'webrtc:offer': (client: Client, message: SignalingOffer) => {\n      const target = this.room.clients.getById(message.targetId);\n      target?.send('webrtc:offer', { peerId: client.sessionId, sdp: message.sdp });\n    },\n\n    /** Client \u2192 server \u2192 target client. Relays an SDP answer. */\n    'webrtc:answer': (client: Client, message: SignalingAnswer) => {\n      const target = this.room.clients.getById(message.targetId);\n      target?.send('webrtc:answer', { peerId: client.sessionId, sdp: message.sdp });\n    },\n\n    /** Client \u2192 server \u2192 target client. Relays an ICE candidate. */\n    'webrtc:ice-candidate': (client: Client, message: SignalingIceCandidate) => {\n      const target = this.room.clients.getById(message.targetId);\n      target?.send('webrtc:ice-candidate', { peerId: client.sessionId, candidate: message.candidate });\n    },\n  };\n\n  protected onLeave(client: Client) {\n    if (!this.peers.has(client.sessionId)) { return; }\n    this.peers.delete(client.sessionId);\n    this.room.broadcast('webrtc:peer-left', client.sessionId, { except: client });\n  }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AA2BA,kBAAwC;AAoBjC,IAAM,eAAN,cAA2B,uBAAW;AAAA,EAAtC;AAAA;AACL,SAAS,aAAa;AAOtB;AAAA;AAAA;AAAA;AAAA;AAAA,SAAQ,QAAQ,oBAAI,IAAY;AAEhC,SAAU,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAOnB,eAAe,CAAC,WAAmB;AACjC,YAAI,KAAK,MAAM,IAAI,OAAO,SAAS,GAAG;AACpC,iBAAO,KAAK,gBAAgB,CAAC,GAAG,KAAK,KAAK,EAAE,OAAO,CAAC,OAAO,OAAO,OAAO,SAAS,CAAC;AACnF;AAAA,QACF;AACA,cAAM,gBAAgB,CAAC,GAAG,KAAK,KAAK;AACpC,aAAK,MAAM,IAAI,OAAO,SAAS;AAC/B,eAAO,KAAK,gBAAgB,aAAa;AACzC,aAAK,KAAK,UAAU,sBAAsB,OAAO,WAAW,EAAE,QAAQ,OAAO,CAAC;AAAA,MAChF;AAAA;AAAA,MAGA,gBAAgB,CAAC,QAAgB,YAA4B;AAC3D,cAAM,SAAS,KAAK,KAAK,QAAQ,QAAQ,QAAQ,QAAQ;AACzD,gBAAQ,KAAK,gBAAgB,EAAE,QAAQ,OAAO,WAAW,KAAK,QAAQ,IAAI,CAAC;AAAA,MAC7E;AAAA;AAAA,MAGA,iBAAiB,CAAC,QAAgB,YAA6B;AAC7D,cAAM,SAAS,KAAK,KAAK,QAAQ,QAAQ,QAAQ,QAAQ;AACzD,gBAAQ,KAAK,iBAAiB,EAAE,QAAQ,OAAO,WAAW,KAAK,QAAQ,IAAI,CAAC;AAAA,MAC9E;AAAA;AAAA,MAGA,wBAAwB,CAAC,QAAgB,YAAmC;AAC1E,cAAM,SAAS,KAAK,KAAK,QAAQ,QAAQ,QAAQ,QAAQ;AACzD,gBAAQ,KAAK,wBAAwB,EAAE,QAAQ,OAAO,WAAW,WAAW,QAAQ,UAAU,CAAC;AAAA,MACjG;AAAA,IACF;AAAA;AAAA,EAEU,QAAQ,QAAgB;AAChC,QAAI,CAAC,KAAK,MAAM,IAAI,OAAO,SAAS,GAAG;AAAE;AAAA,IAAQ;AACjD,SAAK,MAAM,OAAO,OAAO,SAAS;AAClC,SAAK,KAAK,UAAU,oBAAoB,OAAO,WAAW,EAAE,QAAQ,OAAO,CAAC;AAAA,EAC9E;AACF;",
+  "names": []
+}

package/build/plugins/webrtc.d.ts

@@ -0,0 +1,68 @@
+/**
+ * WebRTC signaling plugin — wires the four standard signaling messages
+ * (peers list + offer/answer/ICE relay) onto a room, plus a `peer-left`
+ * broadcast when a connected peer disconnects.
+ *
+ * Ports the standalone `@colyseus/webrtc` package as a `RoomPlugin` so
+ * the plumbing is automatic — no `messages = { ...signaling }` spread
+ * and no manual `onPeerDisconnected(room, client)` call from `onLeave`.
+ *
+ * Usage:
+ *
+ *   import { WebRTCPlugin } from 'colyseus/plugins/webrtc';
+ *
+ *   class GameRoom extends Room {
+ *     plugins = definePlugins({
+ *       webrtc: new WebRTCPlugin(),
+ *     });
+ *   }
+ *
+ * The plugin tracks which clients have explicitly opted into the mesh
+ * (sent `webrtc:join`) so `webrtc:peer-left` is only emitted for them —
+ * spectators and other non-WebRTC clients in the same room don't show
+ * up in peer events.
+ *
+ * @see https://github.com/colyseus/webrtc for the original standalone
+ *      package this plugin is derived from.
+ */
+import { RoomPlugin, type Client } from '@colyseus/core';
+/** WebRTC offer payload (peer ↔ peer). */
+export interface SignalingOffer {
+    targetId: string;
+    sdp: any;
+}
+/** WebRTC answer payload (peer ↔ peer). */
+export interface SignalingAnswer {
+    targetId: string;
+    sdp: any;
+}
+/** WebRTC ICE candidate payload (peer ↔ peer). */
+export interface SignalingIceCandidate {
+    targetId: string;
+    candidate: any;
+}
+export declare class WebRTCPlugin extends RoomPlugin {
+    readonly pluginName: "webrtc";
+    /**
+     * Session IDs that have explicitly opted into the mesh via
+     * `webrtc:join`. Used by `onLeave` so we only emit `webrtc:peer-left`
+     * for clients the rest of the mesh actually knew about.
+     */
+    private peers;
+    protected messages: {
+        /**
+         * Client → server. Opt this client into the mesh: reply with the
+         * current peer list and notify the other peers that a new one has
+         * joined. Idempotent — re-joining sends the (possibly extended) list
+         * again but doesn't double-broadcast.
+         */
+        'webrtc:join': (client: Client) => void;
+        /** Client → server → target client. Relays an SDP offer. */
+        'webrtc:offer': (client: Client, message: SignalingOffer) => void;
+        /** Client → server → target client. Relays an SDP answer. */
+        'webrtc:answer': (client: Client, message: SignalingAnswer) => void;
+        /** Client → server → target client. Relays an ICE candidate. */
+        'webrtc:ice-candidate': (client: Client, message: SignalingIceCandidate) => void;
+    };
+    protected onLeave(client: Client): void;
+}

package/build/plugins/webrtc.mjs

@@ -0,0 +1,57 @@
+// bundles/colyseus/src/plugins/webrtc.ts
+import { RoomPlugin } from "@colyseus/core";
+var WebRTCPlugin = class extends RoomPlugin {
+  constructor() {
+    super(...arguments);
+    this.pluginName = "webrtc";
+    /**
+     * Session IDs that have explicitly opted into the mesh via
+     * `webrtc:join`. Used by `onLeave` so we only emit `webrtc:peer-left`
+     * for clients the rest of the mesh actually knew about.
+     */
+    this.peers = /* @__PURE__ */ new Set();
+    this.messages = {
+      /**
+       * Client → server. Opt this client into the mesh: reply with the
+       * current peer list and notify the other peers that a new one has
+       * joined. Idempotent — re-joining sends the (possibly extended) list
+       * again but doesn't double-broadcast.
+       */
+      "webrtc:join": (client) => {
+        if (this.peers.has(client.sessionId)) {
+          client.send("webrtc:peers", [...this.peers].filter((id) => id !== client.sessionId));
+          return;
+        }
+        const existingPeers = [...this.peers];
+        this.peers.add(client.sessionId);
+        client.send("webrtc:peers", existingPeers);
+        this.room.broadcast("webrtc:peer-joined", client.sessionId, { except: client });
+      },
+      /** Client → server → target client. Relays an SDP offer. */
+      "webrtc:offer": (client, message) => {
+        const target = this.room.clients.getById(message.targetId);
+        target?.send("webrtc:offer", { peerId: client.sessionId, sdp: message.sdp });
+      },
+      /** Client → server → target client. Relays an SDP answer. */
+      "webrtc:answer": (client, message) => {
+        const target = this.room.clients.getById(message.targetId);
+        target?.send("webrtc:answer", { peerId: client.sessionId, sdp: message.sdp });
+      },
+      /** Client → server → target client. Relays an ICE candidate. */
+      "webrtc:ice-candidate": (client, message) => {
+        const target = this.room.clients.getById(message.targetId);
+        target?.send("webrtc:ice-candidate", { peerId: client.sessionId, candidate: message.candidate });
+      }
+    };
+  }
+  onLeave(client) {
+    if (!this.peers.has(client.sessionId)) {
+      return;
+    }
+    this.peers.delete(client.sessionId);
+    this.room.broadcast("webrtc:peer-left", client.sessionId, { except: client });
+  }
+};
+export {
+  WebRTCPlugin
+};

package/build/plugins/webrtc.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/plugins/webrtc.ts"],
+  "sourcesContent": ["/**\n * WebRTC signaling plugin \u2014 wires the four standard signaling messages\n * (peers list + offer/answer/ICE relay) onto a room, plus a `peer-left`\n * broadcast when a connected peer disconnects.\n *\n * Ports the standalone `@colyseus/webrtc` package as a `RoomPlugin` so\n * the plumbing is automatic \u2014 no `messages = { ...signaling }` spread\n * and no manual `onPeerDisconnected(room, client)` call from `onLeave`.\n *\n * Usage:\n *\n *   import { WebRTCPlugin } from 'colyseus/plugins/webrtc';\n *\n *   class GameRoom extends Room {\n *     plugins = definePlugins({\n *       webrtc: new WebRTCPlugin(),\n *     });\n *   }\n *\n * The plugin tracks which clients have explicitly opted into the mesh\n * (sent `webrtc:join`) so `webrtc:peer-left` is only emitted for them \u2014\n * spectators and other non-WebRTC clients in the same room don't show\n * up in peer events.\n *\n * @see https://github.com/colyseus/webrtc for the original standalone\n *      package this plugin is derived from.\n */\nimport { RoomPlugin, type Client } from '@colyseus/core';\n\n/** WebRTC offer payload (peer \u2194 peer). */\nexport interface SignalingOffer {\n  targetId: string;\n  sdp: any; // RTCSessionDescriptionInit \u2014 browser type, intentionally `any` server-side\n}\n\n/** WebRTC answer payload (peer \u2194 peer). */\nexport interface SignalingAnswer {\n  targetId: string;\n  sdp: any;\n}\n\n/** WebRTC ICE candidate payload (peer \u2194 peer). */\nexport interface SignalingIceCandidate {\n  targetId: string;\n  candidate: any; // RTCIceCandidateInit \u2014 browser type\n}\n\nexport class WebRTCPlugin extends RoomPlugin {\n  readonly pluginName = 'webrtc' as const;\n\n  /**\n   * Session IDs that have explicitly opted into the mesh via\n   * `webrtc:join`. Used by `onLeave` so we only emit `webrtc:peer-left`\n   * for clients the rest of the mesh actually knew about.\n   */\n  private peers = new Set<string>();\n\n  protected messages = {\n    /**\n     * Client \u2192 server. Opt this client into the mesh: reply with the\n     * current peer list and notify the other peers that a new one has\n     * joined. Idempotent \u2014 re-joining sends the (possibly extended) list\n     * again but doesn't double-broadcast.\n     */\n    'webrtc:join': (client: Client) => {\n      if (this.peers.has(client.sessionId)) {\n        client.send('webrtc:peers', [...this.peers].filter((id) => id !== client.sessionId));\n        return;\n      }\n      const existingPeers = [...this.peers];\n      this.peers.add(client.sessionId);\n      client.send('webrtc:peers', existingPeers);\n      this.room.broadcast('webrtc:peer-joined', client.sessionId, { except: client });\n    },\n\n    /** Client \u2192 server \u2192 target client. Relays an SDP offer. */\n    'webrtc:offer': (client: Client, message: SignalingOffer) => {\n      const target = this.room.clients.getById(message.targetId);\n      target?.send('webrtc:offer', { peerId: client.sessionId, sdp: message.sdp });\n    },\n\n    /** Client \u2192 server \u2192 target client. Relays an SDP answer. */\n    'webrtc:answer': (client: Client, message: SignalingAnswer) => {\n      const target = this.room.clients.getById(message.targetId);\n      target?.send('webrtc:answer', { peerId: client.sessionId, sdp: message.sdp });\n    },\n\n    /** Client \u2192 server \u2192 target client. Relays an ICE candidate. */\n    'webrtc:ice-candidate': (client: Client, message: SignalingIceCandidate) => {\n      const target = this.room.clients.getById(message.targetId);\n      target?.send('webrtc:ice-candidate', { peerId: client.sessionId, candidate: message.candidate });\n    },\n  };\n\n  protected onLeave(client: Client) {\n    if (!this.peers.has(client.sessionId)) { return; }\n    this.peers.delete(client.sessionId);\n    this.room.broadcast('webrtc:peer-left', client.sessionId, { except: client });\n  }\n}\n"],
+  "mappings": ";AA2BA,SAAS,kBAA+B;AAoBjC,IAAM,eAAN,cAA2B,WAAW;AAAA,EAAtC;AAAA;AACL,SAAS,aAAa;AAOtB;AAAA;AAAA;AAAA;AAAA;AAAA,SAAQ,QAAQ,oBAAI,IAAY;AAEhC,SAAU,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAOnB,eAAe,CAAC,WAAmB;AACjC,YAAI,KAAK,MAAM,IAAI,OAAO,SAAS,GAAG;AACpC,iBAAO,KAAK,gBAAgB,CAAC,GAAG,KAAK,KAAK,EAAE,OAAO,CAAC,OAAO,OAAO,OAAO,SAAS,CAAC;AACnF;AAAA,QACF;AACA,cAAM,gBAAgB,CAAC,GAAG,KAAK,KAAK;AACpC,aAAK,MAAM,IAAI,OAAO,SAAS;AAC/B,eAAO,KAAK,gBAAgB,aAAa;AACzC,aAAK,KAAK,UAAU,sBAAsB,OAAO,WAAW,EAAE,QAAQ,OAAO,CAAC;AAAA,MAChF;AAAA;AAAA,MAGA,gBAAgB,CAAC,QAAgB,YAA4B;AAC3D,cAAM,SAAS,KAAK,KAAK,QAAQ,QAAQ,QAAQ,QAAQ;AACzD,gBAAQ,KAAK,gBAAgB,EAAE,QAAQ,OAAO,WAAW,KAAK,QAAQ,IAAI,CAAC;AAAA,MAC7E;AAAA;AAAA,MAGA,iBAAiB,CAAC,QAAgB,YAA6B;AAC7D,cAAM,SAAS,KAAK,KAAK,QAAQ,QAAQ,QAAQ,QAAQ;AACzD,gBAAQ,KAAK,iBAAiB,EAAE,QAAQ,OAAO,WAAW,KAAK,QAAQ,IAAI,CAAC;AAAA,MAC9E;AAAA;AAAA,MAGA,wBAAwB,CAAC,QAAgB,YAAmC;AAC1E,cAAM,SAAS,KAAK,KAAK,QAAQ,QAAQ,QAAQ,QAAQ;AACzD,gBAAQ,KAAK,wBAAwB,EAAE,QAAQ,OAAO,WAAW,WAAW,QAAQ,UAAU,CAAC;AAAA,MACjG;AAAA,IACF;AAAA;AAAA,EAEU,QAAQ,QAAgB;AAChC,QAAI,CAAC,KAAK,MAAM,IAAI,OAAO,SAAS,GAAG;AAAE;AAAA,IAAQ;AACjD,SAAK,MAAM,OAAO,OAAO,SAAS;AAClC,SAAK,KAAK,UAAU,oBAAoB,OAAO,WAAW,EAAE,QAAQ,OAAO,CAAC;AAAA,EAC9E;AACF;",
+  "names": []
+}

package/build/vite.cjs

@@ -167,11 +167,14 @@ function colyseus(options) {
           currentAppHandler(req, res, next);
         });
         return async () => {
-          if (!server.httpServer) {
-            throw new Error("[colyseus] Vite HTTP server not available.");
+          const httpServer = options.httpServer ?? server.httpServer;
+          if (!httpServer) {
+            throw new Error(
+              "[colyseus] No HTTP server available. When running Vite in middlewareMode, pass `httpServer` to the colyseus() plugin."
+            );
           }
-          await loadServerModule();
-          console.log("[colyseus] Server ready on Vite's HTTP server");
+          await loadServerModule(httpServer);
+          console.log("[colyseus] Server ready on " + (options.httpServer ? "user-provided" : "Vite's") + " HTTP server");
         };
       }
     },
@@ -190,7 +193,7 @@ function colyseus(options) {
       }
     }
   ];
-  async function loadServerModule() {
+  async function loadServerModule(httpServer) {
     const env = viteServer.environments.colyseus;
     if (!env) {
       console.error("[colyseus] Environment not found");
@@ -208,7 +211,7 @@ function colyseus(options) {
         if (typeof transport.attachToServer !== "function") {
           throw new Error("[colyseus] Vite dev mode requires a transport with attachToServer().");
         }
-        transport.attachToServer(viteServer.httpServer, {
+        transport.attachToServer(httpServer ?? viteServer.httpServer, {
           filter(req) {
             return /^\/[a-zA-Z0-9_-]+\/[a-zA-Z0-9_-]+\/?$/.test(
               new URL(req.url || "", "http://localhost").pathname
@@ -223,9 +226,10 @@ function colyseus(options) {
       const router = config?.router;
       if (!expressApp && config?.options?.express) {
         try {
-          const express = (await (0, import_core.dynamicImport)("express")).default;
+          const expressModule = await (0, import_core.dynamicImport)("express");
+          const express = expressModule?.default ?? expressModule;
           expressApp = express();
-          config.options.express(expressApp);
+          await config.options.express(expressApp);
         } catch (e) {
           console.warn("[colyseus] Express not available. Install express to use the express option.");
         }