@usions/sdk 2.2.0 → 2.11.0

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;
+    });
+  }
+}

package/src/modules/netcode/lagcomp.js

@@ -0,0 +1,104 @@
+/**
+ * Usion SDK Netcode — server-side lag compensation ("server rewind").
+ *
+ * The fairness technique behind CS:GO/CS2 and Valorant. The authoritative
+ * server records a short history of world snapshots; when a client claims an
+ * action (e.g. a shot) the server **rewinds** the world to what that client
+ * actually saw — accounting for their latency and interpolation delay — and
+ * resolves the hit against that past state. Without this, high-ping players
+ * must "lead" their targets and hit registration feels broken.
+ *
+ * Entities are matched by `id` and interpolated between the two recorded
+ * snapshots straddling the rewind time (same math as client interpolation).
+ * Pure and testable; use it inside your game server (direct mode).
+ */
+function lerp(a, b, t) { return a + (b - a) * t; }
+
+export class LagCompensator {
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.historyMs=1000]  How far back to retain snapshots.
+   * @param {number} [opts.maxSize=256]      Hard cap on retained snapshots.
+   * @param {function} [opts.now]            Clock source (default Date.now).
+   */
+  constructor(opts = {}) {
+    this._historyMs = opts.historyMs || 1000;
+    this._maxSize = opts.maxSize || 256;
+    this._now = opts.now || (() => Date.now());
+    this._history = []; // [{ time, entities:[{id,...}] }] oldest→newest
+  }
+
+  /**
+   * Record the authoritative world state for this tick.
+   * @param {Array} entities  Array of entities (each with a stable `id`).
+   * @param {number} [time]   Server time (default now()).
+   */
+  record(entities, time) {
+    const t = time != null ? time : this._now();
+    this._history.push({ time: t, entities: entities.map((e) => Object.assign({}, e)) });
+    const cutoff = t - this._historyMs;
+    while (this._history.length > this._maxSize || (this._history.length > 2 && this._history[0].time < cutoff)) {
+      this._history.shift();
+    }
+  }
+
+  get size() { return this._history.length; }
+  clear() { this._history = []; }
+
+  /**
+   * Reconstruct the world as it was at `time` (interpolated), keyed by id.
+   * @param {number} time  Absolute server time to rewind to.
+   * @param {string[]} [keys]  Numeric fields to interpolate (default: all numbers).
+   * @returns {Object<string, object>} entities by id, or {} if no history.
+   */
+  rewind(time, keys) {
+    const h = this._history;
+    if (h.length === 0) return {};
+    if (time <= h[0].time) return byId(h[0].entities);
+    if (time >= h[h.length - 1].time) return byId(h[h.length - 1].entities);
+
+    let older = h[0], newer = h[h.length - 1];
+    for (let i = h.length - 1; i > 0; i--) {
+      if (h[i - 1].time <= time && time <= h[i].time) { older = h[i - 1]; newer = h[i]; break; }
+    }
+    const span = newer.time - older.time;
+    const t = span > 0 ? (time - older.time) / span : 0;
+    const oldById = byId(older.entities);
+    const out = {};
+    const newById = byId(newer.entities);
+    for (const id in newById) {
+      const b = newById[id];
+      const a = oldById[id];
+      const e = Object.assign({}, b);
+      if (a) {
+        const fields = keys || Object.keys(b);
+        for (let k = 0; k < fields.length; k++) {
+          const key = fields[k];
+          if (typeof a[key] === 'number' && typeof b[key] === 'number') e[key] = lerp(a[key], b[key], t);
+        }
+      }
+      out[id] = e;
+    }
+    return out;
+  }
+
+  /**
+   * Convenience: rewind to what a client saw, given their measured round-trip
+   * time and interpolation buffer. rewindMs is clamped to `maxRewindMs` (cap
+   * it — Valorant caps ~35ms; CS allows more).
+   * @returns {Object<string, object>} entities by id
+   */
+  rewindForClient(rttMs, interpBufferMs, opts) {
+    opts = opts || {};
+    const maxRewind = opts.maxRewindMs != null ? opts.maxRewindMs : 250;
+    let rewindMs = (rttMs || 0) / 2 + (interpBufferMs || 0);
+    if (rewindMs > maxRewind) rewindMs = maxRewind;
+    return this.rewind(this._now() - rewindMs, opts.keys);
+  }
+}
+
+function byId(entities) {
+  const m = {};
+  for (let i = 0; i < entities.length; i++) m[entities[i].id] = entities[i];
+  return m;
+}

package/src/modules/netcode/lockstep.js

