@genex-ai/multiplayer 0.15.0 → 0.16.1

package/README.md

@@ -283,9 +283,15 @@ handshake. Past a small party what breaks first is not bandwidth but reliability
 must negotiate with everyone already present, and every leg can fail. The 7th `join()` is
 refused with `voice:rejected`; the room still holds 64 players.
 
-**Configure TURN for real games.** Roughly 10–20% of players sit behind symmetric NAT and
-cannot connect peer-to-peer at all. Without a TURN server they hear nothing and are heard
-by nobody, while everyone else works fine — which is a miserable bug to diagnose:
+**TURN is automatic — you do not configure it.** Roughly 15% of players sit behind symmetric
+NAT, carrier CGNAT, or a firewall that blocks UDP, and cannot connect peer-to-peer at all. In
+a mesh that is not a private problem: they fail *every* leg, so nobody in the party hears them
+and they hear nobody, while everyone else works fine. `join()` fetches short-lived relay
+credentials from the Genex relay before it opens any peer connection, so this is handled for
+you with no key to obtain, nothing to put in your bundle, and no code to write.
+
+Pass `iceServers` only to run your own TURN — it is an override, and it suppresses the
+platform request entirely:
 
 ```ts
 await room.voice.join({ iceServers: [{ urls: 'turn:…', username: '…', credential: '…' }] });

package/dist/index.d.ts

@@ -18,9 +18,10 @@ type VoiceParticipant = {
 };
 type VoiceJoinOptions = {
     /**
-     * Extra ICE servers — in practice a TURN entry. Roughly 10–20% of players sit behind
-     * symmetric NAT and cannot go peer-to-peer at all; without TURN, voice simply never
-     * connects for them. STUN-only is the default because it needs no infrastructure.
+     * OVERRIDE the ICE servers. You do not need this: `join()` asks the relay for short-lived
+     * TURN credentials automatically, so the ~15% of players behind symmetric NAT, carrier
+     * CGNAT or a UDP-blocking firewall connect without any work from the game. Pass this only
+     * to run your own TURN — doing so suppresses the relay request entirely.
      */
     iceServers?: RTCIceServer[];
     /** Join with the mic gated off — the right default for push-to-talk games. */

package/dist/index.js

@@ -1,6 +1,37 @@
 // src/index.ts
 import { Client, getStateCallbacks } from "@colyseus/sdk";
 
+// src/ice-request.ts
+function createIceRequester(send, timeoutMs) {
+  let inFlight = null;
+  let settle = null;
+  return {
+    request() {
+      if (inFlight) return inFlight;
+      inFlight = new Promise((resolve) => {
+        let timer;
+        const done = (cfg) => {
+          if (!settle) return;
+          settle = null;
+          inFlight = null;
+          if (timer) clearTimeout(timer);
+          resolve(cfg);
+        };
+        settle = done;
+        timer = setTimeout(() => done(null), timeoutMs);
+        send();
+      });
+      return inFlight;
+    },
+    deliver(cfg) {
+      settle?.(cfg);
+    },
+    get pending() {
+      return inFlight !== null;
+    }
+  };
+}
+
 // src/voice.ts
 var DEFAULT_ICE = [{ urls: "stun:stun.l.google.com:19302" }];
 var SPEAKING_POLL_MS = 120;
@@ -21,6 +52,13 @@ var VoiceMesh = class {
   micOn = true;
   selfSpeaking = false;
   running = false;
+  // Peering is HELD between acquiring the mic and announcing the join, because both things
+  // that happen in that window must land first: the relay's TURN credentials (a peer built
+  // without them is stuck on STUN for its whole life), and our own `__voice:join` (the relay
+  // drops a signal from a session that is not yet in the roster, and a dropped offer is never
+  // retried). Without the hold, another player joining voice in that window patches `__voice`
+  // and builds us a peer that can neither relay nor negotiate.
+  peeringHeld = false;
   constructor(transport) {
     this.transport = transport;
   }
@@ -51,8 +89,9 @@ var VoiceMesh = class {
   /** Acquire the microphone. Throws if the user denies it or no device exists — the caller
    *  surfaces that; it is a normal outcome, not a bug. Must be called from a user gesture:
    *  browsers gate both the permission prompt and audio playback on one. */
-  async start(options = {}) {
+  async start(options = {}, holdPeering = false) {
     if (this.running) return;
+    this.peeringHeld = holdPeering;
     this.iceServers = options.iceServers?.length ? options.iceServers : DEFAULT_ICE;
     this.spatial = options.spatial === true;
     this.threshold = options.speakingThreshold ?? DEFAULT_SPEAKING_THRESHOLD;
@@ -70,6 +109,7 @@ var VoiceMesh = class {
   /** Tear everything down. Safe to call when not running. */
   stop() {
     this.running = false;
+    this.peeringHeld = false;
     if (this.levelTimer) {
       clearInterval(this.levelTimer);
       this.levelTimer = null;
@@ -85,10 +125,41 @@ var VoiceMesh = class {
     this.selfSpeaking = false;
     this.emit();
   }
+  /**
+   * Swap in ICE servers obtained after `start()` — in practice the relay's short-lived TURN
+   * credentials, which are fetched between acquiring the mic and announcing the join so the
+   * network round trip never spends the user gesture `getUserMedia` needs.
+   *
+   * Peers built from here on use them. Live ones are updated too, but `setConfiguration`
+   * governs FUTURE gathering only: an allocation already relaying media keeps the credential
+   * it was created with. That is why the credential's TTL is sized to outlast a session
+   * rather than to reach the next refresh.
+   */
+  setIceServers(servers) {
+    if (!servers.length) return;
+    this.iceServers = servers;
+    for (const peer of this.peers.values()) {
+      try {
+        peer.pc.setConfiguration({ iceServers: servers });
+      } catch {
+      }
+    }
+  }
+  /**
+   * Release the hold taken by `start(…, true)` and reconcile whatever roster arrived while it
+   * was up. The caller MUST reach this on every path, including the one where no credentials
+   * came back: a mesh that never peers is worse than one peering without TURN.
+   */
+  releasePeering() {
+    if (!this.peeringHeld) return;
+    this.peeringHeld = false;
+    this.setRoster(this.roster);
+  }
   /** The relay's authoritative roster changed: open connections to newcomers, drop leavers. */
   setRoster(ids) {
     this.roster = ids;
     if (!this.running) return;
+    if (this.peeringHeld) return;
     const self = this.transport.selfId();
     const wanted = new Set(ids.filter((id) => id !== self));
     for (const id of wanted) if (!this.peers.has(id)) this.createPeer(id);
@@ -187,7 +258,10 @@ var VoiceMesh = class {
       if (next !== peer.connection) {
         peer.connection = next;
         if (next === "failed") {
-          console.warn(`[multiplayer] voice connection to ${id} failed (no TURN configured?)`);
+          const relayed = this.iceServers.some((s2) => hasTurnUrl(s2));
+          console.warn(
+            `[multiplayer] voice connection to ${id} failed` + (relayed ? "" : " \u2014 no TURN in the ICE list (relay offered none?)")
+          );
         }
         this.emit();
       }
@@ -286,6 +360,10 @@ var VoiceMesh = class {
     }
   }
 };
+function hasTurnUrl(server) {
+  const urls = Array.isArray(server.urls) ? server.urls : [server.urls];
+  return urls.some((u) => typeof u === "string" && u.startsWith("turn"));
+}
 function rms(analyser) {
   if (!analyser) return 0;
   const buf = new Uint8Array(analyser.fftSize);
@@ -329,6 +407,9 @@ var VOICE_JOIN_MSG = "__voice:join";
 var VOICE_LEAVE_MSG = "__voice:leave";
 var VOICE_SIGNAL_MSG = "__voice:signal";
 var VOICE_REJECTED_MSG = "__voice:rejected";
+var VOICE_ICE_REQUEST_MSG = "__voice:ice:request";
+var VOICE_ICE_MSG = "__voice:ice";
+var ICE_REQUEST_TIMEOUT_MS = 3e3;
 var OBJECT_CONTROL_RESULT_MSG = "__object:result";
 var OBJECT_CONTROL_VERSION = 2;
 var STATE_SNAP_MSG = "__state:snap";
@@ -649,7 +730,9 @@ function attachSession(client, initialRoom) {
     VOICE_SIGNAL_MSG,
     VOICE_REJECTED_MSG,
     VOICE_JOIN_MSG,
-    VOICE_LEAVE_MSG
+    VOICE_LEAVE_MSG,
+    VOICE_ICE_REQUEST_MSG,
+    VOICE_ICE_MSG
   ]);
   const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
   const lastShared = /* @__PURE__ */ new Map();
@@ -877,6 +960,24 @@ function attachSession(client, initialRoom) {
     sendSignal: (to, data) => send0(VOICE_SIGNAL_MSG, { to, data }, true)
   });
   voice.onChange(() => emit("voice", voice.participants));
+  let iceRefreshTimer = null;
+  const ice = createIceRequester(() => send0(VOICE_ICE_REQUEST_MSG, {}, true), ICE_REQUEST_TIMEOUT_MS);
+  const clearIceRefresh = () => {
+    if (iceRefreshTimer) clearTimeout(iceRefreshTimer);
+    iceRefreshTimer = null;
+  };
+  const scheduleIceRefresh = (ttl) => {
+    clearIceRefresh();
+    if (typeof ttl !== "number" || !Number.isFinite(ttl) || ttl <= 0) return;
+    iceRefreshTimer = setTimeout(() => {
+      if (!voice.active) return;
+      void ice.request().then((cfg) => {
+        if (!voice.active || !cfg?.iceServers?.length) return;
+        voice.setIceServers(cfg.iceServers);
+        scheduleIceRefresh(cfg.ttl);
+      });
+    }, Math.max(6e4, Math.floor(ttl * 800)));
+  };
   const chatHistory = [];
   const chatSeen = /* @__PURE__ */ new Set();
   const chatListeners = /* @__PURE__ */ new Set();
@@ -995,10 +1096,19 @@ function attachSession(client, initialRoom) {
       if (msg && typeof msg.from === "string") void voice.handleSignal(msg.from, msg.data);
     });
     r.onMessage(VOICE_REJECTED_MSG, (msg) => {
+      clearIceRefresh();
       voice.stop();
       emit("voice:rejected", msg ?? { reason: "full" });
     });
-    for (const inert of [VOICE_JOIN_MSG, VOICE_LEAVE_MSG, CHAT_HISTORY_REQUEST_MSG]) {
+    r.onMessage(VOICE_ICE_MSG, (msg) => {
+      ice.deliver(msg ?? null);
+    });
+    for (const inert of [
+      VOICE_JOIN_MSG,
+      VOICE_LEAVE_MSG,
+      VOICE_ICE_REQUEST_MSG,
+      CHAT_HISTORY_REQUEST_MSG
+    ]) {
       r.onMessage(inert, () => {
       });
     }
@@ -1314,10 +1424,20 @@ function attachSession(client, initialRoom) {
     },
     voice: {
       async join(options) {
-        await voice.start(options);
+        await voice.start(options, true);
+        if (!options?.iceServers?.length) {
+          const cfg = await ice.request();
+          if (voice.active && cfg?.iceServers?.length) {
+            voice.setIceServers(cfg.iceServers);
+            scheduleIceRefresh(cfg.ttl);
+          }
+        }
+        if (!voice.active) return;
         send0(VOICE_JOIN_MSG, {}, true);
+        voice.releasePeering();
       },
       leave() {
+        clearIceRefresh();
         send0(VOICE_LEAVE_MSG, {}, true);
         voice.stop();
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/multiplayer",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "The multiplayer client wrapper + shared room schema for genex.",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,6 +23,7 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.ts",
     "check": "pnpm build && publint && attw --pack . --profile esm-only",
     "prepack": "pnpm build && publint"
   },
@@ -48,9 +49,8 @@
     "typescript": "^5.8.0"
   },
   "repository": {
-    "type": "git",
-    "url": "git+https://github.com/me-ai-org/genex-demo.git",
-    "directory": "packages/multiplayer"
+      "type": "git",
+      "url": "git+https://github.com/genex-games/genex.git"
   },
   "license": "MIT"
 }