ark-stronghold-protocol/public/js/render/interp.js

// render/interp.js — snapshot interpolation buffer for battle rendering (pure logic, no PIXI / DOM).
//
// The server streams `b.snap` at ~20 Hz real time; snapshot time `t` is GAME seconds and combat runs at 2×
// real time (DESIGN §4), so the game clock advances `rate` ≈ 2 game-s per real second. The buffer:
//   * keeps ~2 s of snapshots (each indexed id → tuple once, at push time),
//   * estimates `rate` from arrival times (sliding window, clamped, default 2),
//   * runs a render clock `renderT` that trails the newest snapshot by `delay` real seconds (default 100 ms),
//     advancing at `rate` and gently steered back when network jitter pushes it off target (hard snap when it
//     is more than `snapAfter` real seconds off),
//   * extrapolation guard: renderT never runs more than `maxExtrapolate` real seconds past the newest snapshot;
//     positions are extrapolated along the last velocity for at most that long, then freeze,
//   * sample(): per unit, lerps x/y/hp/sp between the two snapshots bracketing renderT; flags/anim come from
//     the older one. A unit missing from the newer snapshot (died/left mid-buffer) holds its last position
//     until renderT reaches the newer snapshot; a unit that only exists in the newer one (spawned mid-buffer)
//     appears when renderT reaches it. Moves longer than `teleport` tiles between two snapshots snap.
//   * event queue: a `b.ev` batch is stamped with its game time (`gt`, the snapshot it was drained with); a batch
//     without one is placed inside the latest snapshot interval (newest snapshot time minus half an interval),
//     and handed out by `takeEvents()` once renderT passes the stamp. Stale cosmetic events (> `eventMaxLag`
//     game s behind) are dropped by the caller's choice (`isCosmeticEvent`); state events are always delivered.
//
// Snapshot tuple layout (DESIGN §8.2): [id, x, y, hp, maxHp, sp, spMax, flags, anim].

export const TUPLE = Object.freeze({ ID: 0, X: 1, Y: 2, HP: 3, MAXHP: 4, SP: 5, SPMAX: 6, FLAGS: 7, ANIM: 8 });

const MAX_EVENTS = 6000;
const finite = (v, d = 0) => (typeof v === 'number' && Number.isFinite(v) ? v : d);
const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);

/** Cosmetic event kinds that may be dropped when far behind (never state-changing). */
export const COSMETIC_EVENTS = new Set(['atk', 'dmg', 'heal', 'fx', 'layer', 'bounty']);
export const isCosmeticEvent = (ev) => Array.isArray(ev) && COSMETIC_EVENTS.has(ev[0]);

/**
 * Game time (s) of a b.snap / b.ev payload, or NaN. On the wire every frame is `{ t: '<type>', … }`, so the server
 * sends the game time as `gt` (server/match/fields.js snapFrame); raw Battle snapshots and the demo recordings
 * carry it as a numeric `t`. This is the only place that conversion happens.
 */
export function frameTime(msg) {
  if (!msg || typeof msg !== 'object') return NaN;
  const t = typeof msg.gt === 'number' ? msg.gt : msg.t;
  return typeof t === 'number' && Number.isFinite(t) ? t : NaN;
}

/**
 * Validate & normalise a b.snap payload. Returns `{ t, units: Map<id, tuple>, raw }` or null when unusable.
 * Tuples with a non-finite id/x/y are skipped; other numbers default to 0.
 */
export function normalizeSnapshot(snap) {
  if (!snap || typeof snap !== 'object') return null;
  const t = frameTime(snap);
  if (!Number.isFinite(t)) return null;
  const units = new Map();
  const list = Array.isArray(snap.units) ? snap.units : [];
  for (const u of list) {
    if (!Array.isArray(u) || u.length < 3) continue;
    const id = u[0];
    if (!(typeof id === 'number' || typeof id === 'string')) continue;
    const x = u[1], y = u[2];
    if (typeof x !== 'number' || typeof y !== 'number' || !Number.isFinite(x) || !Number.isFinite(y)) continue;
    units.set(id, [id, x, y, finite(u[3]), finite(u[4]), finite(u[5]), finite(u[6]), finite(u[7]) | 0, finite(u[8]) | 0]);
  }
  return { t, units, raw: snap };
}

