feat: live multiplayer ghosts over WebRTC (Trystero/Nostr)

Every open tab broadcasts its duck pose (trunk + joints + jaw + colour)
at 10 Hz over WebRTC data channels with serverless Nostr signaling, and
renders other visitors as translucent ducks (capped at 3). Peers online
count shows in the telemetry line.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -45,6 +45,16 @@ Plug in a controller and the same mapping as the real robot runtime applies:
 - D-pad down: sit / stand toggle
 - Right trigger: mouth (analog) + quack
 
+## Multiplayer ghosts
+
+Other people visiting the Space at the same time show up as translucent
+ducks, live. Peer-to-peer WebRTC via [Trystero](https://github.com/dmotz/trystero)
+(serverless signaling over public Nostr relays), so it works from a static
+Space with no backend. Each tab broadcasts its duck's pose (trunk + 14
+joints + jaw + colour) at 10 Hz; up to 3 ghosts are rendered, extra peers
+stay connected but invisible. The header shows "N online" when peers are
+around.
+
 ## How it works
 
 - `rl.js` fetches the MJCF (`robot_allcollisions.xml`), strips the visual

ghosts.js

@@ -0,0 +1,167 @@
+// Live multiplayer ghosts: every open tab of the sandbox broadcasts its
+// duck state over WebRTC and renders the other visitors as translucent
+// ducks. There is no backend - this is a static Space - so peer discovery
+// uses Trystero's serverless signaling over public Nostr relays. Payloads
+// are tiny (22 floats + a variant name at 10 Hz), and at most MAX_GHOSTS
+// ghosts are instantiated regardless of how many peers are in the room.
+//
+// This module deliberately imports nothing from duck.js / variants.js:
+// on the private Space those need the ?__sign JWT that only rl.js knows
+// how to append, so all rig helpers arrive through init parameters.
+
+const TRYSTERO_URL = "https://esm.run/trystero@0.25.3/nostr";
+const APP_ID = "microduck-sandbox";
+const ROOM = "lobby";
+const MAX_GHOSTS = 3;
+const SEND_HZ = 10;
+const GHOST_OPACITY = 0.35;
+// Per-frame easing toward the last received state (10 Hz updates, ~60 fps
+// rendering): position/joints converge in ~4 frames, fast but smooth.
+const EASE = 0.25;
+
+export async function initGhosts(env) {
+  const noop = { update() {}, peerCount: () => 0, ghostCount: () => 0, debug: () => [] };
+  let room;
+  try {
+    const { joinRoom } = await import(TRYSTERO_URL);
+    room = joinRoom({ appId: APP_ID }, ROOM);
+  } catch (e) {
+    console.warn("ghosts disabled (signaling unavailable):", e);
+    return noop;
+  }
+
+  const { scene, cloneRig, setJoint, setJawOpen, applyVariant, jointNames, getLocalState } = env;
+  // trystero 0.25 (backed by @trystero-p2p): makeAction returns
+  // { send, onMessage, onReceiveProgress } where onMessage is a SETTER -
+  // the receive handler is registered by assignment, not by calling it.
+  const act = room.makeAction("s");
+  // send() rejects when a peer's channel drops mid-transfer; that peer will
+  // be swept anyway, so failures are non-events.
+  const sendState = (data) => act.send(data).catch(() => {});
+
+  // Ghosts share geometry with the local rig (cloneRig), but get their own
+  // transparent material clones so repainting them never touches the
+  // visitor's own duck (variants.js caches materials globally).
+  const ghostify = (rig) => {
+    const cache = new Map();
+    rig.root.traverse((o) => {
+      if (!o.isMesh) return;
+      let m = cache.get(o.material.uuid);
+      if (!m) {
+        m = o.material.clone();
+        m.transparent = true;
+        m.opacity = GHOST_OPACITY;
+        m.depthWrite = false;
+        cache.set(o.material.uuid, m);
+      }
+      o.material = m;
+    });
+  };
+
+  const ghosts = new Map(); // peerId -> ghost
+  const makeGhost = (state) => {
+    const rig = cloneRig(env.rig);
+    applyVariant(rig, state.v);
+    ghostify(rig);
+    scene.add(rig.placer);
+    const trunk = rig.bodies.get("trunk_base");
+    // Snap straight to the first received pose: no fly-in from the origin.
+    trunk.position.set(state.p[0], state.p[1], state.p[2]);
+    trunk.quaternion.set(state.p[4], state.p[5], state.p[6], state.p[3]);
+    return { rig, trunk, target: state, joints: state.j.slice(), jaw: state.w ?? 0, variant: state.v };
+  };
+
+  const removeGhost = (peerId) => {
+    const g = ghosts.get(peerId);
+    if (!g) return;
+    scene.remove(g.rig.placer);
+    const seen = new Set();
+    g.rig.root.traverse((o) => {
+      if (o.isMesh && !seen.has(o.material.uuid)) {
+        seen.add(o.material.uuid);
+        o.material.dispose();
+      }
+    });
+    ghosts.delete(peerId);
+  };
+
+  // Handler signature in this build: (payload, context) where context is
+  // { peerId } - NOT the bare peerId string of classic trystero.
+  act.onMessage = (state, { peerId }) => {
+    let g = ghosts.get(peerId);
+    if (!g) {
+      if (ghosts.size >= MAX_GHOSTS) return; // room stays open, rendering capped
+      // Nostr relays replay recent events, so states from already-dead
+      // sessions can arrive right after joining: only ghost live peers.
+      if (!(peerId in room.getPeers())) return;
+      g = makeGhost(state);
+      ghosts.set(peerId, g);
+      g.lastSeen = performance.now();
+      return;
+    }
+    g.lastSeen = performance.now();
+    g.target = state;
+    if (state.v !== g.variant) {
+      g.variant = state.v;
+      applyVariant(g.rig, state.v);
+      ghostify(g.rig);
+    }
+  };
+
+  // Same setter-style registration as onMessage.
+  room.onPeerLeave = (peerId) => removeGhost(peerId);
+
+  // Graceful exit so other tabs drop this ghost immediately...
+  window.addEventListener("pagehide", () => {
+    try { room.leave(); } catch {}
+  });
+  // ...and a staleness sweep for peers that vanished without leaving
+  // (crashed tab, dropped connection): 5 s without a state packet at
+  // 10 Hz means the peer is gone, not just lagging.
+  const STALE_MS = 5000;
+
+  // Broadcast + stale sweep on setInterval (not rAF) so both keep running
+  // in occluded tabs.
+  setInterval(() => {
+    const s = getLocalState();
+    if (s) sendState(s);
+    const now = performance.now();
+    for (const [peerId, g] of [...ghosts]) {
+      if (now - g.lastSeen > STALE_MS) removeGhost(peerId);
+    }
+  }, 1000 / SEND_HZ);
+
+  // Scratch THREE.Quaternion without importing three: slerp needs a real
+  // instance, cloned here from any node of the already-built local rig.
+  const _q = env.rig.placer.quaternion.clone();
+  return {
+    room,
+    peerCount: () => Object.keys(room.getPeers()).length,
+    ghostCount: () => ghosts.size,
+    debug: () => [...ghosts.values()].map((g) => {
+      let meshes = 0, visible = 0, op = null;
+      g.rig.root.traverse((o) => {
+        if (o.isMesh) { meshes++; if (o.visible) visible++; op ??= o.material.opacity; }
+      });
+      const w = g.trunk.getWorldPosition(g.trunk.position.clone());
+      return { p: g.trunk.position.toArray(), world: w.toArray(), inScene: !!g.rig.placer.parent, meshes, visible, op, v: g.variant };
+    }),
+    update() {
+      for (const g of ghosts.values()) {
+        const t = g.target;
+        // Trunk pose in raw MJCF coords: the cloned root applies Z-up -> Y-up.
+        g.trunk.position.x += (t.p[0] - g.trunk.position.x) * EASE;
+        g.trunk.position.y += (t.p[1] - g.trunk.position.y) * EASE;
+        g.trunk.position.z += (t.p[2] - g.trunk.position.z) * EASE;
+        _q.set(t.p[4], t.p[5], t.p[6], t.p[3]); // THREE order x,y,z,w
+        g.trunk.quaternion.slerp(_q, EASE);
+        for (let i = 0; i < jointNames.length; i++) {
+          g.joints[i] += (t.j[i] - g.joints[i]) * EASE;
+          setJoint(g.rig, jointNames[i], g.joints[i]);
+        }
+        g.jaw += ((t.w ?? 0) - g.jaw) * EASE;
+        setJawOpen(g.rig, g.jaw);
+      }
+    },
+  };
+}

