@usions/sdk 2.1.5 → 2.10.0

package/src/modules/netcode/binary.js

@@ -0,0 +1,113 @@
+/**
+ * Usion SDK Netcode — compact binary codec (zero-dependency).
+ *
+ * A tiny MessagePack-style serializer for JSON-like snapshot payloads. Pair it
+ * with the snapshot sender/receiver (`encode`/`decode` options) to send game
+ * state as binary over the WebRTC data channel or a binary-capable WebSocket —
+ * meaningfully smaller than JSON, especially after quantization (small ints
+ * pack into 1–2 bytes). WebRTC/Socket.IO transmit ArrayBuffers natively.
+ *
+ * NOT for the iframe/WebView proxy path (that bridge relays JSON) — use binary
+ * on direct/mesh transports.
+ *
+ * Wire tags:  0xc0 null · 0xc2 false · 0xc3 true · 0xc4 int(zigzag varint) ·
+ *             0xc5 float64 · 0xc6 string · 0xc7 array · 0xc8 object
+ */
+const NULL = 0xc0, FALSE = 0xc2, TRUE = 0xc3, INT = 0xc4, F64 = 0xc5, STR = 0xc6, ARR = 0xc7, OBJ = 0xc8;
+
+const _enc = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;
+const _dec = typeof TextDecoder !== 'undefined' ? new TextDecoder() : null;
+
+function pushVarint(out, n) {
+  // unsigned LEB128
+  n = n >>> 0;
+  while (n > 0x7f) { out.push((n & 0x7f) | 0x80); n >>>= 7; }
+  out.push(n);
+}
+function zigzag(n) { return ((n << 1) ^ (n >> 31)) >>> 0; }
+function unzigzag(u) { return (u >>> 1) ^ -(u & 1); }
+
+function encodeValue(out, v) {
+  if (v === null || v === undefined) { out.push(NULL); return; }
+  const t = typeof v;
+  if (t === 'boolean') { out.push(v ? TRUE : FALSE); return; }
+  if (t === 'number') {
+    if (Number.isInteger(v) && v >= -2147483648 && v <= 2147483647) {
+      out.push(INT); pushVarint(out, zigzag(v));
+    } else {
+      out.push(F64);
+      const b = new Uint8Array(8); new DataView(b.buffer).setFloat64(0, v, true);
+      for (let i = 0; i < 8; i++) out.push(b[i]);
+    }
+    return;
+  }
+  if (t === 'string') {
+    out.push(STR);
+    const bytes = _enc ? _enc.encode(v) : Buffer.from(v, 'utf8');
+    pushVarint(out, bytes.length);
+    for (let i = 0; i < bytes.length; i++) out.push(bytes[i]);
+    return;
+  }
+  if (Array.isArray(v)) {
+    out.push(ARR); pushVarint(out, v.length);
+    for (let i = 0; i < v.length; i++) encodeValue(out, v[i]);
+    return;
+  }
+  if (t === 'object') {
+    const keys = Object.keys(v);
+    out.push(OBJ); pushVarint(out, keys.length);
+    for (let i = 0; i < keys.length; i++) {
+      const k = keys[i];
+      const kb = _enc ? _enc.encode(k) : Buffer.from(k, 'utf8');
+      pushVarint(out, kb.length);
+      for (let j = 0; j < kb.length; j++) out.push(kb[j]);
+      encodeValue(out, v[k]);
+    }
+    return;
+  }
+  out.push(NULL);
+}
+
+/** Encode a JSON-like value to a Uint8Array. */
+export function encode(value) {
+  const out = [];
+  encodeValue(out, value);
+  return Uint8Array.from(out);
+}
+
+function reader(bytes) {
+  let off = 0;
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  function varint() {
+    let shift = 0, result = 0, b;
+    do { b = bytes[off++]; result |= (b & 0x7f) << shift; shift += 7; } while (b & 0x80);
+    return result >>> 0;
+  }
+  function str() {
+    const len = varint();
+    const slice = bytes.subarray(off, off + len);
+    off += len;
+    return _dec ? _dec.decode(slice) : Buffer.from(slice).toString('utf8');
+  }
+  function value() {
+    const tag = bytes[off++];
+    switch (tag) {
+      case NULL: return null;
+      case TRUE: return true;
+      case FALSE: return false;
+      case INT: return unzigzag(varint());
+      case F64: { const v = dv.getFloat64(off, true); off += 8; return v; }
+      case STR: return str();
+      case ARR: { const n = varint(); const a = new Array(n); for (let i = 0; i < n; i++) a[i] = value(); return a; }
+      case OBJ: { const n = varint(); const o = {}; for (let i = 0; i < n; i++) { const k = str(); o[k] = value(); } return o; }
+      default: return null;
+    }
+  }
+  return value;
+}
+
+/** Decode a Uint8Array / ArrayBuffer produced by `encode`. */
+export function decode(buf) {
+  const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
+  return reader(bytes)();
+}