export class SnapshotBuffer {
  /**
   * @param {{ delay?: number, rate?: number, maxExtrapolate?: number, keep?: number, teleport?: number,
   *           snapAfter?: number, minRate?: number, maxRate?: number }} [opts]
   *   delay / maxExtrapolate / snapAfter / keep are REAL seconds.
   */
  constructor(options) {
    const opts = options && typeof options === 'object' ? options : {};
    this.delay = Math.max(0, finite(opts.delay, 0.1));
    this.defaultRate = clamp(finite(opts.rate, 2), 0.05, 20);
    this.minRate = finite(opts.minRate, 0.25);
    this.maxRate = finite(opts.maxRate, 8);
    this.maxExtrapolate = Math.max(0, finite(opts.maxExtrapolate, 0.12));
    this.keep = Math.max(0.5, finite(opts.keep, 2.5));
    this.teleport = Math.max(0.5, finite(opts.teleport, 2.5));
    this.snapAfter = Math.max(0.2, finite(opts.snapAfter, 0.75));
    this.reset();
  }

  reset() {
    /** @type {{t:number, units:Map<any, any[]>, raw:any, at:number}[]} ascending by t */
    this.snaps = [];
    /** @type {{t:number, at:number}[]} arrival log for rate estimation */
    this.arrivals = [];
    this.rate = this.defaultRate;
    this.renderT = NaN;
    this.lastNow = NaN;
    this.interval = 0.1 * this.defaultRate / 2; // game s between snapshots (estimated)
    /** @type {{t:number, ev:any}[]} */
    this.events = [];
    this.meta = null; // latest snapshot's extra fields (dp, killed, total, boss…)
    return this;
  }

  get newestT() { return this.snaps.length ? this.snaps[this.snaps.length - 1].t : NaN; }
  get oldestT() { return this.snaps.length ? this.snaps[0].t : NaN; }
  get size() { return this.snaps.length; }

  /**
   * Add a snapshot received at real time `now` (seconds). Out-of-order / duplicate snapshots are dropped;
   * a snapshot far older than the newest (a server-side reset, e.g. a new battle) resets the buffer.
   * @returns {boolean} accepted
   */
  push(snap, now) {
    const s = normalizeSnapshot(snap);
    if (!s) return false;
    now = finite(now, this.lastNow || 0);
    const newest = this.newestT;
    if (this.snaps.length) {
      if (s.t < newest - 5) this.reset(); // the server restarted the stream (new battle): old events are obsolete
      else if (s.t <= newest) return false;
    }
    s.at = now;
    const prev = this.snaps[this.snaps.length - 1];
    if (prev) {
      const dt = s.t - prev.t;
      if (dt > 0 && dt < 2) this.interval = this.interval * 0.8 + dt * 0.2;
    }
    this.snaps.push(s);
    this.meta = s.raw;
    // rate estimate over a ~1.5 s window of arrivals
    this.arrivals.push({ t: s.t, at: now });
    while (this.arrivals.length > 2 && now - this.arrivals[0].at > 1.5) this.arrivals.shift();
    if (this.arrivals.length >= 4) {
      const a = this.arrivals[0], b = this.arrivals[this.arrivals.length - 1];
      const dReal = b.at - a.at, dGame = b.t - a.t;
      if (dReal > 0.2 && dGame > 0) this.rate = clamp(this.rate * 0.7 + (dGame / dReal) * 0.3, this.minRate, this.maxRate);
    }
    // trim old snapshots (keep at least 2). Trimming never waits for the render clock: while the page is hidden
    // (no animation frames) snapshots keep arriving and must not pile up; a clock left behind is clamped.
    const horizon = s.t - this.keep * this.rate;
    while (this.snaps.length > 2 && this.snaps[1].t < horizon) this.snaps.shift();
    if (!Number.isFinite(this.renderT)) this.renderT = Math.max(this.snaps[0].t, s.t - this.delay * this.rate);
    else if (this.renderT < this.snaps[0].t) this.renderT = this.snaps[0].t;
    return true;
  }