index.html

@@ -302,7 +302,7 @@
          appended: a plain src attribute can 401 when the browser blocks the
          *.static.hf.space auth cookie inside the hub iframe. -->
     <script type="module">
-      const V = "5"; // bump on rl.js changes to defeat heuristic caching
+      const V = "20"; // bump on rl.js changes to defeat heuristic caching
       const sign = new URLSearchParams(location.search).get("__sign");
       const suffix = sign ? `&__sign=${encodeURIComponent(sign)}` : "";
       import(`./rl.js?v=${V}${suffix}`);

rl.js

@@ -32,7 +32,7 @@ window.__hfSigned = signed; // duck.js uses it for kinematics + STL requests
 
 // Local modules are imported dynamically through signed() for the same
 // reason: a static import of ./duck.js would 401 without the cookie.
-const { buildRig, loadKinematics, setJoint, setJawOpen, MODEL_DIR, MESH_VERSION } =
+const { buildRig, cloneRig, loadKinematics, setJoint, setJawOpen, MODEL_DIR, MESH_VERSION } =
   await import(signed("./duck.js"));
 const { VARIANTS, VARIANT_NAMES, materialHookFor, randomVariantName, applyVariant, specToHex } =
   await import(signed("./variants.js"));
@@ -466,10 +466,13 @@ const quack = () => {
   quackSound.currentTime = 0;
   quackSound.play().catch(() => {});
 };
