@usions/sdk 2.2.0 → 2.10.0

package/src/modules/netcode/mesh.js

@@ -0,0 +1,188 @@
+/**
+ * Usion SDK Netcode — WebRTC peer-to-peer data channels.
+ *
+ * WebSocket runs over TCP (ordered+reliable) → one lost packet stalls
+ * everything behind it (head-of-line blocking). WebRTC data channels run over
+ * UDP/SCTP and can be unreliable+unordered, so the newest state always gets
+ * through. Gameplay flows peer-to-peer (no backend hop, no HOL blocking).
+ *
+ * Practices adopted (WebRTC game-networking guidance):
+ *  - **Two channels**: 'unreliable' (ordered:false, maxRetransmits:0) for
+ *    gameplay, 'reliable' (ordered:true) for must-arrive events.
+ *  - **Sequence numbers** on the unreliable channel → drop stale/out-of-order
+ *    frames (the receiver only ever advances).
+ *  - **TURN-ready**: ~15–20% of sessions need a relay; pass iceServers (use the
+ *    `MeshConnection.iceServers()` helper). Trickle ICE is used by default.
+ *  - **Reconnect**: monitor (ice)connectionState and recover via ICE restart.
+ *
+ * Signaling I/O is injected, so the same class works in every connection mode
+ * and is testable with a fake RTCPeerConnection.
+ */
+const DEFAULT_ICE = [{ urls: 'stun:stun.l.google.com:19302' }];
+
+function isBinary(d) {
+  return d instanceof ArrayBuffer || ArrayBuffer.isView(d);
+}
+
+export class MeshConnection {
+  /**
+   * @param {object} opts
+   * @param {'host'|'guest'} opts.role
+   * @param {(payload:object)=>void} opts.sendSignal
+   * @param {Array} [opts.iceServers]
+   * @param {boolean} [opts.sequenced=true]    Drop stale frames on the unreliable channel.
+   * @param {boolean} [opts.autoReconnect=true] Recover via ICE restart (host).
+   * @param {number}  [opts.maxRestarts=5]
+   * @param {Function} [opts.RTCPeerConnection] Injectable for tests.
+   * @param {Function} [opts.setTimeout]        Injectable for tests.
+   */
+  constructor(opts = {}) {
+    if (opts.role !== 'host' && opts.role !== 'guest') throw new Error("MeshConnection requires role 'host' or 'guest'");
+    if (typeof opts.sendSignal !== 'function') throw new Error('MeshConnection requires a sendSignal(payload) function');
+    this.role = opts.role;
+    this._sendSignal = opts.sendSignal;
+    this._iceServers = opts.iceServers || DEFAULT_ICE;
+    this._sequenced = opts.sequenced !== false;
+    this._autoReconnect = opts.autoReconnect !== false;
+    this._maxRestarts = opts.maxRestarts != null ? opts.maxRestarts : 5;
+    this._RTCPeerConnection = opts.RTCPeerConnection || (typeof RTCPeerConnection !== 'undefined' ? RTCPeerConnection : null);
+    this._setTimeout = opts.setTimeout || (typeof setTimeout !== 'undefined' ? setTimeout : null);
+
+    this.connected = false;
+    this._pc = null;
+    this._unreliable = null;
+    this._reliable = null;
+    this._sendSeq = 0;
+    this._recvSeq = 0;
+    this._restarts = 0;
+
+    this.onOpen = null;          // () => void
+    this.onMessage = null;       // (data, channel) => void
+    this.onClose = null;         // () => void
+    this.onError = null;         // (err) => void
+    this.onStateChange = null;   // (state:string) => void
+  }
+
+  /** Build an iceServers array with optional TURN relay. */
+  static iceServers(cfg = {}) {
+    const list = [{ urls: cfg.stun || 'stun:stun.l.google.com:19302' }];
+    if (cfg.turn) {
+      const entry = { urls: cfg.turn };
+      if (cfg.turnUsername) entry.username = cfg.turnUsername;
+      if (cfg.turnCredential) entry.credential = cfg.turnCredential;
+      list.push(entry);
+    }
+    return list;
+  }
+
+  async start() {
+    if (!this._RTCPeerConnection) throw new Error('RTCPeerConnection unavailable');
+    const pc = new this._RTCPeerConnection({ iceServers: this._iceServers });
+    this._pc = pc;
+
+    pc.onicecandidate = (e) => { if (e && e.candidate) this._sendSignal({ type: 'ice', candidate: e.candidate }); };
+    const onState = () => this._handleStateChange(pc.connectionState || pc.iceConnectionState);
+    pc.onconnectionstatechange = onState;
+    pc.oniceconnectionstatechange = onState;
+
+    if (this.role === 'host') {
+      this._bindChannel((this._unreliable = pc.createDataChannel('unreliable', { ordered: false, maxRetransmits: 0 })), 'unreliable');
+      this._bindChannel((this._reliable = pc.createDataChannel('reliable', { ordered: true })), 'reliable');
+      await this._makeOffer(false);
+    } else {
+      pc.ondatachannel = (e) => {
+        const ch = e.channel;
+        if (ch.label === 'unreliable') this._bindChannel((this._unreliable = ch), 'unreliable');
+        else if (ch.label === 'reliable') this._bindChannel((this._reliable = ch), 'reliable');
+      };
+    }
+  }
+
+  async _makeOffer(iceRestart) {
+    const pc = this._pc;
+    const offer = await pc.createOffer(iceRestart ? { iceRestart: true } : undefined);
+    await pc.setLocalDescription(offer);
+    this._sendSignal({ type: 'offer', sdp: pc.localDescription, restart: !!iceRestart });
+  }
+
+  _handleStateChange(state) {
+    if (this.onStateChange) this.onStateChange(state);
+    if (state === 'connected') { this._restarts = 0; return; }
+    if (state === 'failed' || state === 'disconnected' || state === 'closed') {
+      if (this.connected) { this.connected = false; if (this.onClose) this.onClose(); }
+      if (this._autoReconnect && this.role === 'host' && state !== 'closed' && this._restarts < this._maxRestarts) {
+        this._restarts += 1;
+        const delay = Math.min(1000 * this._restarts, 5000);
+        if (this._setTimeout) this._setTimeout(() => { this._makeOffer(true).catch((err) => { if (this.onError) this.onError(err); }); }, delay);
+      }
+    }
+  }
+
+  async handleSignal(payload) {
+    const pc = this._pc;
+    if (!pc || !payload || !payload.type) return;
+    try {
+      if (payload.type === 'offer') {
+        await pc.setRemoteDescription(payload.sdp);
+        const answer = await pc.createAnswer();
+        await pc.setLocalDescription(answer);
+        this._sendSignal({ type: 'answer', sdp: pc.localDescription });
+      } else if (payload.type === 'answer') {
+        await pc.setRemoteDescription(payload.sdp);
+      } else if (payload.type === 'ice' && payload.candidate) {
+        await pc.addIceCandidate(payload.candidate);
+      }
+    } catch (err) {
+      if (this.onError) this.onError(err);
+    }
+  }
+
+  _bindChannel(ch, label) {
+    ch.binaryType = 'arraybuffer';
+    ch.onopen = () => {
+      if (label === 'unreliable' && !this.connected) { this.connected = true; if (this.onOpen) this.onOpen(); }
+    };
+    ch.onmessage = (e) => {
+      if (!this.onMessage) return;
+      let data = e.data;
+      if (isBinary(data)) { this.onMessage(data, label); return; }
+      try { data = typeof data === 'string' ? JSON.parse(data) : data; } catch (_) { this.onMessage(e.data, label); return; }
+      if (label === 'unreliable' && this._sequenced && data && typeof data.__s === 'number') {
+        if (data.__s <= this._recvSeq) return; // stale / out-of-order — drop
+        this._recvSeq = data.__s;
+        this.onMessage(data.m, label);
+        return;
+      }
+      this.onMessage(data, label);
+    };
+    ch.onclose = () => { if (this.connected) { this.connected = false; if (this.onClose) this.onClose(); } };
+    ch.onerror = (e) => { if (this.onError) this.onError(e); };
+  }
+
+  /** Send over the unreliable/unordered channel (sequenced unless binary). */
+  send(data) {
+    const ch = this._unreliable;
+    if (!ch || ch.readyState !== 'open') return false;
+    if (isBinary(data)) { ch.send(data); return true; }
+    if (this._sequenced) { this._sendSeq += 1; ch.send(JSON.stringify({ __s: this._sendSeq, m: data })); }
+    else ch.send(typeof data === 'string' ? data : JSON.stringify(data));
+    return true;
+  }
+
+  /** Send over the reliable/ordered channel. */
+  sendReliable(data) {
+    const ch = this._reliable;
+    if (!ch || ch.readyState !== 'open') return false;
+    if (isBinary(data)) ch.send(data);
+    else ch.send(typeof data === 'string' ? data : JSON.stringify(data));
+    return true;
+  }
+
+  close() {
+    try { if (this._unreliable) this._unreliable.close(); } catch (_) {}
+    try { if (this._reliable) this._reliable.close(); } catch (_) {}
+    try { if (this._pc) this._pc.close(); } catch (_) {}
+    this._unreliable = this._reliable = this._pc = null;
+    this.connected = false;
+  }
+}