@@ -0,0 +1,103 @@
+/**
+ * Usion SDK Netcode — deterministic lockstep (the League-of-Legends / RTS model).
+ *
+ * Instead of streaming world state, every client runs the **same deterministic
+ * simulation** and exchanges only **inputs**. Bandwidth is tiny even with
+ * hundreds of units, and you get **replays for free** (re-run the input log).
+ *
+ * A frame advances only once every player's input for that frame is known.
+ * Local inputs are scheduled `inputDelay` frames ahead so they have time to
+ * reach peers before that frame is simulated (this hides latency). The game
+ * owns its simulation; this class only orders inputs and tells you when to step.
+ *
+ * Determinism is the contract: your `step(frame, inputsByPlayer)` must be
+ * fully deterministic (no Date.now/Math.random without a seeded source, no
+ * floating-point divergence) or clients will desync.
+ */
+export class Lockstep {
+  /**
+   * @param {object} opts
+   * @param {string} opts.playerId
+   * @param {string[]} opts.players              All player ids in the match.
+   * @param {(frame:number, inputs:Object)=>void} opts.step  Deterministic sim step.
+   * @param {(msg:{frame:number,playerId:string,input:any})=>void} [opts.send]
+   * @param {number} [opts.inputDelay=2]         Frames of input delay (latency hiding).
+   * @param {any} [opts.idleInput=null]          Input used for the seeded startup frames.
+   */
+  constructor(opts = {}) {
+    if (!opts.playerId) throw new Error('Lockstep requires playerId');
+    if (!Array.isArray(opts.players) || opts.players.length === 0) throw new Error('Lockstep requires players[]');
+    if (typeof opts.step !== 'function') throw new Error('Lockstep requires a step(frame, inputs) function');
+    this.playerId = opts.playerId;
+    this._players = opts.players.slice();
+    this._step = opts.step;
+    this._send = opts.send || function () {};
+    this._inputDelay = opts.inputDelay != null ? opts.inputDelay : 2;
+    this._idle = opts.idleInput != null ? opts.idleInput : null;
+
+    this._inputs = {};        // frame -> { playerId: input }
+    this._frame = 0;          // next frame to simulate
+    this._submitFrame = this._inputDelay; // next frame the local player will fill
+    this._replay = [];        // [{ frame, inputs }]
+
+    // Seed the first `inputDelay` frames as idle so the sim can start.
+    for (let f = 0; f < this._inputDelay; f++) {
+      this._inputs[f] = {};
+      for (let i = 0; i < this._players.length; i++) this._inputs[f][this._players[i]] = this._idle;
+    }
+  }
+
+  get frame() { return this._frame; }
+  get players() { return this._players.slice(); }
+
+  /** Submit the local player's input for the next schedulable frame. */
+  submit(input) {
+    const frame = this._submitFrame++;
+    if (!this._inputs[frame]) this._inputs[frame] = {};
+    this._inputs[frame][this.playerId] = input;
+    this._send({ frame: frame, playerId: this.playerId, input: input });
+    return frame;
+  }
+
+  /** Record a remote player's input. */
+  receive(msg) {
+    if (!msg || msg.frame == null || !msg.playerId) return;
+    if (!this._inputs[msg.frame]) this._inputs[msg.frame] = {};
+    this._inputs[msg.frame][msg.playerId] = msg.input;
+  }
+
+  _ready(frame) {
+    const fr = this._inputs[frame];
+    if (!fr) return false;
+    for (let i = 0; i < this._players.length; i++) if (!(this._players[i] in fr)) return false;
+    return true;
+  }
+
+  /**
+   * Advance the simulation by every frame whose inputs are fully known.
+   * @returns {number} frames advanced this call.
+   */
+  tick() {
+    let advanced = 0;
+    while (this._ready(this._frame)) {
+      const inputs = this._inputs[this._frame];
+      this._step(this._frame, inputs);
+      this._replay.push({ frame: this._frame, inputs: inputs });
+      delete this._inputs[this._frame];
+      this._frame += 1;
+      advanced += 1;
+    }
+    return advanced;
+  }
+
+  /** True if the sim is blocked waiting on a missing input (stall detection). */
+  isStalled() { return !this._ready(this._frame); }
+
+  /** The ordered input log — persist it to enable replays. */
+  getReplay() { return this._replay.slice(); }
+
+  /** Re-simulate a recorded match by replaying its input log. */
+  static replay(log, step) {
+    for (let i = 0; i < log.length; i++) step(log[i].frame, log[i].inputs);
+  }
+}

package/src/modules/netcode/mesh-network.js

