@usions/sdk 2.2.0 → 2.11.0

package/src/modules/backend-channel.js

@@ -0,0 +1,76 @@
+/**
+ * Usion SDK — unified backend channel.
+ *
+ * One switchboard for backend request/response + server push that works in
+ * every mode, so features (lobby, matchmaking, presence, …) never reach for a
+ * specific socket:
+ *
+ *   - standalone / platform : uses the SDK's own Socket.IO socket (game.socket)
+ *   - embedded (iframe/WebView): relays through the parent app via postMessage
+ *     (BACKEND_EMIT request → host emits on its authenticated socket; the host
+ *     forwards allow-listed server pushes back as BACKEND_EVENT)
+ *
+ * Security: in embedded mode the host MUST restrict which events it relays to a
+ * safe, namespaced allow-list (e.g. lobby:* / mm:*) so a mini-app can't abuse
+ * the user's authenticated connection. The backend re-validates every call.
+ */
+export function applyBackendChannel(Usion) {
+  Usion._backendHandlers = {};
+  Usion._boundSockets = typeof WeakSet !== 'undefined' ? new WeakSet() : null;
+
+  /**
+   * Bind a Socket.IO socket so any allow-listed server event is routed to the
+   * registered _backendOn handlers (via onAny — robust to registration order).
+   */
+  Usion._bindBackendSocket = function (socket) {
+    if (!socket || typeof socket.onAny !== 'function') return;
+    if (this._boundSockets) {
+      if (this._boundSockets.has(socket)) return;
+      this._boundSockets.add(socket);
+    }
+    const self = this;
+    socket.onAny(function (event, payload) {
+      const h = self._backendHandlers[event];
+      if (h) h(payload);
+    });
+  };
+
+  /** Subscribe to a backend server-push event (works in all modes). */
+  Usion._backendOn = function (event, handler) {
+    this._backendHandlers[event] = handler;
+    const s = this.game && this.game.socket;
+    if (s) {
+      if (typeof s.onAny === 'function') this._bindBackendSocket(s);
+      else if (typeof s.on === 'function') s.on(event, handler); // fallback (tests / minimal sockets)
+    }
+  };
+
+  /**
+   * Emit a backend request and await its ack. Routes to the SDK socket when
+   * standalone, or through the parent host when embedded.
+   * @returns {Promise<any>}
+   */
+  Usion._backendEmit = function (event, data, timeout) {
+    const self = this;
+    timeout = timeout || 8000;
+    const s = self.game && self.game.socket;
+    if (s && s.connected) {
+      return new Promise(function (resolve, reject) {
+        let done = false;
+        const timer = setTimeout(function () { if (done) return; done = true; reject(new Error('Backend request timeout')); }, timeout);
+        try {
+          s.emit(event, data || {}, function (resp) {
+            if (done) return; done = true; clearTimeout(timer);
+            if (resp && resp.error) reject(new Error(resp.message || resp.error));
+            else resolve(resp);
+          });
+        } catch (e) { clearTimeout(timer); reject(e); }
+      });
+    }
+    if (self._isEmbedded) {
+      // Host relays this onto its authenticated socket and replies with the ack.
+      return self._request('BACKEND_EMIT', { event: event, data: data || {} }, timeout);
+    }
+    return Promise.reject(new Error('No backend connection — call Usion.game.connect() first'));
+  };
+}

package/src/modules/cloud.js