package/src/modules/netcode/netsim.js

@@ -0,0 +1,77 @@
+/**
+ * Usion SDK Netcode — network condition simulator.
+ *
+ * Every serious game studio tests under degraded networks. NetworkSim wraps a
+ * send (or receive) function and injects artificial **latency**, **jitter**,
+ * **packet loss**, and **duplication** so creators can feel and tune their game
+ * on a bad connection — locally, before shipping. Pure and deterministic when
+ * you inject `random` / `setTimeout` (used in tests).
+ */
+export class NetworkSim {
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.latencyMs=0]  Base one-way delay added to each message.
+   * @param {number} [opts.jitterMs=0]   Random +/- variation around the latency.
+   * @param {number} [opts.lossPct=0]    Probability (0–100) a message is dropped.
+   * @param {number} [opts.dupPct=0]     Probability (0–100) a message is duplicated.
+   * @param {Function} [opts.setTimeout] Injectable scheduler (tests).
+   * @param {Function} [opts.clearTimeout]
+   * @param {Function} [opts.random]     Injectable RNG (tests).
+   */
+  constructor(opts = {}) {
+    this._set = opts.setTimeout || (typeof setTimeout !== 'undefined' ? setTimeout : null);
+    this._clear = opts.clearTimeout || (typeof clearTimeout !== 'undefined' ? clearTimeout : null);
+    this._rand = opts.random || Math.random;
+    this._timers = new Set();
+    this.set(opts);
+  }
+
+  /** Update conditions live. */
+  set(opts = {}) {
+    if (opts.latencyMs != null) this.latencyMs = Math.max(0, opts.latencyMs);
+    else if (this.latencyMs == null) this.latencyMs = 0;
+    if (opts.jitterMs != null) this.jitterMs = Math.max(0, opts.jitterMs);
+    else if (this.jitterMs == null) this.jitterMs = 0;
+    if (opts.lossPct != null) this.lossPct = Math.max(0, Math.min(100, opts.lossPct));
+    else if (this.lossPct == null) this.lossPct = 0;
+    if (opts.dupPct != null) this.dupPct = Math.max(0, Math.min(100, opts.dupPct));
+    else if (this.dupPct == null) this.dupPct = 0;
+    return this;
+  }
+
+  /** Delay for one message: latency ± jitter (never negative). */
+  _delay() {
+    const j = this.jitterMs ? (this._rand() * 2 - 1) * this.jitterMs : 0;
+    const d = this.latencyMs + j;
+    return d > 0 ? d : 0;
+  }
+
+  _schedule(fn, delay) {
+    if (!this._set) { fn(); return; }
+    const id = this._set(() => { this._timers.delete(id); fn(); }, delay);
+    this._timers.add(id);
+  }
+
+  /**
+   * Wrap a delivery function so calls are delayed/dropped/duplicated per the
+   * current conditions. The returned function has the same signature.
+   */
+  wrap(fn) {
+    const self = this;
+    return function (...args) {
+      // Fast path: no degradation configured.
+      if (!self.latencyMs && !self.jitterMs && !self.lossPct && !self.dupPct) return fn.apply(this, args);
+      if (self.lossPct && self._rand() * 100 < self.lossPct) return undefined; // dropped
+      const ctx = this;
+      self._schedule(() => fn.apply(ctx, args), self._delay());
+      if (self.dupPct && self._rand() * 100 < self.dupPct) self._schedule(() => fn.apply(ctx, args), self._delay());
+      return undefined;
+    };
+  }
+
+  /** Cancel all in-flight scheduled deliveries. */
+  flush() {
+    if (this._clear) for (const id of this._timers) this._clear(id);
+    this._timers.clear();
+  }
+}

