@colyseus/core 0.18.4 → 0.18.5

package/build/utils/UserSessionIndex.cjs.map

@@ -2,6 +2,6 @@
   "version": 3,
   "sources": ["../../src/utils/UserSessionIndex.ts"],
   "sourcesContent": ["/**\n * User \u2192 active sessions index: \"which active rooms is user X in?\"\n *\n * Without this, answering that question would require fanning out\n * `getInspectorView()` across every running room \u2014 O(rooms) per lookup.\n * Instead, each Room writes a small Presence hash entry on `_onJoin` and\n * removes it on `_onAfterLeave` / dispose. The admin endpoint reads the\n * hash with a single `hgetall`, then reconciles against the matchmaker's\n * live room listing to drop stale entries left behind by hard crashes\n * (no `onLeave` ran).\n *\n * Hash schema:\n *   key:   colyseus:user-rooms:{userId}\n *   field: sessionId\n *   value: JSON `{ roomId, roomName, joinedAt }` (joinedAt is unix ms)\n *\n * Anonymous clients (no userId resolvable) are skipped \u2014 the index is\n * for forensic / support workflows, not anonymous traffic. A Room can\n * also opt out wholesale by setting `trackUserSessions = false` (e.g.\n * a high-volume relay room that doesn't want to pay the Presence\n * write per join).\n *\n * Per-Room state (which sessionIds have an entry, and under which userId)\n * lives in a module-level WeakMap rather than as a field on Room itself.\n * Two reasons:\n *\n *   1. Room.ts stays thin \u2014 it only knows about three call points\n *      (`trackRoomJoin`, `releaseRoomLeave`, `sweepRoomDispose`) and\n *      doesn't have to carry an extra Map field or two private helper\n *      methods solely for this concern.\n *   2. The WeakMap is GC-tied to the Room \u2014 when a Room instance is\n *      collected, its entries vanish automatically. No explicit teardown\n *      hook needed beyond the dispose sweep that drains Presence.\n *\n * @internal\n */\nimport type { Presence } from '../presence/Presence.ts';\n\nexport const USER_ROOMS_KEY_PREFIX = 'colyseus:user-rooms:';\n\nexport function userRoomsKey(userId: string): string {\n  return USER_ROOMS_KEY_PREFIX + userId;\n}\n\n/**\n * What's serialized into the Presence hash value (sessionId is the\n * hash field key, not part of the body). Internal write-side shape.\n */\nexport interface UserRoomEntry {\n  roomId: string;\n  roomName: string;\n  joinedAt: number;\n}\n\n/**\n * Public read-side shape returned by `listUserSessions`: a parsed\n * `UserRoomEntry` plus its sessionId, optionally enriched with\n * `processId` when reconcile against the matchmaker was on.\n */\nexport interface UserSessionInfo extends UserRoomEntry {\n  sessionId: string;\n  /**\n   * Process hosting the room, per the matchmaker. Populated only\n   * when `listUserSessions` was called with `reconcile: true` AND\n   * the room is still in the matchmaker roster.\n   */\n  processId?: string;\n}\n\n/**\n * Structural subset of `Room` needed by the index. Lets this module\n * avoid importing `Room` (which would create a cycle) while still\n * staying typed at the call site.\n */\ninterface InspectorRoomShape {\n  roomId: string;\n  roomName: string;\n  presence: Presence;\n}\n\n/**\n * Structural subset of a Client we read at join/leave. `userId` and\n * `auth` are both optional \u2014 the index simply skips clients without\n * either, which is the correct \"anonymous traffic doesn't show up\n * in support tooling\" behavior.\n */\ninterface InspectorClientShape {\n  sessionId: string;\n  userId?: string;\n  auth?: { id?: string } | null;\n}\n\n/**\n * sessionId \u2192 userId for clients currently registered in the index,\n * scoped per Room. WeakMap-keyed so a forgotten Room takes its tracking\n * map with it.\n */\nconst tracked = new WeakMap<InspectorRoomShape, Map<string, string>>();\n\nfunction getTrackingMap(room: InspectorRoomShape): Map<string, string> {\n  let map = tracked.get(room);\n  if (!map) {\n    map = new Map();\n    tracked.set(room, map);\n  }\n  return map;\n}\n\nfunction resolveUserId(client: InspectorClientShape): string | undefined {\n  return client.userId ?? client.auth?.id;\n}\n\n/**\n * Best-effort: write the join entry. Errors are swallowed because the\n * index is observability metadata \u2014 a Presence outage shouldn't reject\n * a player's join. Exposed as a pure helper for tests + the admin\n * endpoint; `trackRoomJoin` is the Room-flavored entrypoint.\n */\nexport async function trackUserSession(\n  presence: Presence,\n  userId: string,\n  sessionId: string,\n  entry: UserRoomEntry,\n): Promise<void> {\n  try {\n    await presence.hset(userRoomsKey(userId), sessionId, JSON.stringify(entry));\n  } catch {\n    // intentional: see fn-doc\n  }\n}\n\n/**\n * Best-effort: remove the join entry. Errors are swallowed so a Presence\n * blip doesn't bubble into `_onAfterLeave` / `_dispose`.\n */\nexport async function releaseUserSession(\n  presence: Presence,\n  userId: string,\n  sessionId: string,\n): Promise<void> {\n  try {\n    await presence.hdel(userRoomsKey(userId), sessionId);\n  } catch {\n    // intentional: see fn-doc\n  }\n}\n\n/**\n * Record `client`'s join under `room` in the reverse index. No-op for\n * clients with no resolvable userId (anonymous), and when the room\n * carries no presence (shouldn't happen \u2014 defensive for unit tests).\n *\n * Fire-and-forget against Presence; the in-memory tracking map updates\n * synchronously so a follow-up `releaseRoomLeave` always finds the\n * right userId even if the Presence write is still in flight.\n */\nexport function trackRoomJoin(room: InspectorRoomShape, client: InspectorClientShape): void {\n  if (!room.presence) { return; }\n  const userId = resolveUserId(client);\n  if (!userId) { return; }\n  getTrackingMap(room).set(client.sessionId, userId);\n  const entry: UserRoomEntry = {\n    roomId: room.roomId,\n    roomName: room.roomName,\n    joinedAt: Date.now(),\n  };\n  void trackUserSession(room.presence, userId, client.sessionId, entry);\n}\n\n/**\n * Drop `client`'s entry from the reverse index. Idempotent \u2014 no-op\n * when the client wasn't tracked (anonymous, or tracking failed at\n * join time).\n */\nexport function releaseRoomLeave(room: InspectorRoomShape, client: InspectorClientShape): void {\n  if (!room.presence) { return; }\n  const map = tracked.get(room);\n  const userId = map?.get(client.sessionId);\n  if (!userId || !map) { return; }\n  map.delete(client.sessionId);\n  void releaseUserSession(room.presence, userId, client.sessionId);\n}\n\n/**\n * Sweep any still-tracked sessions for `room`. Called during dispose to\n * cover the case where `disconnect()` races the per-client `_onAfterLeave`\n * path \u2014 the read-side reconcile handles cross-process crash recovery,\n * but this is the cheap deterministic cleanup for a clean local dispose.\n *\n * Awaits the pending `hdel`s so the caller can sequence against \"the\n * index is now coherent\" \u2014 the dispose path uses that ordering.\n */\nexport async function sweepRoomDispose(room: InspectorRoomShape): Promise<void> {\n  if (!room.presence) { return; }\n  const map = tracked.get(room);\n  if (!map || map.size === 0) { return; }\n  const pending: Promise<void>[] = [];\n  for (const [sessionId, userId] of map) {\n    pending.push(releaseUserSession(room.presence, userId, sessionId));\n  }\n  map.clear();\n  await Promise.all(pending);\n}\n\n/**\n * Minimal shape of a matchmaker room record needed for reconcile \u2014\n * keeps this module decoupled from the matchmaker / driver types.\n * `matchMaker.query()`'s actual return (`IRoomCache[]`) is structurally\n * a supertype of this, so callers can pass `matchMaker.query` directly.\n */\ninterface MatchmakerRoomLike {\n  roomId: string;\n  processId?: string;\n}\n\nexport interface ListUserSessionsOptions {\n  /**\n   * Drop entries whose `roomId` is no longer in the matchmaker roster\n   * (the index can lag a crashed process). When `true`, the returned\n   * entries also carry `processId` from the live room record.\n   *\n   * Off by default \u2014 most callers (kick everyone, count) don't need it\n   * and the extra `matchMaker.query` round-trip isn't free.\n   */\n  reconcile?: boolean;\n\n  /**\n   * Fire-and-forget `hdel` for stale entries \u2014 those dropped by\n   * reconcile (matchmaker doesn't know the room anymore) plus any\n   * with corrupt JSON. Lets read endpoints self-heal the index on\n   * each call. No-op when `reconcile` is `false`.\n   */\n  removeStale?: boolean;\n}\n\n/**\n * Read the user \u2192 active sessions index. Pure helper \u2014 the\n * `Presence` + matchmaker batch lookup are injected so this module\n * stays free of matchmaker imports (and so unit tests can drive it\n * with fake deps).\n *\n * Wire-op count per call:\n *   - 1 HGETALL on the user's hash (always).\n *   - 1 batch room lookup when `reconcile: true` AND there are\n *     entries to verify; skipped otherwise.\n *\n * Bounded at 2 wire ops regardless of the user's session count.\n */\nexport async function listUserSessions(\n  presence: Presence,\n  findRooms: (roomIds: string[]) => Promise<Map<string, MatchmakerRoomLike>>,\n  userId: string,\n  options: ListUserSessionsOptions = {},\n): Promise<UserSessionInfo[]> {\n  const reconcile = options.reconcile === true;\n  const removeStale = reconcile && options.removeStale === true;\n\n  let raw: Record<string, string>;\n  try {\n    raw = await presence.hgetall(userRoomsKey(userId));\n  } catch {\n    // Presence outage \u2014 observability shouldn't bring down the caller.\n    return [];\n  }\n  const fields = Object.keys(raw);\n  if (fields.length === 0) { return []; }\n\n  const staleSessions: string[] = [];\n  const parsed: Array<{ sessionId: string; entry: UserRoomEntry }> = [];\n  for (const sessionId of fields) {\n    try {\n      parsed.push({ sessionId, entry: JSON.parse(raw[sessionId]) as UserRoomEntry });\n    } catch {\n      // Corrupt JSON \u2014 index drift. Removable even without reconcile.\n      staleSessions.push(sessionId);\n    }\n  }\n\n  if (!reconcile) {\n    return parsed.map(({ sessionId, entry }) => ({ sessionId, ...entry }));\n  }\n\n  // One batch lookup for the K roomIds we care about. K = entries\n  // surviving the JSON.parse stage, not cluster size.\n  const live = parsed.length > 0\n    ? await findRooms(parsed.map((p) => p.entry.roomId))\n    : new Map<string, MatchmakerRoomLike>();\n\n  const result: UserSessionInfo[] = [];\n  for (const { sessionId, entry } of parsed) {\n    const room = live.get(entry.roomId);\n    if (!room) {\n      // Matchmaker doesn't know this roomId anymore \u2014 stale entry\n      // from a crashed process. Drop it (and remove if requested).\n      staleSessions.push(sessionId);\n      continue;\n    }\n    const info: UserSessionInfo = { sessionId, ...entry };\n    if (room.processId !== undefined) { info.processId = room.processId; }\n    result.push(info);\n  }\n\n  if (removeStale && staleSessions.length > 0) {\n    const key = userRoomsKey(userId);\n    void Promise.all(\n      staleSessions.map((s) => presence.hdel(key, s)),\n    ).catch(() => { /* presence outage, swallow */ });\n  }\n\n  return result;\n}\n"],