@@ -0,0 +1,67 @@
+/**
+ * Usion SDK Cloud — server-persisted KV storage for mini-apps.
+ *
+ * Unlike `Usion.storage` (device-local), cloud values live on the backend and
+ * survive reinstall / device switch. Enabled for every service, bounded by
+ * quotas (64 KB per value, 200 keys / 1 MB per bucket, 60 ops/min).
+ * Rides the unified backend channel, so it works standalone AND embedded.
+ *
+ * Per-user scope (each user sees only their own data):
+ *   await Usion.cloud.set('save', { level: 3 });
+ *   const save = await Usion.cloud.get('save');   // null if absent
+ *   await Usion.cloud.remove('save');
+ *   const keys = await Usion.cloud.keys();
+ *
+ * Shared scope (one bucket per app — ALL users read and write):
+ *   await Usion.cloud.shared.set('motd', 'hello');
+ *   const plays = await Usion.cloud.shared.incr('plays');  // atomic counter
+ *
+ * Keys: 1-128 chars of A-Za-z0-9_.-:/
+ */
+export function createCloudModule(Usion) {
+  function serviceId(opts) {
+    return (opts && opts.serviceId) || (Usion.config && Usion.config.serviceId);
+  }
+
+  function emit(event, scope, extra, opts) {
+    var payload = Object.assign({ service_id: serviceId(opts), scope: scope }, extra);
+    return Usion._backendEmit(event, payload);
+  }
+
+  function scopeApi(scope) {
+    return {
+      /** Get a value; resolves to null when the key doesn't exist. */
+      get: function (key, opts) {
+        return emit('kv:get', scope, { key: key }, opts)
+          .then(function (r) { return r && r.exists ? r.value : null; });
+      },
+
+      /** Set a JSON-serializable value (max 64 KB). */
+      set: function (key, value, opts) {
+        return emit('kv:set', scope, { key: key, value: value }, opts);
+      },
+
+      /** Remove a key. Resolves to { success, removed }. */
+      remove: function (key, opts) {
+        return emit('kv:remove', scope, { key: key }, opts);
+      },
+
+      /** List keys in this scope's bucket. */
+      keys: function (opts) {
+        return emit('kv:keys', scope, {}, opts)
+          .then(function (r) { return (r && r.keys) || []; });
+      },
+    };
+  }
+
+  var cloud = scopeApi('user');
+  cloud.shared = scopeApi('shared');
+
+  /** Atomically increment a shared numeric value (default delta 1). Resolves to the new value. */
+  cloud.shared.incr = function (key, delta, opts) {
+    return emit('kv:incr', 'shared', { key: key, delta: delta == null ? 1 : delta }, opts)
+      .then(function (r) { return r && r.value; });
+  };
+
+  return cloud;
+}

package/src/modules/core.js

@@ -181,6 +181,12 @@ export const core = {
       if (data.type === 'BOT_MESSAGE' && self.bot && self.bot._messageHandler) {
         self.bot._messageHandler(data.message);
       }
+
+      // Handle backend server-push events relayed by the host (embedded mode).
+      if (data.type === 'BACKEND_EVENT' && data.event && self._backendHandlers) {
+        const h = self._backendHandlers[data.event];
+        if (h) h(data.data);
+      }
     });
 
     // Signal ready to parent

package/src/modules/game-core.js

@@ -6,6 +6,7 @@ import { applyGameDirect } from './game-direct.js';
 import { applyGameSocket } from './game-socket.js';
 import { applyGameProxy } from './game-proxy.js';
 import { applyGameMethods } from './game-methods.js';