package/src/modules/netcode/ping.js

@@ -0,0 +1,69 @@
+/**
+ * Usion SDK Netcode — Round-trip-time meter.
+ *
+ * Tracks RTT with an exponentially-weighted moving average plus a jitter
+ * estimate, so games (and the debug overlay) can surface real latency and so
+ * the interpolation buffer can be tuned to network conditions. Transport
+ * agnostic: feed it raw samples, or use begin()/end() to time individual
+ * probes.
+ */
+export class PingMeter {
+  /**
+   * @param {object} [opts]
+   * @param {number} [opts.alpha=0.2]  EWMA smoothing factor (0..1).
+   * @param {Function} [opts.now]      Clock source (default Date.now).
+   */
+  constructor(opts = {}) {
+    this._alpha = opts.alpha != null ? opts.alpha : 0.2;
+    this._now = opts.now || (() => Date.now());
+    this._rtt = null;
+    this._jitter = 0;
+    this._last = null;
+    this._id = 0;
+    this._outstanding = {};
+  }
+
+  /** Smoothed round-trip time in ms (null until the first sample). */
+  get rtt() { return this._rtt; }
+  /** One-way latency estimate (≈ rtt / 2). */
+  get latency() { return this._rtt == null ? null : this._rtt / 2; }
+  /** Smoothed absolute variation between samples (ms). */
+  get jitter() { return this._jitter; }
+  /** Most recent raw RTT sample (ms). */
+  get last() { return this._last; }
+
+  /** Start timing a probe; pass the returned id to end(). */
+  begin() {
+    const id = ++this._id;
+    this._outstanding[id] = this._now();
+    return id;
+  }
+
+  /** Complete a probe started with begin(); returns the RTT sample or null. */
+  end(id) {
+    const sent = this._outstanding[id];
+    if (sent == null) return null;
+    delete this._outstanding[id];
+    return this.sample(this._now() - sent);
+  }
+
+  /** Feed a raw RTT sample (ms). Returns the same value. */
+  sample(rttMs) {
+    if (!(rttMs >= 0)) return null;
+    if (this._rtt == null) {
+      this._rtt = rttMs;
+    } else {
+      this._jitter += this._alpha * (Math.abs(rttMs - this._rtt) - this._jitter);
+      this._rtt += this._alpha * (rttMs - this._rtt);
+    }
+    this._last = rttMs;
+    return rttMs;
+  }
+
+  reset() {
+    this._rtt = null;
+    this._jitter = 0;
+    this._last = null;
+    this._outstanding = {};
+  }
+}

