@colyseus/core 0.17.42 → 0.18.0

package/build/Room.mjs

@@ -1,6 +1,9 @@
 // packages/core/src/Room.ts
-import { unpack } from "@colyseus/msgpackr";
-import { decode, $changes } from "@colyseus/schema";
+import { unpack } from "msgpackr";
+import { decode, Encoder, Reflection, $changes } from "@colyseus/schema";
+import { InputDecoder } from "@colyseus/schema/input";
+import { InputAccessorImpl, InputBufferImpl, NO_OP_INPUT_ACCESSOR } from "./input/InputBuffer.mjs";
+import {} from "./input/InputBuffer.mjs";
 import { ClockTimer as Clock } from "@colyseus/timer";
 import { EventEmitter } from "events";
 import { logger } from "./Logger.mjs";
@@ -19,11 +22,29 @@ import * as matchMaker from "./MatchMaker.mjs";
 import {
   CloseCode,
   ErrorCode,
-  Protocol
+  HandshakeSection,
+  Protocol,
+  ResponseStatus
 } from "@colyseus/shared-types";
+import {
+  setupRoomPlugins
+} from "./RoomPlugin.mjs";
+import {
+  RoomPlugin as RoomPlugin2,
+  definePlugins,
+  attachToTestRoom
+} from "./RoomPlugin.mjs";
+var _inputReflectionCache = /* @__PURE__ */ new WeakMap();
 var DEFAULT_PATCH_RATE = 1e3 / 20;
 var DEFAULT_SIMULATION_INTERVAL = 1e3 / 60;
 var noneSerializer = new NoneSerializer();