  /**
   * Queue a b.ev batch. `t` (game s, the frame's `gt`) when the server stamps it; otherwise the batch is placed
   * inside the latest snapshot interval (see header).
   */
  pushEvents(evs, now, t) {
    if (!Array.isArray(evs) || !evs.length) return 0;
    let stamp = typeof t === 'number' && Number.isFinite(t) ? t : NaN;
    if (!Number.isFinite(stamp)) {
      const n = this.newestT;
      stamp = Number.isFinite(n) ? n - this.interval * 0.5 : (Number.isFinite(this.renderT) ? this.renderT : 0);
    }
    let added = 0;
    for (const ev of evs) {
      if (!Array.isArray(ev) || typeof ev[0] !== 'string') continue;
      this.events.push({ t: stamp, ev });
      added++;
    }
    // bounded queue (hidden tab: nothing consumes it) — shed the oldest cosmetic events first
    if (this.events.length > MAX_EVENTS) {
      const keep = [];
      const excess = this.events.length - MAX_EVENTS;
      let shed = 0;
      for (const e of this.events) {
        if (shed < excess && isCosmeticEvent(e.ev)) { shed++; continue; }
        keep.push(e);
      }
      this.events = keep.length > MAX_EVENTS * 2 ? keep.slice(keep.length - MAX_EVENTS * 2) : keep;
    }
    // keep sorted (batches normally arrive in order; a server stamp may be older)
    if (this.events.length > 1 && this.events[this.events.length - 1].t < this.events[this.events.length - 1 - added]?.t) {
      this.events.sort((a, b) => a.t - b.t);
    }
    return added;
  }

  /**
   * Advance the render clock to real time `now` (seconds). Returns renderT (NaN until the first snapshot).
   */
  update(now) {
    now = finite(now, 0);
    if (!this.snaps.length) { this.lastNow = now; return NaN; }
    const dt = Number.isFinite(this.lastNow) ? clamp(now - this.lastNow, 0, 1) : 0;
    this.lastNow = now;
    const newest = this.newestT;
    const target = newest - this.delay * this.rate;
    if (!Number.isFinite(this.renderT)) this.renderT = target;
    this.renderT += dt * this.rate;
    const err = target - this.renderT;
    if (Math.abs(err) > this.snapAfter * this.rate) this.renderT = target;
    else this.renderT += err * Math.min(1, dt * 3);
    const cap = newest + this.maxExtrapolate * this.rate;
    if (this.renderT > cap) this.renderT = cap;
    if (this.renderT < this.snaps[0].t) this.renderT = this.snaps[0].t;
    return this.renderT;
  }

  /** Jump the render clock to the newest snapshot (scrubbing / first frame after a reset). */
  snapToNewest() {
    if (this.snaps.length) this.renderT = this.newestT;
    return this.renderT;
  }

  /** Index of the newest snapshot with t ≤ time (−1 when time is before all). */
  _indexAt(time) {
    const s = this.snaps;
    let lo = 0, hi = s.length - 1, ans = -1;
    while (lo <= hi) {
      const mid = (lo + hi) >> 1;
      if (s[mid].t <= time) { ans = mid; lo = mid + 1; } else hi = mid - 1;
    }
    return ans;
  }