package/src/modules/netcode/prediction.js

@@ -0,0 +1,113 @@
+/**
+ * Usion SDK Netcode — Client-side prediction + server reconciliation.
+ *
+ * Apply local input instantly (tagged with a sequence number); when the
+ * authoritative state arrives carrying the last input the server processed,
+ * snap to it and replay every still-unacknowledged input on top. The local
+ * player sees zero input delay while staying consistent with the server.
+ *
+ * Error smoothing (Overwatch / Gabriel Gambetta): hard-snapping the render
+ * position on every correction looks jittery. Instead we keep the visible
+ * position as `corrected + error`, where `error` is the gap a correction
+ * introduced, and decay that error to zero over a few frames — so corrections
+ * are smooth and, in the common case, invisible. Enable via `opts.smooth`.
+ *
+ * The game supplies a pure `apply(state, input) -> newState` (must not mutate).
+ */
+function parseSmoothKeys(smooth) {
+  if (!smooth) return null;
+  let keys = smooth.keys != null ? smooth.keys : smooth;
+  if (typeof keys === 'string') keys = keys.trim().split(/\s+/).filter(Boolean);
+  return Array.isArray(keys) && keys.length ? keys : null;
+}
+
+export class Predictor {
+  /**
+   * @param {object} opts
+   * @param {(state:any, input:any)=>any} opts.apply  Pure state transition.
+   * @param {any} [opts.initialState]
+   * @param {{keys?:string|string[], rate?:number, snapTo?:number}|string} [opts.smooth]
+   *   Error-smoothing config. `keys` are numeric fields to blend; `rate` is the
+   *   per-frame decay (0..1, default 0.2); `snapTo` is the residual below which
+   *   the error is zeroed (default 0.001).
+   */
+  constructor(opts = {}) {
+    if (typeof opts.apply !== 'function') throw new Error('Predictor requires an apply(state, input) function');
+    this._apply = opts.apply;
+    this._state = opts.initialState !== undefined ? opts.initialState : null;
+    this._seq = 0;
+    this._pending = [];
+    this._smoothKeys = parseSmoothKeys(opts.smooth);
+    this._smoothRate = (opts.smooth && opts.smooth.rate != null) ? opts.smooth.rate : 0.2;
+    this._snapTo = (opts.smooth && opts.smooth.snapTo != null) ? opts.smooth.snapTo : 0.001;
+    this._error = {};
+  }
+
+  get state() { return this._state; }
+  get pending() { return this._pending.slice(); }
+  get lastSeq() { return this._seq; }
+
+  /** Apply an input locally and record it. Attach the returned `seq` when sending. */
+  predict(input) {
+    this._seq += 1;
+    const seq = this._seq;
+    this._pending.push({ seq, input });
+    this._state = this._apply(this._state, input);
+    return { seq, state: this._state };
+  }
+
+  /**
+   * Reconcile against authoritative server state.
+   * @param {any} serverState   Authoritative state.
+   * @param {number} ackedSeq   Highest input sequence the server has applied.
+   * @returns {any} the corrected predicted state (authoritative + replayed inputs)
+   */
+  reconcile(serverState, ackedSeq) {
+    const before = this._state;
+    const ack = ackedSeq == null ? -1 : ackedSeq;
+    this._pending = this._pending.filter((p) => p.seq > ack);
+    let s = serverState;
+    for (let i = 0; i < this._pending.length; i++) s = this._apply(s, this._pending[i].input);
+
+    // Accumulate the correction gap into the error offset for smoothing.
+    if (this._smoothKeys && before && s) {
+      for (let i = 0; i < this._smoothKeys.length; i++) {
+        const k = this._smoothKeys[i];
+        if (typeof before[k] === 'number' && typeof s[k] === 'number') {
+          this._error[k] = (this._error[k] || 0) + (before[k] - s[k]);
+        }
+      }
+    }
+    this._state = s;
+    return this._state;
+  }
+
+  /**
+   * The state to render: corrected state plus the decaying error offset.
+   * Call once per rendered frame; it decays the error toward zero.
+   * @param {number} [rate] Override the per-frame decay factor.
+   * @returns {any}
+   */
+  view(rate) {
+    if (!this._smoothKeys || !this._state || typeof this._state !== 'object') return this._state;
+    const r = rate != null ? rate : this._smoothRate;
+    const out = Array.isArray(this._state) ? this._state.slice() : Object.assign({}, this._state);
+    for (let i = 0; i < this._smoothKeys.length; i++) {
+      const k = this._smoothKeys[i];
+      let e = this._error[k] || 0;
+      if (typeof out[k] === 'number' && e !== 0) out[k] = out[k] + e;
+      e *= (1 - r);
+      if (Math.abs(e) < this._snapTo) e = 0;
+      this._error[k] = e;
+    }
+    return out;
+  }
+
+  /** Hard reset (e.g. on rematch). */
+  reset(state) {
+    this._state = state !== undefined ? state : null;
+    this._seq = 0;
+    this._pending = [];
+    this._error = {};
+  }
+}

