@genex-ai/multiplayer 0.13.0 → 0.16.0

package/README.md

@@ -223,12 +223,85 @@ and seed its world from each object's `stateRaw`, so simulation survives host mi
 
 ## `send` — custom one-off events
 
-Fire-and-forget to all **other** clients (not stored in state). For shots, emotes, chat, pings.
+Fire-and-forget to all **other** clients (not stored in state). For shots, emotes, pings.
 
 ```ts
 room.send('hit', { from: room.id, target: 'xyz', dmg: 10 });
 ```
 
+Text chat has its own channel — use `room.chat`, not this.
+
+## `chat` — room text chat
+
+```ts
+room.chat.send('on my way');
+
+room.chat.on((m) => {                // fires once per line you hadn't seen
+  addLine(`${m.name}: ${m.text}`);   // m.text is already sanitized — render as TEXT
+});
+
+room.chat.history;                   // every known line, oldest first — render on mount
+room.chat.mute(playerId);            // local only; nothing is sent, nobody else is affected
+```
+
+**Chat is not `send`** — three differences that matter:
+
+- **Your own lines come back to you**, in server order with the server's timestamp. Render only
+  what arrives in `on`; appending your own line locally on submit shows it twice.
+- **The relay stamps `from` and `name`** from the verified session. A player cannot post under
+  someone else's name, so the name is safe to display as-is.
+- **History replays on connect** (last ~50 lines), so a player joining mid-game sees the recent
+  conversation. `on` fires for those too, de-duplicated by `id`, and a reconnect backfills exactly
+  what the blip missed — a handler that just appends stays correct.
+
+The relay trims each line, strips control and bidi characters, and clamps to 500 code points.
+Chat has its own rate budget (~2 lines/second), separate from gameplay traffic, so a busy room
+can't starve it and a chat flood can't starve movement.
+
+> **Render `m.text` with `textContent`, never `innerHTML`.** It is another player's input.
+
+## `voice` — mesh voice chat
+
+```ts
+// MUST be inside a click/tap handler — browsers gate the mic prompt AND playback on a gesture.
+joinBtn.onclick = async () => {
+  try { await room.voice.join(); }            // rejects if the player denies the microphone
+  catch (err) { showNotice('Microphone needed for voice'); }
+};
+
+room.on('voice', (participants) => renderVoiceHud(participants));  // joined/left/speaking/connected
+room.on('voice:rejected', (info) => showNotice(`Voice is full (${info.limit})`));
+
+room.voice.setMicEnabled(false);      // push-to-talk gate — instant, no renegotiation
+room.voice.mute(playerId);            // local only
+room.voice.leave();                   // releases the mic (turns the recording indicator off)
+```
+
+**Party-sized, not room-sized — max 6.** Audio goes peer-to-peer in a full mesh: everyone
+uploads to everyone. The relay carries no audio at all, only the roster and the WebRTC
+handshake. Past a small party what breaks first is not bandwidth but reliability — a joiner
+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.
+
+**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: '…' }] });
+```
+
+**Spatial voice** (`npx genex controller voice`) is the version worth shipping in a 3D game:
+join with `{ spatial: true }` and the SDK stops playing audio flat, handing you `p.stream`
+per participant to drive a `THREE.PositionalAudio`. Distance falloff also softens the cap —
+six audible neighbours read as a populated world rather than as a limit.
+
 ## `leave`
 
 ```ts

package/dist/index.d.ts

@@ -1,6 +1,43 @@
 export { PlayerState, RoomState } from './schema.js';
 import '@colyseus/schema';
 
