@colyseus/core 0.17.43 → 0.18.0

package/build/Room.d.ts

@@ -1,3 +1,5 @@
+import { type InputAPI, type NumericFieldsOf } from './input/InputBuffer.ts';
+export { type InputAccessor, type InputAPI, type InputOptions, type NumericFieldsOf } from './input/InputBuffer.ts';
 import { ClockTimer as Clock } from '@colyseus/timer';
 import type { Presence } from './presence/Presence.ts';
 import type { Serializer } from './serializer/Serializer.ts';
@@ -6,12 +8,24 @@ import { type AuthContext, type Client, ClientArray, type ISendOptions, type Mes
 import { type RoomMethodName, type RoomException } from './errors/RoomExceptions.ts';
 import { type StandardSchemaV1 } from './utils/StandardSchema.ts';
 import { type MessageHandlerWithFormat as SharedMessageHandlerWithFormat, type MessageHandler as SharedMessageHandler, type Messages as SharedMessages } from '@colyseus/shared-types';
+import { RoomPlugin, type PluginLayout } from './RoomPlugin.ts';
+export { RoomPlugin, definePlugins, attachToTestRoom, type RoomPluginOrder, } from './RoomPlugin.ts';
 export declare const DEFAULT_SEAT_RESERVATION_TIME: number;
 export type SimulationCallback = (deltaTime: number) => void;
 export interface RoomOptions {
     state?: object;
     metadata?: any;
     client?: Client;
+    /**
+     * Schema class for client→server input packets. When set, the Room
+     * allocates one instance per joining client and binds an InputDecoder.
+     * Must be a flat Schema (primitive fields only — see InputEncoder docs).
+     *
+     * Typed loosely (no `Schema` constraint) to avoid type-identity clashes
+     * when the user's app loads a different copy of `@colyseus/schema` than
+     * `@colyseus/core` does. Runtime validation happens via the encoder.
+     */
+    input?: any;
 }
 export type ExtractRoomState<T> = T extends {
     state?: infer S extends object;
@@ -22,6 +36,9 @@ export type ExtractRoomMetadata<T> = T extends {
 export type ExtractRoomClient<T> = T extends {
     client?: infer C extends Client;
 } ? C : Client;
+export type ExtractRoomInput<T> = T extends {
+    input?: infer I;
+} ? I : never;
 export interface IBroadcastOptions extends ISendOptions {
     except?: Client | Client[];
 }
@@ -172,6 +189,44 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
     private _reconnections;
     private _reconnectionAttempts;
     messages?: Messages<any>;
+    /**
+     * Room plugins, keyed by an operator-chosen handle. Each plugin
+     * contributes any subset of: declarative message handlers (merged
+     * into `this.messages`), lifecycle hooks (composed with the room's
+     * own), and public methods callable via `this.plugins.<key>.X()`.
+     *
+     * The framework walks this record once per Room subclass to compute
+     * the lifecycle/message layout and install hook wrappers on the
+     * class prototype; subsequent constructs reuse the cached layout
+     * and just inject `.room` + merge messages.
+     *
+     * Use `definePlugins({...})` so TypeScript preserves each plugin's
+     * literal instance type. Frozen after `__init`.
+     */
+    plugins?: any;
+    /**
+     * Auto-included plugin instances pulled in via `static
+     * dependencies` declarations on user-registered plugins. Kept
+     * separate from `this.plugins` so the user's typed view doesn't
+     * gain framework-managed keys. Sentinel-keyed (`__dep:<ClassName>`)
+     * so the hook wrappers can route lookups to the right map.
+     *
+     * @internal
+     */
+    _autoPlugins?: Record<string, RoomPlugin<any>>;
+    /**
+     * Layout cache populated on the FIRST construction of each Room
+     * subclass. Holds the precomputed hook participation order + message
+     * key → plugin key mapping. Stored on the constructor (a static field)
+     * so all instances of the same class share it.
+     *
+     * `null` is a sentinel meaning "no plugins on this class" — distinct
+     * from `undefined` ("not yet computed") so we don't re-walk an empty
+     * plugin record on every construct.
+     *
+     * @internal
+     */
+    static __pluginLayout?: PluginLayout | null;
     private onMessageEvents;
     private onMessageValidators;
     private onMessageFallbacks;
@@ -248,6 +303,64 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
      * @param code - The close code of the leave event.
      */
     onLeave?(client: ExtractRoomClient<T>, code?: number): void | Promise<any>;
+    /**
+     * Per-client input accessor. Set by `defineInput()`. Call `room.input(sessionId)`
+     * each tick to read the latest decoded input and/or the buffered snapshot ring
+     * for that client.
+     *
+     * @example
+     * ```typescript
+     * class FpsRoom extends Room<{ input: MoveInput }> {
+     *   input = this.defineInput(MoveInput);
+     *
+     *   onCreate() {
+     *     this.setSimulationInterval(() => {
+     *       for (const c of this.clients) {
+     *         const input = this.input(c.sessionId);
+     *         if (input.latest) this.apply(c, input.latest);
+     *         // for rollback / lockstep:
+     *         //   const snapshot = input.at(this.clock.ticks);
+     *         //   for (const snapshot of input.drain()) ...
+     *       }
+     *     }, 1000 / 30);
+     *   }
+     * }
+     * ```
+     */
+    input?: InputAPI<ExtractRoomInput<T>>;
+    /**
+     * Input configuration. Set via {@link defineInput} only.
+     * @internal
+     */
+    private inputOptions?;
+    /**
+     * 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).
+     */
+    protected defineInput<C extends new () => any>(type: C, opts?: {
+        seqField?: NumericFieldsOf<InstanceType<C>>;
+        bufferMaxSize?: number;
+    }): InputAPI<InstanceType<C>>;
     /**
      * This method is called when the room is disposed.
      */
@@ -326,6 +439,38 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
      * @param delay - Interval delay on executing `onTickCallback` in milliseconds.
      */
     setSimulationInterval(onTickCallback?: SimulationCallback, delay?: number): void;
+    /**
+     * 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: (tick: number, deltaTime: number) => void, delay?: number, startTick?: number): void;
+    /**
+     * Current server tick. Incremented by {@link setTickedSimulation} after each
+     * tick callback returns. Returns 0 when no ticked simulation is running.
+     */
+    get tick(): number;
     /**
      * @deprecated Use `.patchRate=` instead.
      */
@@ -335,7 +480,7 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
      */
     setState(newState: ExtractRoomState<T>): void;
     setSerializer(serializer: Serializer<ExtractRoomState<T>>): void;
-    setMetadata(meta: Partial<ExtractRoomMetadata<T>>, persist?: boolean): Promise<void>;
+    setMetadata(meta: ExtractRoomMetadata<T>, persist?: boolean): Promise<void>;
     setPrivate(bool?: boolean, persist?: boolean): Promise<void>;
     /**
      * Update multiple matchmaking/listing properties at once with a single persist operation.
@@ -364,7 +509,8 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
      *
      * @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 }
      * });
@@ -439,6 +585,44 @@ export declare class Room<T extends RoomOptions = RoomOptions> {
     onMessage<T = any, C extends Client = ExtractRoomClient<T>>(messageType: string | number, validationSchema: StandardSchemaV1<T>, callback: (client: C, message: T) => void): any;
     onMessageBytes<T = any, C extends Client = ExtractRoomClient<T>>(messageType: string | number, callback: (client: C, message: T) => void): any;
     onMessageBytes<T = any, C extends Client = ExtractRoomClient<T>>(messageType: string | number, validationSchema: StandardSchemaV1<T>, callback: (client: C, message: T) => void): any;
+    /**
+     * 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(): {
+        roomId: string;
+        name: string;
+        clients: number;
+        maxClients: number;
+        locked: boolean;
+        elapsedTime: number;
+        metadata: any;
+        clientList: Array<{
+            sessionId: string;
+            userId: string | null;
+            userEmail: string | null;
+            elapsedTime: number;
+        }>;
+        state: any;
+        stateSize: number;
+    };
+    /**
+     * 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: string, closeCode?: number, reason?: string): void;
     /**
      * Disconnect all connected clients, and then dispose the room.
      *
@@ -485,4 +669,3 @@ type DefineRoomOptions<T extends RoomOptions = RoomOptions> = Partial<Pick<Room<
     state?: ExtractRoomState<T> | (() => ExtractRoomState<T>);
 } & ThisType<Exclude<Room<T>, RoomLifecycleMethods>> & ThisType<Room<T>>;
 export declare function room<T>(options: DefineRoomOptions<T>): typeof Room<T>;
-export {};