  /**
   * Interpolated state at `time` (default renderT). Fills and returns `out` (a Map id → sample object reused
   * across calls: `{ id, x, y, hp, maxHp, sp, spMax, flags, anim, vx, vy, seen }`). Samples of units no longer
   * present are deleted from `out`.
   */
  sample(time = this.renderT, out = new Map()) {
    const s = this.snaps;
    if (!s.length || !Number.isFinite(time)) { out.clear(); return out; }
    let ia = this._indexAt(time);
    if (ia < 0) ia = 0;
    const A = s[ia];
    const B = ia + 1 < s.length ? s[ia + 1] : null;
    const span = B ? B.t - A.t : 0;
    const alpha = B && span > 0 ? clamp((time - A.t) / span, 0, 1) : 0;
    const P = !B && ia > 0 ? s[ia - 1] : null; // for extrapolation
    const ext = !B ? clamp(time - A.t, 0, this.maxExtrapolate * this.rate) : 0;
    const stamp = A.t;
    for (const [id, a] of A.units) {
      let o = out.get(id);
      if (!o) { o = { id, x: 0, y: 0, hp: 0, maxHp: 0, sp: 0, spMax: 0, flags: 0, anim: 0, vx: 0, vy: 0, seen: 0 }; out.set(id, o); }
      const b = B ? B.units.get(id) : null;
      if (b) {
        const dx = b[1] - a[1], dy = b[2] - a[2];
        const tele = dx * dx + dy * dy > this.teleport * this.teleport;
        o.x = tele ? (alpha < 1 ? a[1] : b[1]) : a[1] + dx * alpha;
        o.y = tele ? (alpha < 1 ? a[2] : b[2]) : a[2] + dy * alpha;
        o.vx = !tele && span > 0 ? dx / span : 0;
        o.vy = !tele && span > 0 ? dy / span : 0;
        o.hp = a[3] + (b[3] - a[3]) * alpha;
        o.maxHp = b[4] || a[4];
        o.sp = a[5] + (b[5] - a[5]) * alpha;
        o.spMax = b[6] || a[6];
      } else {
        let vx = 0, vy = 0;
        if (P && ext > 0) {
          const p = P.units.get(id);
          const dtp = A.t - P.t;
          if (p && dtp > 0) {
            vx = (a[1] - p[1]) / dtp; vy = (a[2] - p[2]) / dtp;
            if (vx * vx + vy * vy > (this.teleport / dtp) ** 2) { vx = 0; vy = 0; }
          }
        }
        o.x = a[1] + vx * ext;
        o.y = a[2] + vy * ext;
        o.vx = vx; o.vy = vy;
        o.hp = a[3]; o.maxHp = a[4]; o.sp = a[5]; o.spMax = a[6];
      }
      // the sim rounds hp up and maxHp to nearest, so a snapshot may say hp = maxHp + 1
      if (o.hp > o.maxHp && o.maxHp > 0) o.hp = o.maxHp;
      else if (!(o.hp > 0)) o.hp = 0;
      o.flags = a[7];
      o.anim = a[8];
      o.seen = stamp;
    }
    for (const id of out.keys()) if (!A.units.has(id)) out.delete(id);
    return out;
  }

  /**
   * Remove and return (in order) the queued events due at `time` (default renderT). When `dropCosmeticBefore`
   * is a number, cosmetic events stamped earlier than it are discarded instead of returned.
   */
  takeEvents(time = this.renderT, out = [], dropCosmeticBefore = null) {
    if (!this.events.length || !Number.isFinite(time)) return out;
    let n = 0;
    while (n < this.events.length && this.events[n].t <= time) n++;
    if (!n) return out;
    const list = this.events;
    for (let i = 0; i < n; i++) {
      const e = list[i];
      if (typeof dropCosmeticBefore === 'number' && e.t < dropCosmeticBefore && isCosmeticEvent(e.ev)) continue;
      out.push(e.ev);
    }
    const rest = list.length - n;
    list.copyWithin(0, n);
    list.length = rest;
    return out;
  }

  /**
   * Look ahead: call `fn(ev, t)` for every queued event stamped in (from, to] (ascending; nothing is removed).
   * Lets the renderer start animations that must peak when an event becomes due (attack wind-ups).
   */
  forEachUpcoming(from, to, fn) {
    const list = this.events;
    for (let i = 0; i < list.length; i++) {
      const e = list[i];
      if (e.t > to) break;
      if (e.t > from) fn(e.ev, e.t);
    }
  }

  /** Deliver every queued event now (used before a reset so state events are not lost). */
  flushEvents(out = []) {
    for (const e of this.events) out.push(e.ev);
    this.events.length = 0;
    return out;
  }
}