+/** One remote participant in the voice mesh. */
+type VoiceParticipant = {
+    id: string;
+    /** Relay-verified display name (same source as `players`). */
+    name: string;
+    /** Their audio. Null until the peer connection produces a track. */
+    stream: MediaStream | null;
+    /** True while they are above the speaking threshold. */
+    speaking: boolean;
+    /** Muted by YOU, locally. Nothing is sent to them or to the relay. */
+    muted: boolean;
+    /** 0..1, applied to the default playback element (ignored in spatial mode). */
+    volume: number;
+    connection: 'connecting' | 'connected' | 'failed';
+};
+type VoiceJoinOptions = {
+    /**
+     * 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. */
+    startMuted?: boolean;
+    /**
+     * Spatial mode: the SDK does NOT play remote audio, it only hands you `p.stream` so you
+     * can drive a THREE.PositionalAudio yourself (`genex controller voice` does this). A
+     * muted sink element is still created per peer — without one attached, Chrome does not
+     * flow a remote WebRTC stream into WebAudio at all, which reads as "spatial voice is
+     * silent" and is the single most confusing bug in this lane.
+     */
+    spatial?: boolean;
+    /** RMS threshold for the speaking flag, 0..1. Default 0.02. */
+    speakingThreshold?: number;
+};
+
 type ColyseusAuth = {
     embedToken: string;
 };
@@ -181,6 +218,15 @@ type Session<TState extends Record<string, unknown>> = {
     on(event: 'object', cb: (id: string) => void): () => void;
     /** The room host changed (fires with the new host's id, or `undefined`). */
     on(event: 'host', cb: (host: string | undefined) => void): () => void;
+    /** The voice roster or a participant's state changed (joined, left, started/stopped
+     *  speaking, connected, muted). Fires with the full participant list — re-render from it. */
+    on(event: 'voice', cb: (participants: VoiceParticipant[]) => void): () => void;
+    /** Your `voice.join()` was refused by the relay — the room is at the 6-participant cap.
+     *  The mic is already released; show the reason rather than retrying in a loop. */
+    on(event: 'voice:rejected', cb: (info: {
+        reason: string;
+        limit?: number;
+    }) => void): () => void;
     /**
      * The connection dropped unexpectedly and auto-reconnect is underway (attempts run
      * ~0.5s→8s backoff inside the server's grace window). Show a "reconnecting…" overlay;
@@ -204,6 +250,10 @@ type Session<TState extends Record<string, unknown>> = {
      * by the relay itself (`state`, `shared`, `claim`, `obj`, `release`, `destroy`, and the
      * `match:`/`__` prefixes) are refused with a console warning — pick another name. */
     send(type: string, payload?: unknown): void;
+    /** Text chat for this room. See {@link ChatApi}. */
+    chat: ChatApi;
+    /** Mesh voice chat for this room. See {@link VoiceApi}. */
+    voice: VoiceApi;
     /**
      * HOST ONLY. Stop (or resume) the matchmaker placing NEW players into THIS room.
      *
@@ -220,6 +270,82 @@ type Session<TState extends Record<string, unknown>> = {
     /** Leave the room (deliberate — no auto-reconnect, no `disconnect` event). */
     leave(): void;
 };