@@ -0,0 +1,103 @@
+/**
+ * Usion SDK Netcode — N-peer full mesh.
+ *
+ * Manages one MeshConnection per remote peer so >2 players can talk directly
+ * peer-to-peer. For each pair, the peer with the lexicographically smaller id
+ * is the host (deterministic role assignment avoids offer/answer "glare").
+ * Signaling is routed per-peer (`sendSignal(toPeerId, payload)`); feed inbound
+ * signaling with `handleSignal(fromPeerId, payload)`.
+ */
+import { MeshConnection } from './mesh.js';
+
+export class MeshNetwork {
+  /**
+   * @param {object} opts
+   * @param {string} opts.selfId
+   * @param {(toPeerId:string, payload:object)=>void} opts.sendSignal
+   * @param {Array} [opts.iceServers]
+   * @param {Function} [opts.RTCPeerConnection]
+   * @param {Function} [opts.setTimeout]
+   * @param {boolean} [opts.sequenced]
+   * @param {boolean} [opts.autoReconnect]
+   */
+  constructor(opts = {}) {
+    if (!opts.selfId) throw new Error('MeshNetwork requires a selfId');
+    if (typeof opts.sendSignal !== 'function') throw new Error('MeshNetwork requires sendSignal(toPeerId, payload)');
+    this.selfId = opts.selfId;
+    this._sendSignal = opts.sendSignal;
+    this._opts = opts;
+    this._peers = {}; // peerId -> MeshConnection
+
+    this.onPeerOpen = null;    // (peerId) => void
+    this.onPeerClose = null;   // (peerId) => void
+    this.onMessage = null;     // (peerId, data, channel) => void
+    this.onError = null;       // (peerId, err) => void
+  }
+
+  get peerIds() { return Object.keys(this._peers); }
+  get connectedCount() { let n = 0; for (const id in this._peers) if (this._peers[id].connected) n += 1; return n; }
+  peer(peerId) { return this._peers[peerId] || null; }
+
+  _roleFor(peerId) { return this.selfId < peerId ? 'host' : 'guest'; }
+
+  _ensurePeer(peerId) {
+    if (this._peers[peerId]) return this._peers[peerId];
+    const self = this;
+    const conn = new MeshConnection({
+      role: this._roleFor(peerId),
+      iceServers: this._opts.iceServers,
+      RTCPeerConnection: this._opts.RTCPeerConnection,
+      setTimeout: this._opts.setTimeout,
+      sequenced: this._opts.sequenced,
+      autoReconnect: this._opts.autoReconnect,
+      sendSignal: (payload) => self._sendSignal(peerId, payload),
+    });
+    conn.onOpen = () => { if (self.onPeerOpen) self.onPeerOpen(peerId); };
+    conn.onClose = () => { if (self.onPeerClose) self.onPeerClose(peerId); };
+    conn.onMessage = (data, channel) => { if (self.onMessage) self.onMessage(peerId, data, channel); };
+    conn.onError = (err) => { if (self.onError) self.onError(peerId, err); };
+    this._peers[peerId] = conn;
+    return conn;
+  }
+
+  /** Connect to a peer (creates the connection and starts negotiation). */
+  async addPeer(peerId) {
+    if (peerId === this.selfId) return null;
+    const conn = this._ensurePeer(peerId);
+    await conn.start();
+    return conn;
+  }
+
+  /** Sync the mesh to a roster of peer ids: connect to new ones, drop missing. */
+  async setRoster(peerIds) {
+    const want = {};
+    for (let i = 0; i < peerIds.length; i++) if (peerIds[i] !== this.selfId) want[peerIds[i]] = true;
+    for (const id in want) if (!this._peers[id]) await this.addPeer(id);
+    for (const id in this._peers) if (!want[id]) this.removePeer(id);
+  }
+
+  removePeer(peerId) {
+    const conn = this._peers[peerId];
+    if (!conn) return;
+    try { conn.close(); } catch (_) {}
+    delete this._peers[peerId];
+  }
+
+  /** Route an inbound signaling message from a peer. */
+  async handleSignal(fromPeerId, payload) {
+    if (!fromPeerId || fromPeerId === this.selfId) return;
+    const conn = this._ensurePeer(fromPeerId);
+    if (!conn._pc) await conn.start(); // lazily start guest side on first offer
+    await conn.handleSignal(payload);
+  }
+
+  /** Send to one peer over the unreliable channel. */
+  send(peerId, data) { const c = this._peers[peerId]; return c ? c.send(data) : false; }
+  sendReliable(peerId, data) { const c = this._peers[peerId]; return c ? c.sendReliable(data) : false; }
+
+  /** Broadcast to all connected peers (unreliable). */
+  broadcast(data) { for (const id in this._peers) this._peers[id].send(data); }
+  broadcastReliable(data) { for (const id in this._peers) this._peers[id].sendReliable(data); }
+
+  close() { for (const id in this._peers) { try { this._peers[id].close(); } catch (_) {} } this._peers = {}; }
+}