@genex-ai/multiplayer 0.12.1 → 0.15.0

package/README.md

@@ -223,12 +223,79 @@ 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.
+
+**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:
+
+```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,42 @@
 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 = {
+    /**
+     * 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.
+     */
+    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 +217,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,9 +249,102 @@ 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.
+     *
+     * For a lobby game: call `setRoomOpen(false)` when your match starts, so arrivals
+     * form the NEXT room instead of dropping into a fight already in progress, and
+     * `setRoomOpen(true)` when you return to the lobby. Everyone already in the room
+     * keeps playing, and a reconnecting player still gets back in (reconnection uses a
+     * reserved seat, not matchmaking).
+     *
+     * Ignored (with no error) when called by a non-host — read `isHost` first. All
+     * clients are told either way, so you can render "closed" from the `room:open` event.
+     */
+    setRoomOpen(open: boolean): void;
     /** 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:
  *
@@ -330,4 +468,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,304 @@
 // src/index.ts
 import { Client, getStateCallbacks } from "@colyseus/sdk";
+
+// 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;
+  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 = {}) {
+    if (this.running) return;
+    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;
+    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();
+  }
+  /** The relay's authoritative roster changed: open connections to newcomers, drop leavers. */
+  setRoster(ids) {
+    this.roster = ids;
+    if (!this.running) 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") {
+          console.warn(`[multiplayer] voice connection to ${id} failed (no TURN configured?)`);
+        }
+        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 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,9 +321,18 @@ 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 OBJECT_CONTROL_RESULT_MSG = "__object:result";
 var OBJECT_CONTROL_VERSION = 2;
 var STATE_SNAP_MSG = "__state:snap";
+var ROOM_OPEN_MSG = "__room:open";
 var OBJECT_SNAP_MSG = "__object:snap";
 var MP_PROTOCOL = 2;
 async function relayClient(opts) {
@@ -319,6 +627,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",
@@ -327,7 +639,17 @@ 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
   ]);
   const emit = (event, ...args) => emitters.get(event)?.forEach((cb) => cb(...args));
   const lastShared = /* @__PURE__ */ new Map();
@@ -343,6 +665,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);
@@ -543,6 +871,37 @@ 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));
+  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);
@@ -632,6 +991,23 @@ 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) => {
+      voice.stop();
+      emit("voice:rejected", msg ?? { reason: "full" });
+    });
+    for (const inert of [VOICE_JOIN_MSG, VOICE_LEAVE_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);
@@ -913,8 +1289,72 @@ 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);
+        send0(VOICE_JOIN_MSG, {}, true);
+      },
+      leave() {
+        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.12.1",
+  "version": "0.15.0",
   "description": "The multiplayer client wrapper + shared room schema for genex.",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,7 +44,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",