@colyseus/core 0.17.44 → 0.18.1

package/build/Rewind.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/Rewind.ts"],
+  "sourcesContent": ["import { $values, type MapSchema, type ArraySchema, type SetSchema } from \"@colyseus/schema\";\nimport { $METADATA } from \"./utils/Utils.ts\";\n\nconst DEFAULT_MAX_REWIND_MS = 500;\n/** Ring-sizing fallback when the record cadence isn't supplied (manual `record(now)`\n *  without a hint). `allowRewindState` feeds the real sim interval, so this only\n *  matters for ad-hoc manual use. */\nconst DEFAULT_SAMPLE_INTERVAL_MS = 1000 / 60;\n\n// Hot record() path: dense `$values[index]` is ~15\u00D7 faster than `inst[fieldName]`; entity symbol prop ~8\u00D7 faster than a WeakMap.\n/** Per-entity history, under this private symbol ON the entity. Symbol-keyed so it's\n *  invisible to Object.keys / `assign` / `clone`, and GC'd with the entity. */\nconst $HISTORY = Symbol(\"rewind.history\");\n\n/** Keys of T whose value type is `number` \u2014 the only rewindable fields. */\ntype NumericKeys<T> = { [K in keyof T]-?: T[K] extends number ? K : never }[keyof T] & string;\n/** A Colyseus collection whose element type is `E`. Inferring `E` from the live\n *  collection the caller passes is what lets `fields` narrow with zero state-type\n *  plumbing. */\ntype Collection<E> = MapSchema<E> | ArraySchema<E> | SetSchema<E>;\n\n/** Options for {@link Rewind.get} / {@link Room.allowRewindState}. */\nexport interface RewindOptions {\n  /** Default rewind window (ms) for attaches that don't pass their own \u2014 sizes the\n   *  per-entity history ring. Per-attach `maxRewindMs` overrides it. Default 500. */\n  maxRewindMs?: number;\n}\n\n/** Field's `$values` index from the schema metadata (`metadata[name]` = index), or\n *  -1 if unknown. Resolved ONCE per constructor (cold path), never per tick. */\nfunction fieldIndexOf(instance: object, field: string): number {\n  const md = (instance.constructor as any)[$METADATA] as Record<string, unknown> | undefined;\n  const idx = md?.[field];\n  return typeof idx === \"number\" ? idx : -1;\n}\n\n/** The lag-comp technique an attach-group rewinds to \u2014 the TIMELINE the client\n *  displays those targets on. `\"snapshot\"` (default): the renderTime stamp (what\n *  a lerping/damped client shows, behind real time). `\"reckon\"`: the reckonTime\n *  stamp (what a forward-extrapolated client shows, \u2248 serverNow). Declared at\n *  {@link Rewind.attachAll}, not on the schema. */\nexport type RewindMode = \"snapshot\" | \"reckon\";\n\n/**\n * Per-entity ring of recent field snapshots. `valueAt(time, col)` reconstructs\n * one field's recorded PATH at an arbitrary past time \u2014 `linear` interp for\n * continuous motion (patrol, a sine bob), or `step` (hold the last value) for\n * discrete motion (teleport snaps), where a lerp would smear across the jump.\n */\nclass EntityHistory {\n  readonly fields: readonly string[];\n  /** The attach-group's `mode: \"reckon\"` technique, mirrored here so a view can\n   *  pick its aim time PER FIELD (each field's covering history carries it). */\n  readonly reckoned: boolean;\n  /** The attach-group this history belongs to. One entity can have several\n   *  histories (attached to multiple groups over disjoint fields); `record()`\n   *  finds the right one by this id. */\n  readonly groupId: number;\n  /** Each tracked field's index into the entity's dense `$values` array \u2014\n   *  resolved per CONSTRUCTOR (mixed-type collections differ per type). */\n  private readonly fieldIdx: readonly number[];\n  private readonly cap: number;\n  private readonly t: Float64Array;\n  private readonly cols: Float64Array[];   // one column per field\n  private readonly step: boolean;           // hold (vs lerp) between samples\n  private head = 0;                         // next write slot\n  private count = 0;\n\n  constructor(fields: readonly string[], fieldIdx: readonly number[], maxRewindMs: number, sampleIntervalMs: number, step: boolean, reckoned: boolean, groupId: number) {\n    this.fields = fields;\n    this.fieldIdx = fieldIdx;\n    this.step = step;\n    this.reckoned = reckoned;\n    this.groupId = groupId;\n    this.cap = Math.max(2, Math.ceil(maxRewindMs / sampleIntervalMs) + 4);\n    this.t = new Float64Array(this.cap);\n    this.cols = fields.map(() => new Float64Array(this.cap));\n  }\n\n  /** `values` = the entity's dense `$values` array. Direct array reads \u2014 no\n   *  per-field megamorphic accessor. */\n  record(time: number, values: ArrayLike<number>): void {\n    const fieldIdx = this.fieldIdx;\n    this.t[this.head] = time;\n    for (let f = 0; f < fieldIdx.length; f++) this.cols[f][this.head] = values[fieldIdx[f]];\n    this.head = (this.head + 1) % this.cap;\n    if (this.count < this.cap) this.count++;\n  }\n\n  /** Interpolated value of column `col` at `time`, clamped to the retained range. */\n  valueAt(time: number, col: number): number {\n    const c = this.cols[col];\n    const oldest = (this.head - this.count + this.cap) % this.cap;\n    if (time <= this.t[oldest]) return c[oldest];\n    const newest = (this.head - 1 + this.cap) % this.cap;\n    if (time >= this.t[newest]) return c[newest];\n    let prev = oldest;\n    for (let i = 1; i < this.count; i++) {\n      const idx = (oldest + i) % this.cap;\n      if (this.t[idx] >= time) {\n        if (this.step) return c[prev];   // discrete: hold the value before `time`\n        const t0 = this.t[prev], t1 = this.t[idx];\n        const a = t1 > t0 ? (time - t0) / (t1 - t0) : 0;\n        return c[prev] + (c[idx] - c[prev]) * a;\n      }\n      prev = idx;\n    }\n    return c[newest];   // unreachable: `newest` guard above covers it\n  }\n}\n\n/** The histories an entity accumulates \u2014 one per attach-group it belongs to\n *  (length 1 in the common single-group case). Stored under {@link $HISTORY} on\n *  the entity; GC'd with it. */\ntype EntityHistories = EntityHistory[];\n\n/** Find the history covering `field` (the group that recorded it), or undefined\n *  \u2192 read live. Disjoint field sets across groups make the first match the only\n *  match; the scan is length-1 in every common case. */\nfunction historyForField(instance: object, field: string): EntityHistory | undefined {\n  const arr = (instance as any)[$HISTORY] as EntityHistories | undefined;\n  if (arr === undefined) return undefined;\n  for (let i = 0; i < arr.length; i++) {\n    if (arr[i].fields.indexOf(field) >= 0) return arr[i];\n  }\n  return undefined;\n}\n\n/** How `valueAt` reconstructs a value between recorded samples: `linear` interp\n *  (continuous motion) or `step` = hold the last sample (discrete motion). */\ntype Interp = \"linear\" | \"step\";\n\n/**\n * A read-only view of the tracked world at ONE past time \u2014 the rewound state a\n * hit test reads instead of live positions. Created by {@link Rewind.at} /\n * {@link Rewind.lastSeenBy}, which bake in the `maxRewindMs` clamp and the\n * live-fallback so callers never re-implement either.\n *\n * The view assumes NOTHING about your schema's field names \u2014 you name the\n * fields (and therefore the shape) at the call site:\n *\n * ```ts\n * const seen = rewind.lastSeenBy(shooterSessionId);\n * // read fields directly\u2026\n * overlaps(bullet, seen.value(target, \"x\"), seen.value(target, \"y\"));\n * // \u2026or batch them into an object shaped by YOUR field list:\n * const pos = seen.read(target, [\"x\", \"y\"]);        // { x, y }\n * seen.read(enemy, [\"x\", \"y\"], this.seenScratch);   // fill + return a reused scratch\n * ```\n *\n * By default `at`/`lastSeenBy` re-aim and return the Rewind's own internal\n * view \u2014 the usual \"one view at a time, read it right away\" flow is zero-alloc\n * AND zero-setup (the server is single-threaded; nothing interleaves a\n * synchronous read). Need more than one view alive at once (compare two\n * shooters' perspectives, A/B a rewind window)? Pass your own instance as\n * their `out` \u2014 it is re-aimed and returned instead of the shared one:\n *\n * ```ts\n * const a = rewind.lastSeenBy(shooterA);                      // shared default view\n * const b = rewind.lastSeenBy(shooterB, new RewindView());    // independent second view\n * ```\n *\n * Don't store a view across calls or ticks: the default is re-aimed by the\n * next `at`/`lastSeenBy`, and ANY view's clamp was computed against\n * `lastRecordedAt`, so it goes stale at the next `record()` regardless.\n */\nexport class RewindView {\n  /** Bound (and re-bound) by {@link _retarget} \u2014 a bare `new RewindView()` is\n   *  un-aimed scratch until it first passes through at()/lastSeenBy(). */\n  private rewind?: Rewind;\n  private _time = 0;\n  private _reckonTime = 0;\n\n  /** The clamped server-time (ms) this view reads at \u2014 after the maxRewindMs\n   *  clamp and the live (newest-sample) fallback. Mostly for logging/debug. */\n  get time(): number { return this._time; }\n\n  /** The clamped server-time (ms) `mode: \"reckon\"` groups read at \u2014 the\n   *  client's reconstructed simulation instant, not the raw stamp (see\n   *  {@link Rewind.at}). Always a resolved instant: a clamped direct stamp,\n   *  or the midpoint/live reconstruction when unstamped. `0` only before the\n   *  first `record()`. */\n  get reckonTime(): number { return this._reckonTime; }\n\n  /** @internal Aim at a rewind + clamped times ({@link Rewind.at} owns the clamps). */\n  _retarget(rewind: Rewind, at: number, reckonAt: number): this {\n    this.rewind = rewind;\n    this._time = at;\n    this._reckonTime = reckonAt;\n    return this;\n  }\n\n  /** Rewound value of a numeric `field` on `entity` (live if it isn't tracked). */\n  value<T extends object>(entity: T, field: NumericKeys<T>): number {\n    if (this.rewind === undefined) {\n      throw new Error(\"RewindView is not aimed \u2014 obtain it from rewind.at()/lastSeenBy(), or pass it to them as `out`.\");\n    }\n    // The field's covering attach-group picks the timeline: mode:\"reckon\" reads\n    // at the reckon-display instant, mode:\"snapshot\" at the renderTime stamp.\n    const h = historyForField(entity, field);\n    if (h === undefined) return (entity as Record<string, number>)[field];   // untracked \u2192 live\n    return h.valueAt(h.reckoned ? this._reckonTime : this._time, h.fields.indexOf(field));\n  }\n\n  /**\n   * Batch {@link value} reads: the `fields` YOU list define the result's shape\n   * (`Record<field, number>`). Pass `out` to fill (and return) a reused scratch\n   * instead of allocating \u2014 its properties beyond `fields` are left untouched,\n   * so a scratch can carry extra context (an `alive` flag, say).\n   */\n  read<T extends object, F extends NumericKeys<T>, O extends Record<F, number> = Record<F, number>>(\n    entity: T,\n    fields: readonly F[],\n    out?: O,\n  ): O {\n    const o = (out ?? {}) as Record<F, number>;\n    for (let i = 0; i < fields.length; i++) o[fields[i]] = this.value(entity, fields[i]);\n    return o as O;\n  }\n}\n\n/** Array-form `fields` resolved against one constructor: names with a known\n *  `$values` index, in lock-step. Fields a type doesn't declare are dropped\n *  (they read live) instead of recording `values[-1]` garbage. */\ninterface ResolvedFields { fields: readonly string[]; idx: readonly number[]; }\n\ninterface TrackedGroup {\n  entities: () => Iterable<object>;\n  fields: readonly string[] | ((entity: any) => readonly string[]);\n  /** Per-constructor resolution of array-form `fields` \u2014 one entry per entity\n   *  type seen in the group (mixed-type collections differ per type). */\n  resolvedByCtor: Map<Function, ResolvedFields>;\n  maxRewindMs: number;\n  interpolate: Interp | ((entity: any) => Interp);\n  /** `true` when this group's `mode` is `\"reckon\"` (vs the `\"snapshot\"` default). */\n  reckoned: boolean;\n  /** Stable id (push index) \u2014 links an entity's per-group {@link EntityHistory}\n   *  back to its group so the same collection can be attached more than once. */\n  groupId: number;\n}\n\n/**\n * Per-attach options for {@link Rewind.attachAll} / {@link Rewind.attach}.\n */\ninterface AttachOptions<E> {\n  /** Numeric fields to record per tick. An array applies to every type in the\n   *  collection (fields a type lacks are skipped \u2014 they read live); a per-entity\n   *  fn picks the list per entity, mirroring `interpolate`'s fn form. */\n  fields: readonly NumericKeys<E>[] | ((entity: E) => readonly NumericKeys<E>[]);\n  maxRewindMs?: number;\n  /** How `valueAt` reconstructs between samples (a mode or a per-entity fn,\n   *  default `linear`) \u2014 use `step` for discrete motion (e.g. teleporters). */\n  interpolate?: Interp | ((entity: E) => Interp);\n  /**\n   * The lag-comp TIMELINE these fields rewind to \u2014 must match how the CLIENT\n   * displays this target (\"what you see is what you hit\"):\n   *   - `\"snapshot\"` (default): rewind to the client's `renderTime` \u2014 for\n   *     targets it shows INTERPOLATED (Predict `lerp`/`damped`), behind real\n   *     time by its interp buffer + rtt/2.\n   *   - `\"reckon\"`: rewind to the client's `reckonTime` (\u2248 its serverNow) \u2014 for\n   *     targets it forward-extrapolates (Predict `reckon`).\n   * Attach the same collection twice with disjoint `fields` to mix techniques.\n   * The room ships exactly the stamp(s) its attached groups need (see the\n   * handshake derivation in `Room`).\n   */\n  mode?: RewindMode;\n}\n\n/**\n * Server-side lag compensation \u2014 the dual of the client's `Predict`. Where\n * `Predict` forward-reckons entities it RECEIVES, `Rewind` records the recent\n * positions of entities it OWNS and rewinds field reads to a past (client\n * render) time, so a hit test judges against where the client actually SAW an\n * entity \u2014 not where it has slid to ~RTT later.\n *\n * Prefer {@link Room.allowRewindState}, which creates a `Rewind` and records it\n * automatically each simulation tick:\n *\n * @example\n * ```ts\n * onCreate() {\n *   const rewind = this.allowRewindState({ maxRewindMs: 500 });\n *   rewind.attachAll(this.state.enemies, { fields: [\"x\", \"y\"] });  // fields \u2190 Enemy's numeric keys\n *   this.setTimestep((dt) => { ...move enemies... }, 1000 / 30);\n *   // framework calls rewind.record() after each tick.\n * }\n * // in your hit test, with the client's renderTime:\n * const seenX = rewind.valueAt(enemy, renderTime, \"x\");\n * ```\n *\n * `attachAll` takes the live collection (not a string key), so the element type\n * \u2014 and the legal `fields` / `valueAt` field names \u2014 are inferred with no\n * state-type generic. Entities are keyed by object identity \u2014 removed entities\n * and their history are reclaimed automatically.\n *\n * The rewind TIMELINE is declared per attach-group via `attachAll(coll, { mode })`:\n * `\"snapshot\"` (default) reads at the client's `renderTime` stamp, `\"reckon\"` at\n * its `reckonTime` (see {@link at}). Not-attached = not rewound (reads are live)\n * \u2014 there is no \"none\". The same collection may be attached more than once with\n * disjoint `fields` to put different fields on different timelines. The room\n * ships exactly the stamp(s) these groups need (handshake derivation reads\n * {@link timelineMode}); the client declares its display mode independently.\n */\nexport class Rewind {\n  private static readonly byRoom = new WeakMap<object, Rewind>();\n\n  /** One `Rewind` per room (idempotent). `room` is only the cache key. */\n  static get(room: object, opts?: RewindOptions): Rewind {\n    let r = Rewind.byRoom.get(room);\n    if (r === undefined) { r = new Rewind(opts?.maxRewindMs ?? DEFAULT_MAX_REWIND_MS); Rewind.byRoom.set(room, r); }\n    return r;\n  }\n\n  private readonly groups: TrackedGroup[] = [];\n  private readonly defaultMaxRewindMs: number;\n  private _sampleIntervalMs = DEFAULT_SAMPLE_INTERVAL_MS;\n  private _lastRecordedAt = -1;\n  /** Resolves a client's auto-stamped render time (set by `Room.allowRewindState`\n   *  when a `mode:\"snapshot\"` group is attached); powers {@link lastSeenBy}. */\n  private _renderTimeOf?: (sessionId: string) => number;\n  /** Resolves a client's auto-stamped reckon-display instant (its serverNow\n   *  estimate at input-sample time). When present (> 0), {@link lastSeenBy}\n   *  reads `mode:\"reckon\"` groups AT this stamp directly \u2014 exact regardless\n   *  of the client's clock/RTT-estimation error (it displayed f(est), we read\n   *  f(est)) \u2014 instead of reconstructing it via the midpoint. */\n  private _reckonTimeOf?: (sessionId: string) => number;\n  /** Resolves the CURRENT server time (set by `Room.allowRewindState`) \u2014 the\n   *  reckon midpoint's \"now\" anchor in {@link at}. Without it, the anchor falls\n   *  back to `lastRecordedAt`, which is one tick stale at hit-test time. */\n  private _nowOf?: () => number;\n  /** Default view returned by at/lastSeenBy when no `out` is given \u2014 one per\n   *  Rewind, re-aimed per call (zero alloc, zero userland setup). */\n  private readonly _view = new RewindView();\n\n  private constructor(defaultMaxRewindMs: number) { this.defaultMaxRewindMs = defaultMaxRewindMs; }\n\n  /** The default rewind window (ms). Use it to bound a hit test:\n   *  `Math.max(renderTime, now - rewind.maxRewindMs)`. */\n  get maxRewindMs(): number { return this.defaultMaxRewindMs; }\n  /** Server time of the last {@link record} (or -1). The auto-record skips a tick\n   *  whose time was already recorded manually \u2014 your `record()` wins. */\n  get lastRecordedAt(): number { return this._lastRecordedAt; }\n\n  /** Track every entity in a collection (Map/Array/Set schema). `fields` narrows\n   *  to its element's numeric fields. `interpolate` (a mode or a per-entity fn,\n   *  default `linear`) picks how `valueAt` reconstructs between samples \u2014 use\n   *  `step` for discrete-motion entities (e.g. teleporters). `mode` picks the\n   *  lag-comp timeline (default `\"snapshot\"`; see {@link AttachOptions}). */\n  attachAll<E extends object>(\n    collection: Collection<E>,\n    opts: AttachOptions<E>,\n  ): this {\n    const c = collection as unknown as { values(): Iterable<object> };\n    this.groups.push({ entities: () => c.values(), fields: opts.fields, resolvedByCtor: new Map(), maxRewindMs: opts.maxRewindMs ?? this.defaultMaxRewindMs, interpolate: opts.interpolate ?? \"linear\", reckoned: opts.mode === \"reckon\", groupId: this.groups.length });\n    return this;\n  }\n\n  /** Track a single entity (e.g. a boss). `fields` narrows to its numeric fields. */\n  attach<E extends object>(instance: E, opts: AttachOptions<E>): this {\n    const one: object[] = [instance];   // reused; no per-tick alloc\n    this.groups.push({ entities: () => one, fields: opts.fields, resolvedByCtor: new Map(), maxRewindMs: opts.maxRewindMs ?? this.defaultMaxRewindMs, interpolate: opts.interpolate ?? \"linear\", reckoned: opts.mode === \"reckon\", groupId: this.groups.length });\n    return this;\n  }\n\n  /**\n   * Snapshot every tracked entity at `now`. Call once per tick, AFTER they move \u2014\n   * {@link Room.allowRewindState} does this for you. `sampleIntervalMs` (the gap\n   * between records) sizes the history rings; the framework passes the sim\n   * interval. Calling this yourself during a tick suppresses that tick's\n   * auto-record (see {@link lastRecordedAt}).\n   */\n  record(now: number, sampleIntervalMs?: number): void {\n    if (sampleIntervalMs !== undefined && sampleIntervalMs > 0) this._sampleIntervalMs = sampleIntervalMs;\n    this._lastRecordedAt = now;\n    for (const g of this.groups) {\n      for (const e of g.entities()) {\n        const t = e as any;   // private-symbol access on a foreign schema instance\n        let arr = t[$HISTORY] as EntityHistories | undefined;\n        if (arr === undefined) { arr = []; t[$HISTORY] = arr; }\n        let h: EntityHistory | undefined;\n        for (let i = 0; i < arr.length; i++) { if (arr[i].groupId === g.groupId) { h = arr[i]; break; } }\n        if (h === undefined) { h = this.createHistory(g, e); arr.push(h); }   // cold: once per (entity, group)\n        h.record(now, t[$values] as ArrayLike<number>);\n      }\n    }\n  }\n\n  /** Cold path \u2014 first time an entity is seen by `record()` for a given group.\n   *  Resolves the field\u2192`$values` indices (cached per constructor for array-form\n   *  `fields`; fn-form resolves per entity) and bakes in the group's `mode`. */\n  private createHistory(g: TrackedGroup, e: object): EntityHistory {\n    let rf: ResolvedFields;\n    if (typeof g.fields === \"function\") {\n      rf = this.resolveFields(e, g.fields(e));\n    } else {\n      let cached = g.resolvedByCtor.get(e.constructor);\n      if (cached === undefined) {\n        cached = this.resolveFields(e, g.fields);\n        g.resolvedByCtor.set(e.constructor, cached);\n      }\n      rf = cached;\n    }\n    const interp = typeof g.interpolate === \"function\" ? g.interpolate(e) : g.interpolate;\n    return new EntityHistory(rf.fields, rf.idx, g.maxRewindMs, this._sampleIntervalMs, interp === \"step\", g.reckoned, g.groupId);\n  }\n\n  /** Keep only the fields this entity's type declares (unknown \u2192 read live). */\n  private resolveFields(e: object, names: readonly string[]): ResolvedFields {\n    const fields: string[] = [];\n    const idx: number[] = [];\n    for (const name of names) {\n      const i = fieldIndexOf(e, name);\n      if (i >= 0) { fields.push(name); idx.push(i); }\n    }\n    return { fields, idx };\n  }\n\n  /**\n   * `instance`'s `field` value at past `time` (interpolated from history). Falls\n   * back to the live value when the entity has no history yet, or the field\n   * isn't tracked.\n   */\n  valueAt<T extends object>(instance: T, time: number, field: NumericKeys<T>): number {\n    const h = historyForField(instance, field);\n    if (h === undefined) return (instance as Record<string, number>)[field];\n    return h.valueAt(time, h.fields.indexOf(field));\n  }\n\n  /**\n   * Which timeline(s) the attached groups rewind to \u2014 `reckon` true iff any\n   * group is `mode:\"reckon\"`, `snapshot` true iff any is `mode:\"snapshot\"`. The\n   * room reads this once (groups are declared in `onCreate`, before any join) to\n   * pick which stamp(s) the client must ship: reckon-only / render-only / both /\n   * none. @internal\n   */\n  timelineMode(): { reckon: boolean; snapshot: boolean } {\n    let reckon = false, snapshot = false;\n    for (const g of this.groups) {\n      if (g.reckoned) reckon = true; else snapshot = true;\n    }\n    return { reckon, snapshot };\n  }\n\n  /**\n   * @internal Wire a resolver from sessionId \u2192 that client's auto-stamped\n   * `renderTime`. Called by {@link Room.allowRewindState} so {@link lastSeenBy}\n   * works for `mode:\"snapshot\"` groups; auto-enabled by attaching one.\n   */\n  bindRenderTime(resolver: (sessionId: string) => number): void {\n    this._renderTimeOf = resolver;\n  }\n\n  /**\n   * @internal Wire a resolver for the CURRENT server time (ms, same epoch as\n   * `record` times). Called by {@link Room.allowRewindState}; standalone users\n   * (tests/harnesses) should bind their own. Anchors the reckon midpoint in\n   * {@link at} at the true processing instant \u2014 the `lastRecordedAt` fallback\n   * is one tick stale by hit-test time, biasing the aim ~half a tick early:\n   * imperceptible on slow horizontal motion, but enough to flip knife-edge\n   * stomp/hit verdicts on fast vertical movers (a bobbing jumper).\n   */\n  bindNow(resolver: () => number): void {\n    this._nowOf = resolver;\n  }\n\n  /**\n   * @internal Wire a resolver from sessionId \u2192 that client's auto-stamped\n   * reckon-display instant (`input(sid).reckonTime`). Called by\n   * {@link Room.allowRewindState}. With it, {@link lastSeenBy} aims\n   * `mode:\"reckon\"` groups at the EXACT instant the client displayed them\n   * (immune to its RTT-estimation error); without it (or while the stamp is\n   * still 0), the midpoint reconstruction in {@link at} is the fallback.\n   */\n  bindReckonTime(resolver: (sessionId: string) => number): void {\n    this._reckonTimeOf = resolver;\n  }\n\n  /**\n   * A {@link RewindView} of the tracked world at `time` (an acting client's render\n   * time), with the two things every hit test re-implements baked in:\n   *  - **clamp** to `[lastRecordedAt \u2212 maxRewindMs, lastRecordedAt]` \u2014 an\n   *    anti-spoof / clock-skew bound (a client can't rewind arbitrarily far), and\n   *  - **live fallback**: `time <= 0` (the client's clock hasn't synced) \u2192 the\n   *    newest recorded sample (\u2248 current position).\n   *\n   * Sugar over {@link valueAt}; pass the render time yourself (e.g. from\n   * `input(sid).renderTime`, or a value stored on the entity). For the common\n   * \"rewind to a specific client's view\" case use {@link lastSeenBy}.\n   *\n   * Re-aims and returns this Rewind's internal view by default \u2014 zero alloc,\n   * nothing to declare. Pass `out` to aim a view of your own instead; needed\n   * only to hold several views at once \u2014 see the {@link RewindView} doc.\n   */\n  at(time: number, out?: RewindView): RewindView {\n    return this._aim(time, 0, out);\n  }\n\n  /**\n   * Shared aiming: clamp the snapshot-timeline `time`, and resolve the reckon\n   * timeline either from the DIRECT `reckonStamp` (the instant the client's\n   * forward-reckoned entities were displayed at \u2014 exact, immune to the\n   * client's RTT-estimation error) or, when absent (0), by reconstruction.\n   */\n  private _aim(time: number, reckonStamp: number, out?: RewindView): RewindView {\n    const newest = this._lastRecordedAt;\n    const oldest = newest - this.defaultMaxRewindMs;\n    // time<=0 \u2192 not synced yet \u2192 read live (newest). Else clamp into the window.\n    const at = time <= 0 ? newest : (time < oldest ? oldest : time > newest ? newest : time);\n    // mode:\"reckon\" groups display forward-extrapolated to \u2248 the client's\n    // serverNow \u2014 rewinding them to the raw snapshot stamp would double-\n    // compensate (client extrapolates forward + server rewinds back = a\n    // full-RTT ghost in the entity's past).\n    let reckonAt: number;\n    if (reckonStamp > 0) {\n      // Direct stamp: read at exactly what the client displayed. The clamp is\n      // the anti-spoof bound, same as the snapshot timeline's.\n      reckonAt = reckonStamp < oldest ? oldest : reckonStamp > newest ? newest : reckonStamp;\n    } else if (time <= 0) {\n      reckonAt = newest;\n    } else {\n      // Reconstruction fallback (custom `at(time)` users / old clients): with\n      // symmetric latency the client's instant is the midpoint of the stamp\n      // and ARRIVAL \u2014 anchored at the bound \"now\" (the true processing\n      // instant; the lastRecordedAt fallback is one tick stale by hit-test\n      // time and biases the aim ~half a tick early \u2014 see bindNow). NOTE: the\n      // stamp itself embeds the client's rtt/2 estimate, so this path inherits\n      // its error \u2014 the direct stamp above is the accurate one.\n      const anchor = this._nowOf !== undefined ? this._nowOf() : newest;\n      const mid = (time + anchor) / 2;\n      reckonAt = mid < oldest ? oldest : mid > newest ? newest : mid;\n    }\n    return (out ?? this._view)._retarget(this, at, reckonAt);\n  }\n\n  /**\n   * A {@link RewindView} of the world as session `sessionId` LAST saw it \u2014\n   * resolves the render time stamped on that client's most recently CONSUMED\n   * input (hence \"last\": under a multi-frame `drain()` it is the newest frame's\n   * stamp) and hands off to {@link at}. This is the \"what you see is what you\n   * hit\" path:\n   *\n   * ```ts\n   * const seen = this.rewind.lastSeenBy(shooterSessionId);\n   * const hit = overlaps(bullet, seen.value(target, \"x\"), seen.value(target, \"y\"));\n   * ```\n   *\n   * Requires the room's framework input (`this.defineInput(Input)`) \u2014 the\n   * per-client stamp auto-enables from the `attachAll` `mode` of the groups you\n   * rewind (declaration order vs `allowRewindState` doesn't matter). A client\n   * that merely hasn't stamped yet (clock still syncing, unknown sessionId) is\n   * NOT an error \u2014 it reads 0 and the view falls back to live. Use\n   * {@link at} with an explicit time if you stamp render times yourself.\n   *\n   * Re-aims and returns this Rewind's internal view by default \u2014 zero alloc,\n   * nothing to declare. Pass `out` to aim a view of your own instead; needed\n   * only to hold several views at once \u2014 see the {@link RewindView} doc.\n   */\n  lastSeenBy(sessionId: string, out?: RewindView): RewindView {\n    if (this._renderTimeOf === undefined) {\n      throw new Error(\n        \"Rewind.lastSeenBy(sessionId) needs the framework input API. Declare \" +\n        \"`this.defineInput(Input)` (stamps auto-enable from your attachAll `mode`), \" +\n        \"or call `at(time)` and pass the render time yourself.\",\n      );\n    }\n    return this._aim(\n      this._renderTimeOf(sessionId),\n      this._reckonTimeOf !== undefined ? this._reckonTimeOf(sessionId) : 0,\n      out,\n    );\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/build/Rewind.d.ts

@@ -0,0 +1,291 @@
+import { type MapSchema, type ArraySchema, type SetSchema } from "@colyseus/schema";
+/** Keys of T whose value type is `number` — the only rewindable fields. */
+type NumericKeys<T> = {
+    [K in keyof T]-?: T[K] extends number ? K : never;
+}[keyof T] & string;
+/** A Colyseus collection whose element type is `E`. Inferring `E` from the live
+ *  collection the caller passes is what lets `fields` narrow with zero state-type
+ *  plumbing. */
+type Collection<E> = MapSchema<E> | ArraySchema<E> | SetSchema<E>;
+/** Options for {@link Rewind.get} / {@link Room.allowRewindState}. */
+export interface RewindOptions {
+    /** Default rewind window (ms) for attaches that don't pass their own — sizes the
+     *  per-entity history ring. Per-attach `maxRewindMs` overrides it. Default 500. */
+    maxRewindMs?: number;
+}
+/** The lag-comp technique an attach-group rewinds to — the TIMELINE the client
+ *  displays those targets on. `"snapshot"` (default): the renderTime stamp (what
+ *  a lerping/damped client shows, behind real time). `"reckon"`: the reckonTime
+ *  stamp (what a forward-extrapolated client shows, ≈ serverNow). Declared at
+ *  {@link Rewind.attachAll}, not on the schema. */
+export type RewindMode = "snapshot" | "reckon";
+/** How `valueAt` reconstructs a value between recorded samples: `linear` interp
+ *  (continuous motion) or `step` = hold the last sample (discrete motion). */
+type Interp = "linear" | "step";
+/**
+ * A read-only view of the tracked world at ONE past time — the rewound state a
+ * hit test reads instead of live positions. Created by {@link Rewind.at} /
+ * {@link Rewind.lastSeenBy}, which bake in the `maxRewindMs` clamp and the
+ * live-fallback so callers never re-implement either.
+ *
+ * The view assumes NOTHING about your schema's field names — you name the
+ * fields (and therefore the shape) at the call site:
+ *
+ * ```ts
+ * const seen = rewind.lastSeenBy(shooterSessionId);
+ * // read fields directly…
+ * overlaps(bullet, seen.value(target, "x"), seen.value(target, "y"));
+ * // …or batch them into an object shaped by YOUR field list:
+ * const pos = seen.read(target, ["x", "y"]);        // { x, y }
+ * seen.read(enemy, ["x", "y"], this.seenScratch);   // fill + return a reused scratch
+ * ```
+ *
+ * By default `at`/`lastSeenBy` re-aim and return the Rewind's own internal
+ * view — the usual "one view at a time, read it right away" flow is zero-alloc
+ * AND zero-setup (the server is single-threaded; nothing interleaves a
+ * synchronous read). Need more than one view alive at once (compare two
+ * shooters' perspectives, A/B a rewind window)? Pass your own instance as
+ * their `out` — it is re-aimed and returned instead of the shared one:
+ *
+ * ```ts
+ * const a = rewind.lastSeenBy(shooterA);                      // shared default view
+ * const b = rewind.lastSeenBy(shooterB, new RewindView());    // independent second view
+ * ```
+ *
+ * Don't store a view across calls or ticks: the default is re-aimed by the
+ * next `at`/`lastSeenBy`, and ANY view's clamp was computed against
+ * `lastRecordedAt`, so it goes stale at the next `record()` regardless.
+ */
+export declare class RewindView {
+    /** Bound (and re-bound) by {@link _retarget} — a bare `new RewindView()` is
+     *  un-aimed scratch until it first passes through at()/lastSeenBy(). */
+    private rewind?;
+    private _time;
+    private _reckonTime;
+    /** The clamped server-time (ms) this view reads at — after the maxRewindMs
+     *  clamp and the live (newest-sample) fallback. Mostly for logging/debug. */
+    get time(): number;
+    /** The clamped server-time (ms) `mode: "reckon"` groups read at — the
+     *  client's reconstructed simulation instant, not the raw stamp (see
+     *  {@link Rewind.at}). Always a resolved instant: a clamped direct stamp,
+     *  or the midpoint/live reconstruction when unstamped. `0` only before the
+     *  first `record()`. */
+    get reckonTime(): number;
+    /** @internal Aim at a rewind + clamped times ({@link Rewind.at} owns the clamps). */
+    _retarget(rewind: Rewind, at: number, reckonAt: number): this;
+    /** Rewound value of a numeric `field` on `entity` (live if it isn't tracked). */
+    value<T extends object>(entity: T, field: NumericKeys<T>): number;
+    /**
+     * Batch {@link value} reads: the `fields` YOU list define the result's shape
+     * (`Record<field, number>`). Pass `out` to fill (and return) a reused scratch
+     * instead of allocating — its properties beyond `fields` are left untouched,
+     * so a scratch can carry extra context (an `alive` flag, say).
+     */
+    read<T extends object, F extends NumericKeys<T>, O extends Record<F, number> = Record<F, number>>(entity: T, fields: readonly F[], out?: O): O;
+}
+/**
+ * Per-attach options for {@link Rewind.attachAll} / {@link Rewind.attach}.
+ */
+interface AttachOptions<E> {
+    /** Numeric fields to record per tick. An array applies to every type in the
+     *  collection (fields a type lacks are skipped — they read live); a per-entity
+     *  fn picks the list per entity, mirroring `interpolate`'s fn form. */
+    fields: readonly NumericKeys<E>[] | ((entity: E) => readonly NumericKeys<E>[]);
+    maxRewindMs?: number;
+    /** How `valueAt` reconstructs between samples (a mode or a per-entity fn,
+     *  default `linear`) — use `step` for discrete motion (e.g. teleporters). */
+    interpolate?: Interp | ((entity: E) => Interp);
+    /**
+     * The lag-comp TIMELINE these fields rewind to — must match how the CLIENT
+     * displays this target ("what you see is what you hit"):
+     *   - `"snapshot"` (default): rewind to the client's `renderTime` — for
+     *     targets it shows INTERPOLATED (Predict `lerp`/`damped`), behind real
+     *     time by its interp buffer + rtt/2.
+     *   - `"reckon"`: rewind to the client's `reckonTime` (≈ its serverNow) — for
+     *     targets it forward-extrapolates (Predict `reckon`).
+     * Attach the same collection twice with disjoint `fields` to mix techniques.
+     * The room ships exactly the stamp(s) its attached groups need (see the
+     * handshake derivation in `Room`).
+     */
+    mode?: RewindMode;
+}
+/**
+ * Server-side lag compensation — the dual of the client's `Predict`. Where
+ * `Predict` forward-reckons entities it RECEIVES, `Rewind` records the recent
+ * positions of entities it OWNS and rewinds field reads to a past (client
+ * render) time, so a hit test judges against where the client actually SAW an
+ * entity — not where it has slid to ~RTT later.
+ *
+ * Prefer {@link Room.allowRewindState}, which creates a `Rewind` and records it
+ * automatically each simulation tick:
+ *
+ * @example
+ * ```ts
+ * onCreate() {
+ *   const rewind = this.allowRewindState({ maxRewindMs: 500 });
+ *   rewind.attachAll(this.state.enemies, { fields: ["x", "y"] });  // fields ← Enemy's numeric keys
+ *   this.setTimestep((dt) => { ...move enemies... }, 1000 / 30);
+ *   // framework calls rewind.record() after each tick.
+ * }
+ * // in your hit test, with the client's renderTime:
+ * const seenX = rewind.valueAt(enemy, renderTime, "x");
+ * ```
+ *
+ * `attachAll` takes the live collection (not a string key), so the element type
+ * — and the legal `fields` / `valueAt` field names — are inferred with no
+ * state-type generic. Entities are keyed by object identity — removed entities
+ * and their history are reclaimed automatically.
+ *
+ * The rewind TIMELINE is declared per attach-group via `attachAll(coll, { mode })`:
+ * `"snapshot"` (default) reads at the client's `renderTime` stamp, `"reckon"` at
+ * its `reckonTime` (see {@link at}). Not-attached = not rewound (reads are live)
+ * — there is no "none". The same collection may be attached more than once with
+ * disjoint `fields` to put different fields on different timelines. The room
+ * ships exactly the stamp(s) these groups need (handshake derivation reads
+ * {@link timelineMode}); the client declares its display mode independently.
+ */
+export declare class Rewind {
+    private static readonly byRoom;
+    /** One `Rewind` per room (idempotent). `room` is only the cache key. */
+    static get(room: object, opts?: RewindOptions): Rewind;
+    private readonly groups;
+    private readonly defaultMaxRewindMs;
+    private _sampleIntervalMs;
+    private _lastRecordedAt;
+    /** Resolves a client's auto-stamped render time (set by `Room.allowRewindState`
+     *  when a `mode:"snapshot"` group is attached); powers {@link lastSeenBy}. */
+    private _renderTimeOf?;
+    /** Resolves a client's auto-stamped reckon-display instant (its serverNow
+     *  estimate at input-sample time). When present (> 0), {@link lastSeenBy}
+     *  reads `mode:"reckon"` groups AT this stamp directly — exact regardless
+     *  of the client's clock/RTT-estimation error (it displayed f(est), we read
+     *  f(est)) — instead of reconstructing it via the midpoint. */
+    private _reckonTimeOf?;
+    /** Resolves the CURRENT server time (set by `Room.allowRewindState`) — the
+     *  reckon midpoint's "now" anchor in {@link at}. Without it, the anchor falls
+     *  back to `lastRecordedAt`, which is one tick stale at hit-test time. */
+    private _nowOf?;
+    /** Default view returned by at/lastSeenBy when no `out` is given — one per
+     *  Rewind, re-aimed per call (zero alloc, zero userland setup). */
+    private readonly _view;
+    private constructor();
+    /** The default rewind window (ms). Use it to bound a hit test:
+     *  `Math.max(renderTime, now - rewind.maxRewindMs)`. */
+    get maxRewindMs(): number;
+    /** Server time of the last {@link record} (or -1). The auto-record skips a tick
+     *  whose time was already recorded manually — your `record()` wins. */
+    get lastRecordedAt(): number;
+    /** Track every entity in a collection (Map/Array/Set schema). `fields` narrows
+     *  to its element's numeric fields. `interpolate` (a mode or a per-entity fn,
+     *  default `linear`) picks how `valueAt` reconstructs between samples — use
+     *  `step` for discrete-motion entities (e.g. teleporters). `mode` picks the
+     *  lag-comp timeline (default `"snapshot"`; see {@link AttachOptions}). */
+    attachAll<E extends object>(collection: Collection<E>, opts: AttachOptions<E>): this;
+    /** Track a single entity (e.g. a boss). `fields` narrows to its numeric fields. */
+    attach<E extends object>(instance: E, opts: AttachOptions<E>): this;
+    /**
+     * Snapshot every tracked entity at `now`. Call once per tick, AFTER they move —
+     * {@link Room.allowRewindState} does this for you. `sampleIntervalMs` (the gap
+     * between records) sizes the history rings; the framework passes the sim
+     * interval. Calling this yourself during a tick suppresses that tick's
+     * auto-record (see {@link lastRecordedAt}).
+     */
+    record(now: number, sampleIntervalMs?: number): void;
+    /** Cold path — first time an entity is seen by `record()` for a given group.
+     *  Resolves the field→`$values` indices (cached per constructor for array-form
+     *  `fields`; fn-form resolves per entity) and bakes in the group's `mode`. */
+    private createHistory;
+    /** Keep only the fields this entity's type declares (unknown → read live). */
+    private resolveFields;
+    /**
+     * `instance`'s `field` value at past `time` (interpolated from history). Falls
+     * back to the live value when the entity has no history yet, or the field
+     * isn't tracked.
+     */
+    valueAt<T extends object>(instance: T, time: number, field: NumericKeys<T>): number;
+    /**
+     * Which timeline(s) the attached groups rewind to — `reckon` true iff any
+     * group is `mode:"reckon"`, `snapshot` true iff any is `mode:"snapshot"`. The
+     * room reads this once (groups are declared in `onCreate`, before any join) to
+     * pick which stamp(s) the client must ship: reckon-only / render-only / both /
+     * none. @internal
+     */
+    timelineMode(): {
+        reckon: boolean;
+        snapshot: boolean;
+    };
+    /**
+     * @internal Wire a resolver from sessionId → that client's auto-stamped
+     * `renderTime`. Called by {@link Room.allowRewindState} so {@link lastSeenBy}
+     * works for `mode:"snapshot"` groups; auto-enabled by attaching one.
+     */
+    bindRenderTime(resolver: (sessionId: string) => number): void;
+    /**
+     * @internal Wire a resolver for the CURRENT server time (ms, same epoch as
+     * `record` times). Called by {@link Room.allowRewindState}; standalone users
+     * (tests/harnesses) should bind their own. Anchors the reckon midpoint in
+     * {@link at} at the true processing instant — the `lastRecordedAt` fallback
+     * is one tick stale by hit-test time, biasing the aim ~half a tick early:
+     * imperceptible on slow horizontal motion, but enough to flip knife-edge
+     * stomp/hit verdicts on fast vertical movers (a bobbing jumper).
+     */
+    bindNow(resolver: () => number): void;
+    /**
+     * @internal Wire a resolver from sessionId → that client's auto-stamped
+     * reckon-display instant (`input(sid).reckonTime`). Called by
+     * {@link Room.allowRewindState}. With it, {@link lastSeenBy} aims
+     * `mode:"reckon"` groups at the EXACT instant the client displayed them
+     * (immune to its RTT-estimation error); without it (or while the stamp is
+     * still 0), the midpoint reconstruction in {@link at} is the fallback.
+     */
+    bindReckonTime(resolver: (sessionId: string) => number): void;
+    /**
+     * A {@link RewindView} of the tracked world at `time` (an acting client's render
+     * time), with the two things every hit test re-implements baked in:
+     *  - **clamp** to `[lastRecordedAt − maxRewindMs, lastRecordedAt]` — an
+     *    anti-spoof / clock-skew bound (a client can't rewind arbitrarily far), and
+     *  - **live fallback**: `time <= 0` (the client's clock hasn't synced) → the
+     *    newest recorded sample (≈ current position).
+     *
+     * Sugar over {@link valueAt}; pass the render time yourself (e.g. from
+     * `input(sid).renderTime`, or a value stored on the entity). For the common
+     * "rewind to a specific client's view" case use {@link lastSeenBy}.
+     *
+     * Re-aims and returns this Rewind's internal view by default — zero alloc,
+     * nothing to declare. Pass `out` to aim a view of your own instead; needed
+     * only to hold several views at once — see the {@link RewindView} doc.
+     */
+    at(time: number, out?: RewindView): RewindView;
+    /**
+     * Shared aiming: clamp the snapshot-timeline `time`, and resolve the reckon
+     * timeline either from the DIRECT `reckonStamp` (the instant the client's
+     * forward-reckoned entities were displayed at — exact, immune to the
+     * client's RTT-estimation error) or, when absent (0), by reconstruction.
+     */
+    private _aim;
+    /**
+     * A {@link RewindView} of the world as session `sessionId` LAST saw it —
+     * resolves the render time stamped on that client's most recently CONSUMED
+     * input (hence "last": under a multi-frame `drain()` it is the newest frame's
+     * stamp) and hands off to {@link at}. This is the "what you see is what you
+     * hit" path:
+     *
+     * ```ts
+     * const seen = this.rewind.lastSeenBy(shooterSessionId);
+     * const hit = overlaps(bullet, seen.value(target, "x"), seen.value(target, "y"));
+     * ```
+     *
+     * Requires the room's framework input (`this.defineInput(Input)`) — the
+     * per-client stamp auto-enables from the `attachAll` `mode` of the groups you
+     * rewind (declaration order vs `allowRewindState` doesn't matter). A client
+     * that merely hasn't stamped yet (clock still syncing, unknown sessionId) is
+     * NOT an error — it reads 0 and the view falls back to live. Use
+     * {@link at} with an explicit time if you stamp render times yourself.
+     *
+     * Re-aims and returns this Rewind's internal view by default — zero alloc,
+     * nothing to declare. Pass `out` to aim a view of your own instead; needed
+     * only to hold several views at once — see the {@link RewindView} doc.
+     */
+    lastSeenBy(sessionId: string, out?: RewindView): RewindView;
+}
+export {};