package/src/modules/netcode/sender.js

@@ -0,0 +1,102 @@
+/**
+ * Usion SDK Netcode — Outbound send coalescing at a fixed tick rate.
+ *
+ * Games tend to emit on every input event or every animation frame (often
+ * 60+/s). Each emit is a separate Socket.IO message and, in platform mode,
+ * a separate server-side broadcast (and historically a Redis write). That
+ * floods the wire and the server far beyond what gameplay needs.
+ *
+ * The Coalescer buffers outbound messages and flushes them on a fixed tick
+ * (e.g. 20 Hz). Two modes per channel:
+ *   - queue(type, data): latest-wins — only the newest value per type is sent
+ *     each tick. Ideal for state snapshots, cursor/position updates.
+ *   - append(type, data): buffered — every value is kept and sent as a batch.
+ *     Use for discrete inputs you can't afford to drop.
+ *
+ * `onFlush(entries)` receives `[{ type, data }]` in insertion order. The
+ * Coalescer is transport-agnostic; the caller decides how to send each entry
+ * (game.realtime, game.action, a WebRTC datachannel, etc.).
+ */
+export class Coalescer {
+  /**
+   * @param {object} opts
+   * @param {number} [opts.hz=20]                 Flush frequency.
+   * @param {(entries:Array<{type:string,data:any}>)=>void} opts.onFlush
+   * @param {boolean} [opts.autoStart=true]
+   * @param {Function} [opts.setInterval]         Injectable for tests.
+   * @param {Function} [opts.clearInterval]
+   */
+  constructor(opts = {}) {
+    if (typeof opts.onFlush !== 'function') {
+      throw new Error('Coalescer requires an onFlush(entries) callback');
+    }
+    this._onFlush = opts.onFlush;
+    this._hz = opts.hz || 20;
+    this._setInterval = opts.setInterval || (typeof setInterval !== 'undefined' ? setInterval : null);
+    this._clearInterval = opts.clearInterval || (typeof clearInterval !== 'undefined' ? clearInterval : null);
+    this._order = [];          // slot keys in first-seen order
+    this._slots = {};          // key -> { mode:'latest'|'list', value, list }
+    this._timer = null;
+    if (opts.autoStart !== false) this.start();
+  }
+
+  get running() { return this._timer !== null; }
+
+  _ensure(type, mode) {
+    let slot = this._slots[type];
+    if (!slot) {
+      slot = { mode, value: undefined, list: [] };
+      this._slots[type] = slot;
+      this._order.push(type);
+    }
+    return slot;
+  }
+
+  /** Latest-wins: only the newest data for `type` is sent on the next flush. */
+  queue(type, data) {
+    const slot = this._ensure(type, 'latest');
+    slot.mode = 'latest';
+    slot.value = data;
+  }
+
+  /** Buffered: every value for `type` is kept and sent on the next flush. */
+  append(type, data) {
+    const slot = this._ensure(type, 'list');
+    slot.mode = 'list';
+    slot.list.push(data);
+  }
+
+  /** Build pending entries (insertion order) and clear the buffer. */
+  drain() {
+    const entries = [];
+    for (let i = 0; i < this._order.length; i++) {
+      const type = this._order[i];
+      const slot = this._slots[type];
+      if (slot.mode === 'latest') {
+        if (slot.value !== undefined) entries.push({ type, data: slot.value });
+      } else {
+        for (let j = 0; j < slot.list.length; j++) entries.push({ type, data: slot.list[j] });
+      }
+    }
+    this._order = [];
+    this._slots = {};
+    return entries;
+  }
+
+  /** Flush now (also called automatically on each tick). */
+  flush() {
+    if (this._order.length === 0) return;
+    const entries = this.drain();
+    if (entries.length) this._onFlush(entries);
+  }
+
+  start() {
+    if (this._timer || !this._setInterval) return;
+    this._timer = this._setInterval(() => this.flush(), Math.max(1, Math.round(1000 / this._hz)));
+  }
+
+  stop() {
+    if (this._timer && this._clearInterval) this._clearInterval(this._timer);
+    this._timer = null;
+  }
+}