+import { applyGameNetcode } from './game-netcode.js';
 
 /**
  * Create the game module with all sub-modules applied
@@ -30,6 +31,8 @@ export function createGameModule(Usion) {
     _useProxy: false,
     _proxyListenerSetup: false,
     _heartbeatInterval: null,
+    _pingMeter: null,
+    _pongWaiters: [],
 
     /**
      * Connect to the game socket server
@@ -145,6 +148,7 @@ export function createGameModule(Usion) {
   applyGameSocket(game, Usion);
   applyGameProxy(game, Usion);
   applyGameMethods(game, Usion);
+  applyGameNetcode(game, Usion);
 
   return game;
 }

package/src/modules/game-direct.js

@@ -26,6 +26,9 @@ export function applyGameDirect(game, Usion) {
 
     self._connecting = true;
     self.directMode = true;
+    self._autoReconnect = config.autoReconnect !== undefined
+      ? config.autoReconnect
+      : !(Usion.config && Usion.config.autoReconnect === false);
     self._connectPromise = self._fetchDirectAccess(config)
       .then(function(access) {
         self.directConfig = access;
@@ -154,6 +157,10 @@ export function applyGameDirect(game, Usion) {
         if (self._eventHandlers.disconnect) {
           self._eventHandlers.disconnect(evt && evt.reason ? evt.reason : 'direct socket closed');
         }
+        // Seamless resume: if the drop wasn't an intentional disconnect()
+        // (which clears directMode), transparently re-establish + re-join +
+        // resync from the last sequence.
+        if (self.directMode && self._autoReconnect !== false) self._scheduleDirectReconnect();
       };
 
       ws.onmessage = function(evt) {
@@ -162,6 +169,39 @@ export function applyGameDirect(game, Usion) {
     });
   };
 
+  /**
+   * Reconnect a dropped direct-mode socket with capped exponential backoff,
+   * then re-join the room and request a resync (Dota-style "fetch latest
+   * snapshot = instant rejoin"). Keeps retrying while still in directMode.
+   * @private
+   */
+  game._scheduleDirectReconnect = function() {
+    var self = this;
+    if (self._reconnecting) return;
+    self._reconnecting = true;
+    var attempt = self._reconnectAttempt || 0;
+    var go = function() {
+      if (!self.directMode) { self._reconnecting = false; return; } // disconnected meanwhile
+      attempt += 1;
+      self._reconnectAttempt = attempt;
+      self._fetchDirectAccess({})
+        .then(function(access) { self.directConfig = access; return self._initDirectSocket(access); })
+        .then(function() {
+          self.connected = true;
+          self._reconnecting = false;
+          self._reconnectAttempt = 0;
+          if (self._eventHandlers.reconnect) self._eventHandlers.reconnect(attempt);
+          if (self.roomId) self.requestSync(self._lastSequence || 0); // resync / resume
+        })
+        .catch(function() {
+          if (!self.directMode) { self._reconnecting = false; return; }
+          var delay = Math.min(1000 * Math.pow(2, attempt - 1), 15000);
+          setTimeout(go, delay);
+        });
+    };
+    setTimeout(go, 500);
+  };
+
   game._sendDirect = function(type, payload) {
     if (!this.directSocket || this.directSocket.readyState !== WebSocket.OPEN) return;
     this._directSeq = this._directSeq + 1;
@@ -205,6 +245,11 @@ export function applyGameDirect(game, Usion) {
       return;
     }
     if (data.type === 'pong') {
+      // Resolve a pending game.ping() RTT probe, if any.
+      if (this._pongWaiters && this._pongWaiters.length) {
+        const waiter = this._pongWaiters.shift();
+        if (waiter) waiter();
+      }
       if (this._eventHandlers.sync) this._eventHandlers.sync(payload);
       return;
     }

package/src/modules/game-netcode.js

@@ -0,0 +1,346 @@
+/**
+ * Usion SDK Game Netcode — convenience wiring of the netcode toolkit onto the
+ * game module. These helpers ride on the existing realtime/action channels, so
+ * they work in every connection mode with no host/backend change (the one
+ * exception is RTT measurement — see game.ping below).
+ */
+import { SnapshotInterpolation } from './netcode/interpolation.js';
+import { Predictor } from './netcode/prediction.js';
+import { Coalescer } from './netcode/sender.js';
+import { PingMeter } from './netcode/ping.js';
+import { MeshConnection } from './netcode/mesh.js';
+import { MeshNetwork } from './netcode/mesh-network.js';
+import { WebTransportConnection } from './netcode/webtransport.js';
+import { NetworkSim } from './netcode/netsim.js';
+import { Lockstep } from './netcode/lockstep.js';
+import { LagCompensator } from './netcode/lagcomp.js';
+import { diff, patch, quantize } from './netcode/delta.js';
+import { encode, decode } from './netcode/binary.js';
+
+export function applyGameNetcode(game, Usion) {
+  game.diff = diff;
+  game.patch = patch;
+  game.quantize = quantize;
+  game.encode = encode;
+  game.decode = decode;
+
+  game.createInterpolation = function (opts) { return new SnapshotInterpolation(opts || {}); };
+  game.createPredictor = function (opts) { return new Predictor(opts || {}); };
+  game.createLagCompensator = function (opts) { return new LagCompensator(opts || {}); };
+  game.createLockstep = function (opts) { return new Lockstep(opts || {}); };
+
+  // ── Realtime channel router ──────────────────────────────────────────────
+  // Multiplexes realtime by action_type so replicate / mesh / mesh-network and
+  // the game's own onRealtime can coexist. Also the inject point for the
+  // network simulator's inbound side.
+  game._channels = game._channels || {};
+  game._userRealtime = game._userRealtime || null;
+  game._inboundDispatch = null;
+  function dispatchRealtime(data) {
+    const at = data && data.action_type;
+    if (at && game._channels[at]) { game._channels[at](data && (data.action_data !== undefined ? data.action_data : data), data); return; }
+    if (game._userRealtime) game._userRealtime(data);
+  }
+  game._dispatchRealtime = dispatchRealtime;
+  game._installRealtimeRouter = function () {
+    if (game._routerInstalled) return;
+    if (game._eventHandlers.realtime && game._eventHandlers.realtime !== game._router) game._userRealtime = game._eventHandlers.realtime;
+    game._router = function (data) { (game._inboundDispatch || game._dispatchRealtime)(data); };
+    game._eventHandlers.realtime = game._router;
+    game._routerInstalled = true;
+  };
+  /** Register a handler for one realtime action_type. Returns an unsubscribe fn. */
+  game._onChannel = function (type, handler) { game._channels[type] = handler; game._installRealtimeRouter(); return function () { delete game._channels[type]; }; };
+  // Route onRealtime through the router so channels keep working.
+  game.onRealtime = function (cb) { game._userRealtime = cb; game._installRealtimeRouter(); };
+
+  /** Fixed-rate outbound sender (defaults to game.realtime). */
+  game.createSender = function (opts) {
+    opts = opts || {};
+    const self = this;
+    const send = opts.send || function (type, data) { self.realtime(type, data); };
+    return new Coalescer({
+      hz: opts.hz || 20,
+      autoStart: opts.autoStart !== false,
+      onFlush: function (entries) { for (let i = 0; i < entries.length; i++) send(entries[i].type, entries[i].data); },
+    });
+  };
+
+  /**
+   * Coalesced, sequence-guarded, delta-compressed snapshot sender.
+   *
+   * Deltas are computed against the **last keyframe** (not the previous frame),
+   * so a single lost delta on an unreliable channel never desyncs — the next
+   * delta still applies to the keyframe the receiver holds. Each message
+   * carries a monotonic seq (`s`) and, for deltas, the keyframe seq it's based
+   * on (`b`); the receiver uses these to drop stale/out-of-order frames and to
+   * hold until it has the right keyframe. Optional float `precision`
+   * (quantization) and binary `encode` shrink the wire further.
+   *
+   * Pass `source` (a getter) to auto-read the state each tick — the basis for
+   * game.replicate(). Pair with game.createSnapshotReceiver().
+   */
+  game.createSnapshotSender = function (opts) {
+    opts = opts || {};
+    const self = this;
+    const channel = opts.channel || 'state';
+    const useDelta = opts.delta !== false;
+    const keyframeEvery = opts.keyframeEvery != null ? opts.keyframeEvery : 30;
+    const precision = opts.precision;
+    const enc = opts.encode === true ? encode : (typeof opts.encode === 'function' ? opts.encode : null);
+    const send = opts.send || function (type, data) { self.realtime(type, data); };
+    const source = typeof opts.source === 'function' ? opts.source : null;
+    let keyframeState = null; // an immutable clone (deltas diff against this)
+    let keyframeSeq = 0;
+    let seq = 0;
+    let sinceKey = 0;
+
+    function snapshotClone(v) { return v == null ? v : JSON.parse(JSON.stringify(v)); }
+
+    function emit(raw) {
+      if (raw === undefined || raw === null) return;
+      const state = precision != null ? quantize(raw, precision) : raw;
+      let payload;
+      const wantKey = !useDelta || keyframeState === null || sinceKey >= keyframeEvery;
+      if (wantKey) {
+        seq += 1; keyframeState = snapshotClone(state); keyframeSeq = seq; sinceKey = 0;
+        payload = { s: seq, f: state };
+      } else {
+        const d = diff(keyframeState, state);
+        if (d === undefined) return; // nothing changed — don't burn a seq
+        seq += 1; sinceKey += 1;
+        payload = { s: seq, b: keyframeSeq, d: d };
+      }
+      send(channel, enc ? enc(payload) : payload);
+    }
+
+    // Two drive modes: a `source` getter (read every tick) or queued send().
+    const hz = opts.hz || 20;
+    let queued;
+    const co = source ? null : new Coalescer({
+      hz: hz, autoStart: opts.autoStart !== false,
+      onFlush: function (entries) { for (let i = 0; i < entries.length; i++) if (entries[i].type === '__snap') queued = entries[i].data; emit(queued); },
+    });
+    let timer = null;
+    function start() {
+      if (co) { co.start(); return; }
+      if (timer || typeof setInterval === 'undefined') return;
+      timer = setInterval(function () { emit(source()); }, Math.max(1, Math.round(1000 / hz)));
+    }
+    function stop() { if (co) co.stop(); if (timer) { clearInterval(timer); timer = null; } }
+    if (source && opts.autoStart !== false) start();
+
+    return {
+      send: function (state) { if (co) co.queue('__snap', state); else emit(state); },
+      flush: function () { if (co) co.flush(); else if (source) emit(source()); },
+      start: start,
+      stop: stop,
+      reset: function () { keyframeState = null; keyframeSeq = 0; seq = 0; sinceKey = 0; },
+    };
+  };
+
+  /**
+   * Receiver for createSnapshotSender. Holds the keyframe baseline + last
+   * applied seq, so it safely drops stale/out-of-order frames and ignores
+   * deltas whose keyframe it missed (until the next keyframe arrives).
+   * @returns {{ receive:(msg:any)=>any, state:any, stats:object, reset:()=>void }}
+   */
+  game.createSnapshotReceiver = function (opts) {
+    opts = opts || {};
+    const dec = opts.decode === true ? decode : (typeof opts.decode === 'function' ? opts.decode : null);
+    let base = null, baseSeq = -1, current = null, appliedSeq = -1, dropped = 0;
+    return {
+      receive: function (msg) {
+        if (dec && (msg instanceof ArrayBuffer || ArrayBuffer.isView(msg))) msg = dec(msg);
+        if (!msg) return current;
+        if (msg.f !== undefined) {
+          if (msg.s !== undefined && msg.s <= appliedSeq) { dropped += 1; return current; }
+          base = msg.f; baseSeq = msg.s !== undefined ? msg.s : 0; current = msg.f; appliedSeq = baseSeq;
+          return current;
+        }
+        if (msg.d !== undefined) {
+          if (msg.b !== undefined && msg.b !== baseSeq) { dropped += 1; return current; } // missed keyframe
+          if (msg.s !== undefined && msg.s <= appliedSeq) { dropped += 1; return current; } // stale/dup
+          current = patch(base, msg.d);
+          if (msg.s !== undefined) appliedSeq = msg.s;
+          return current;
+        }
+        return current;
+      },
+      get state() { return current; },
+      get stats() { return { appliedSeq: appliedSeq, baseSeq: baseSeq, dropped: dropped }; },
+      reset: function () { base = null; baseSeq = -1; current = null; appliedSeq = -1; dropped = 0; },
+    };
+  };
+
+  /**
+   * Declarative state replication (host side). Mutate the plain object you pass
+   * in; the SDK auto-diffs and broadcasts it every tick (sequence-guarded,
+   * delta-compressed, optional quantize/binary). Clients read it with
+   * game.replica(). This is the ~40-lines-into-2 ergonomic.
+   * @returns {{ state:any, flush:()=>void, start:()=>void, stop:()=>void }}
+   */
+  game.replicate = function (obj, opts) {
+    opts = opts || {};
+    let state = obj != null ? obj : {};
+    const sender = this.createSnapshotSender(Object.assign({}, opts, { source: function () { return state; } }));
+    return {
+      get state() { return state; },
+      set state(v) { state = v; },
+      flush: function () { sender.flush(); },
+      start: function () { sender.start(); },
+      stop: function () { sender.stop(); },
+    };
+  };
+
+  /**
+   * Declarative state replication (client side). Receives what a host
+   * replicate()s on the same channel, drops stale/out-of-order frames, and
+   * (optionally) interpolates. Read `.state` for the latest authoritative state,
+   * or `.view()` for smoothed entities when `interpolate` keys are given.
+   * @returns {{ state:any, view:()=>any, onChange:(cb)=>void, stop:()=>void }}
+   */
+  game.replica = function (opts) {
+    opts = opts || {};
+    const channel = opts.channel || 'state';
+    const rx = this.createSnapshotReceiver({ decode: opts.decode });
+    const interp = opts.interpolate ? this.createInterpolation(typeof opts.interpolate === 'object' ? opts.interpolate : {}) : null;
+    const keys = typeof opts.interpolate === 'string' ? opts.interpolate : (opts.keys || (opts.interpolate && opts.interpolate.keys));
+    const group = opts.group || (opts.interpolate && opts.interpolate.group);
+    let onChange = null;
+    const off = this._onChannel(channel, function (data) {
+      const next = rx.receive(data);
+      if (interp && next != null) interp.add(next);
+      if (onChange) onChange(next);
+    });
+    return {
+      get state() { return rx.state; },
+      view: function () { return interp ? interp.calc(keys || 'x y', group) : rx.state; },
+      onChange: function (cb) { onChange = cb; },
+      stop: function () { off(); },
+    };
+  };
+
+  /**
+   * One-line WebRTC peer-to-peer setup (2 peers). Signaling rides the realtime
+   * channel via the router; gameplay then flows directly peer-to-peer over UDP.
+   */
+  game.createMesh = function (opts) {
+    opts = opts || {};
+    const self = this;
+    const channel = opts.signalChannel || 'signal';
+    const mesh = new MeshConnection(Object.assign({}, opts, {
+      sendSignal: function (payload) { self.realtime(channel, payload); },
+    }));
+    this._onChannel(channel, function (payload) { if (payload && payload.type) mesh.handleSignal(payload); });
+    return mesh;
+  };
+
+  /**
+   * N-peer full mesh. Signaling routed per-peer over the realtime channel (each
+   * message carries {to, from}); messages addressed to us are dispatched to the
+   * right peer connection. selfId defaults to the current user id.
+   * @returns {MeshNetwork}
+   */
+  game.createMeshNetwork = function (opts) {
+    opts = opts || {};
+    const self = this;
+    const channel = opts.signalChannel || 'mesh';
+    const selfId = opts.selfId || (Usion.user && Usion.user.getId && Usion.user.getId());
+    const net = new MeshNetwork(Object.assign({}, opts, {
+      selfId: selfId,
+      sendSignal: function (toPeerId, payload) { self.realtime(channel, { to: toPeerId, from: selfId, payload: payload }); },
+    }));
+    this._onChannel(channel, function (ad) { if (ad && ad.to === selfId && ad.from) net.handleSignal(ad.from, ad.payload); });
+    return net;
+  };
+
+  /**
+   * Inject artificial latency / jitter / packet loss locally to test how the
+   * game feels on a bad network (every studio has this). Affects both outbound
+   * realtime sends and inbound realtime dispatch. Call with null/false to turn
+   * it off. No-op safety: realtime must exist on the game module.
+   * @param {{latencyMs?:number,jitterMs?:number,lossPct?:number,dupPct?:number}|null} opts
+   */
+  game.simulateNetwork = function (opts) {
+    const self = this;
+    self._installRealtimeRouter();
+    if (!self._realtimeRaw && typeof self.realtime === 'function') self._realtimeRaw = self.realtime.bind(self);
+    if (!opts) {
+      if (self._realtimeRaw) self.realtime = self._realtimeRaw;
+      self._inboundDispatch = null;
+      if (self._sim) self._sim.flush();
+      self._sim = null;
+      return;
+    }
+    if (!self._sim) self._sim = new NetworkSim(opts);
+    else self._sim.set(opts);
+    if (self._realtimeRaw) self.realtime = self._sim.wrap(self._realtimeRaw);
+    self._inboundDispatch = self._sim.wrap(self._dispatchRealtime);
+    return self._sim;
+  };
+
+  /**
+   * Create a WebTransport (HTTP/3) connection — the lowest-latency client-server
+   * path (UDP-like datagrams, no TCP head-of-line blocking). `url` defaults to
+   * Usion.config.webTransportUrl. Call `connect()`, then `send()` (datagram) /
+   * `sendReliable()`; feed `onMessage` into a snapshot receiver. Direct/standalone
+   * games only (the iframe/WebView proxy relay can't carry datagrams).
+   * @returns {WebTransportConnection}
+   */
+  game.createWebTransport = function (opts) {
+    opts = opts || {};
+    const url = opts.url || (Usion.config && (Usion.config.webTransportUrl || Usion.config.wtUrl));
+    return new WebTransportConnection(Object.assign({}, opts, { url: url }));
+  };
+
+  /**
+   * Measure round-trip time once (single outstanding probe), updating the
+   * rolling estimate (game.getRtt). Direct mode uses the protocol ping/pong;
+   * platform mode uses a lightweight server ack. Resolves to ms, or null if
+   * unavailable (proxy mode, or not connected).
+   * @returns {Promise<number|null>}
+   */
+  game.ping = function () {
+    const self = this;
+    if (!self._pingMeter) self._pingMeter = new PingMeter();
+    if (self._pingInFlight) return self._pingInFlight; // single outstanding probe
+
+    let promise;
+    if (self.directMode) {
+      if (!self.directSocket || self.directSocket.readyState !== 1) return Promise.resolve(null);
+      promise = new Promise(function (resolve) {
+        const id = self._pingMeter.begin();
+        let done = false;
+        const finish = function () { if (done) return; done = true; resolve(self._pingMeter.end(id)); };
+        self._pongWaiters.push(finish);
+        self._sendDirect('ping', { t: Date.now() });
+        setTimeout(function () {
+          if (done) return; done = true;
+          const idx = self._pongWaiters.indexOf(finish);
+          if (idx >= 0) self._pongWaiters.splice(idx, 1);
+          delete self._pingMeter._outstanding[id];
+          resolve(null);
+        }, 3000);
+      });
+    } else if (self.socket && self.connected && !self._useProxy) {
+      promise = new Promise(function (resolve) {
+        const start = Date.now();
+        let done = false;
+        try {
+          self.socket.emit('game:ping', { t: start }, function () { if (done) return; done = true; resolve(self._pingMeter.sample(Date.now() - start)); });
+        } catch (e) { resolve(null); return; }
+        setTimeout(function () { if (done) return; done = true; resolve(null); }, 3000);
+      });
+    } else {
+      return Promise.resolve(null); // proxy mode has no point-to-point ack
+    }
+
+    self._pingInFlight = promise;
+    promise.then(function () { self._pingInFlight = null; }, function () { self._pingInFlight = null; });
+    return promise;
+  };
+
+  /** Latest smoothed round-trip time in ms (null until first ping). */
+  game.getRtt = function () { return this._pingMeter ? this._pingMeter.rtt : null; };
+}

package/src/modules/game-socket.js

@@ -40,6 +40,10 @@ export function applyGameSocket(game, Usion) {
         reconnectionDelayMax: 10000
       });
 