-function syncJaw() {
+function jawOpenNow() {
   const t = (performance.now() - quackAt) / QUACK_MS;
   const flap = t >= 0 && t < 1 ? Math.sin(Math.PI * t) : 0;
-  setJawOpen(rig, Math.max(flap, padJaw));
+  return Math.max(flap, padJaw);
+}
+function syncJaw() {
+  setJawOpen(rig, jawOpenNow());
 }
 
 // HUD elements for the mini command sticks + hint highlighting.
@@ -491,8 +494,10 @@ function renderStats() {
   const [vx, vy, wz] = effectiveCmd();
   // The active policy lives in the big center label and the twist in the
   // mini sticks; up here only the bare telemetry remains.
+  const peers = ghosts?.peerCount() ?? 0;
   statsEl.textContent =
-    `ctrl ${ctrlHz.toFixed(0)} Hz \u00b7 sim t ${data.time.toFixed(1)} s`;
+    `ctrl ${ctrlHz.toFixed(0)} Hz \u00b7 sim t ${data.time.toFixed(1)} s` +
+    (peers ? ` \u00b7 ${peers + 1} online` : "");
 
   // Mini sticks: the dot mirrors the effective twist, lit yellow while the
   // user is actually driving.
@@ -520,12 +525,15 @@ function renderStats() {
 // Real implementation assigned in the gamepad section below; the render
 // loop starts before that section has evaluated, hence the indirection.
 let pollPad = () => {};
+// Multiplayer ghosts, initialised asynchronously at the end of the module.
+let ghosts = null;
 
 function loop() {
   requestAnimationFrame(loop);
   pollPad();
   syncRig();
   syncJaw();
+  ghosts?.update();
   controls.update();
   renderStats();
   renderer.render(scene, camera);
@@ -728,4 +736,34 @@ window.rl = {
   velCmd, lastAction, resetSim,
   step: async (n = 1) => { for (let i = 0; i < n; i++) await controlStep(); },
   render: () => { syncRig(); renderer.render(scene, camera); },
+  get ghosts() { return ghosts; },
 };
+
+// ── Multiplayer ghosts (WebRTC, serverless signaling) ───────────────────
+// Broadcast this duck's pose and render up to 3 other visitors live as
+// translucent ducks. Fire-and-forget: any failure just means no ghosts.
+const r3 = (x) => Math.round(x * 1000) / 1000;
+try {
+  // Same heuristic-cache pitfall as everything else served without
+  // Cache-Control: reuse rl.js's own ?v= so ghosts.js updates ship together.
+  const selfV = new URL(import.meta.url).searchParams.get("v") ?? "0";
+  const { initGhosts } = await import(signed(`./ghosts.js?v=${selfV}`));
+  ghosts = await initGhosts({
+    scene, rig, cloneRig, setJoint, setJawOpen, applyVariant,
+    jointNames: JOINT_NAMES,
+    getLocalState: () => {
+      const qpos = data.qpos;
+      const j = new Array(NUM_JOINTS);
+      for (let i = 0; i < NUM_JOINTS; i++) j[i] = r3(qpos[qposAdr[i]]);
+      return {
+        p: [r3(qpos[0]), r3(qpos[1]), r3(qpos[2]), r3(qpos[3]), r3(qpos[4]), r3(qpos[5]), r3(qpos[6])],
+        j,
+        w: r3(jawOpenNow()),
+        v: currentVariant,
+      };
+    },
+  });
+} catch (e) {
+  window.__ghostErr = String((e && e.stack) || e);
+  console.warn("ghosts disabled:", e);
+}