@usions/sdk 2.1.5 → 2.10.0

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 = {}; }
+}

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 = {};
+  }
+}