+/** One chat line, as the relay stamped it. Only `text` came from the sender's client —
+ *  `from` and `name` are filled in server-side from the verified session, so a player
+ *  cannot post under someone else's name. */
+type ChatMessage = {
+    /** Monotonic per room, ascending. Stable across a reconnect — use it as a render key. */
+    id: number;
+    /** Sender's player id (`room.id` for your own lines). */
+    from: string;
+    /** Sender's verified display name. */
+    name: string;
+    /** Sanitized text: ≤500 code points, no control or bidi characters, single-spaced. */
+    text: string;
+    /** Server timestamp (epoch ms). */
+    at: number;
+};
+/**
+ * Room text chat. The relay keeps the last ~50 lines and replays them on connect, so a
+ * player joining mid-game sees the recent conversation.
+ *
+ * IMPORTANT — chat is NOT `send()`: your own lines come back to you, in server order
+ * with the server's timestamp. Render only what arrives here; do not also append your
+ * own line locally on submit, or it will appear twice.
+ */
+type ChatApi = {
+    /** Send a line. Empty/whitespace-only text is ignored; the relay trims, strips control
+     *  and bidi characters, and clamps to 500 code points. Over ~2 lines/second the relay
+     *  drops the excess (and warns via `rate:drop`). */
+    send(text: string): void;
+    /**
+     * Fires once per line you had not seen — live messages, plus any the replayed history
+     * fills in on connect or after a reconnect blip. Append-only and de-duplicated by `id`,
+     * so a handler that just appends stays correct across reconnects. Returns a disposer.
+     */
+    on(cb: (message: ChatMessage) => void): () => void;
+    /** Every line known to this client, oldest first, de-duplicated. Safe to render on mount. */
+    readonly history: ChatMessage[];
+    /** Hide a player's lines locally (client-side only — nothing is sent to the server and
+     *  other players are unaffected). Applies to messages received from now on. */
+    mute(playerId: string): void;
+    unmute(playerId: string): void;
+    /** Currently muted player ids. */
+    readonly muted: string[];
+};
+/**
+ * Mesh voice chat — real-time talking between players. Audio travels peer-to-peer; the
+ * relay only keeps the roster and couriers the WebRTC handshake.
+ *
+ * **Party-sized, not room-sized.** The relay caps voice at 6 participants because a mesh
+ * makes every participant upload to every other one, and a joiner has to negotiate with
+ * everyone already present — reliability, not bandwidth, is what breaks first. A 7th
+ * `join()` is refused with `voice:rejected`; the room itself still holds up to 64 players.
+ *
+ * `join()` must be called from a click or tap: browsers gate both the microphone prompt
+ * and audio playback on a user gesture. It rejects if the player denies the mic — that is
+ * an ordinary outcome to show in the UI, not an error to swallow.
+ */
+type VoiceApi = {
+    /** Ask for the mic and enter the room's voice roster. Rejects if permission is denied. */
+    join(options?: VoiceJoinOptions): Promise<void>;
+    /** Leave voice and release the microphone (this is what turns the recording indicator off). */
+    leave(): void;
+    readonly active: boolean;
+    /** Everyone else in voice, with their stream, speaking flag and connection state. */
+    readonly participants: VoiceParticipant[];
+    /** Push-to-talk: gate your outgoing audio instantly, without renegotiating. */
+    setMicEnabled(on: boolean): void;
+    readonly micEnabled: boolean;
+    /** True while YOU are above the speaking threshold and un-gated. */
+    readonly speaking: boolean;
+    /** Silence a player locally. Nothing is sent to them, to the relay, or to anyone else. */
+    mute(playerId: string): void;
+    unmute(playerId: string): void;
+    /** 0..1 playback volume for one player (ignored in `spatial` mode — you own the audio then). */
+    setVolume(playerId: string, volume: number): void;
+    readonly muted: string[];
+};
 /**
  * Connect to a genex multiplayer room. You must supply your player-state type:
  *
@@ -343,4 +469,4 @@ declare function createPrivate<TState extends Record<string, unknown> = never>(o
  */
 declare function joinPrivate<TState extends Record<string, unknown> = never>(code: string, opts: MatchmakeOptions): Promise<Matchmaking<TState>>;
 
-export { type AuthSource, type ColyseusAuth, type ConnectOptions, type MatchStatus, type MatchmakeOptions, type Matchmaking, type MatchmakingView, type ObjectControlOperation, type ObjectControlOptions, type ObjectControlReason, type ObjectControlResult, type ObjectView, type PlayerView, type PrivateMatch, type Session, connect, createPrivate, joinPrivate, matchmake };
+export { type AuthSource, type ChatApi, type ChatMessage, type ColyseusAuth, type ConnectOptions, type MatchStatus, type MatchmakeOptions, type Matchmaking, type MatchmakingView, type ObjectControlOperation, type ObjectControlOptions, type ObjectControlReason, type ObjectControlResult, type ObjectView, type PlayerView, type PrivateMatch, type Session, type VoiceApi, type VoiceJoinOptions, type VoiceParticipant, connect, createPrivate, joinPrivate, matchmake };

package/dist/index.js

@@ -1,5 +1,382 @@
 // 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;