-  "mappings": "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",
+  "mappings": "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",
   "names": []
 }

package/build/utils/Utils.cjs

@@ -1,3 +1,4 @@
+const __cjsImportMetaUrl = require('node:url').pathToFileURL(__filename).href;
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/build/utils/Utils.cjs.map

@@ -2,6 +2,6 @@
   "version": 3,
   "sources": ["../../src/utils/Utils.ts"],
   "sourcesContent": ["import { nanoid } from 'nanoid';\nimport { type RoomException, type RoomMethodName } from '../errors/RoomExceptions.ts';\n\nimport { debugAndPrintError, debugMatchMaking } from '../Debug.ts';\n\nexport type Type<T> = new (...args: any[]) => T;\nexport type MethodName<T> = string & {\n  [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never\n}[keyof T];\n\n/**\n * Utility type that extracts the return type of a method or the type of a property\n * from a given class/object type.\n *\n * - If the key is a method, returns the awaited return type of that method\n * - If the key is a property, returns the type of that property\n */\nexport type ExtractMethodOrPropertyType<\n  TClass,\n  TKey extends keyof TClass\n> = TClass[TKey] extends (...args: any[]) => infer R\n  ? Awaited<R>\n  : TClass[TKey];\n\n/**\n * Return type of `remoteRoomCall()`.\n *\n * Resolves to the method's awaited return type (or the property's type) when\n * the method name was captured as a literal type. Falls back to `any` when it\n * wasn't \u2014 e.g. `remoteRoomCall<MyRoom>(...)` with only the room type given:\n * TypeScript applies the `TMethod` default instead of inferring the literal\n * once an explicit type argument list is present (microsoft/TypeScript#26242).\n * Pass both type arguments (`remoteRoomCall<MyRoom, 'myMethod'>`) for a\n * precise return type.\n */\nexport type RemoteRoomCallReturn<\n  TRoom,\n  TMethod extends keyof TRoom\n> = keyof TRoom extends TMethod\n  ? any\n  : ExtractMethodOrPropertyType<TRoom, TMethod>;\n\n// remote room call timeouts\nexport const REMOTE_ROOM_SHORT_TIMEOUT = Number(process.env.COLYSEUS_PRESENCE_SHORT_TIMEOUT || 2000);\nexport const MAX_CONCURRENT_CREATE_ROOM_WAIT_TIME = Number(process.env.COLYSEUS_MAX_CONCURRENT_CREATE_ROOM_WAIT_TIME || 0.5);\n\n/**\n * The well-known `Symbol.metadata` (TC39 decorator metadata), falling back to the\n * registered symbol on runtimes that don't expose it globally yet. `@colyseus/schema`\n * stores each class's field metadata under this key \u2014 read it via\n * `instance.constructor[$METADATA]`. Shared so every reader resolves the IDENTICAL\n * symbol (InputBuffer's field-name walk, Rewind's field-index lookup).\n */\nexport const $METADATA: symbol = (Symbol as { metadata?: symbol }).metadata ?? Symbol.for(\"Symbol.metadata\");\n\nexport function generateId(length: number = 9) {\n  return nanoid(length);\n}\n\nexport function getBearerToken(authHeader: string) {\n  return (authHeader && authHeader.startsWith(\"Bearer \") && authHeader.substring(7, authHeader.length)) || undefined;\n}\n\n// nodemon sends SIGUSR2 before reloading\n// (https://github.com/remy/nodemon#controlling-shutdown-of-your-script)\n//\nconst signals: NodeJS.Signals[] = ['SIGINT', 'SIGTERM', 'SIGUSR2'];\n\nexport function registerGracefulShutdown(callback: (err?: Error) => void) {\n  /**\n   * Gracefully shutdown on uncaught errors\n   */\n  process.on('uncaughtException', (err) => {\n    debugAndPrintError(err);\n    callback(err);\n  });\n\n  signals.forEach((signal) =>\n    process.once(signal, () => callback()));\n}\n\nexport function retry<T = any>(\n  cb: Function,\n  maxRetries: number = 3,\n  errorWhiteList: any[] = [],\n  retries: number = 0,\n) {\n  return new Promise<T>((resolve, reject) => {\n    cb()\n      .then(resolve)\n      .catch((e: any) => {\n        if (\n          errorWhiteList.indexOf(e.constructor) !== -1 &&\n          retries++ < maxRetries\n        ) {\n          setTimeout(() => {\n            debugMatchMaking(\"retrying due to error (error: %s, retries: %s, maxRetries: %s)\", e.message, retries, maxRetries);\n            retry<T>(cb, maxRetries, errorWhiteList, retries).\n              then(resolve).\n              catch((e2) => reject(e2));\n          }, Math.floor(Math.random() * Math.pow(2, retries) * 400));\n\n        } else {\n          reject(e);\n        }\n      });\n  });\n}\n\nexport function spliceOne(arr: any[], index: number): boolean {\n  // manually splice availableRooms array\n  // http://jsperf.com/manual-splice\n  if (index === -1 || index >= arr.length) {\n    return false;\n  }\n\n  const len = arr.length - 1;\n  for (let i = index; i < len; i++) {\n    arr[i] = arr[i + 1];\n  }\n\n  arr.length = len;\n  return true;\n}\n\nexport class Deferred<T = any> {\n  public promise: Promise<T>;\n\n  public resolve: Function;\n  public reject: Function;\n\n  constructor(promise?: Promise<T>) {\n    this.promise = promise ?? new Promise<T>((resolve, reject) => {\n      this.resolve = resolve;\n      this.reject = reject;\n    });\n  }\n\n  public then(onFulfilled?: (value: T) => any, onRejected?: (reason: any) => any) {\n    return this.promise.then(onFulfilled, onRejected);\n  }\n\n  public catch(func: (value: any) => any) {\n    return this.promise.catch(func);\n  }\n\n  static reject (reason?: any) {\n    return new Deferred(Promise.reject(reason));\n  }\n\n  static resolve<T = any>(value?: T) {\n    return new Deferred<T>(Promise.resolve(value));\n  }\n\n}\n\nexport function merge(a: any, ...objs: any[]): any {\n  for (let i = 0, len = objs.length; i < len; i++) {\n    const b = objs[i];\n    for (const key in b) {\n      if (b.hasOwnProperty(key)) {\n        a[key] = b[key];\n      }\n    }\n  }\n  return a;\n}\n\nexport function wrapTryCatch(\n  method: Function,\n  onError: (error: RoomException, methodName: RoomMethodName) => void,\n  exceptionClass: Type<RoomException>,\n  methodName: RoomMethodName,\n  rethrow: boolean = false,\n  ...additionalErrorArgs: any[]\n) {\n  return (...args: any[]) => {\n    try {\n      const result = method(...args);\n      if (typeof (result?.catch) === \"function\") {\n        return result.catch((e: Error) => {\n          onError(new exceptionClass(e, e.message, ...args, ...additionalErrorArgs), methodName);\n          if (rethrow) { throw e; }\n        });\n      }\n      return result;\n    } catch (e: any) {\n      onError(new exceptionClass(e, e.message, ...args, ...additionalErrorArgs), methodName);\n      if (rethrow) { throw e; }\n    }\n  };\n}\n\n/**\n * Dynamically import a module using either require() or import()\n * based on the current module system (CJS vs ESM).\n *\n * This avoids double-loading packages when running in mixed ESM/CJS environments.\n * Errors are silently caught - await the promise and handle errors at usage site.\n */\nexport function dynamicImport<T = any>(moduleName: string): Promise<T> {\n  // __dirname exists in CJS but not in ESM\n  if (\n    typeof __dirname !== 'undefined' &&\n    // @ts-ignore\n    typeof (Bun) === 'undefined' // prevent bun from loading CJS modules\n  ) {\n    // CJS context - use require()\n    try {\n      return Promise.resolve(require(moduleName));\n    } catch (e: any) {\n      // If the error is not a MODULE_NOT_FOUND error, reject with the error.\n      if (e.code !== 'MODULE_NOT_FOUND') {\n        return Promise.reject(e);\n      }\n      return Promise.resolve(undefined);\n    }\n  } else {\n    // ESM context - use import()\n    const promise = import(/* @vite-ignore */ moduleName);\n    promise.catch(() => {}); // prevent unhandled rejection warnings\n    return promise;\n  }\n}\n"],
