@colyseus/core 0.18.0 → 0.18.1

package/build/input/RoomInput.cjs

@@ -0,0 +1,306 @@
+"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);
+
+// packages/core/src/input/RoomInput.ts
+var RoomInput_exports = {};
+__export(RoomInput_exports, {
+  RoomInput: () => RoomInput
+});
+module.exports = __toCommonJS(RoomInput_exports);
+var import_schema = require("@colyseus/schema");
+var import_input = require("@colyseus/schema/input");
+var import_shared_types = require("@colyseus/shared-types");
+var import_InputBuffer = require("./InputBuffer.cjs");
+var import_Debug = require("../Debug.cjs");
+var _inputReflectionCache = /* @__PURE__ */ new WeakMap();
+var InputAPIImpl = class {
+  constructor(input) {
+    this.input = input;
+  }
+  /** Registry, not room.clients: an accessor outlives its client through the
+   *  reconnection window, so a dropped seat still synthesizes the idle policy. */
+  get(sessionId) {
+    return this.input.accessors.get(sessionId) ?? import_InputBuffer.NO_OP_INPUT_ACCESSOR;
+  }
+  // Live reads off `options` (mutated in place by a later setTimestep/
+  // setFixedTimestep back-fill, so a derived tickRate is reflected); 1/hz is
+  // correctly-rounded IEEE-754 → bit-identical to the client's stepSeconds.
+  get tickRate() {
+    return this.input.options.tickRate;
+  }
+  get stepSeconds() {
+    const hz = this.input.options.tickRate;
+    return hz ? 1 / hz : void 0;
+  }
+  get stepMs() {
+    const hz = this.input.options.tickRate;
+    return hz ? 1e3 / hz : void 0;
+  }
+  // Sub-step trio: same derivation as the client handle ((1/hz)/n) — bit-identical dt.
+  get subSteps() {
+    return this.input.options.subSteps ?? 1;
+  }
+  get subStepSeconds() {
+    const hz = this.input.options.tickRate;
+    return hz ? 1 / hz / (this.input.options.subSteps ?? 1) : void 0;
+  }
+  get subStepMs() {
+    const hz = this.input.options.tickRate;
+    return hz ? 1e3 / hz / (this.input.options.subSteps ?? 1) : void 0;
+  }
+};
+var RoomInput = class {
+  constructor(room) {
+    /** sessionId → accessor. Decoupled from `this.clients`: an entry outlives its
+     *  client across the reconnection window, so {@link InputAPI.get} keeps
+     *  synthesizing the idle policy for an absent seat (its buffer was cleared on
+     *  leave → idle). Set on join, deleted on full leave. Read by
+     *  {@link InputAPIImpl.get} (hence not `private`). */
+    this.accessors = /* @__PURE__ */ new Map();
+    // Wire stamp mode derived from the rewind timeline, resolved once on first
+    // handshake/decode then frozen so advertise + decode never disagree mid-session:
+    // the renderTime/reckonTime prefix per input.
+    this.#stampRender = false;
+    this.#stampReckon = false;
+    this.#stampResolved = false;
+    this.room = room;
+    this.nowOf = () => this.room.clock.elapsedTime;
+  }
+  #stampRender;
+  #stampReckon;
+  #stampResolved;
+  /**
+   * Build the input configuration + `InputAPI` (the body of
+   * {@link Room.defineInput}). Returns the api; the Room hands it back to
+   * userland and keeps the framework-owned reference.
+   */
+  define(type, opts) {
+    const tickRate = opts?.stepSeconds !== void 0 ? 1 / opts.stepSeconds : opts?.stepMs !== void 0 ? 1e3 / opts.stepMs : opts?.tickRate;
+    if (opts?.tickRate !== void 0 && opts.stepMs === void 0 && opts.stepSeconds === void 0 && (!Number.isInteger(opts.tickRate) || opts.tickRate > 240)) {
+      console.warn(
+        `[defineInput] tickRate is a rate in Hz (got ${opts.tickRate}); a value like 1000/rate is a step interval in ms \u2014 pass { stepMs } instead.`
+      );
+    }
+    this.options = {
+      ctor: type,
+      // Opt-in: a default would silently drop frames for any app with a numeric `seq` field.
+      seqField: opts?.seqField,
+      bufferMaxSize: opts?.bufferMaxSize ?? 32,
+      idle: opts?.idle,
+      // Compiled once (map → dense min/max walk); applied per decoded frame.
+      sanitize: opts?.sanitize !== void 0 ? (0, import_InputBuffer.compileSanitizer)(opts.sanitize) : void 0,
+      tickRate,
+      subSteps: (0, import_InputBuffer.validateSubSteps)(opts?.subSteps, "defineInput")
+    };
+    if (!_inputReflectionCache.has(type)) {
+      _inputReflectionCache.set(type, import_schema.Reflection.encode(new import_schema.Encoder(new type())));
+    }
+    const api = new InputAPIImpl(this);
+    this.api = api;
+    return api;
+  }
+  // --- per-client lifecycle (called from Room._onJoin/_onLeave/etc.) ---
+  /** Allocate the per-client input instance + decoder, the ring buffer (opt-in
+   *  via `bufferMaxSize > 0`, for rollback/lockstep), and the accessor. */
+  allocate(client) {
+    client._input = new this.options.ctor();
+    client._inputDecoder = new import_input.InputDecoder(client._input);
+    client._reckonBaseline = 0;
+    const maxSize = this.options.bufferMaxSize;
+    if (maxSize > 0) {
+      client._inputBuffer = new import_InputBuffer.InputBufferImpl(maxSize, this.options.seqField, this.options.ctor, client, this.options.idle);
+    }
+    client._inputAccessor = new import_InputBuffer.InputAccessorImpl(client, this.nowOf);
+  }
+  /** @internal Raw reckon stamp for {@link Room.allowRewindState}'s
+   *  `bindReckonTime` — bypasses the accessor's resolved getter so the rewind
+   *  midpoint fallback still engages for unstamped clients. instanceof-narrowed:
+   *  the registry only ever holds `InputAccessorImpl` (see {@link allocate}),
+   *  so the 0 fallback covers only a missing session. */
+  rawReckonTime(sessionId) {
+    const acc = this.accessors.get(sessionId);
+    return acc instanceof import_InputBuffer.InputAccessorImpl ? acc.rawReckonTime : 0;
+  }
+  /** Register a (re)joined client's accessor. On reconnect this overwrites the
+   *  dropped session's stale entry. Called after the client is in `this.clients`
+   *  (so a pre-push failure can't leak it) and before onJoin (so `get()` resolves
+   *  there). */
+  register(sessionId, client) {
+    this.accessors.set(sessionId, client._inputAccessor);
+  }
+  /** Freeze a leaving seat: drop pending inputs so a held (reconnecting) session
+   *  idles from the first tick rather than replaying last-known moves. `_input`
+   *  (the idle ctx's `latest`) is left intact. */
+  freeze(client) {
+    client._inputBuffer?.clear();
+  }
+  /** Drop a fully-gone session's accessor (delete of a missing key is a no-op). */
+  release(sessionId) {
+    this.accessors.delete(sessionId);
+  }
+  /** Release every held accessor (room dispose). */
+  dispose() {
+    this.accessors.clear();
+  }
+  // --- encode / decode (called from Room._onMessage) ---
+  /**
+   * Sanitize the freshly-decoded `client._input`, then (when buffering is on)
+   * push a clone into the per-client buffer. Honors the framework seq
+   * (unreliable) / a user `inputOptions.seqField` (reliable) to dedupe the
+   * redundancy ring.
+   */
+  capture(client, renderTime = 0, reckonTime = 0, seq) {
+    this.options.sanitize?.(client._input);
+    const buf = client._inputBuffer;
+    if (!buf) {
+      return;
+    }
+    const inst = client._input;
+    if (seq !== void 0) {
+      if (!buf.accept(seq)) {
+        return;
+      }
+    } else {
+      const seqField = this.options.seqField;
+      if (seqField !== void 0) {
+        const value = inst[seqField];
+        if (typeof value === "number" && !buf.accept(value)) {
+          return;
+        }
+      }
+    }
+    buf.push(inst.clone(), renderTime, reckonTime, seq);
+  }
+  /** Decode a `ROOM_INPUT_RELIABLE` frame: an optional TIMED stamp prefix (shape
+   *  set by this room's derived stamp mode) then the input body. `it` starts at
+   *  offset 1, so the body begins at `it.offset`. */
+  decodeReliable(client, buffer, it, modifiers) {
+    if (!client._inputDecoder) {
+      return;
+    }
+    let renderTime = 0;
+    let reckonTime = 0;
+    if (modifiers & import_shared_types.ProtocolModifier.TIMED) {
+      this.#resolveWireModes();
+      const stamp = client._reckonBaseline += import_schema.decode.number(buffer, it);
+      if (this.#stampReckon && this.#stampRender) {
+        reckonTime = stamp;
+        const renderDelta = import_schema.decode.uint16(buffer, it);
+        renderTime = stamp > renderDelta ? stamp - renderDelta : 0;
+      } else if (this.#stampReckon) {
+        reckonTime = stamp;
+      } else {
+        renderTime = stamp;
+      }
+    }
+    try {
+      client._inputDecoder.decode(buffer.subarray(it.offset, buffer.byteLength));
+    } catch (e) {
+      (0, import_Debug.debugAndPrintError)(e);
+      return;
+    }
+    client._lastInputReceivedAt = performance.now();
+    client._receivedInputCount = (client._receivedInputCount ?? 0) + 1;
+    this.capture(client, renderTime, reckonTime);
+  }
+  /** Decode a `ROOM_INPUT_UNRELIABLE` redundancy ring — each slot carries its
+   *  framework seq (base seq + position) for ring dedupe, no user seqField. */
+  decodeUnreliable(client, buffer, _modifiers) {
+    if (!client._inputDecoder) {
+      return;
+    }
+    try {
+      client._inputDecoder.decodeAll(buffer.subarray(1), (_inst, seq) => this.capture(client, 0, 0, seq));
+    } catch (e) {
+      (0, import_Debug.debugAndPrintError)(e);
+      return;
+    }
+    client._lastInputReceivedAt = performance.now();
+  }
+  // --- handshake + stamp mode ---
+  /** Resolve the wire stamp mode from the rewind timeline (once, then frozen). */
+  #resolveWireModes() {
+    if (this.#stampResolved) return;
+    this.#stampResolved = true;
+    const tl = this.room._timelineMode();
+    this.#stampRender = tl?.snapshot ?? false;
+    this.#stampReckon = tl?.reckon ?? false;
+  }
+  /**
+   * The join-handshake input sections: INPUT_REFLECTION (the SDK-deserializable
+   * input ctor bytes) and, when any runtime config differs from defaults,
+   * INPUT_OPTIONS (`[flags uint8][tickRate varint?][patchRate varint?][subSteps
+   * varint?]`). The client mirrors RENDER_TIME/RECKON_TIME (auto-stamp timeline),
+   * tickRate (predict at dt=1/tickRate), patchRate (reconcile cadence), and
+   * subSteps (physics sub-steps per input, omitted when 1). Returns `undefined`
+   * when there's nothing to add.
+   */
+  handshakeSections() {
+    let sections;
+    const inputBytes = _inputReflectionCache.get(this.options.ctor);
+    if (inputBytes !== void 0) {
+      sections = [{ tag: import_shared_types.HandshakeSection.INPUT_REFLECTION, bytes: inputBytes }];
+    }
+    this.#resolveWireModes();
+    const stampRender = this.#stampRender;
+    const stampReckon = this.#stampReckon;
+    const tickRate = this.options.tickRate;
+    const patchRate = typeof this.room.patchRate === "number" && this.room.patchRate > 0 ? Math.round(this.room.patchRate) : void 0;
+    const subSteps = this.options.subSteps !== void 0 && this.options.subSteps > 1 ? this.options.subSteps : void 0;
+    if (stampRender || stampReckon || tickRate || patchRate || subSteps) {
+      let flags = 0;
+      if (stampRender) {
+        flags |= import_shared_types.InputFlags.RENDER_TIME;
+      }
+      if (stampReckon) {
+        flags |= import_shared_types.InputFlags.RECKON_TIME;
+      }
+      if (tickRate) {
+        flags |= import_shared_types.InputFlags.FIXED_TIMESTEP;
+      }
+      if (patchRate) {
+        flags |= import_shared_types.InputFlags.PATCH_RATE;
+      }
+      if (subSteps) {
+        flags |= import_shared_types.InputFlags.SUB_STEPS;
+      }
+      const buf = new Uint8Array(24);
+      const sit = { offset: 0 };
+      buf[sit.offset++] = flags;
+      if (tickRate) {
+        import_schema.encode.number(buf, tickRate, sit);
+      }
+      if (patchRate) {
+        import_schema.encode.number(buf, patchRate, sit);
+      }
+      if (subSteps) {
+        import_schema.encode.number(buf, subSteps, sit);
+      }
+      (sections ??= []).push({
+        tag: import_shared_types.HandshakeSection.INPUT_OPTIONS,
+        bytes: buf.subarray(0, sit.offset)
+      });
+    }
+    return sections;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RoomInput
+});