+var DEFAULT_SPEAKING_THRESHOLD = 0.02;
+var SPEAKING_RELEASE_RATIO = 0.6;
+var VoiceMesh = class {
+  transport;
+  peers = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  roster = [];
+  local = null;
+  audio = null;
+  localAnalyser = null;
+  levelTimer = null;
+  iceServers = DEFAULT_ICE;
+  spatial = false;
+  threshold = DEFAULT_SPEAKING_THRESHOLD;
+  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;
+  }
+  get active() {
+    return this.running;
+  }
+  get micEnabled() {
+    return this.micOn;
+  }
+  get speaking() {
+    return this.selfSpeaking;
+  }
+  get participants() {
+    return [...this.peers.values()].map((p) => ({
+      id: p.id,
+      name: this.transport.nameOf(p.id),
+      stream: p.stream,
+      speaking: p.speaking,
+      muted: p.muted,
+      volume: p.volume,
+      connection: p.connection
+    }));
+  }
+  onChange(cb) {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+  /** 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 = {}, 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;
+    this.micOn = options.startMuted !== true;
+    this.local = await navigator.mediaDevices.getUserMedia({
+      audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true },
+      video: false
+    });
+    for (const t of this.local.getAudioTracks()) t.enabled = this.micOn;
+    this.audio = new AudioContext();
+    this.localAnalyser = this.makeAnalyser(this.local);
+    this.running = true;
+    this.levelTimer = setInterval(() => this.pollLevels(), SPEAKING_POLL_MS);
+  }
+  /** 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;
+    }
+    for (const id of [...this.peers.keys()]) this.destroyPeer(id);
+    for (const t of this.local?.getTracks() ?? []) t.stop();
+    this.local = null;
+    this.localAnalyser = null;
+    void this.audio?.close().catch(() => {
+    });
+    this.audio = null;
+    this.roster = [];
+    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);
+    for (const id of [...this.peers.keys()]) if (!wanted.has(id)) this.destroyPeer(id);
+    this.emit();
+  }
+  /** Push-to-talk. Gates the track rather than renegotiating — instant, and it keeps the
+   *  peer connections warm so the first syllable after a key press is not clipped. */
+  setMicEnabled(on) {
+    this.micOn = on;
+    for (const t of this.local?.getAudioTracks() ?? []) t.enabled = on;
+    if (!on && this.selfSpeaking) {
+      this.selfSpeaking = false;
+      this.emit();
+    }
+  }
+  mute(id) {
+    this.setMuted(id, true);
+  }
+  unmute(id) {
+    this.setMuted(id, false);
+  }
+  setVolume(id, volume) {
+    const p = this.peers.get(id);
+    if (!p) return;
+    p.volume = Math.max(0, Math.min(1, volume));
+    if (p.el) p.el.volume = p.volume;
+    this.emit();
+  }
+  /** A signal arrived from `from` (the relay stamped it — it cannot be spoofed). */
+  async handleSignal(from, raw) {
+    if (!this.running) return;
+    const signal = raw;
+    if (!signal || typeof signal !== "object" || typeof signal.t !== "string") return;
+    const peer = this.peers.get(from) ?? (this.roster.includes(from) ? this.createPeer(from) : void 0);
+    if (!peer) return;
+    try {
+      if (signal.t === "offer") {
+        await peer.pc.setRemoteDescription(signal.sdp);
+        await this.flushIce(peer);
+        const answer = await peer.pc.createAnswer();
+        await peer.pc.setLocalDescription(answer);
+        this.transport.sendSignal(from, { t: "answer", sdp: answer });
+      } else if (signal.t === "answer") {
+        if (peer.pc.signalingState !== "have-local-offer") return;
+        await peer.pc.setRemoteDescription(signal.sdp);
+        await this.flushIce(peer);
+      } else if (signal.t === "ice") {
+        if (peer.pc.remoteDescription) await peer.pc.addIceCandidate(signal.c);
+        else peer.pendingIce.push(signal.c);
+      }
+    } catch (err) {
+      console.warn(`[multiplayer] voice signaling failed with ${from}`, err);
+    }
+  }
+  // ---- internals ----
+  setMuted(id, muted) {
+    const p = this.peers.get(id);
+    if (!p || p.muted === muted) return;
+    p.muted = muted;
+    if (p.el) p.el.muted = muted || this.spatial;
+    if (muted && p.speaking) p.speaking = false;
+    this.emit();
+  }
+  createPeer(id) {
+    const pc = new RTCPeerConnection({ iceServers: this.iceServers });
+    const peer = {
+      id,
+      pc,
+      el: null,
+      stream: null,
+      analyser: null,
+      pendingIce: [],
+      speaking: false,
+      muted: false,
+      volume: 1,
+      connection: "connecting"
+    };
+    this.peers.set(id, peer);
+    for (const track of this.local?.getAudioTracks() ?? []) {
+      if (this.local) pc.addTrack(track, this.local);
+    }
+    pc.onicecandidate = (e) => {
+      if (e.candidate) this.transport.sendSignal(id, { t: "ice", c: e.candidate.toJSON() });
+    };
+    pc.ontrack = (e) => {
+      const stream = e.streams[0] ?? new MediaStream([e.track]);
+      peer.stream = stream;
+      peer.el = this.attachSink(stream, peer);
+      peer.analyser = this.makeAnalyser(stream);
+      this.emit();
+    };
+    pc.onconnectionstatechange = () => {
+      const s = pc.connectionState;
+      const next = s === "connected" ? "connected" : s === "failed" || s === "closed" ? "failed" : "connecting";
+      if (next !== peer.connection) {
+        peer.connection = next;
+        if (next === "failed") {
+          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();
+      }
+    };
+    if (this.transport.selfId() < id) void this.offer(peer);
+    return peer;
+  }
+  async offer(peer) {
+    try {
+      const offer = await peer.pc.createOffer();
+      await peer.pc.setLocalDescription(offer);
+      this.transport.sendSignal(peer.id, { t: "offer", sdp: offer });
+    } catch (err) {
+      console.warn(`[multiplayer] voice offer to ${peer.id} failed`, err);
+    }
+  }
+  async flushIce(peer) {
+    const queued = peer.pendingIce.splice(0);
+    for (const c of queued) {
+      try {
+        await peer.pc.addIceCandidate(c);
+      } catch {
+      }
+    }
+  }
+  destroyPeer(id) {
+    const peer = this.peers.get(id);
+    if (!peer) return;
+    this.peers.delete(id);
+    peer.pc.onicecandidate = null;
+    peer.pc.ontrack = null;
+    peer.pc.onconnectionstatechange = null;
+    try {
+      peer.pc.close();
+    } catch {
+    }
+    if (peer.el) {
+      peer.el.srcObject = null;
+      peer.el.remove();
+    }
+  }
+  /** Attach the stream to an element. Required even in spatial mode (see VoiceJoinOptions). */
+  attachSink(stream, peer) {
+    const el = document.createElement("audio");
+    el.autoplay = true;
+    el.srcObject = stream;
+    el.muted = this.spatial || peer.muted;
+    el.volume = peer.volume;
+    el.style.display = "none";
+    document.body.appendChild(el);
+    void el.play().catch((err) => {
+      console.warn("[multiplayer] voice playback was blocked \u2014 join voice from a click/tap", err);
+    });
+    return el;
+  }
+  makeAnalyser(stream) {
+    if (!this.audio) return null;
+    try {
+      const src = this.audio.createMediaStreamSource(stream);
+      const analyser = this.audio.createAnalyser();
+      analyser.fftSize = 512;
+      src.connect(analyser);
+      return analyser;
+    } catch {
+      return null;
+    }
+  }
+  pollLevels() {
+    let changed = false;
+    const localLevel = this.micOn ? rms(this.localAnalyser) : 0;
+    const nextSelf = this.crossed(localLevel, this.selfSpeaking);
+    if (nextSelf !== this.selfSpeaking) {
+      this.selfSpeaking = nextSelf;
+      changed = true;
+    }
+    for (const peer of this.peers.values()) {
+      const next = peer.muted ? false : this.crossed(rms(peer.analyser), peer.speaking);
+      if (next !== peer.speaking) {
+        peer.speaking = next;
+        changed = true;
+      }
+    }
+    if (changed) this.emit();
+  }
+  /** Threshold with hysteresis so a name tag does not strobe between syllables. */
+  crossed(level, was) {
+    return level >= (was ? this.threshold * SPEAKING_RELEASE_RATIO : this.threshold);
+  }
+  emit() {
+    for (const cb of [...this.listeners]) {
+      try {
+        cb();
+      } catch (err) {
+        console.error("[multiplayer] a voice listener threw", err);
+      }
+    }
+  }
+};
+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);
+  analyser.getByteTimeDomainData(buf);
+  let sum = 0;
+  for (let i = 0; i < buf.length; i++) {
+    const v = ((buf[i] ?? 128) - 128) / 128;
+    sum += v * v;
+  }
+  return Math.sqrt(sum / buf.length);
+}
+
+// src/index.ts
 var RELAY_ROOM_TYPE = "play";
 var QUEUE_ROOM_TYPE = "queue";
 var MATCH_ROOM_TYPE = "match";
