@usions/sdk 2.1.5 → 2.10.0

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

package/src/modules/netcode/webtransport.js

@@ -0,0 +1,195 @@
+/**
+ * Usion SDK Netcode — WebTransport (HTTP/3 / QUIC) client transport.
+ *
+ * The lowest-latency *client-server* path for browser games (Baseline across
+ * major browsers since 2026). Unlike WebSocket (TCP → head-of-line blocking)
+ * it offers UDP-like unreliable **datagrams** — the newest snapshot always
+ * gets through — plus reliable **streams** for must-arrive events, over a
+ * single QUIC connection, without WebRTC's ICE/STUN/TURN/SDP complexity.
+ *
+ * Uses the native `WebTransport` API (zero dependency). On the server, pair
+ * with an HTTP/3 server such as the open-source `@fails-components/webtransport`
+ * (Node). Same interface shape as MeshConnection so it drops into the same
+ * snapshot sender/receiver + interpolation pipeline.
+ *
+ * Framing:
+ *   - datagram = [seq:uint32 BE][type:uint8][payload]  (one datagram = one msg)
+ *   - stream   = [len:uint32 BE][type:uint8][payload]  (len = 1 + payload bytes)
+ *   - type 0 = binary (Uint8Array), 1 = JSON (utf8). Sequenced datagrams drop
+ *     stale/out-of-order frames (receiver only advances).
+ */
+const _enc = typeof TextEncoder !== 'undefined' ? new TextEncoder() : null;
+const _dec = typeof TextDecoder !== 'undefined' ? new TextDecoder() : null;
+
+function toBytes(s) { return _enc ? _enc.encode(s) : Uint8Array.from(Buffer.from(s, 'utf8')); }
+function fromBytes(b) { return _dec ? _dec.decode(b) : Buffer.from(b).toString('utf8'); }
+function isBinary(d) { return d instanceof ArrayBuffer || ArrayBuffer.isView(d); }
+
+/** Encode a value to { type, bytes }: binary passthrough or JSON utf8. */
+function encodePayload(data) {
+  if (isBinary(data)) return { type: 0, bytes: data instanceof Uint8Array ? data : new Uint8Array(data.buffer || data) };
+  return { type: 1, bytes: toBytes(JSON.stringify(data)) };
+}
+function decodePayload(type, bytes) {
+  if (type === 1) { try { return JSON.parse(fromBytes(bytes)); } catch (_) { return null; } }
+  return bytes;
+}
+
+/** datagram frame: [seq:4][type:1][payload] */
+export function encodeDatagram(seq, data) {
+  const { type, bytes } = encodePayload(data);
+  const out = new Uint8Array(5 + bytes.length);
+  new DataView(out.buffer).setUint32(0, seq >>> 0, false);
+  out[4] = type;
+  out.set(bytes, 5);
+  return out;
+}
+export function decodeDatagram(frame) {
+  const b = frame instanceof Uint8Array ? frame : new Uint8Array(frame);
+  if (b.length < 5) return null;
+  const seq = new DataView(b.buffer, b.byteOffset, b.byteLength).getUint32(0, false);
+  return { seq: seq, value: decodePayload(b[4], b.subarray(5)) };
+}
+
+/** stream frame: [len:4][type:1][payload], len = 1 + payload length */
+export function encodeStreamFrame(data) {
+  const { type, bytes } = encodePayload(data);
+  const out = new Uint8Array(4 + 1 + bytes.length);
+  new DataView(out.buffer).setUint32(0, 1 + bytes.length, false);
+  out[4] = type;
+  out.set(bytes, 5);
+  return out;
+}
+
+/** Stateful deframer for the reliable byte stream. push(bytes) → [values]. */
+export class StreamDeframer {
+  constructor() { this._buf = new Uint8Array(0); }
+  push(chunk) {
+    const c = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
+    const merged = new Uint8Array(this._buf.length + c.length);
+    merged.set(this._buf, 0); merged.set(c, this._buf.length);
+    this._buf = merged;
+    const out = [];
+    while (this._buf.length >= 4) {
+      const len = new DataView(this._buf.buffer, this._buf.byteOffset, 4).getUint32(0, false);
+      if (this._buf.length < 4 + len) break;
+      const type = this._buf[4];
+      const payload = this._buf.subarray(5, 4 + len);
+      out.push(decodePayload(type, payload.slice()));
+      this._buf = this._buf.subarray(4 + len);
+    }
+    return out;
+  }
+}
+
+export class WebTransportConnection {
+  /**
+   * @param {object} opts
+   * @param {string} opts.url                          https:// HTTP/3 endpoint
+   * @param {Array}  [opts.serverCertificateHashes]    for self-signed dev certs
+   * @param {boolean}[opts.sequenced=true]             drop stale datagrams
+   * @param {Function}[opts.WebTransport]              injectable for tests
+   */
+  constructor(opts = {}) {
+    if (!opts.url) throw new Error('WebTransportConnection requires a url');
+    this._url = opts.url;
+    this._opts = opts;
+    this._sequenced = opts.sequenced !== false;
+    this._WT = opts.WebTransport || (typeof WebTransport !== 'undefined' ? WebTransport : null);
+
+    this.connected = false;
+    this._t = null;
+    this._dgWriter = null;
+    this._streamWriter = null;
+    this._deframer = new StreamDeframer();
+    this._sendSeq = 0;
+    this._recvSeq = 0;
+
+    this.onOpen = null;        // () => void
+    this.onMessage = null;     // (data, channel:'datagram'|'reliable') => void
+    this.onClose = null;       // () => void
+    this.onError = null;       // (err) => void
+  }
+
+  async connect() {
+    if (!this._WT) throw new Error('WebTransport unavailable in this environment');
+    const init = {};
+    if (this._opts.serverCertificateHashes) init.serverCertificateHashes = this._opts.serverCertificateHashes;
+    const t = new this._WT(this._url, init);
+    this._t = t;
+    if (t.ready && typeof t.ready.then === 'function') await t.ready;
+
+    if (t.datagrams && t.datagrams.writable) this._dgWriter = t.datagrams.writable.getWriter();
+    if (typeof t.createBidirectionalStream === 'function') {
+      try {
+        const s = await t.createBidirectionalStream();
+        this._streamWriter = s.writable.getWriter();
+        this._pumpReadable(s.readable, 'reliable');
+      } catch (e) { /* reliable stream optional */ }
+    }
+    if (t.datagrams && t.datagrams.readable) this._pumpDatagrams(t.datagrams.readable);
+    if (t.closed && typeof t.closed.then === 'function') t.closed.then(() => this._onClosed(), () => this._onClosed());
+
+    this.connected = true;
+    if (this.onOpen) this.onOpen();
+  }
+
+  async _pumpDatagrams(readable) {
+    try {
+      const reader = readable.getReader();
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value) this._onDatagramBytes(value);
+      }
+    } catch (e) { if (this.onError) this.onError(e); }
+  }
+
+  async _pumpReadable(readable, channel) {
+    try {
+      const reader = readable.getReader();
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value) { const msgs = this._deframer.push(value); for (let i = 0; i < msgs.length; i++) if (this.onMessage) this.onMessage(msgs[i], channel); }
+      }
+    } catch (e) { if (this.onError) this.onError(e); }
+  }
+
+  /** Handle one inbound datagram frame (also the test entry point). */
+  _onDatagramBytes(frame) {
+    const parsed = decodeDatagram(frame);
+    if (!parsed) return;
+    if (this._sequenced) {
+      if (parsed.seq <= this._recvSeq) return; // stale / out-of-order
+      this._recvSeq = parsed.seq;
+    }
+    if (this.onMessage) this.onMessage(parsed.value, 'datagram');
+  }
+
+  /** Send over the unreliable datagram channel (sequenced). */
+  send(data) {
+    if (!this._dgWriter) return false;
+    this._sendSeq += 1;
+    try { this._dgWriter.write(encodeDatagram(this._sendSeq, data)); return true; }
+    catch (e) { return false; }
+  }
+
+  /** Send over the reliable ordered stream. */
+  sendReliable(data) {
+    if (!this._streamWriter) return false;
+    try { this._streamWriter.write(encodeStreamFrame(data)); return true; }
+    catch (e) { return false; }
+  }
+
+  _onClosed() {
+    if (this.connected) { this.connected = false; if (this.onClose) this.onClose(); }
+  }
+
+  close() {
+    try { if (this._dgWriter) this._dgWriter.releaseLock && this._dgWriter.releaseLock(); } catch (_) {}
+    try { if (this._t) this._t.close(); } catch (_) {}
+    this._t = this._dgWriter = this._streamWriter = null;
+    this.connected = false;
+  }
+}

package/src/modules/wallet.js

@@ -2,7 +2,7 @@
  * Usion SDK Wallet Module — wallet and payment operations
  */
 
-import { getNextRequestId } from './core.js';
+import { getNextRequestId, isTrustedMessageSource } from './core.js';
 
 /**
  * @param {object} Usion - Reference to the main Usion object
@@ -57,6 +57,10 @@ export function createWalletModule(Usion) {
 
         // Listen for response
         function handler(event) {
+          // Only honor payment results from the trusted host shell — a forged
+          // PAYMENT_SUCCESS must never resolve this promise.
+          if (!isTrustedMessageSource(event)) return;
+
           let response;
           try {
             response = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;