+function toResponseError(e) {
+  if (e instanceof Error) {
+    const code = e.code;
+    return code !== void 0 ? { name: e.name, message: e.message, code } : { name: e.name, message: e.message };
+  }
+  return { name: "Error", message: String(e) };
+}
 var DEFAULT_SEAT_RESERVATION_TIME = Number(process.env.COLYSEUS_SEAT_RESERVATION_TIME || 15);
 function validate(format, handler) {
   return { format, handler };
@@ -106,6 +127,7 @@ var Room = class _Room {
     this._internalState = RoomInternalState.CREATING;
     this._lockedExplicitly = false;
     this.#_locked = false;
+    this.#_tick = 0;
     this._events.once("dispose", () => {
       this.#_dispose().catch((e) => debugAndPrintError(`onDispose error: ${e && e.stack || e.message || e || "promise rejected"} (roomId: ${this.roomId})`)).finally(() => this._events.emit("disconnect"));
     });
@@ -222,6 +244,9 @@ var Room = class _Room {
     if (this.#_state) {
       this.state = this.#_state;
     }
+    if (this.plugins !== void 0) {
+      setupRoomPlugins(this);
+    }
     if (this.messages !== void 0) {
       if (this.messages["_"]) {
         this.onMessage("*", this.messages["_"].bind(this));
@@ -278,6 +303,44 @@ var Room = class _Room {
     }
     this.#_roomId = roomId;
   }
+  /**
+   * Declare the input schema and configuration in a single line. Returns the
+   * callable accessor that gets assigned to `this.input` — call
+   * `this.input(sessionId)` per tick to consume.
+   *
+   * ```typescript
+   * class FpsRoom extends Room<{ input: MoveInput }> {
+   *   input = this.defineInput(MoveInput, {
+   *     seqField: "tick",       // typed: only numeric fields of MoveInput
+   *     bufferMaxSize: 64,
+   *   });
+   *
+   *   // …or without options — defaults to seqField: "seq", bufferMaxSize: 32:
+   *   // input = this.defineInput(MoveInput);
+   * }
+   * ```
+   *
+   * **Defaults** when `opts` (or individual fields) are omitted:
+   * - `seqField`: `"seq"` — framework dedupes by `input.seq` if the schema has
+   *   such a field. Schemas without it gracefully skip dedupe.
+   * - `bufferMaxSize`: `32` — enables per-client snapshot buffering for
+   *   `room.input(sessionId).drain() / .peek() / .at()`. Set to `0` to disable
+   *   buffering (the `.latest` read still works).
+   */
+  defineInput(type, opts) {
+    this.inputOptions = {
+      ctor: type,
+      seqField: opts?.seqField ?? "seq",
+      bufferMaxSize: opts?.bufferMaxSize ?? 32
+    };
+    if (!_inputReflectionCache.has(type)) {
+      _inputReflectionCache.set(type, Reflection.encode(new Encoder(new type())));
+    }
+    return ((sessionId) => {
+      const c = this.clients.getById(sessionId);
+      return c?._inputAccessor ?? NO_OP_INPUT_ACCESSOR;
+    });
+  }
   /**
    * This method is called before onJoin() - this is where you should authenticate the client
    * @param client - The client that is authenticating.
@@ -378,6 +441,47 @@ var Room = class _Room {
       }, delay);
     }
   }
+  /**
+   * Run a fixed-rate simulation tagged with a monotonic server tick number.
+   * Combine with `room.input(sessionId).at(tick)` to retrieve each client's
+   * input *for a specific tick* — the building block for lockstep / rollback
+   * netcode.
+   *
+   * Replaces any previous {@link setSimulationInterval}. The current tick is
+   * exposed via {@link tick}.
+   *
+   * @example
+   * ```typescript
+   * class LockstepRoom extends Room<{ input: MoveInput }> {
+   *   input = this.defineInput(MoveInput, { seqField: "tick", bufferMaxSize: 64 });
+   *
+   *   onCreate() {
+   *     this.setTickedSimulation((tick, dt) => {
+   *       for (const c of this.clients) {
+   *         const snapshot = this.input(c.sessionId).at(tick);
+   *         if (snapshot) this.apply(c, snapshot);
+   *         // else: predict, freeze, etc. — game-level decision
+   *       }
+   *     }, 1000 / 60);
+   *   }
+   * }
+   * ```
+   */
+  setTickedSimulation(onTickCallback, delay = DEFAULT_SIMULATION_INTERVAL, startTick = 0) {
+    this.#_tick = startTick;
+    this.setSimulationInterval((dt) => {
+      onTickCallback(this.#_tick, dt);
+      this.#_tick++;
+    }, delay);
+  }
+  /**
+   * Current server tick. Incremented by {@link setTickedSimulation} after each
+   * tick callback returns. Returns 0 when no ticked simulation is running.
+   */
+  get tick() {
+    return this.#_tick;
+  }
+  #_tick;
   /**
    * @deprecated Use `.patchRate=` instead.
    */
@@ -394,19 +498,7 @@ var Room = class _Room {
     this._serializer = serializer;
   }
   async setMetadata(meta, persist = true) {
-    if (!this._listing.metadata) {
-      this._listing.metadata = meta;
-    } else {
-      for (const field in meta) {
-        if (!meta.hasOwnProperty(field)) {
-          continue;
-        }
-        this._listing.metadata[field] = meta[field];
-      }
-      if ("markModified" in this._listing) {
-        this._listing.markModified("metadata");
-      }
-    }
+    this._listing.metadata = meta;
     if (persist && this._internalState === RoomInternalState.CREATED) {
       await matchMaker.driver.persist(this._listing);
       this._events.emit("metadata-change");
@@ -447,7 +539,8 @@ var Room = class _Room {
    *
    * @example
    * ```typescript
-   * // Partial metadata update (merges with existing)
+   * // Merging with existing metadata: spread `this.metadata` yourself.
+   * // `metadata` is always REPLACED (not merged) by setMatchmaking()/setMetadata().
    * await this.setMatchmaking({
    *   metadata: { ...this.metadata, round: this.metadata.round + 1 }
    * });
@@ -621,6 +714,100 @@ var Room = class _Room {
       return this.onMessage(messageType, callback);
     }
   }
+  // ---------------------------------------------------------------------------
+  // Operator API — used by @colyseus/admin (and monitor in due course)
+  // through `remoteRoomCall(roomId, methodName)`. Marked `@internal` because
+  // they're framework-tooling primitives, not part of the game-code surface.
+  // ---------------------------------------------------------------------------
+  /**
+   * Snapshot the room's live state for an inspector / admin UI. Includes:
+   *
+   *   roomId, name, maxClients, locked, elapsedTime (ms),
+   *   metadata, clients (sessionId + per-client elapsed + userId when set),
+   *   state (the schema/json the SDK would see),
+   *   stateSize (bytes of the encoded full state, or 0 when no serializer).
+   *
+   * The payload is intentionally plain JSON — `remoteRoomCall` serializes
+   * the return value across process boundaries.
+   *
+   * @internal Operator-only. Game code should not call this.
+   */
+  getInspectorView() {
+    const elapsed = this.clock.elapsedTime;
+    return {
+      roomId: this.roomId,
+      name: this.roomName,
+      clients: this.clients.length,
+      maxClients: this.maxClients,
+      locked: this.#_locked,
+      elapsedTime: elapsed,
+      metadata: this.metadata ?? null,
+      // Cast through `unknown`: `ExtractRoomClient<T>` vs `Client & ClientPrivate`
+      // don't structurally overlap (the user's `client` generic may carry a
+      // narrower userData/auth shape), but the runtime objects we walk here
+      // always have the private join-time field. The narrow per-property
+      // `(c as any)` reads below keep the cast scoped.
+      //
+      // userId / userEmail read straight off `client.auth` — the JWT
+      // payload @colyseus/auth's default onAuth decodes carries both
+      // when the user has them on file. Saves the admin a per-client
+      // database round-trip; falls back to null when the client signed
+      // in anonymously (or with a custom onAuth that returns a shape
+      // without those fields).
+      clientList: this.clients.map((c) => {
+        const auth = c.auth;
+        return {
+          sessionId: c.sessionId,
+          userId: c.userId ?? auth?.id ?? null,
+          userEmail: auth?.email ?? null,
+          elapsedTime: elapsed - (c._joinedAt ?? elapsed)
+        };
+      }),
+      state: this.state ?? null,
+      stateSize: this.#_inspectorStateSize()
+    };
+  }
+  /**
+   * Force-disconnect a single client by sessionId. No-op when the client
+   * isn't connected (idempotent — the caller doesn't need to race-check).
+   *
+   * @internal Operator-only. Game code disconnects clients by calling
+   *   `.leave()` on the Client object directly.
+   */
+  kickClient(sessionId, closeCode = CloseCode.CONSENTED, reason) {
+    for (const client of this.clients) {
+      if (client.sessionId === sessionId) {
+        this.#_forciblyCloseClient(client, closeCode, reason);
+        return;
+      }
+    }
+  }
+  /**
+   * Best-effort byte size of the current full state. Falls back to `0`
+   * when the room has no serializer or the serializer can't produce a
+   * payload (raw rooms, very-early-onCreate, etc.). The serializer
+   * detection mirrors `@colyseus/monitor`'s — we read whichever buffer
+   * is available across schema v2 and v3.
+   */
+  #_inspectorStateSize() {
+    const ser = this._serializer;
+    if (!ser) {
+      return 0;
+    }
+    const hasState = ser.encoder || ser.state;
+    if (!hasState) {
+      return 0;
+    }
+    try {
+      const full = ser.getFullState?.();
+      if (!full) {
+        return 0;
+      }
+      return full.byteLength ?? full.length ?? 0;
+    } catch {
+      return 0;
+    }
+  }
   /**
    * Disconnect all connected clients, and then dispose the room.
    *
@@ -658,6 +845,15 @@ var Room = class _Room {
   async _onJoin(client, authContext, connectionOptions) {
     const sessionId = client.sessionId;
     client.reconnectionToken = generateId();
+    if (this.inputOptions !== void 0) {
+      client._input = new this.inputOptions.ctor();
+      client._inputDecoder = new InputDecoder(client._input);
+      const maxSize = this.inputOptions.bufferMaxSize;
+      if (maxSize > 0) {
+        client._inputBuffer = new InputBufferImpl(maxSize, this.inputOptions.seqField);
+      }
+      client._inputAccessor = new InputAccessorImpl(client);
+    }
     if (this._reservedSeatTimeouts[sessionId]) {
       clearTimeout(this._reservedSeatTimeouts[sessionId]);
       delete this._reservedSeatTimeouts[sessionId];
@@ -760,6 +956,13 @@ var Room = class _Room {
       client.ref["onleave"] = this._onLeave.bind(this, client);
       client.ref.once("close", client.ref["onleave"]);
       client.ref.on("message", this._onMessage.bind(this, client));
+      let extraSections;
+      if (!connectionOptions?.skipHandshake && this.inputOptions !== void 0) {
+        const inputBytes = _inputReflectionCache.get(this.inputOptions.ctor);
+        if (inputBytes !== void 0) {
+          extraSections = [{ tag: HandshakeSection.INPUT_REFLECTION, bytes: inputBytes }];
+        }
+      }
       client.raw(getMessageBytes[Protocol.JOIN_ROOM](
         client.reconnectionToken,
         this._serializer.id,
@@ -767,7 +970,8 @@ var Room = class _Room {
          * if skipHandshake is true, we don't need to send the handshake
          * (in case client already has handshake data)
          */
-        connectionOptions?.skipHandshake ? void 0 : this._serializer.handshake && this._serializer.handshake()
+        connectionOptions?.skipHandshake ? void 0 : this._serializer.handshake && this._serializer.handshake(),
+        extraSections
       ));
     }
   }
@@ -834,7 +1038,7 @@ var Room = class _Room {
     }).finally(() => {
       cleanup();
     });
-    if (this._reconnectionAttempts[reconnectionToken]) {
+    if (this._reconnectionAttempts[reconnectionToken] !== void 0) {
       debugMatchMaking("resolving reconnection attempt for client - sessionId: '%s', roomId: '%s'", sessionId, this.roomId);
       this._reconnectionAttempts[reconnectionToken].resolve(true);
     }
@@ -862,6 +1066,12 @@ var Room = class _Room {
       }
     }
   }
+  // Encode and enqueue a ROOM_RESPONSE for a client request. If the client has
+  // already left, `enqueueRaw` is a no-op — no response is needed.
+  #replyToRequest(client, requestId, status, payload) {
+    debugMessage("response #%d: status=%d -> %j (roomId: %s)", requestId, status, payload, this.roomId);
+    client.enqueueRaw(getMessageBytes[Protocol.ROOM_RESPONSE](requestId, status, payload));
+  }
   sendFullState(client) {
     client.raw(this._serializer.getFullState(client));
   }
@@ -959,6 +1169,26 @@ var Room = class _Room {
     this.clock.stop();
     return await (userReturnData || Promise.resolve());
   }
+  /**
+   * After the decoder has mutated `client._input`, push a clone into the
+   * per-client buffer (when buffering is enabled). Honors
+   * `inputOptions.seqField` for dedupe of redundant frames.
+   */
+  #captureInput(client) {
+    const buf = client._inputBuffer;
+    if (!buf) {
+      return;
+    }
+    const inst = client._input;
+    const seqField = this.inputOptions?.seqField;
+    if (seqField !== void 0) {
+      const value = inst[seqField];
+      if (typeof value === "number" && !buf.accept(value)) {
+        return;
+      }
+    }
+    buf.push(inst.clone());
+  }
   _onMessage(client, buffer) {
     if (client.state === ClientState.LEAVING) {
       return;
@@ -997,6 +1227,36 @@ var Room = class _Room {
       } else {
         this.onMessageFallbacks["__no_message_handler"](client, messageType, message);
       }
+    } else if (code === Protocol.ROOM_REQUEST) {
+      const requestId = decode.number(buffer, it);
+      const messageType = decode.stringCheck(buffer, it) ? decode.string(buffer, it) : decode.number(buffer, it);
+      let message;
+      try {
+        message = buffer.byteLength > it.offset ? unpack(buffer.subarray(it.offset, buffer.byteLength)) : void 0;
+        debugMessage("request #%d: '%s' -> %j (roomId: %s)", requestId, messageType, message, this.roomId);
+        if (this.onMessageValidators[messageType] !== void 0) {
+          message = standardValidate(this.onMessageValidators[messageType], message);
+        }
+      } catch (e) {
+        debugAndPrintError(e);
+        this.#replyToRequest(client, requestId, ResponseStatus.ERROR, toResponseError(e));
+        return;
+      }
+      const handler = this.onMessageEvents.events[messageType]?.[0];
+      if (handler === void 0) {
+        this.#replyToRequest(client, requestId, ResponseStatus.ERROR, {
+          name: "no_handler",
+          message: `room "${this.roomName}" has no onMessage("${messageType}") handler to answer this request.`
+        });
+        return;
+      }
+      Promise.resolve().then(() => handler(client, message)).then(
+        (response) => this.#replyToRequest(client, requestId, ResponseStatus.OK, response),
+        (e) => {
+          debugAndPrintError(e);
+          this.#replyToRequest(client, requestId, ResponseStatus.ERROR, toResponseError(e));
+        }
+      );
     } else if (code === Protocol.ROOM_DATA_BYTES) {
       const messageType = decode.stringCheck(buffer, it) ? decode.string(buffer, it) : decode.number(buffer, it);
       let message = buffer.subarray(it.offset, buffer.byteLength);
@@ -1018,6 +1278,25 @@ var Room = class _Room {
       } else {
         this.onMessageFallbacks["__no_message_handler"](client, messageType, message);
       }
+    } else if (code === Protocol.ROOM_INPUT_RELIABLE) {
+      if (client._inputDecoder) {
+        try {
+          client._inputDecoder.decode(buffer.subarray(1));
+        } catch (e) {
+          debugAndPrintError(e);
+          return;
+        }
+        this.#captureInput(client);
+      }
+    } else if (code === Protocol.ROOM_INPUT_UNRELIABLE) {
+      if (client._inputDecoder) {
+        try {
+          client._inputDecoder.decodeAll(buffer.subarray(1), () => this.#captureInput(client));
+        } catch (e) {
+          debugAndPrintError(e);
+          return;
+        }
+      }
     } else if (code === Protocol.JOIN_ROOM && client.state === ClientState.JOINING) {
       client.state = ClientState.JOINED;
       client._joinedAt = this.clock.elapsedTime;
@@ -1034,10 +1313,10 @@ var Room = class _Room {
       this.#_forciblyCloseClient(client, CloseCode.CONSENTED);
     }
   }
-  #_forciblyCloseClient(client, closeCode) {
+  #_forciblyCloseClient(client, closeCode, reason) {
     client.ref.removeAllListeners("message");
     client.ref.removeListener("close", client.ref["onleave"]);
-    this._onLeave(client, closeCode).then(() => client.leave(closeCode));
+    this._onLeave(client, closeCode).then(() => client.leave(closeCode, reason));
   }
   async _onLeave(client, code) {
     const method = code === CloseCode.CONSENTED || client.state === ClientState.RECONNECTING ? this.onLeave : this.onDrop || this.onLeave;
@@ -1155,6 +1434,9 @@ export {
   DEFAULT_SEAT_RESERVATION_TIME,
   Room,
   RoomInternalState,
+  RoomPlugin2 as RoomPlugin,
+  attachToTestRoom,
+  definePlugins,
   room,
   validate
 };