package/src/modules/netcode/delta.js

@@ -0,0 +1,236 @@
+/**
+ * Usion SDK Netcode — Delta compression for JSON game state.
+ *
+ * Real-time games typically re-send their entire world every tick. Most of
+ * that payload is unchanged. `diff` produces a minimal patch describing only
+ * what changed since the previous state; `patch` reconstructs the new state
+ * from a base + patch. Both are plain JSON, so the patch rides on the existing
+ * realtime/action channels unchanged.
+ *
+ * Wire format:
+ *   - Objects → `{ k: <patch> }` for changed keys, `_d: [keys]` for deletions.
+ *   - **Entity arrays** (every element a plain object with a stable `id`) →
+ *     keyed diff `{ _ka:{id:patch}, _add:[entities], _del:[ids], _ord:[ids] }`.
+ *     This is O(changes), not O(index shift): inserting/removing an element no
+ *     longer rewrites every following index. (Gaffer-on-Games "state sync".)
+ *   - Other arrays → index diff `{ _a:{i:patch}, _n:length }`.
+ *   - Primitives / type changes → `{ _s: value }`.
+ *   - No change → `undefined`.
+ *
+ * `quantize` rounds numeric fields to a fixed resolution before diffing, so
+ * sub-resolution jitter doesn't produce spurious deltas and payloads shrink
+ * (the single biggest, simplest snapshot-compression win — Gaffer on Games).
+ */
+
+const SET = '_s';   // wholesale set
+const DEL = '_d';   // deleted object keys
+const ARR = '_a';   // index array patches
+const LEN = '_n';   // index array length
+const KA = '_ka';   // keyed-array: per-id patches
+const ADD = '_add'; // keyed-array: added entities (full)
+const KDEL = '_del';// keyed-array: removed ids
+const ORD = '_ord'; // keyed-array: explicit id order (only when it changes)
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function isEntityArray(v) {
+  if (!Array.isArray(v) || v.length === 0) return false;
+  for (let i = 0; i < v.length; i++) {
+    const e = v[i];
+    if (!isPlainObject(e) || (typeof e.id !== 'string' && typeof e.id !== 'number')) return false;
+  }
+  return true;
+}
+
+function sameOrder(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/**
+ * Compute a minimal patch turning `prev` into `next`.
+ * @returns the patch, or `undefined` when nothing changed.
+ */
+export function diff(prev, next) {
+  if (prev === next) return undefined;
+
+  const prevArr = Array.isArray(prev);
+  const nextArr = Array.isArray(next);
+
+  // Type changed (or one side primitive) — send the whole value.
+  if (prevArr !== nextArr || isPlainObject(prev) !== isPlainObject(next)) {
+    return { [SET]: next };
+  }
+
+  if (nextArr) {
+    // Keyed (entity) arrays: diff by id so index shifts are free.
+    if (isEntityArray(prev) && isEntityArray(next)) return diffKeyedArray(prev, next);
+    return diffIndexArray(prev, next);
+  }
+
+  if (isPlainObject(next)) return diffObject(prev, next);
+
+  // Two differing primitives.
+  return { [SET]: next };
+}
+
+function diffObject(prev, next) {
+  const out = {};
+  let changed = false;
+  for (const k in next) {
+    if (!Object.prototype.hasOwnProperty.call(next, k)) continue;
+    const d = diff(prev[k], next[k]);
+    if (d !== undefined) { out[k] = d; changed = true; }
+  }
+  const deleted = [];
+  for (const k in prev) {
+    if (!Object.prototype.hasOwnProperty.call(prev, k)) continue;
+    if (!Object.prototype.hasOwnProperty.call(next, k)) deleted.push(k);
+  }
+  if (deleted.length) { out[DEL] = deleted; changed = true; }
+  return changed ? out : undefined;
+}
+
+function diffIndexArray(prev, next) {
+  const out = { [ARR]: {} };
+  let changed = false;
+  for (let i = 0; i < next.length; i++) {
+    const d = i < prev.length ? diff(prev[i], next[i]) : { [SET]: next[i] };
+    if (d !== undefined) { out[ARR][i] = d; changed = true; }
+  }
+  if (next.length !== prev.length) { out[LEN] = next.length; changed = true; }
+  return changed ? out : undefined;
+}
+
+function diffKeyedArray(prev, next) {
+  const prevById = {};
+  const prevIds = [];
+  for (let i = 0; i < prev.length; i++) { prevById[prev[i].id] = prev[i]; prevIds.push(prev[i].id); }
+  const nextIds = [];
+  const out = {};
+  let changed = false;
+
+  for (let i = 0; i < next.length; i++) {
+    const e = next[i];
+    nextIds.push(e.id);
+    if (Object.prototype.hasOwnProperty.call(prevById, e.id)) {
+      const d = diff(prevById[e.id], e);
+      if (d !== undefined) {
+        if (!out[KA]) out[KA] = {};
+        out[KA][e.id] = d;
+        changed = true;
+      }
+    } else {
+      if (!out[ADD]) out[ADD] = [];
+      out[ADD].push(e);
+      changed = true;
+    }
+  }
+
+  const nextIdSet = {};
+  for (let i = 0; i < nextIds.length; i++) nextIdSet[nextIds[i]] = true;
+  for (let i = 0; i < prevIds.length; i++) {
+    if (!nextIdSet[prevIds[i]]) {
+      if (!out[KDEL]) out[KDEL] = [];
+      out[KDEL].push(prevIds[i]);
+      changed = true;
+    }
+  }
+
+  if (!sameOrder(prevIds, nextIds)) { out[ORD] = nextIds; changed = true; }
+  return changed ? out : undefined;
+}
+
+/**
+ * Apply a patch produced by `diff` to `base`, returning the new value.
+ * Does not mutate `base`. A nullish patch returns `base` unchanged.
+ */
+export function patch(base, p) {
+  if (p === undefined || p === null) return base;
+  if (Object.prototype.hasOwnProperty.call(p, SET)) return p[SET];
+
+  // Keyed (entity) array.
+  if (p[KA] || p[ADD] || p[KDEL] || p[ORD]) return patchKeyedArray(base, p);
+
+  // Index array.
+  if (Object.prototype.hasOwnProperty.call(p, ARR) || Object.prototype.hasOwnProperty.call(p, LEN)) {
+    const src = Array.isArray(base) ? base : [];
+    const len = Object.prototype.hasOwnProperty.call(p, LEN) ? p[LEN] : src.length;
+    const out = src.slice(0, len);
+    const patches = p[ARR] || {};
+    for (const i in patches) {
+      if (!Object.prototype.hasOwnProperty.call(patches, i)) continue;
+      out[i] = patch(out[i], patches[i]);
+    }
+    return out;
+  }
+
+  // Object patch.
+  const out = isPlainObject(base) ? Object.assign({}, base) : {};
+  const deleted = p[DEL];
+  for (const k in p) {
+    if (k === DEL) continue;
+    if (!Object.prototype.hasOwnProperty.call(p, k)) continue;
+    out[k] = patch(out[k], p[k]);
+  }
+  if (Array.isArray(deleted)) for (let i = 0; i < deleted.length; i++) delete out[deleted[i]];
+  return out;
+}
+
+function patchKeyedArray(base, p) {
+  const baseArr = Array.isArray(base) ? base : [];
+  const byId = {};
+  const baseOrder = [];
+  for (let i = 0; i < baseArr.length; i++) {
+    const e = baseArr[i];
+    if (e && (typeof e.id === 'string' || typeof e.id === 'number')) { byId[e.id] = e; baseOrder.push(e.id); }
+  }
+  // Apply per-id field patches.
+  if (p[KA]) for (const id in p[KA]) {
+    if (Object.prototype.hasOwnProperty.call(p[KA], id) && byId[id] !== undefined) byId[id] = patch(byId[id], p[KA][id]);
+  }
+  // Additions.
+  if (p[ADD]) for (let i = 0; i < p[ADD].length; i++) { const e = p[ADD][i]; byId[e.id] = e; }
+  // Removals.
+  const removed = {};
+  if (p[KDEL]) for (let i = 0; i < p[KDEL].length; i++) removed[p[KDEL][i]] = true;
+
+  if (p[ORD]) {
+    const out = [];
+    for (let i = 0; i < p[ORD].length; i++) {
+      const id = p[ORD][i];
+      if (byId[id] !== undefined) out.push(byId[id]);
+    }
+    return out;
+  }
+  // No order change: keep base order minus removals, patched in place.
+  const out = [];
+  for (let i = 0; i < baseOrder.length; i++) {
+    const id = baseOrder[i];
+    if (!removed[id]) out.push(byId[id]);
+  }
+  return out;
+}
+
+/**
+ * Round every numeric field to `precision` decimal places (default 2),
+ * returning a new value. Apply before diffing so sub-resolution jitter and
+ * float noise don't generate spurious deltas, and payloads stay small.
+ */
+export function quantize(value, precision = 2) {
+  const f = Math.pow(10, precision);
+  function q(v) {
+    if (typeof v === 'number') return Number.isFinite(v) ? Math.round(v * f) / f : v;
+    if (Array.isArray(v)) return v.map(q);
+    if (isPlainObject(v)) {
+      const o = {};
+      for (const k in v) if (Object.prototype.hasOwnProperty.call(v, k)) o[k] = q(v[k]);
+      return o;
+    }
+    return v;
+  }
+  return q(value);
+}

package/src/modules/netcode/index.js

@@ -0,0 +1,41 @@
+/**
+ * Usion SDK Netcode — public namespace.
+ *
+ * A small, zero-dependency, transport-agnostic toolkit for smooth low-latency
+ * multiplayer. Works across all Usion connection modes (platform / direct /
+ * proxy) and both platforms, computing on top of the existing realtime/action
+ * plumbing — no host or backend changes required to use it.
+ *
+ *   SnapshotInterpolation — smooth rendering; adaptive buffer + capped extrapolation
+ *   Predictor             — client prediction + reconciliation + error smoothing
+ *   Coalescer             — fixed-Hz outbound send batching
+ *   PingMeter             — RTT / jitter telemetry
+ *   MeshConnection        — WebRTC P2P (sequenced, TURN-ready, auto-reconnect)
+ *   MeshNetwork           — N-peer full mesh
+ *   diff / patch / quantize — JSON delta compression (id-keyed arrays)
+ *   encode / decode        — compact binary codec
+ */
+import { SnapshotInterpolation, Vault } from './interpolation.js';
+import { Predictor } from './prediction.js';
+import { Coalescer } from './sender.js';
+import { PingMeter } from './ping.js';
+import { MeshConnection } from './mesh.js';
+import { MeshNetwork } from './mesh-network.js';
+import { WebTransportConnection } from './webtransport.js';
+import { NetworkSim } from './netsim.js';
+import { Lockstep } from './lockstep.js';
+import { LagCompensator } from './lagcomp.js';
+import { diff, patch, quantize } from './delta.js';
+import { encode, decode } from './binary.js';
+
+export const netcode = {
+  SnapshotInterpolation, Vault, Predictor, Coalescer, PingMeter,
+  MeshConnection, MeshNetwork, WebTransportConnection, NetworkSim, Lockstep, LagCompensator,
+  diff, patch, quantize, encode, decode,
+};
+
+export {
+  SnapshotInterpolation, Vault, Predictor, Coalescer, PingMeter,
+  MeshConnection, MeshNetwork, WebTransportConnection, NetworkSim, Lockstep, LagCompensator,
+  diff, patch, quantize, encode, decode,
+};

package/src/modules/netcode/interpolation.js

@@ -0,0 +1,235 @@
+/**
+ * Usion SDK Netcode — Snapshot interpolation.
+ *
+ * Render every entity slightly in the past and interpolate between the two
+ * snapshots straddling "renderTime", so motion stays smooth and late /
+ * duplicate / out-of-order / dropped packets are absorbed for free. This is
+ * the single biggest perceived-lag fix for real-time games.
+ *
+ * Practices adopted (Valve Source "Interpolation" + geckos.io):
+ *  - Interpolation delay (buffer) sized in server-frames, with an **adaptive**
+ *    mode that grows the buffer with measured network jitter (cl_interp_ratio).
+ *  - **Capped extrapolation** when the buffer underruns (packet loss): project
+ *    forward from the last known velocity, bounded (Source caps at 0.25s) so
+ *    prediction error stays small.
+ *  - Optional **server-time domain**: if snapshots carry a server `time`, render
+ *    against an estimated server clock (robust to bursty arrival). Default stays
+ *    the client arrival-time domain — zero clock sync required.
+ *
+ * Key-spec syntax: 'x y angle(deg) r(rad)'.
+ */
+
+function shortestAngle(a, b, twoPi) {
+  let d = (b - a) % twoPi;
+  const half = twoPi / 2;
+  if (d > half) d -= twoPi;
+  if (d < -half) d += twoPi;
+  return d;
+}
+
+function parseKeys(spec) {
+  return String(spec || '')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((tok) => {
+      const m = tok.match(/^(.+?)\((deg|rad)\)$/);
+      return m ? { key: m[1], type: m[2] } : { key: tok, type: 'linear' };
+    });
+}
+
+function lerpField(a, b, t, type) {
+  if (type === 'deg') return a + shortestAngle(a, b, 360) * t;
+  if (type === 'rad') return a + shortestAngle(a, b, Math.PI * 2) * t;
+  return a + (b - a) * t;
+}
+
+/** Time-ordered ring buffer of snapshots. Newest last. */
+export class Vault {
+  constructor(maxSize = 120) {
+    this._items = [];
+    this._maxSize = maxSize;
+  }
+  add(snapshot) {
+    this._items.push(snapshot);
+    if (this._items.length > this._maxSize) this._items.shift();
+  }
+  get size() { return this._items.length; }
+  setMaxSize(n) { this._maxSize = Math.max(2, n | 0); }
+  latest() { return this._items.length ? this._items[this._items.length - 1] : null; }
+  prevLatest() { return this._items.length >= 2 ? this._items[this._items.length - 2] : null; }
+  clear() { this._items = []; }
+
+  /** [older, newer] snapshots straddling `time`, clamping at the ends. */
+  straddle(time) {
+    const items = this._items;
+    if (items.length === 0) return [null, null];
+    if (items.length === 1) return [items[0], items[0]];
+    if (time <= items[0].time) return [items[0], items[0]];
+    const last = items[items.length - 1];
+    if (time >= last.time) return [last, last];
+    for (let i = items.length - 1; i > 0; i--) {
+      if (items[i - 1].time <= time && time <= items[i].time) return [items[i - 1], items[i]];
+    }
+    return [last, last];
+  }
+}
+
+function asEntityArray(state, group) {
+  if (group) return Array.isArray(state[group]) ? state[group] : [];
+  return Array.isArray(state) ? state : [];
+}
+
+export class SnapshotInterpolation {
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.serverFps=20]      Expected snapshot rate (sets default buffer).
+   * @param {number} [opts.bufferMs]          Fixed interpolation delay (default ≈ 3 frames).
+   * @param {boolean} [opts.adaptive=false]   Grow the buffer with measured jitter.
+   * @param {number} [opts.minBufferMs]       Lower clamp for adaptive buffer.
+   * @param {number} [opts.maxBufferMs]       Upper clamp for adaptive buffer.
+   * @param {number} [opts.extrapolationMs=0] Max forward extrapolation on underrun (0 = off).
+   * @param {boolean} [opts.serverTime=false] Use snapshot.time (server clock) domain.
+   * @param {number} [opts.maxSize=120]
+   * @param {function} [opts.now]
+   */
+  constructor(opts = {}) {
+    const serverFps = opts.serverFps || 20;
+    this._frameMs = 1000 / serverFps;
+    this.vault = new Vault(opts.maxSize || 120);
+    this._fixedBuffer = opts.bufferMs != null ? opts.bufferMs : Math.ceil(this._frameMs * 3);
+    this._bufferMs = this._fixedBuffer;
+    this._adaptive = !!opts.adaptive;
+    this._minBuffer = opts.minBufferMs != null ? opts.minBufferMs : Math.ceil(this._frameMs * 2);
+    this._maxBuffer = opts.maxBufferMs != null ? opts.maxBufferMs : Math.ceil(this._frameMs * 8);
+    this._extrapolationMs = opts.extrapolationMs || 0;
+    this._useServerTime = !!opts.serverTime;
+    this._now = opts.now || (() => Date.now());
+
+    // adaptive/jitter + server-clock estimation state
+    this._lastArrival = null;
+    this._avgInterval = this._frameMs;
+    this._jitter = 0;
+    this._offset = null; // EWMA(arrival - serverTime)
+  }
+
+  getBufferMs() { return this._bufferMs; }
+  setBufferMs(ms) { this._fixedBuffer = Math.max(0, ms | 0); this._bufferMs = this._fixedBuffer; }
+  getJitter() { return this._jitter; }
+
+  /**
+   * Add a received snapshot. `state` is an entity array (each needs a stable
+   * `id`) or a map of named groups → entity arrays. Pass `{ state, time }` to
+   * supply a server timestamp for the server-time domain.
+   */
+  add(snapshot) {
+    if (!snapshot) return;
+    const arrival = this._now();
+    const state = snapshot.state !== undefined ? snapshot.state : snapshot;
+    const serverTime = snapshot.time;
+
+    // Jitter / interval estimate (EWMA), used by the adaptive buffer.
+    if (this._lastArrival != null) {
+      const interval = arrival - this._lastArrival;
+      this._avgInterval += 0.1 * (interval - this._avgInterval);
+      this._jitter += 0.1 * (Math.abs(interval - this._avgInterval) - this._jitter);
+      if (this._adaptive) {
+        const target = this._avgInterval + 2 * this._jitter;
+        this._bufferMs = Math.max(this._minBuffer, Math.min(this._maxBuffer, target));
+      }
+    }
+    this._lastArrival = arrival;
+
+    // Server-clock offset estimate.
+    if (this._useServerTime && typeof serverTime === 'number') {
+      const o = arrival - serverTime;
+      this._offset = this._offset == null ? o : this._offset + 0.05 * (o - this._offset);
+    }
+
+    // Stamp the time used for the interpolation domain.
+    const time = (this._useServerTime && typeof serverTime === 'number') ? serverTime : arrival;
+    this.vault.add({ time, state });
+  }
+
+  _renderTime() {
+    if (this._useServerTime && this._offset != null) return (this._now() - this._offset) - this._bufferMs;
+    return this._now() - this._bufferMs;
+  }
+
+  /**
+   * Interpolated entities for the current render instant.
+   * @param {string} keys   e.g. 'x y' or 'x y angle(deg)'
+   * @param {string} [group]
+   * @returns {Array|null}
+   */
+  calc(keys, group) {
+    const renderTime = this._renderTime();
+    const latest = this.vault.latest();
+    if (!latest) return null;
+    const specs = parseKeys(keys);
+
+    // Buffer underrun: render time is ahead of the newest snapshot.
+    if (renderTime > latest.time) {
+      if (this._extrapolationMs > 0) return this._extrapolate(renderTime, specs, group);
+      return asEntityArray(latest.state, group).map((e) => Object.assign({}, e));
+    }
+
+    const [older, newer] = this.vault.straddle(renderTime);
+    if (!older || !newer) return null;
+
+    let t = 0;
+    if (newer.time !== older.time) {
+      t = (renderTime - older.time) / (newer.time - older.time);
+      t = t < 0 ? 0 : t > 1 ? 1 : t;
+    }
+    return this._blend(asEntityArray(older.state, group), asEntityArray(newer.state, group), t, specs);
+  }
+
+  _blend(oldEntities, newEntities, t, specs) {
+    const oldById = {};
+    for (let i = 0; i < oldEntities.length; i++) oldById[oldEntities[i].id] = oldEntities[i];
+    return newEntities.map((nentity) => {
+      const oentity = oldById[nentity.id];
+      const out = Object.assign({}, nentity);
+      if (oentity) {
+        for (let i = 0; i < specs.length; i++) {
+          const { key, type } = specs[i];
+          const a = oentity[key];
+          const b = nentity[key];
+          if (typeof a === 'number' && typeof b === 'number') out[key] = lerpField(a, b, t, type);
+        }
+      }
+      return out;
+    });
+  }
+
+  _extrapolate(renderTime, specs, group) {
+    const newer = this.vault.latest();
+    const older = this.vault.prevLatest();
+    const newEntities = asEntityArray(newer.state, group);
+    if (!older || newer.time <= older.time) return newEntities.map((e) => Object.assign({}, e));
+
+    const dt = Math.min(renderTime - newer.time, this._extrapolationMs); // cap
+    const span = newer.time - older.time;
+    const oldById = {};
+    const oldEntities = asEntityArray(older.state, group);
+    for (let i = 0; i < oldEntities.length; i++) oldById[oldEntities[i].id] = oldEntities[i];
+
+    return newEntities.map((nentity) => {
+      const oentity = oldById[nentity.id];
+      const out = Object.assign({}, nentity);
+      if (oentity) {
+        for (let i = 0; i < specs.length; i++) {
+          const { key } = specs[i]; // linear extrapolation (angles handled as linear here)
+          const a = oentity[key];
+          const b = nentity[key];
+          if (typeof a === 'number' && typeof b === 'number') {
+            const vel = (b - a) / span;
+            out[key] = b + vel * dt;
+          }
+        }
+      }
+      return out;
+    });
+  }
+}