package/build/input/RoomInput.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/input/RoomInput.ts"],
+  "sourcesContent": ["import { decode, encode, Encoder, Reflection, type Iterator } from '@colyseus/schema';\nimport { InputDecoder } from '@colyseus/schema/input';\nimport { HandshakeSection, InputFlags, ProtocolModifier } from '@colyseus/shared-types';\n\nimport {\n  InputAccessorImpl, InputBufferImpl, NO_OP_INPUT_ACCESSOR,\n  compileSanitizer, validateSubSteps,\n} from './InputBuffer.ts';\nimport type {\n  InputAccessor, InputAPI, NormalizedInputOptions,\n  DefineInputOptions, IdleDeclared,\n} from './types.ts';\nimport type { Client, ClientPrivate } from '../Transport.ts';\nimport type { Room } from '../Room.ts';\nimport { debugAndPrintError } from '../Debug.ts';\n\n/**\n * Module-level cache of `Reflection.encode` output keyed by input\n * constructor \u2014 pays the encoding cost once per Room class regardless of\n * room instance count. WeakMap so unused classes can be GC'd.\n */\nconst _inputReflectionCache = new WeakMap<Function, Uint8Array>();\n\n/**\n * Runtime behind {@link InputAPI}. A class, not a per-`define()` object literal:\n * literal (and `defineProperty`) accessors carry their closure identity in the\n * hidden class, so every room instance would get a UNIQUE map \u2014 sending shared\n * `this.inputs.*` call sites megamorphic. Prototype getters are created once,\n * every instance shares one hidden class (reads stay monomorphic), and\n * `define()` allocates a single 1-field object instead of 7 closures + a map\n * lineage per room.\n *\n * @internal\n */\nclass InputAPIImpl {\n  private input: RoomInput;\n  constructor(input: RoomInput) { this.input = input; }\n  /** Registry, not room.clients: an accessor outlives its client through the\n   *  reconnection window, so a dropped seat still synthesizes the idle policy. */\n  get(sessionId: string): InputAccessor<any> {\n    return this.input.accessors.get(sessionId) ?? NO_OP_INPUT_ACCESSOR;\n  }\n  // Live reads off `options` (mutated in place by a later setTimestep/\n  // setFixedTimestep back-fill, so a derived tickRate is reflected); 1/hz is\n  // correctly-rounded IEEE-754 \u2192 bit-identical to the client's stepSeconds.\n  get tickRate(): number | undefined { return this.input.options.tickRate; }\n  get stepSeconds(): number | undefined { const hz = this.input.options.tickRate; return hz ? 1 / hz : undefined; }\n  get stepMs(): number | undefined { const hz = this.input.options.tickRate; return hz ? 1000 / hz : undefined; }\n  // Sub-step trio: same derivation as the client handle ((1/hz)/n) \u2014 bit-identical dt.\n  get subSteps(): number { return this.input.options.subSteps ?? 1; }\n  get subStepSeconds(): number | undefined { const hz = this.input.options.tickRate; return hz ? (1 / hz) / (this.input.options.subSteps ?? 1) : undefined; }\n  get subStepMs(): number | undefined { const hz = this.input.options.tickRate; return hz ? (1000 / hz) / (this.input.options.subSteps ?? 1) : undefined; }\n}\n\n/**\n * Per-room input subsystem, owned by {@link Room} and created lazily on the\n * first {@link Room.defineInput} call \u2014 rooms without inputs allocate none of\n * it. Owns the input options, the per-session accessor registry (decoupled\n * from `this.clients` so an entry outlives a dropped client across its\n * reconnection window), the wire stamp mode, and the encode/decode/handshake\n * machinery. Reads back into its Room for context it doesn't own (the patch\n * rate and the rewind timeline mode).\n *\n * @internal\n */\nexport class RoomInput {\n  /** Owning room \u2014 for `patchRate` and the rewind timeline mode. */\n  private room: Room<any>;\n\n  /** Input configuration (ctor, seqField, bufferMaxSize, idle, sanitize,\n   *  tickRate, subSteps). `tickRate`/`subSteps` may be back-filled by\n   *  `setTimestep`/`setFixedTimestep`. Set in {@link define}. */\n  options!: NormalizedInputOptions;\n\n  /** The `InputAPI` returned to userland from `defineInput`, also the\n   *  framework-owned handle the rewind binding resolves accessors through. */\n  api!: InputAPI<any>;\n\n  /** sessionId \u2192 accessor. Decoupled from `this.clients`: an entry outlives its\n   *  client across the reconnection window, so {@link InputAPI.get} keeps\n   *  synthesizing the idle policy for an absent seat (its buffer was cleared on\n   *  leave \u2192 idle). Set on join, deleted on full leave. Read by\n   *  {@link InputAPIImpl.get} (hence not `private`). */\n  readonly accessors: Map<string, InputAccessor<any>> = new Map();\n\n  // Wire stamp mode derived from the rewind timeline, resolved once on first\n  // handshake/decode then frozen so advertise + decode never disagree mid-session:\n  // the renderTime/reckonTime prefix per input.\n  #stampRender = false;\n  #stampReckon = false;\n  #stampResolved = false;\n\n  /** One shared now-resolver handed to every accessor (see {@link InputAccessorImpl}). */\n  private nowOf: () => number;\n\n  constructor(room: Room<any>) {\n    this.room = room;\n    this.nowOf = () => this.room.clock.elapsedTime;\n  }\n\n  /**\n   * Build the input configuration + `InputAPI` (the body of\n   * {@link Room.defineInput}). Returns the api; the Room hands it back to\n   * userland and keeps the framework-owned reference.\n   */\n  define<\n    C extends new () => any,\n    O extends DefineInputOptions<InstanceType<C>> = DefineInputOptions<InstanceType<C>>,\n  >(\n    type: C,\n    opts?: O,\n  ): InputAPI<InstanceType<C>, IdleDeclared<O, InstanceType<C>>> {\n    // Normalize the step declaration to the canonical wire form (Hz). stepSeconds\n    // / stepMs are the unit-safe spellings; both sides derive dt = 1/tickRate, so\n    // one declared number drives the server's physics step AND the client's.\n    const tickRate =\n      opts?.stepSeconds !== undefined ? 1 / opts.stepSeconds :\n      opts?.stepMs !== undefined ? 1000 / opts.stepMs :\n      opts?.tickRate;\n    if (\n      opts?.tickRate !== undefined && opts.stepMs === undefined && opts.stepSeconds === undefined &&\n      (!Number.isInteger(opts.tickRate) || opts.tickRate > 240)\n    ) {\n      console.warn(\n        `[defineInput] tickRate is a rate in Hz (got ${opts.tickRate}); a value ` +\n        `like 1000/rate is a step interval in ms \u2014 pass { stepMs } instead.`,\n      );\n    }\n    this.options = {\n      ctor: type,\n      // Opt-in: a default would silently drop frames for any app with a numeric `seq` field.\n      seqField: opts?.seqField,\n      bufferMaxSize: opts?.bufferMaxSize ?? 32,\n      idle: opts?.idle,\n      // Compiled once (map \u2192 dense min/max walk); applied per decoded frame.\n      sanitize: opts?.sanitize !== undefined ? compileSanitizer(opts.sanitize) : undefined,\n      tickRate,\n      subSteps: validateSubSteps(opts?.subSteps, 'defineInput'),\n    };\n    if (!_inputReflectionCache.has(type)) {\n      // SDK-deserializable ctor bytes (Reflection.decode rebuilds the ctor client-side).\n      _inputReflectionCache.set(type, Reflection.encode(new Encoder(new type())));\n    }\n    const api = new InputAPIImpl(this) as InputAPI<InstanceType<C>, IdleDeclared<O, InstanceType<C>>>;\n    this.api = api;\n    return api;\n  }\n\n  // --- per-client lifecycle (called from Room._onJoin/_onLeave/etc.) ---\n\n  /** Allocate the per-client input instance + decoder, the ring buffer (opt-in\n   *  via `bufferMaxSize > 0`, for rollback/lockstep), and the accessor. */\n  allocate(client: Client & ClientPrivate): void {\n    client._input = new this.options.ctor();\n    client._inputDecoder = new InputDecoder(client._input);\n    client._reckonBaseline = 0; // mirrors the SDK's delta-coded stamp baseline (reset together on (re)connect)\n    const maxSize = this.options.bufferMaxSize;\n    if (maxSize > 0) {\n      // ctor \u2192 idle synthesis; client ref \u2192 idle ctx; idle policy \u2192 total drain()/next().\n      client._inputBuffer = new InputBufferImpl(maxSize, this.options.seqField, this.options.ctor, client, this.options.idle);\n    }\n    client._inputAccessor = new InputAccessorImpl(client, this.nowOf);\n  }\n\n  /** @internal Raw reckon stamp for {@link Room.allowRewindState}'s\n   *  `bindReckonTime` \u2014 bypasses the accessor's resolved getter so the rewind\n   *  midpoint fallback still engages for unstamped clients. instanceof-narrowed:\n   *  the registry only ever holds `InputAccessorImpl` (see {@link allocate}),\n   *  so the 0 fallback covers only a missing session. */\n  rawReckonTime(sessionId: string): number {\n    const acc = this.accessors.get(sessionId);\n    return acc instanceof InputAccessorImpl ? acc.rawReckonTime : 0;\n  }\n\n  /** Register a (re)joined client's accessor. On reconnect this overwrites the\n   *  dropped session's stale entry. Called after the client is in `this.clients`\n   *  (so a pre-push failure can't leak it) and before onJoin (so `get()` resolves\n   *  there). */\n  register(sessionId: string, client: ClientPrivate): void {\n    this.accessors.set(sessionId, client._inputAccessor!);\n  }\n\n  /** Freeze a leaving seat: drop pending inputs so a held (reconnecting) session\n   *  idles from the first tick rather than replaying last-known moves. `_input`\n   *  (the idle ctx's `latest`) is left intact. */\n  freeze(client: ClientPrivate): void {\n    client._inputBuffer?.clear();\n  }\n\n  /** Drop a fully-gone session's accessor (delete of a missing key is a no-op). */\n  release(sessionId: string): void {\n    this.accessors.delete(sessionId);\n  }\n\n  /** Release every held accessor (room dispose). */\n  dispose(): void {\n    this.accessors.clear();\n  }\n\n  // --- encode / decode (called from Room._onMessage) ---\n\n  /**\n   * Sanitize the freshly-decoded `client._input`, then (when buffering is on)\n   * push a clone into the per-client buffer. Honors the framework seq\n   * (unreliable) / a user `inputOptions.seqField` (reliable) to dedupe the\n   * redundancy ring.\n   */\n  capture(client: ClientPrivate, renderTime: number = 0, reckonTime: number = 0, seq?: number): void {\n    // Sanitize before anything reads it (latest, the clone below, the idle ctx).\n    this.options.sanitize?.(client._input);\n    const buf = client._inputBuffer;\n    if (!buf) { return; } // no consumer registered \u2014 skip the clone allocation\n    const inst = client._input!;\n    if (seq !== undefined) {\n      // Unreliable: dedup the ring by the framework wire seq (user seqField is for .at() only).\n      if (!buf.accept(seq)) { return; }\n    } else {\n      // Reliable: no framework seq (implicit count). Honor a user `seqField` if set.\n      const seqField = this.options.seqField;\n      if (seqField !== undefined) {\n        const value = (inst as any)[seqField] as number;\n        if (typeof value === 'number' && !buf.accept(value)) { return; }\n      }\n    }\n    buf.push(inst.clone() as any, renderTime, reckonTime, seq);\n  }\n\n  /** Decode a `ROOM_INPUT_RELIABLE` frame: an optional TIMED stamp prefix (shape\n   *  set by this room's derived stamp mode) then the input body. `it` starts at\n   *  offset 1, so the body begins at `it.offset`. */\n  decodeReliable(client: ClientPrivate, buffer: Buffer, it: Iterator, modifiers: number): void {\n    if (!client._inputDecoder) { return; }\n    // Optional stamp prefix (TIMED bit), DELTA-CODED, length set by this room's\n    // stamp mode (the timeline value is reconstructed against the per-client\n    // baseline; the wire carries only the signed change from the previous frame):\n    //   both:        [varint \u0394reckon][uint16 renderDelta] \u2192 renderTime = reckon \u2212 renderDelta\n    //   reckon-only: [varint \u0394reckon]\n    //   render-only: [varint \u0394render]\n    let renderTime = 0;\n    let reckonTime = 0;\n    if (modifiers & ProtocolModifier.TIMED) {\n      this.#resolveWireModes();\n      // Reconstruct the absolute timeline value: baseline += signed delta. Both\n      // sides start at 0 (so the first delta is absolute) and re-zero together on\n      // (re)connect; reliable+in-order keeps the mirror locked.\n      const stamp = client._reckonBaseline! += decode.number(buffer, it);\n      if (this.#stampReckon && this.#stampRender) {\n        reckonTime = stamp;\n        const renderDelta = decode.uint16(buffer, it);\n        renderTime = stamp > renderDelta ? stamp - renderDelta : 0;\n      } else if (this.#stampReckon) {\n        reckonTime = stamp;\n      } else {\n        renderTime = stamp;\n      }\n    }\n    try {\n      client._inputDecoder.decode(buffer.subarray(it.offset, buffer.byteLength));\n    } catch (e: any) {\n      debugAndPrintError(e);\n      return;\n    }\n    client._lastInputReceivedAt = performance.now();\n    // Mirrors the SDK's sent count; echoed back as lastInputSeq for RTT.\n    client._receivedInputCount = (client._receivedInputCount ?? 0) + 1;\n    this.capture(client, renderTime, reckonTime);\n  }\n\n  /** Decode a `ROOM_INPUT_UNRELIABLE` redundancy ring \u2014 each slot carries its\n   *  framework seq (base seq + position) for ring dedupe, no user seqField. */\n  decodeUnreliable(client: ClientPrivate, buffer: Buffer, _modifiers: number): void {\n    if (!client._inputDecoder) { return; }\n    try {\n      client._inputDecoder.decodeAll(buffer.subarray(1), (_inst, seq) => this.capture(client, 0, 0, seq));\n    } catch (e: any) {\n      debugAndPrintError(e);\n      return;\n    }\n    client._lastInputReceivedAt = performance.now();\n  }\n\n  // --- handshake + stamp mode ---\n\n  /** Resolve the wire stamp mode from the rewind timeline (once, then frozen). */\n  #resolveWireModes(): void {\n    if (this.#stampResolved) return;\n    this.#stampResolved = true;\n    const tl = this.room._timelineMode();\n    this.#stampRender = tl?.snapshot ?? false;\n    this.#stampReckon = tl?.reckon ?? false;\n  }\n\n  /**\n   * The join-handshake input sections: INPUT_REFLECTION (the SDK-deserializable\n   * input ctor bytes) and, when any runtime config differs from defaults,\n   * INPUT_OPTIONS (`[flags uint8][tickRate varint?][patchRate varint?][subSteps\n   * varint?]`). The client mirrors RENDER_TIME/RECKON_TIME (auto-stamp timeline),\n   * tickRate (predict at dt=1/tickRate), patchRate (reconcile cadence), and\n   * subSteps (physics sub-steps per input, omitted when 1). Returns `undefined`\n   * when there's nothing to add.\n   */\n  handshakeSections(): Array<{ tag: number; bytes: Uint8Array }> | undefined {\n    let sections: Array<{ tag: number; bytes: Uint8Array }> | undefined;\n    const inputBytes = _inputReflectionCache.get(this.options.ctor);\n    if (inputBytes !== undefined) {\n      sections = [{ tag: HandshakeSection.INPUT_REFLECTION, bytes: inputBytes }];\n    }\n    this.#resolveWireModes();\n    const stampRender = this.#stampRender;\n    const stampReckon = this.#stampReckon;\n    const tickRate = this.options.tickRate;\n    const patchRate = (typeof this.room.patchRate === \"number\" && this.room.patchRate > 0)\n      ? Math.round(this.room.patchRate) : undefined;\n    const subSteps = (this.options.subSteps !== undefined && this.options.subSteps > 1)\n      ? this.options.subSteps : undefined;\n    if (stampRender || stampReckon || tickRate || patchRate || subSteps) {\n      let flags = 0;\n      if (stampRender) { flags |= InputFlags.RENDER_TIME; }\n      if (stampReckon) { flags |= InputFlags.RECKON_TIME; }\n      if (tickRate) { flags |= InputFlags.FIXED_TIMESTEP; }\n      if (patchRate) { flags |= InputFlags.PATCH_RATE; }\n      if (subSteps) { flags |= InputFlags.SUB_STEPS; }\n      // 24B: worst case = flags + float64 tickRate (9) + uint32 patchRate (5) + subSteps (2).\n      const buf = new Uint8Array(24);\n      const sit = { offset: 0 };\n      buf[sit.offset++] = flags;\n      if (tickRate) { encode.number(buf, tickRate, sit); }\n      if (patchRate) { encode.number(buf, patchRate, sit); }\n      if (subSteps) { encode.number(buf, subSteps, sit); }\n      (sections ??= []).push({\n        tag: HandshakeSection.INPUT_OPTIONS,\n        bytes: buf.subarray(0, sit.offset),\n      });\n    }\n    return sections;\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/build/input/RoomInput.d.ts

@@ -0,0 +1,91 @@
+import { type Iterator } from '@colyseus/schema';
+import type { InputAccessor, InputAPI, NormalizedInputOptions, DefineInputOptions, IdleDeclared } from './types.ts';
+import type { Client, ClientPrivate } from '../Transport.ts';
+import type { Room } from '../Room.ts';
+/**
+ * Per-room input subsystem, owned by {@link Room} and created lazily on the
+ * first {@link Room.defineInput} call — rooms without inputs allocate none of
+ * it. Owns the input options, the per-session accessor registry (decoupled
+ * from `this.clients` so an entry outlives a dropped client across its
+ * reconnection window), the wire stamp mode, and the encode/decode/handshake
+ * machinery. Reads back into its Room for context it doesn't own (the patch
+ * rate and the rewind timeline mode).
+ *
+ * @internal
+ */
+export declare class RoomInput {
+    #private;
+    /** Owning room — for `patchRate` and the rewind timeline mode. */
+    private room;
+    /** Input configuration (ctor, seqField, bufferMaxSize, idle, sanitize,
+     *  tickRate, subSteps). `tickRate`/`subSteps` may be back-filled by
+     *  `setTimestep`/`setFixedTimestep`. Set in {@link define}. */
+    options: NormalizedInputOptions;
+    /** The `InputAPI` returned to userland from `defineInput`, also the
+     *  framework-owned handle the rewind binding resolves accessors through. */
+    api: InputAPI<any>;
+    /** sessionId → accessor. Decoupled from `this.clients`: an entry outlives its
+     *  client across the reconnection window, so {@link InputAPI.get} keeps
+     *  synthesizing the idle policy for an absent seat (its buffer was cleared on
+     *  leave → idle). Set on join, deleted on full leave. Read by
+     *  {@link InputAPIImpl.get} (hence not `private`). */
+    readonly accessors: Map<string, InputAccessor<any>>;
+    /** One shared now-resolver handed to every accessor (see {@link InputAccessorImpl}). */
+    private nowOf;
+    constructor(room: Room<any>);
+    /**
+     * Build the input configuration + `InputAPI` (the body of
+     * {@link Room.defineInput}). Returns the api; the Room hands it back to
+     * userland and keeps the framework-owned reference.
+     */
+    define<C extends new () => any, O extends DefineInputOptions<InstanceType<C>> = DefineInputOptions<InstanceType<C>>>(type: C, opts?: O): InputAPI<InstanceType<C>, IdleDeclared<O, InstanceType<C>>>;
+    /** Allocate the per-client input instance + decoder, the ring buffer (opt-in
+     *  via `bufferMaxSize > 0`, for rollback/lockstep), and the accessor. */
+    allocate(client: Client & ClientPrivate): void;
+    /** @internal Raw reckon stamp for {@link Room.allowRewindState}'s
+     *  `bindReckonTime` — bypasses the accessor's resolved getter so the rewind
+     *  midpoint fallback still engages for unstamped clients. instanceof-narrowed:
+     *  the registry only ever holds `InputAccessorImpl` (see {@link allocate}),
+     *  so the 0 fallback covers only a missing session. */
+    rawReckonTime(sessionId: string): number;
+    /** Register a (re)joined client's accessor. On reconnect this overwrites the
+     *  dropped session's stale entry. Called after the client is in `this.clients`
+     *  (so a pre-push failure can't leak it) and before onJoin (so `get()` resolves
+     *  there). */
+    register(sessionId: string, client: ClientPrivate): void;
+    /** Freeze a leaving seat: drop pending inputs so a held (reconnecting) session
+     *  idles from the first tick rather than replaying last-known moves. `_input`
+     *  (the idle ctx's `latest`) is left intact. */
+    freeze(client: ClientPrivate): void;
+    /** Drop a fully-gone session's accessor (delete of a missing key is a no-op). */
+    release(sessionId: string): void;
+    /** Release every held accessor (room dispose). */
+    dispose(): void;
+    /**
+     * Sanitize the freshly-decoded `client._input`, then (when buffering is on)
+     * push a clone into the per-client buffer. Honors the framework seq
+     * (unreliable) / a user `inputOptions.seqField` (reliable) to dedupe the
+     * redundancy ring.
+     */
+    capture(client: ClientPrivate, renderTime?: number, reckonTime?: number, seq?: number): void;
+    /** Decode a `ROOM_INPUT_RELIABLE` frame: an optional TIMED stamp prefix (shape
+     *  set by this room's derived stamp mode) then the input body. `it` starts at
+     *  offset 1, so the body begins at `it.offset`. */
+    decodeReliable(client: ClientPrivate, buffer: Buffer, it: Iterator, modifiers: number): void;
+    /** 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;
+    /**
+     * The join-handshake input sections: INPUT_REFLECTION (the SDK-deserializable
+     * input ctor bytes) and, when any runtime config differs from defaults,
+     * INPUT_OPTIONS (`[flags uint8][tickRate varint?][patchRate varint?][subSteps
+     * varint?]`). The client mirrors RENDER_TIME/RECKON_TIME (auto-stamp timeline),
+     * tickRate (predict at dt=1/tickRate), patchRate (reconcile cadence), and
+     * subSteps (physics sub-steps per input, omitted when 1). Returns `undefined`
+     * when there's nothing to add.
+     */
+    handshakeSections(): Array<{
+        tag: number;
+        bytes: Uint8Array;
+    }> | undefined;
+}