-  "mappings": "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",
+  "mappings": "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",
   "names": []
 }

package/build/utils/nanoevents.cjs

@@ -1,3 +1,4 @@
+const __cjsImportMetaUrl = require('node:url').pathToFileURL(__filename).href;
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/build/utils/nanoevents.cjs.map

@@ -2,6 +2,6 @@
   "version": 3,
   "sources": ["../../src/utils/nanoevents.ts"],
   "sourcesContent": ["export const createNanoEvents = () => ({\n    emit(event: string, ...args: any[]) {\n      for (\n        let callbacks = this.events[event] || [],\n          i = 0,\n          length = callbacks.length;\n        i < length;\n        i++\n      ) {\n        callbacks[i](...args)\n      }\n    },\n    // null-prototype: event names are client-supplied (message types), and on a\n    // plain object \"__proto__\" / \"constructor\" / \"toString\" resolve to inherited\n    // members instead of missing (colyseus/colyseus#951)\n    events: Object.create(null) as { [event: string]: Array<(...args: any[]) => void> },\n    on(event: string, cb: (...args: any[]) => void) {\n      ;(this.events[event] ||= []).push(cb)\n      return () => {\n        this.events[event] = this.events[event]?.filter(i => cb !== i)\n      }\n    }\n  })"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,IAAM,mBAAmB,OAAO;AAAA,EACnC,KAAK,UAAkB,MAAa;AAClC,aACM,YAAY,KAAK,OAAO,KAAK,KAAK,CAAC,GACrC,IAAI,GACJ,SAAS,UAAU,QACrB,IAAI,QACJ,KACA;AACA,gBAAU,CAAC,EAAE,GAAG,IAAI;AAAA,IACtB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAIA,QAAQ,uBAAO,OAAO,IAAI;AAAA,EAC1B,GAAG,OAAe,IAA8B;AAC9C;AAAC,KAAC,KAAK,OAAO,KAAK,MAAM,CAAC,GAAG,KAAK,EAAE;AACpC,WAAO,MAAM;AACX,WAAK,OAAO,KAAK,IAAI,KAAK,OAAO,KAAK,GAAG,OAAO,OAAK,OAAO,CAAC;AAAA,IAC/D;AAAA,EACF;AACF;",
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,IAAM,mBAAmB,OAAO;AAAA,EACnC,KAAK,UAAkB,MAAa;AAClC,aACM,YAAY,KAAK,OAAO,KAAK,KAAK,CAAC,GACrC,IAAI,GACJ,SAAS,UAAU,QACrB,IAAI,QACJ,KACA;AACA,gBAAU,CAAC,EAAE,GAAG,IAAI;AAAA,IACtB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAIA,QAAQ,uBAAO,OAAO,IAAI;AAAA,EAC1B,GAAG,OAAe,IAA8B;AAC9C;AAAC,KAAC,KAAK,OAAO,KAAK,MAAM,CAAC,GAAG,KAAK,EAAE;AACpC,WAAO,MAAM;AACX,WAAK,OAAO,KAAK,IAAI,KAAK,OAAO,KAAK,GAAG,OAAO,OAAK,OAAO,CAAC;AAAA,IAC/D;AAAA,EACF;AACF;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/core",
-  "version": "0.18.4",
+  "version": "0.18.5",
   "description": "Multiplayer Framework for Node.js.",
   "type": "module",
   "input": "./src/index.ts",
@@ -52,14 +52,14 @@
     "msgpackr": "^2.0.1",
     "nanoid": "^3.3.11",
     "@colyseus/better-call": "^1.3.1",
-    "@colyseus/greeting-banner": "^4.0.1",
-    "@colyseus/shared-types": "^0.18.1"
+    "@colyseus/shared-types": "^0.18.1",
+    "@colyseus/greeting-banner": "^4.0.1"
   },
   "devDependencies": {
     "@colyseus/schema": "^5.0.8",
     "express": "^5.0.0",
     "vitest": "^3.1.1",
-    "@colyseus/redis-driver": "^0.18.1",
+    "@colyseus/redis-driver": "^0.18.2",
     "@colyseus/redis-presence": "^0.18.2",
     "@colyseus/tools": "^0.18.2"
   },