+      // Route allow-listed backend server events (lobby, etc.) to the unified
+      // backend channel — robust to listener registration order.
+      if (Usion._bindBackendSocket) Usion._bindBackendSocket(self.socket);
+
       self.socket.on('connect', function() {
         self.connected = true;
         self._connecting = false;

package/src/modules/index.js

@@ -25,6 +25,12 @@ import { uiMethods } from './ui.js';
 import { miscMethods } from './misc.js';
 import { createFileStorageModule } from './file-storage.js';
 import { createGameModule } from './game-core.js';
+import { createLobbyModule } from './lobby.js';
+import { createLeaderboardModule } from './leaderboard.js';
+import { createCloudModule } from './cloud.js';
+import { createMatchmakingModule } from './matchmaking.js';
+import { applyBackendChannel } from './backend-channel.js';
+import { netcode } from './netcode/index.js';
 
 // Build the Usion object from core
 const Usion = Object.assign({}, core);
@@ -38,6 +44,15 @@ Usion.chat = createChatModule(Usion);
 Usion.bot = createBotModule(Usion);
 Usion.fileStorage = createFileStorageModule(Usion);
 Usion.game = createGameModule(Usion);
+// Unified backend channel (used by lobby etc.; works standalone + embedded).
+applyBackendChannel(Usion);
+Usion.lobby = createLobbyModule(Usion);
+Usion.leaderboard = createLeaderboardModule(Usion);
+Usion.cloud = createCloudModule(Usion);
+Usion.matchmaking = createMatchmakingModule(Usion);
+
+// Netcode toolkit (transport-agnostic, zero-dependency).
+Usion.netcode = netcode;
 
 // Attach results methods directly on Usion
 Object.assign(Usion, createResultsMethods(Usion));