@usions/sdk 2.2.0 → 2.11.0

package/README.md

@@ -121,6 +121,91 @@ Usion.game.disconnect()
 Usion.game.isConnected()              // boolean
 ```
 
+### Netcode (low-latency realtime toolkit)
+
+Zero-dependency, transport-agnostic helpers for smooth, lossless multiplayer.
+They work across all connection modes (platform / direct / proxy) and both
+platforms. Adopt incrementally. Full guide: [`docs/realtime-netcode.md`](../../docs/realtime-netcode.md).
+
+```javascript
+// 1. Snapshot interpolation — smooth rendering, absorbs jitter & packet loss
+const interp = Usion.game.createInterpolation({ serverFps: 20 });
+Usion.game.onRealtime((m) => { if (m.action_type === 'state') interp.add(m.action_data); });
+function render() {
+  const players = interp.calc('x y angle(deg)'); // entities at "now - bufferMs"
+  if (players) draw(players);
+  requestAnimationFrame(render);
+}
+
+// 2. Sequence-guarded, delta-compressed snapshot sender (cuts bandwidth + flood)
+const snap = Usion.game.createSnapshotSender({ hz: 20, channel: 'state', precision: 2 });
+loop(() => snap.send(world));
+// receiver (drops stale/out-of-order frames; never patches the wrong base):
+const rx = Usion.game.createSnapshotReceiver();
+let world = {};
+Usion.game.onRealtime((m) => { if (m.action_type === 'state') world = rx.receive(m.action_data); });
+
+// 3. Client-side prediction + reconciliation + smooth error blending
+const p = Usion.game.createPredictor({ apply: (s, i) => move(s, i), initialState, smooth: { keys: 'x y' } });
+const { seq } = p.predict(input);                 // apply locally, send seq
+Usion.game.onStateUpdate((s) => p.reconcile(s.game_state.me, s.game_state.ackSeq));
+function render() { draw(p.view()); requestAnimationFrame(render); } // blended, no snaps
+
+// 4. WebRTC peer-to-peer (UDP) — escapes TCP head-of-line blocking
+const mesh = Usion.game.createMesh({
+  role: amHost ? 'host' : 'guest',
+  iceServers: Usion.netcode.MeshConnection.iceServers({ turn: 'turn:host:3478', turnUsername: 'u', turnCredential: 'p' }),
+});
+mesh.onMessage = (d) => applyRemote(d);
+await mesh.start();
+mesh.send({ x, y });          // unreliable + unordered + sequenced (drops stale)
+mesh.sendReliable({ event }); // ordered, must-arrive
+
+// 4b. N-player mesh
+const net = Usion.game.createMeshNetwork();
+await net.setRoster(allPlayerIds);
+net.onMessage = (peerId, d) => applyRemote(peerId, d);
+net.broadcast({ x, y });
+
+// 4c. WebTransport (HTTP/3) — lowest-latency client-server (no TCP HOL blocking)
+const wt = Usion.game.createWebTransport({ url: 'https://game.example.com:4433/wt' });
+wt.onMessage = (m, ch) => { if (ch === 'datagram') applyState(m); };
+await wt.connect();
+wt.send(stateBytes);           // UDP-like datagram (unreliable, sequenced)
+wt.sendReliable({ event });    // reliable stream
+// (server: use the open-source @fails-components/webtransport Node HTTP/3 server)
+
+// 4d. Declarative replication — mutate a plain object, it auto-syncs (host)
+const world = Usion.game.replicate({ players: [] }, { channel: 'world', hz: 20, precision: 2 });
+world.state.players.push({ id: myId, x: 0, y: 0 });   // just mutate it
+// client:
+const remote = Usion.game.replica({ channel: 'world', interpolate: { keys: 'x y', group: 'players' } });
+function render() { draw(remote.view()); requestAnimationFrame(render); }
+
+// 4e. Test under a bad network locally (latency / jitter / loss)
+Usion.game.simulateNetwork({ latencyMs: 120, jitterMs: 30, lossPct: 5 });
+Usion.game.simulateNetwork(null); // off
+
+// 4f. Deterministic lockstep (inputs-only sim + free replays) — MOBA/RTS
+const ls = Usion.game.createLockstep({ playerId: myId, players, step: (frame, inputs) => sim(frame, inputs) });
+gameLoop(() => { ls.submit(localInput); ls.tick(); });
+// replay later: Usion.netcode.Lockstep.replay(ls.getReplay(), sim);
+
+// 4g. Server-side lag compensation (server rewind) — fair hits across pings
+const lag = Usion.game.createLagCompensator({ historyMs: 1000 });
+serverTick(() => lag.record(allEntities));                 // each tick
+function onShot(shooter, ray) { const past = lag.rewindForClient(shooter.rtt, shooter.interpMs); resolveHit(ray, past); }
+
+// 5. Telemetry, delta + binary helpers
+await Usion.game.ping(); Usion.game.getRtt();                 // ms
+const d = Usion.game.diff(prev, next); const next2 = Usion.game.patch(prev, d);
+const bytes = Usion.game.encode(state); const back = Usion.game.decode(bytes);
+```
+
+Also available directly: `Usion.netcode.{ SnapshotInterpolation, Predictor,
+Coalescer, PingMeter, MeshConnection, MeshNetwork, diff, patch, quantize,
+encode, decode }`.
+
 ### Utility
 
 ```javascript
@@ -130,6 +215,39 @@ Usion.exit()                         // Close the mini-app
 Usion.log(message)                   // Debug log
 ```
 
+### Leaderboard (opt-in per game)
+
+Enable on the service (`leaderboard: { enabled: true, order: 'desc' }`), then:
+
+```javascript
+await Usion.leaderboard.submit(1500, { level: 3 });   // best score is kept
+const friends = await Usion.leaderboard.friends();    // people you've messaged + you
+const top = await Usion.leaderboard.top({ limit: 20 });// global top
+const me = await Usion.leaderboard.me();              // { score, rank, total }
+// entry: { user_id, name, avatar, score, rank, is_me, metadata }
+```
+`friends()` is scoped to users you've chatted with (your conversations) plus
+yourself. Works in standalone *and* embedded games (rides the backend channel).
+
+### Matchmaking (play with online strangers)
+
+Pair players who don't know each other into a game:
+
+```javascript
+const match = await Usion.matchmaking.find();      // resolves when matched
+// match = { roomId, players, serviceId }
+await Usion.game.connect();
+await Usion.game.join(match.roomId);
+
+// while waiting you can stop:
+Usion.matchmaking.cancel();
+// or react to matches:
+Usion.matchmaking.onMatch(({ roomId, players }) => { /* ... */ });
+```
+`find({ size })` controls party size (default 2). Works standalone *and*
+embedded (rides the backend channel). Pair this with `Usion.lobby` for
+invite-a-friend, and `Usion.matchmaking` for quick-match with strangers.
+
 ## TypeScript
 
 Full type declarations included:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usions/sdk",
-  "version": "2.2.0",
+  "version": "2.11.0",
   "description": "Usion Mini App SDK for iframe games and services",
   "type": "module",
   "main": "src/modules/index.js",
@@ -26,7 +26,8 @@
     "build": "rollup -c",
     "build:copy": "npm run build && cp src/browser.js ../../web/public/usion-sdk.js && cp src/browser.js ../../microservices/shared/usion-sdk.js",
     "watch": "rollup -c --watch",
-    "test": "npm run build && vitest run"
+    "test": "npm run build && vitest run",
+    "prepublishOnly": "npm run build && vitest run"
   },
   "devDependencies": {
     "rollup": "^4.0.0",