@@ -68,9 +68,9 @@
     "@pm2/io": "^6.1.0",
     "express": "^4.16.0 || ^5.0.0",
     "zod": "^4.1.12",
+    "@colyseus/ws-transport": "^0.18.1",
     "@colyseus/auth": "^0.18.1",
-    "@colyseus/better-call": "^1.3.1",
-    "@colyseus/ws-transport": "^0.18.1"
+    "@colyseus/better-call": "^1.3.1"
   },
   "peerDependenciesMeta": {
     "@colyseus/auth": {

package/src/MatchMaker.ts

@@ -37,6 +37,16 @@ const handlers: {[id: string]: RegisteredHandler} = Object.create(null);
 const rooms: {[roomId: string]: Room} = {};
 const events = new EventEmitter();
 
+// A room isn't gone when 'dispose' fires — that only *starts* `Room.#_dispose()`,
+// which awaits the user's async `onDispose()`. `roomCount` is decremented there,
+// so this covers the window until 'disconnect' (emitted once `#_dispose()`
+// settles). Invariant: roomCount + disposingRoomCount = rooms not yet fully gone.
+let disposingRoomCount = 0;
+
+function hasActiveRooms() {
+  return stats.local.roomCount > 0 || disposingRoomCount > 0;
+}
+
 export let publicAddress: string;
 export let processId: string;
 export let presence: Presence;
@@ -103,6 +113,7 @@ export async function setup(
   publicAddress = _publicAddress || getDefaultPublicAddress();
 
   stats.reset(false);
+  disposingRoomCount = 0;
 
   // ensure processId is set
   if (!processId) { processId = generateId(); }
@@ -648,11 +659,14 @@ export async function handleCreateRoom(roomName: string, clientOptions: ClientOp
       room['_events'].removeAllListeners('metadata-change');
     }
 
+    // this room's `onDispose()` has settled
+    disposingRoomCount--;
+
     //
     // emit "no active rooms" event when there are no more rooms in this process
     // (used during graceful shutdown)
     //
-    if (stats.local.roomCount <= 0) {
+    if (!hasActiveRooms()) {
       events.emit('no-active-rooms');
     }
   });
@@ -713,7 +727,7 @@ async function lockAndDisposeAll(): Promise<any> {
   }
 
   const noActiveRooms = new Deferred();
-  if (stats.local.roomCount <= 0) {
+  if (!hasActiveRooms()) {
     // no active rooms to dispose
     noActiveRooms.resolve();
 
@@ -820,7 +834,7 @@ export async function hotReload(): Promise<void> {
 
   // Lock all rooms and trigger default onBeforeShutdown (dev mode impl).
   const noActiveRooms = new Deferred();
-  if (stats.local.roomCount <= 0) {
+  if (!hasActiveRooms()) {
     noActiveRooms.resolve();
   } else {
     events.once('no-active-rooms', () => noActiveRooms.resolve());
@@ -1205,6 +1219,9 @@ async function disposeRoom(roomName: string, room: Room) {
   driver.remove(room['_listing'].roomId);
   stats.local.roomCount--;
 
+  // `onDispose()` is still pending — released on 'disconnect'
+  disposingRoomCount++;
+
   // decrease amount of rooms this process is handling
   if (state !== MatchMakerState.SHUTTING_DOWN) {
     stats.persist();

package/src/Room.ts

@@ -56,6 +56,9 @@ export {
 
 const DEFAULT_PATCH_RATE = 1000 / 20; // 20fps (50ms)
 const DEFAULT_SIMULATION_INTERVAL = 1000 / 60; // 60fps (16.66ms)
+
+// Shared so the unarmed `_flushUnreliable` call site stays monomorphic.
+const NOOP = () => {};
 const noneSerializer = new NoneSerializer();
 
 /** Shared `enqueueRaw` options routing a frame onto `_pendingFrames` to ride the
@@ -276,6 +279,45 @@ export class Room<T extends RoomOptions = RoomOptions> {
   #_patchRate: number;
   #_patchInterval: NodeJS.Timeout;
 
+  /**
+   * Frequency to flush `@unreliable` state fields, in milliseconds.
+   *
+   * Those fields never ride a state patch — they go out over the transport's
+   * unreliable channel (a WebTransport datagram), so a dropped frame costs one
+   * stale value instead of stalling the reliable stream behind a retransmit.
+   * Setting this decouples them from {@link patchRate}, which is the point:
+   * 60Hz movement over a 20Hz structural patch.
+   *
+   * KNOWN COST of a rate faster than {@link patchRate}: an entity's ADD travels
+   * the reliable channel, so datagrams sent between patches can reference a
+   * refId the client hasn't been told about yet. Those frames are skipped by the
+   * client's decoder — safe (the ref graph can't desync, since `@unreliable` is
+   * primitives-only) but each one logs `"refId" not found`, and that entity's
+   * first value lands one mutation later. Measured at `patchRate/this` reports
+   * per mid-session spawn. Leave this unset and the flush rides
+   * {@link broadcastPatch}, which ships the ADD first and avoids it entirely.
+   *
+   * Requires a transport with a datagram channel — today only
+   * `@colyseus/h3-transport` (WebTransport), which is **experimental**. Every
+   * WebSocket transport lacks one, and those clients are skipped entirely (the
+   * room warns once), so `@unreliable` fields keep their join-time value there.
+   *
+   * @default null — flush alongside every {@link broadcastPatch}, and only when
+   * the state actually declares an `@unreliable` field.
+   */
+  public unreliablePatchRate: number | null = null;
+  #_unreliablePatchRate: number | null = null;
+  #_unreliablePatchInterval: NodeJS.Timeout;
+
+  /**
+   * The unreliable flush, called unconditionally at the end of every
+   * {@link broadcastPatch}. Stays {@link NOOP} unless the state actually
+   * declares an `@unreliable` field, so a room that never uses the channel
+   * pays an empty call the engine inlines away — and there is no second
+   * entry point that could drift from `broadcastPatch()`.
+   */
+  private _flushUnreliable: () => void = NOOP;
+
   /**
    * Maximum number of messages a client can send to the server per second.
    * If a client sends more messages than this, it will be disconnected.
@@ -420,6 +462,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
     this.#_state = this.state;
     this.#_autoDispose = this.autoDispose;
     this.#_patchRate = this.patchRate;
+    this.#_unreliablePatchRate = this.unreliablePatchRate;
     this.#_maxClients = this.maxClients;
 
     Object.defineProperties(this, {
@@ -436,6 +479,7 @@ export class Room<T extends RoomOptions = RoomOptions> {
           }
           this._serializer.reset(newState);
           this.#_state = newState;
+          this._armUnreliablePatches();
         },
       },
 
@@ -479,6 +523,15 @@ export class Room<T extends RoomOptions = RoomOptions> {
           }
         },
       },
+
+      unreliablePatchRate: {
+        enumerable: true,
+        get: () => this.#_unreliablePatchRate,
+        set: (milliseconds: number | null) => {
+          this.#_unreliablePatchRate = milliseconds;
+          this._armUnreliablePatches();
+        },
+      },
     });
 
     // set patch interval, now with the setter
@@ -1300,6 +1353,12 @@ export class Room<T extends RoomOptions = RoomOptions> {
       this._inputController !== undefined ? { sNow } : undefined,
     );
 
+    // Flush `@unreliable` fields over the datagram channel, after the reliable
+    // patch so a spawn's ADD is already on the wire when the datagram mutating
+    // it goes out. No-op unless the state declares such a field, and skipped
+    // when `unreliablePatchRate` gave the flush its own timer.
+    this._flushUnreliable();
+
     // Deliver any per-client `afterNextPatch` frames as standalone frames right
     // after the patch (never coalesced into it). Iterates only the clients that
     // staged frames this cycle (`#pendingFrameClients`), never the full list.
@@ -1321,6 +1380,64 @@ export class Room<T extends RoomOptions = RoomOptions> {
     return hasChanges;
   }
 
+  /**
+   * Encode and send the `@unreliable` state fields over each client's
+   * unreliable channel. Those fields never appear in a {@link broadcastPatch}
+   * frame, and clients on a transport without a datagram channel are skipped.
+   *
+   * Driven automatically once the state declares an `@unreliable` field — right
+   * after each {@link broadcastPatch}, or on its own timer when
+   * {@link unreliablePatchRate} is set. Public so a room driving
+   * `broadcastPatch()` by hand can drive this by hand too.
+   */
+  public broadcastUnreliablePatch() {
+    if (!this.state) {
+      return false;
+    }
+    return this._serializer.applyUnreliablePatches?.(this.clients) ?? false;
+  }
+
+  /**
+   * Decide how the unreliable channel is driven — and, for the rooms that never
+   * touch it, decide to not drive it at all. Runs when the state is assigned
+   * (the serializer knows by then whether any `@unreliable` field exists) and
+   * whenever {@link unreliablePatchRate} changes.
+   *
+   * A room whose state declares no `@unreliable` field leaves
+   * {@link _flushUnreliable} at {@link NOOP}, so its patch tick costs exactly
+   * what it did before this feature existed.
+   */
+  private _armUnreliablePatches() {
+    if (this.#_unreliablePatchInterval) {
+      clearInterval(this.#_unreliablePatchInterval);
+      this.#_unreliablePatchInterval = undefined;
+    }
+
+    const armed = this._serializer?.hasUnreliableFields === true;
+    const rate = this.#_unreliablePatchRate;
+    const dedicated = armed && rate !== null && rate !== 0;
+
+    // Default mode flushes from the patch itself rather than an independent
+    // timer of the same period, which would put the datagram ahead of a spawn's
+    // ADD about half the time.
+    const inline = armed && !dedicated;
+
+    this._flushUnreliable = inline
+      ? () => { this.broadcastUnreliablePatch(); }
+      : NOOP;
+
+    if (dedicated) {
+      this.#_unreliablePatchInterval = setInterval(() => this.broadcastUnreliablePatch(), rate);
+
+    } else if (inline && !this.#_patchRate) {
+      // patchRate 0/null means no patch tick to piggyback on.
+      logger.warn(
+        "@colyseus/core: state has @unreliable fields but patchRate is disabled —" +
+        " set `room.unreliablePatchRate` to flush them, or they will never update."
+      );
+    }
+  }
+
   /**
    * Register a message handler for a specific message type.
    * This method is used to handle messages sent by clients to the room.
@@ -2078,6 +2195,11 @@ export class Room<T extends RoomOptions = RoomOptions> {
       this.#_patchInterval = undefined;
     }
 
+    if (this.#_unreliablePatchInterval) {
+      clearInterval(this.#_unreliablePatchInterval);
+      this.#_unreliablePatchInterval = undefined;
+    }
+
     if (this._simulationInterval) {
       clearInterval(this._simulationInterval);
       this._simulationInterval = undefined;

package/src/Transport.ts

@@ -8,7 +8,8 @@ import { StateView } from '@colyseus/schema';
 import type { InputDecoder } from '@colyseus/schema/input';
 
 import { EventEmitter } from 'events';
-import { spliceOne } from './utils/Utils.ts';
+import { debugAndPrintError } from './Debug.ts';
+import { getBearerToken, spliceOne } from './utils/Utils.ts';
 import { ServerError } from './errors/ServerError.ts';
 
 import type { Room } from './Room.ts';
@@ -46,12 +47,129 @@ export abstract class Transport {
     public bindRouter?(router: Router): void;
 }
 
+/**
+ * Intercepts an incoming WebSocket upgrade request, before the handshake.
+ *
+ * Return a `Response` to answer the request instead of upgrading it. Return
+ * nothing to upgrade as usual. The handler may be async, and the handshake waits
+ * for it to resolve.
+ *
+ * `context` is the same shape `onAuth()` receives, read-only here: mutating it
+ * does not carry over to `onAuth()`.
+ *
+ * Not supported by `H3Transport`: WebTransport has no upgrade handshake.
+ *
+ * @example
+ * ```typescript
+ * new uWebSocketsTransport({
+ *   beforeUpgrade: async (request, context) => {
+ *     if (await isBanned(context.ip)) {
+ *       return new Response(null, { status: 403 });
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export type BeforeUpgradeHandler = (
+  request: Request,
+  context: Readonly<AuthContext>,
+) => Response | void | Promise<Response | void>;
+
+/**
+ * Invokes a `beforeUpgrade` handler, resolving with the `Response` to send
+ * instead of upgrading, or `undefined` to proceed with the upgrade.
+ *
+ * Every transport goes through here, so a handler written against one keeps
+ * working on the others. Never rejects: uWebSockets.js aborts the process on an
+ * upgrade handler that yields without responding, and on the other transports a
+ * raw socket left behind leaks a connection.
+ *
+ * @internal
+ */
+export async function runBeforeUpgrade(
+  handler: BeforeUpgradeHandler,
+  url: string, // path, optionally including the query string
+  context: AuthContext,
+): Promise<Response | undefined> {
+  let request: Request;
+
+  try {
+    const host = context.headers.get('host') || 'localhost';
+    request = new Request(`http://${host}${url}`, { headers: context.headers });
+
+  } catch (e: any) {
+    // a `Host` header that isn't a valid authority fails to parse as a URL
+    debugAndPrintError(e);
+    return new Response(null, { status: 400 });
+  }
+
+  try {
+    return (await handler(request, context)) ?? undefined;
+
+  } catch (e: any) {
+    debugAndPrintError(e);
+    return new Response(null, { status: 500 });
+  }
+}
+
+/** Headers as the transport has them: uWebSockets.js and Node give a plain record. */
+type RawHeaders = Headers | Record<string, string | undefined>;
+
+const readHeader = (headers: RawHeaders, name: string) =>
+  (headers instanceof Headers) ? headers.get(name) : headers[name];
+
+/**
+ * Builds the context passed to `beforeUpgrade` and `onAuth`.
+ *
+ * Every transport goes through here, so the context is identical everywhere,
+ * down to how the client address is resolved. `headers` is materialized on
+ * first read: a connection nobody inspects pays nothing for the conversion.
+ *
+ * @internal
+ */
+export function createAuthContext(options: {
+  headers: RawHeaders,
+  token?: string | null,
+  remoteAddress?: string,
+  req?: any,
+}): AuthContext {
+  const source = options.headers;
+  let headers: Headers | undefined;
+
+  return {
+    token: options.token ?? getBearerToken(readHeader(source, 'authorization')),
+    ip: resolveClientIp(source, options.remoteAddress),
+    req: options.req,
+    get headers() {
+      return headers ??= (source instanceof Headers)
+        ? source
+        : new Headers(source as Record<string, string>);
+    },
+  };
+}
+
+/**
+ * A single address, resolved the same way on every transport: `x-forwarded-for`
+ * carries the whole proxy chain, and only its first entry is the client.
+ */
+function resolveClientIp(headers: RawHeaders, remoteAddress?: string): string | undefined {
+  // an empty header counts as absent
+  const firstHop = (name: string) => readHeader(headers, name)?.split(',')[0].trim() || undefined;
+
+  return (
+    firstHop('x-real-ip') ??
+    firstHop('x-forwarded-for') ??
+    firstHop('x-client-ip') ??
+    (remoteAddress || undefined)
+  );
+}
+
 export type AuthContext = {
   token?: string,
+  /** Undefined when no proxy header carries it and the transport has no peer address. */
+  ip: string | undefined;
   headers: Headers,
-  ip: string | string[];
-  // FIXME: each transport may have its own specific properties.
-  // "req" only applies to WebSocketTransport.
+  /** Only set on the HTTP matchmaking request, where it is the `Request` itself. */
   req?: any;
 };
 
@@ -136,6 +254,16 @@ export interface Client<T extends { userData?: any, auth?: any, messages?: Recor
   raw(data: Uint8Array | Buffer, options?: ISendOptions, cb?: (err?: Error) => void): void;
   enqueueRaw(data: Uint8Array | Buffer, options?: ISendOptions): void;
 
+  /**
+   * Send raw bytes over the transport's UNRELIABLE channel — no delivery,
+   * ordering, or duplication guarantee. Used for `@unreliable` state patches.
+   *
+   * Absent on transports with no datagram channel (every WebSocket transport).
+   * Its presence IS the capability check — callers feature-detect rather than
+   * reading a separate flag, and skip clients that can't receive.
+   */
+  rawUnreliable?(data: Uint8Array | Buffer, options?: ISendOptions, cb?: (err?: Error) => void): void;
+
   /**
    * Send a type of message to the client. Messages are encoded with MsgPack and can hold any
    * JSON-serializable data structure.

package/src/index.ts

@@ -56,7 +56,7 @@ export * from './matchmaker/LocalDriver/LocalDriver.ts';
 export { initializeRoomCache } from './matchmaker/driver.ts';
 
 // Transport
-export { type Client, type ClientPrivate, type AuthContext, ClientState, ClientArray, Transport, type ISendOptions, connectClientToRoom, enqueueClientRaw } from './Transport.ts';
+export { type Client, type ClientPrivate, type AuthContext, ClientState, ClientArray, Transport, type ISendOptions, type BeforeUpgradeHandler, runBeforeUpgrade, createAuthContext, connectClientToRoom, enqueueClientRaw } from './Transport.ts';
 
 // Presence
 export { type Presence } from './presence/Presence.ts';

package/src/input/RoomInput.ts

@@ -21,6 +21,20 @@ import { debugAndPrintError } from '../Debug.ts';
  */
 const _inputReflectionCache = new WeakMap<Function, Uint8Array>();
 
+/**
+ * Rebuild one `k`-length series of the unreliable stamp block: `newest` is the
+ * absolute anchor, and each wire delta walks one slot older
+ * (`out[i] = out[i+1] − Δ`). Mirrors the SDK's `_writeSeriesDeltas`.
+ */
+function readSeriesDeltas(buffer: Buffer, it: Iterator, k: number, newest: number): number[] {
+  const out = new Array<number>(k);
+  out[k - 1] = newest;
+  for (let i = k - 2; i >= 0; i--) {
+    out[i] = out[i + 1] - decode.number(buffer, it);
+  }
+  return out;
+}
+
 /**
  * Runtime behind {@link InputAPI}. A class, not a per-`define()` object literal:
  * literal (and `defineProperty`) accessors carry their closure identity in the
@@ -272,11 +286,70 @@ export class RoomInput {
   }
 
   /** Decode a `ROOM_INPUT_UNRELIABLE` redundancy ring — each slot carries its
-   *  framework seq (base seq + position) for ring dedupe, no user seqField. */
-  decodeUnreliable(client: ClientPrivate, buffer: Buffer, _modifiers: number): void {
+   *  framework seq (base seq + position) for ring dedupe, no user seqField.
+   *
+   *  With the TIMED bit, a self-contained lag-comp stamp block precedes the ring:
+   *
+   *      [varint k][uint32 newest][varint Δ]×(k−1)
+   *      [uint16 rdNewest][varint Δrd]×(k−1)        ← BOTH mode only
+   *
+   *  One stamp per slot, because a packet carries k inputs sampled at k
+   *  different instants. The anchor is absolute and the deltas never leave the
+   *  packet, so — unlike the reliable channel's running baseline — no amount of
+   *  loss or reordering can desync it, and an input recovered redundantly from a
+   *  later packet still arrives with its own instant. Stamps are paired
+   *  positionally with `decodeAll`'s oldest→newest yields; a `k` that disagrees
+   *  with the decoded slot count means a malformed packet, so the stamps are
+   *  dropped rather than misapplied (inputs still land, read live). */
+  decodeUnreliable(client: ClientPrivate, buffer: Buffer, modifiers: number): void {
     if (!client._inputDecoder) { return; }
+
+    const it: Iterator = { offset: 1 };
+    let stamps: number[] | undefined;
+    let renderDeltas: number[] | undefined;
+
+    if (modifiers & ProtocolModifier.TIMED) {
+      this.#resolveWireModes();
+      try {
+        const k = decode.number(buffer, it);
+        stamps = readSeriesDeltas(buffer, it, k, decode.uint32(buffer, it));
+        // BOTH mode trails the renderDelta series in the same shape, so each
+        // slot keeps the latency term it was actually sampled with.
+        if (this.#stampReckon && this.#stampRender) {
+          renderDeltas = readSeriesDeltas(buffer, it, k, decode.uint16(buffer, it));
+        }
+      } catch (e: any) {
+        debugAndPrintError(e);
+        return;
+      }
+    }
+
+    let i = 0;
     try {
-      client._inputDecoder.decodeAll(buffer.subarray(1), (_inst, seq) => this.capture(client, 0, 0, seq));
+      const count = client._inputDecoder.decodeAll(buffer.subarray(it.offset), (_inst, seq) => {
+        // Positional pairing — `decodeAll` yields oldest→newest, the order the
+        // block was written in.
+        const slot = i++;
+        const stamp = stamps?.[slot] ?? 0;
+        let renderTime = 0, reckonTime = 0;
+        if (stamp > 0) {
+          if (this.#stampReckon && this.#stampRender) {
+            const rd = renderDeltas?.[slot] ?? 0;
+            reckonTime = stamp;
+            renderTime = stamp > rd ? stamp - rd : 0;
+          } else if (this.#stampReckon) {
+            reckonTime = stamp;
+          } else {
+            renderTime = stamp;
+          }
+        }
+        this.capture(client, renderTime, reckonTime, seq);
+      });
+      if (stamps !== undefined && count !== stamps.length) {
+        debugAndPrintError(new Error(
+          `@colyseus/core: unreliable input stamp block declared ${stamps.length} slots, decoded ${count}`
+        ));
+      }
     } catch (e: any) {
       debugAndPrintError(e);
       return;