@@ -22,6 +399,17 @@ var MATCH_KEY = "__match";
 var INPUT_MSG = "__input";
 var CAPABILITIES_MSG = "__capabilities";
 var CAPABILITIES_REQUEST_MSG = "__capabilities:request";
+var CHAT_MSG = "__chat";
+var CHAT_HISTORY_MSG = "__chat:history";
+var CHAT_HISTORY_REQUEST_MSG = "__chat:history:request";
+var VOICE_KEY = "__voice";
+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";
@@ -320,6 +708,10 @@ function attachSession(client, initialRoom) {
     "reconnecting",
     "reconnected",
     "disconnect",
+    // Locally emitted by the voice mesh — never relay message types. Without these here,
+    // room.on('voice', …) would register a stray room.onMessage('voice') as well.
+    "voice",
+    "voice:rejected",
     INPUT_MSG,
     // inputs.on() has its own channel — never bridged as a custom event
     "rate:drop",
@@ -328,7 +720,19 @@ function attachSession(client, initialRoom) {
     CAPABILITIES_REQUEST_MSG,
     OBJECT_CONTROL_RESULT_MSG,
     STATE_SNAP_MSG,
-    OBJECT_SNAP_MSG
+    OBJECT_SNAP_MSG,
+    // chat.on() has its own channel. Bridging these would re-register room.onMessage for
+    // the same type and clobber the chat listener, silently killing chat for that game.
+    CHAT_MSG,
+    CHAT_HISTORY_MSG,
+    CHAT_HISTORY_REQUEST_MSG,
+    // voice.* owns these; bridging them would clobber the mesh's own listeners.
+    VOICE_SIGNAL_MSG,
+    VOICE_REJECTED_MSG,
+    VOICE_JOIN_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();
@@ -344,6 +748,12 @@ function attachSession(client, initialRoom) {
       }
       return;
     }
+    if (key === VOICE_KEY) {
+      const ids = parseValue(value);
+      voice.setRoster(Array.isArray(ids) ? ids.filter((v) => typeof v === "string") : []);
+      emit("voice", voice.participants);
+      return;
+    }
     if (key.startsWith(OBJ_PREFIX)) {
       const id = key.slice(OBJ_PREFIX.length);
       const blob = parseValue(value);
@@ -544,6 +954,55 @@ function attachSession(client, initialRoom) {
     }
     if (countIfDropped) droppedWhileOffline++;
   };
+  const voice = new VoiceMesh({
+    selfId: () => room.sessionId,
+    nameOf: (id) => room.state?.players?.get(id)?.name ?? "",
+    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();
+  const chatMuted = /* @__PURE__ */ new Set();
+  const isChatMessage = (m) => !!m && typeof m === "object" && typeof m.id === "number" && typeof m.from === "string" && typeof m.name === "string" && typeof m.text === "string";
+  const acceptChat = (message) => {
+    if (!isChatMessage(message)) return;
+    if (chatSeen.has(message.id)) return;
+    if (chatMuted.has(message.from)) return;
+    chatSeen.add(message.id);
+    const last = chatHistory[chatHistory.length - 1];
+    if (!last || message.id > last.id) chatHistory.push(message);
+    else {
+      let i = chatHistory.length;
+      while (i > 0 && (chatHistory[i - 1]?.id ?? 0) > message.id) i--;
+      chatHistory.splice(i, 0, message);
+    }
+    for (const cb of [...chatListeners]) {
+      try {
+        cb(message);
+      } catch (err) {
+        console.error("[multiplayer] a chat listener threw", err);
+      }
+    }
+  };
   const wireRoom = (r) => {
     let hydrated;
     const $ = getStateCallbacks(r);
@@ -633,6 +1092,32 @@ function attachSession(client, initialRoom) {
     r.onMessage(CAPABILITIES_REQUEST_MSG, () => {
     });
     send0(CAPABILITIES_REQUEST_MSG, { objectControl: OBJECT_CONTROL_VERSION });
+    r.onMessage(VOICE_SIGNAL_MSG, (msg) => {
+      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" });
+    });
+    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, () => {
+      });
+    }
+    r.onMessage(CHAT_MSG, (msg) => acceptChat(msg));
+    r.onMessage(CHAT_HISTORY_MSG, (msg) => {
+      if (!Array.isArray(msg?.messages)) return;
+      for (const m of msg.messages) acceptChat(m);
+    });
+    send0(CHAT_HISTORY_REQUEST_MSG, {});
     r.onMessage(OBJECT_CONTROL_RESULT_MSG, (msg) => {
       if (!msg || typeof msg.requestId !== "string") return;
       const pending = pendingControls.get(msg.requestId);
@@ -914,11 +1399,82 @@ function attachSession(client, initialRoom) {
       }
       send0(type, payload, true);
     },
+    chat: {
+      send(text) {
+        if (typeof text !== "string") return;
+        if (!text.trim()) return;
+        send0(CHAT_MSG, { text }, true);
+      },
+      on(cb) {
+        chatListeners.add(cb);
+        return () => chatListeners.delete(cb);
+      },
+      get history() {
+        return [...chatHistory];
+      },
+      mute(playerId) {
+        if (typeof playerId === "string" && playerId) chatMuted.add(playerId);
+      },
+      unmute(playerId) {
+        chatMuted.delete(playerId);
+      },
+      get muted() {
+        return [...chatMuted];
+      }
+    },
+    voice: {
+      async join(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();
+      },
+      get active() {
+        return voice.active;
+      },
+      get participants() {
+        return voice.participants;
+      },
+      setMicEnabled(on2) {
+        voice.setMicEnabled(on2 === true);
+      },
+      get micEnabled() {
+        return voice.micEnabled;
+      },
+      get speaking() {
+        return voice.speaking;
+      },
+      mute(playerId) {
+        voice.mute(playerId);
+      },
+      unmute(playerId) {
+        voice.unmute(playerId);
+      },
+      setVolume(playerId, volume) {
+        voice.setVolume(playerId, volume);
+      },
+      get muted() {
+        return voice.participants.filter((p) => p.muted).map((p) => p.id);
+      }
+    },
     setRoomOpen(open) {
       room.send(ROOM_OPEN_MSG, { open });
     },
     leave() {
       intentionalLeave = true;
+      voice.stop();
       connected = false;
       syncHostTicks();
       settleAllControls("aborted");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genex-ai/multiplayer",
-  "version": "0.13.0",
+  "version": "0.16.0",
   "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"
   },
@@ -44,7 +45,8 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.0",
     "publint": "^0.3.0",
-    "tsup": "^8.0.0"
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.0"
   },
   "repository": {
     "type": "git",