@relu-interactives/spatial-ecs 0.8.0 → 0.10.0

package/dist/network/index.js

@@ -1,6 +1,6 @@
-import { spawnPrefab, despawnPrefab, Behaviour, reportBehaviourHookError } from '../chunk-U727NTWQ.js';
-import '../chunk-G4XJ53LS.js';
-import { NetworkIdentityComponent, TransformComponent, NetworkedPropsComponent, NetworkSpawnerComponent, NetworkTransformComponent, ScriptComponent } from '../chunk-NNDUOQ7O.js';
+import { spawnPrefab, despawnPrefab, Behaviour, reportBehaviourHookError } from '../chunk-WWP46AEF.js';
+import '../chunk-JEPUCLZX.js';
+import { NetworkIdentityComponent, TransformComponent, NetworkedPropsComponent, NetworkSpawnerComponent, NetworkTransformComponent, ScriptComponent } from '../chunk-JNYPJB55.js';
 import '../chunk-CKTHDXPS.js';
 import '../chunk-GSWC6LLD.js';
 import { __name } from '../chunk-XE4OXN2W.js';
@@ -69,6 +69,12 @@ var _ColyseusTransport = class _ColyseusTransport {
   onCorrect(cb) {
     this.room.onMessage("correct", (m) => cb(m.id, m));
   }
+  onSound(cb) {
+    this.room.onMessage("sound", (m) => cb(m, m.from));
+  }
+  onVoice(cb) {
+    this.room.onMessage("voice", cb);
+  }
   onClose(cb) {
     this.room.onLeave(() => cb());
   }
@@ -90,6 +96,12 @@ var _ColyseusTransport = class _ColyseusTransport {
   send(name, payload) {
     this.room.send("m", { name, payload });
   }
+  sendSound(sound) {
+    this.room.send("sound", sound);
+  }
+  sendVoice(message) {
+    this.room.send("voice", message);
+  }
   leave() {
     void this.room.leave();
   }
@@ -172,6 +184,623 @@ var _SnapshotBuffer = class _SnapshotBuffer {
 __name(_SnapshotBuffer, "SnapshotBuffer");
 var SnapshotBuffer = _SnapshotBuffer;
 
+// core/network/sdp.ts
+var OPUS_VOICE = {
+  useinbandfec: "1",
+  usedtx: "1",
+  stereo: "0",
+  "sprop-stereo": "0",
+  maxaveragebitrate: "20000",
+  maxplaybackrate: "24000"
+};
+var VOICE_PTIME = 40;
+function mergeFmtp(fmtp, params) {
+  const pairs = fmtp.split(";").map((part) => part.trim()).filter(Boolean).map((part) => {
+    const i = part.indexOf("=");
+    return i < 0 ? [part, ""] : [part.slice(0, i), part.slice(i + 1)];
+  });
+  for (const [key, value] of Object.entries(params)) {
+    const found = pairs.find((pair) => pair[0].toLowerCase() === key.toLowerCase());
+    if (found) found[1] = value;
+    else pairs.push([key, value]);
+  }
+  return pairs.map(([k, v]) => v === "" ? k : `${k}=${v}`).join(";");
+}
+__name(mergeFmtp, "mergeFmtp");
+function tuneOpus(sdp, params = OPUS_VOICE, ptime = VOICE_PTIME) {
+  const eol = sdp.includes("\r\n") ? "\r\n" : "\n";
+  const sections = [[]];
+  for (const line of sdp.split(eol)) {
+    if (line.startsWith("m=")) sections.push([]);
+    sections[sections.length - 1].push(line);
+  }
+  const out = [];
+  for (const section of sections) {
+    const opus = section.flatMap((line) => {
+      const match = /^a=rtpmap:(\d+) opus\/48000/i.exec(line);
+      return match ? [match[1]] : [];
+    });
+    if (!section[0]?.startsWith("m=audio") || !opus.length) {
+      out.push(...section);
+      continue;
+    }
+    const tuned = [];
+    for (const line of section) {
+      const fmtp = /^a=fmtp:(\d+) (.*)$/.exec(line);
+      if (fmtp && opus.includes(fmtp[1])) {
+        tuned.push(`a=fmtp:${fmtp[1]} ${mergeFmtp(fmtp[2], params)}`);
+        continue;
+      }
+      tuned.push(line);
+      const rtpmap = /^a=rtpmap:(\d+) opus\/48000/i.exec(line);
+      if (rtpmap && !section.some((l) => l.startsWith(`a=fmtp:${rtpmap[1]} `))) {
+        tuned.push(`a=fmtp:${rtpmap[1]} ${mergeFmtp("", params)}`);
+      }
+    }
+    if (ptime && !tuned.some((line) => line.startsWith("a=ptime:"))) {
+      const at = tuned[tuned.length - 1] === "" ? tuned.length - 1 : tuned.length;
+      tuned.splice(at, 0, `a=ptime:${ptime}`);
+    }
+    out.push(...tuned);
+  }
+  return out.join(eol);
+}
+__name(tuneOpus, "tuneOpus");
+
+// core/network/voice.ts
+var LEVEL_BPS = [24e3, 16e3, 1e4];
+var WORST_LEVEL = 2;
+var TICK_MS = 2e3;
+var POLL_MS = 100;
+var GOOD_TO_STEP_UP_MS = 1e4;
+var MAX_LOSS = 0.05;
+var MAX_RTT_MS = 400;
+var TALKING_LEVEL = 0.06;
+var DUCK_SECONDS = 0.6;
+var MAX_RESTARTS = 3;
+function startingLevel(others) {
+  if (others <= 2) return 0;
+  return others <= 4 ? 1 : 2;
+}
+__name(startingLevel, "startingLevel");
+function adaptLevel(level, best, bad, goodMs) {
+  let next = Math.max(level, best);
+  if (bad) {
+    return { level: Math.min(WORST_LEVEL, next + 1), goodMs: 0 };
+  }
+  let good = goodMs + TICK_MS;
+  if (good >= GOOD_TO_STEP_UP_MS && next > best) {
+    next -= 1;
+    good = 0;
+  }
+  return { level: next, goodMs: good };
+}
+__name(adaptLevel, "adaptLevel");
+function micError(error) {
+  const name = error.name;
+  if (name === "NotAllowedError") return "Microphone blocked: allow it in your browser settings";
+  if (name === "NotFoundError") return "No microphone found";
+  return "Could not start the microphone";
+}
+__name(micError, "micError");
+async function readLinkStats(pc) {
+  const stats = await pc.getStats();
+  let loss = 0;
+  let rttMs = 0;
+  stats.forEach((report) => {
+    const r = report;
+    if (r.type === "remote-inbound-rtp" && r.kind === "audio") {
+      if (typeof r.fractionLost === "number") loss = Math.max(loss, r.fractionLost);
+    }
+    if (r.type === "candidate-pair" && r.state === "succeeded" && r.nominated !== false) {
+      if (typeof r.currentRoundTripTime === "number") {
+        rttMs = Math.max(rttMs, r.currentRoundTripTime * 1e3);
+      }
+    }
+  });
+  return { loss, rttMs };
+}
+__name(readLinkStats, "readLinkStats");
+var _VoiceChat = class _VoiceChat {
+  constructor(transport, deps) {
+    this.transport = transport;
+    this.deps = deps;
+    this.available = false;
+    this.state = "off";
+    this.micMuted = false;
+    this.talking = false;
+    this.error = "";
+    /** Hear each voice from its character, when there is one. Off, everyone's in your ear. */
+    this.positional = true;
+    this.peersById = /* @__PURE__ */ new Map();
+    this.listeners = /* @__PURE__ */ new Set();
+    this.config = {};
+    this.track = null;
+    this.meter = null;
+    this.level = 0;
+    this.goodMs = 0;
+    this.stopTimers = null;
+    this.disposed = false;
+    transport.onVoice((message) => this.fromRoom(message));
+    transport.sendVoice({ t: "hello" });
+  }
+  get peers() {
+    return [...this.peersById.values()].map((p) => ({
+      id: p.id,
+      connected: p.connected,
+      talking: p.talking,
+      micOn: p.micOn,
+      muted: p.muted,
+      volume: p.volume
+    }));
+  }
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  changed() {
+    for (const listener of this.listeners) listener();
+  }
+  /** Turn voice on. Call from a tap or key: that's what lets the browser ask for the mic. */
+  async enable() {
+    if (this.state !== "off") return true;
+    if (!this.available) return false;
+    this.error = "";
+    this.state = "connecting";
+    this.changed();
+    this.deps.setCapture(true);
+    try {
+      await this.acquire();
+    } catch (error) {
+      this.deps.setCapture(false);
+      this.state = "off";
+      this.error = micError(error);
+      this.changed();
+      return false;
+    }
+    if (this.disposed || this.state !== "connecting") {
+      this.release();
+      return false;
+    }
+    this.micMuted = false;
+    this.transport.sendVoice({ t: "join" });
+    return true;
+  }
+  async acquire() {
+    const stream = await this.deps.getMic({
+      audio: {
+        echoCancellation: true,
+        noiseSuppression: true,
+        autoGainControl: true,
+        channelCount: 1
+      },
+      video: false
+    });
+    this.track = stream.getAudioTracks()[0] ?? null;
+    if (this.track) this.track.onended = () => this.lost();
+    this.meter?.close();
+    this.meter = this.deps.analyse(stream);
+  }
+  release() {
+    try {
+      this.track?.stop();
+    } catch {
+    }
+    this.track = null;
+    this.meter?.close();
+    this.meter = null;
+    this.talking = false;
+    this.deps.setCapture(false);
+  }
+  /** The mic stopped by itself: the phone took it for a call, or the device went away. */
+  lost() {
+    if (this.state === "off") return;
+    this.track = null;
+    this.micMuted = true;
+    this.error = "Your mic stopped: tap the mic to turn it back on";
+    this.transport.sendVoice({ t: "mic", on: false });
+    this.sendMicToAll();
+    this.changed();
+  }
+  /** Turn voice off. The mic stops at once. */
+  disable() {
+    if (this.state === "off") return;
+    this.transport.sendVoice({ t: "leave" });
+    this.shutDown();
+    this.changed();
+  }
+  shutDown() {
+    this.state = "off";
+    this.micMuted = false;
+    this.stopTimers?.();
+    this.stopTimers = null;
+    for (const peer of [...this.peersById.values()]) this.closePeer(peer);
+    this.release();
+  }
+  /** Mute or unmute this player's mic. Everyone in voice sees it. */
+  async setMicMuted(muted) {
+    if (this.state !== "on") return;
+    if (!muted && !this.track) {
+      try {
+        this.deps.setCapture(true);
+        await this.acquire();
+        this.error = "";
+      } catch (error) {
+        this.error = micError(error);
+        this.changed();
+        return;
+      }
+    }
+    this.micMuted = muted;
+    this.transport.sendVoice({ t: "mic", on: !muted });
+    this.sendMicToAll();
+    this.changed();
+  }
+  /** Stop hearing someone. They aren't told. */
+  setPeerMuted(id, muted) {
+    const peer = this.peersById.get(id);
+    if (!peer) return;
+    peer.muted = muted;
+    peer.player?.setVolume(muted ? 0 : peer.volume);
+    this.changed();
+  }
+  setPeerVolume(id, volume) {
+    const peer = this.peersById.get(id);
+    if (!peer) return;
+    peer.volume = volume;
+    if (!peer.muted) peer.player?.setVolume(volume);
+    this.changed();
+  }
+  fromRoom(m) {
+    if (m.t === "caps") {
+      this.available = m.available && this.deps.supported();
+      this.changed();
+    } else if (m.t === "refused") {
+      if (this.state === "off") return;
+      this.shutDown();
+      this.error = m.reason === "full" ? "Voice is full in this room" : "Voice chat isn't available in this game";
+      this.changed();
+    } else if (m.t === "welcome") {
+      if (this.state !== "connecting") return;
+      this.config = {
+        iceServers: m.iceServers,
+        iceTransportPolicy: m.relayOnly ? "relay" : "all"
+      };
+      this.state = "on";
+      this.level = startingLevel(m.peers.length);
+      this.startTimers();
+      for (const other of m.peers) {
+        void this.call(this.addPeer(other.id, true, other.mic));
+      }
+      this.changed();
+    } else if (this.state !== "on") ; else if (m.t === "joined") {
+      this.addPeer(m.id, false, true);
+      this.retune();
+      this.changed();
+    } else if (m.t === "left") {
+      const peer = this.peersById.get(m.id);
+      if (peer) this.closePeer(peer);
+      this.retune();
+      this.changed();
+    } else if (m.t === "mic") {
+      const peer = this.peersById.get(m.id);
+      if (peer) peer.micOn = m.on;
+      this.changed();
+    } else if (m.t === "signal") {
+      void this.onSignal(m.from, m.signal);
+    }
+  }
+  addPeer(id, caller, micOn) {
+    const existing = this.peersById.get(id);
+    if (existing) return existing;
+    const pc = this.deps.createConnection(this.config);
+    const peer = {
+      id,
+      pc,
+      caller,
+      audio: null,
+      pendingIce: [],
+      player: null,
+      meter: null,
+      connected: false,
+      micOn,
+      muted: false,
+      volume: 1,
+      talking: false,
+      restarts: 0
+    };
+    this.peersById.set(id, peer);
+    pc.ontrack = (event) => {
+      if (event.track.kind === "audio") this.hear(peer, event.track);
+    };
+    pc.onicecandidate = (event) => {
+      if (event.candidate) this.signal(id, { kind: "ice", candidate: event.candidate.toJSON() });
+    };
+    pc.onconnectionstatechange = () => this.connectionChanged(peer);
+    return peer;
+  }
+  signal(to, signal) {
+    this.transport.sendVoice({ t: "signal", to, signal });
+  }
+  hear(peer, track) {
+    peer.player?.stop();
+    peer.meter?.close();
+    peer.player = this.deps.playRemote(track);
+    peer.player.setVolume(peer.muted ? 0 : peer.volume);
+    peer.meter = this.deps.analyse(track);
+  }
+  connectionChanged(peer) {
+    if (this.peersById.get(peer.id) !== peer) return;
+    const state = peer.pc.connectionState;
+    if (state === "connected") {
+      peer.connected = true;
+      peer.restarts = 0;
+      void this.applyBitrate(peer);
+      this.changed();
+    } else if (state === "failed") {
+      peer.connected = false;
+      this.changed();
+      if (peer.caller && peer.restarts < MAX_RESTARTS) {
+        peer.restarts += 1;
+        void this.offer(peer, true);
+      }
+    }
+  }
+  async call(peer) {
+    peer.audio = peer.pc.addTransceiver("audio", { direction: "sendrecv" });
+    await this.sendMic(peer);
+    await this.offer(peer, false);
+  }
+  async offer(peer, restart) {
+    try {
+      if (restart) peer.pc.restartIce();
+      await peer.pc.setLocalDescription(await peer.pc.createOffer({ iceRestart: restart }));
+      const sdp = peer.pc.localDescription?.sdp;
+      if (sdp) this.signal(peer.id, { kind: "offer", sdp });
+    } catch (error) {
+      console.warn("[relu] Couldn't start a voice connection.", error);
+    }
+  }
+  async onSignal(from, signal) {
+    const peer = this.addPeer(from, false, true);
+    try {
+      if (signal.kind === "ice") {
+        if (peer.pc.remoteDescription) await peer.pc.addIceCandidate(signal.candidate);
+        else peer.pendingIce.push(signal.candidate);
+        return;
+      }
+      await peer.pc.setRemoteDescription({ type: signal.kind, sdp: tuneOpus(signal.sdp) });
+      for (const candidate of peer.pendingIce.splice(0)) {
+        await peer.pc.addIceCandidate(candidate);
+      }
+      if (signal.kind === "answer") return;
+      if (!peer.audio) {
+        const slot = peer.pc.getTransceivers().find((t) => t.receiver.track.kind === "audio");
+        if (slot) {
+          slot.direction = "sendrecv";
+          peer.audio = slot;
+        }
+      }
+      await this.sendMic(peer);
+      await peer.pc.setLocalDescription(await peer.pc.createAnswer());
+      const sdp = peer.pc.localDescription?.sdp;
+      if (sdp) this.signal(from, { kind: "answer", sdp });
+    } catch (error) {
+      console.warn("[relu] A voice connection failed to set up.", error);
+    }
+  }
+  async sendMic(peer) {
+    const sender = peer.audio?.sender;
+    if (!sender) return;
+    await sender.replaceTrack(this.micMuted ? null : this.track).catch(() => void 0);
+    await this.applyBitrate(peer);
+  }
+  sendMicToAll() {
+    for (const peer of this.peersById.values()) void this.sendMic(peer);
+  }
+  async applyBitrate(peer) {
+    const sender = peer.audio?.sender;
+    if (!sender) return;
+    try {
+      const parameters = sender.getParameters();
+      if (!parameters.encodings?.length) parameters.encodings = [{}];
+      parameters.encodings[0].maxBitrate = LEVEL_BPS[this.level];
+      await sender.setParameters(parameters);
+    } catch {
+    }
+  }
+  setLevel(level) {
+    if (level === this.level) return;
+    this.level = level;
+    for (const peer of this.peersById.values()) void this.applyBitrate(peer);
+  }
+  /** Someone came or went: the rate each connection gets changes with it. */
+  retune() {
+    this.setLevel(Math.max(this.level, startingLevel(this.peersById.size)));
+  }
+  closePeer(peer) {
+    peer.player?.stop();
+    peer.meter?.close();
+    peer.pc.ontrack = null;
+    peer.pc.onicecandidate = null;
+    peer.pc.onconnectionstatechange = null;
+    peer.pc.close();
+    this.peersById.delete(peer.id);
+  }
+  startTimers() {
+    const stopPoll = this.deps.every(POLL_MS, () => this.poll());
+    const stopTick = this.deps.every(TICK_MS, () => void this.tick());
+    this.stopTimers = () => {
+      stopPoll();
+      stopTick();
+    };
+  }
+  /** Who's talking, where they are, and the music under them. */
+  poll() {
+    let anyone = false;
+    let moved2 = false;
+    for (const peer of this.peersById.values()) {
+      const talking = !peer.muted && (peer.meter?.level() ?? 0) > TALKING_LEVEL;
+      if (talking !== peer.talking) moved2 = true;
+      peer.talking = talking;
+      anyone || (anyone = talking);
+      peer.player?.setPosition(this.positional ? this.deps.positionOf(peer.id) : null);
+    }
+    const me = !this.micMuted && (this.meter?.level() ?? 0) > TALKING_LEVEL;
+    if (me !== this.talking) moved2 = true;
+    this.talking = me;
+    if (anyone) this.deps.duck(DUCK_SECONDS);
+    if (moved2) this.changed();
+  }
+  /** Step quality to what the connections can carry. */
+  async tick() {
+    let bad = false;
+    for (const peer of this.peersById.values()) {
+      if (!peer.connected) continue;
+      const stats = await readLinkStats(peer.pc).catch(() => null);
+      if (stats && (stats.loss > MAX_LOSS || stats.rttMs > MAX_RTT_MS)) bad = true;
+    }
+    if (this.state !== "on") return;
+    const step = adaptLevel(this.level, startingLevel(this.peersById.size), bad, this.goodMs);
+    this.goodMs = step.goodMs;
+    this.setLevel(step.level);
+  }
+  /** The room is going: stop everything. There's no one left to tell. */
+  dispose() {
+    this.disposed = true;
+    this.shutDown();
+    this.available = false;
+    this.changed();
+    this.listeners.clear();
+  }
+};
+__name(_VoiceChat, "VoiceChat");
+var VoiceChat = _VoiceChat;
+
+// core/network/voiceBrowser.ts
+var FULL_VOLUME_DISTANCE = 2;
+var SILENT_DISTANCE = 60;
+var POSITION_SMOOTHING = 0.05;
+function voiceGraph(mixer, stream) {
+  const context = mixer?.listener.context;
+  if (!mixer || !context || context.state !== "running") return null;
+  const bus = mixer.input("voice");
+  const source = context.createMediaStreamSource(stream);
+  const gain = context.createGain();
+  const panner = context.createPanner();
+  panner.panningModel = "equalpower";
+  panner.distanceModel = "inverse";
+  panner.refDistance = FULL_VOLUME_DISTANCE;
+  panner.maxDistance = SILENT_DISTANCE;
+  source.connect(gain);
+  gain.connect(bus);
+  let placed = false;
+  return {
+    setVolume(volume) {
+      gain.gain.setTargetAtTime(Math.max(0, Math.min(2, volume)), context.currentTime, 0.02);
+    },
+    setPosition(position) {
+      if (Boolean(position) !== placed) {
+        placed = !placed;
+        gain.disconnect();
+        panner.disconnect();
+        if (placed) {
+          gain.connect(panner);
+          panner.connect(bus);
+        } else {
+          gain.connect(bus);
+        }
+      }
+      if (!position) return;
+      const now = context.currentTime;
+      panner.positionX.setTargetAtTime(position.x, now, POSITION_SMOOTHING);
+      panner.positionY.setTargetAtTime(position.y, now, POSITION_SMOOTHING);
+      panner.positionZ.setTargetAtTime(position.z, now, POSITION_SMOOTHING);
+    },
+    stop() {
+      source.disconnect();
+      gain.disconnect();
+      panner.disconnect();
+    }
+  };
+}
+__name(voiceGraph, "voiceGraph");
+function playRemote(mixer, track) {
+  const stream = new MediaStream([track]);
+  const element = document.createElement("audio");
+  element.autoplay = true;
+  element.setAttribute("playsinline", "");
+  element.srcObject = stream;
+  element.style.display = "none";
+  const graph = voiceGraph(mixer, stream);
+  element.muted = graph !== null;
+  document.body.appendChild(element);
+  void element.play().catch(() => void 0);
+  return {
+    setVolume(volume) {
+      if (graph) graph.setVolume(volume);
+      else element.volume = Math.max(0, Math.min(1, volume));
+    },
+    setPosition(position) {
+      graph?.setPosition(position);
+    },
+    stop() {
+      graph?.stop();
+      element.pause();
+      element.srcObject = null;
+      element.remove();
+    }
+  };
+}
+__name(playRemote, "playRemote");
+function analyse(mixer, from) {
+  const context = mixer?.listener.context;
+  if (!context) return null;
+  const stream = from instanceof MediaStream ? from : new MediaStream([from]);
+  const source = context.createMediaStreamSource(stream);
+  const analyser = context.createAnalyser();
+  analyser.fftSize = 512;
+  source.connect(analyser);
+  const samples = new Float32Array(analyser.fftSize);
+  return {
+    level() {
+      analyser.getFloatTimeDomainData(samples);
+      let sum = 0;
+      for (const sample of samples) sum += sample * sample;
+      return Math.min(1, Math.sqrt(sum / samples.length) * 3);
+    },
+    close() {
+      source.disconnect();
+      analyser.disconnect();
+    }
+  };
+}
+__name(analyse, "analyse");
+function browserVoiceDeps(world, positionOf) {
+  const mixer = /* @__PURE__ */ __name(() => world.getAudioSystem()?.getMixer() ?? null, "mixer");
+  return {
+    supported: /* @__PURE__ */ __name(() => typeof RTCPeerConnection !== "undefined" && globalThis.isSecureContext && Boolean(navigator.mediaDevices?.getUserMedia), "supported"),
+    createConnection: /* @__PURE__ */ __name((config) => new RTCPeerConnection(config), "createConnection"),
+    getMic: /* @__PURE__ */ __name((constraints) => navigator.mediaDevices.getUserMedia(constraints), "getMic"),
+    setCapture(on) {
+      const session = navigator.audioSession;
+      if (session) session.type = on ? "play-and-record" : "playback";
+      if (on) void mixer()?.listener.context.resume();
+    },
+    analyse: /* @__PURE__ */ __name((from) => analyse(mixer(), from), "analyse"),
+    playRemote: /* @__PURE__ */ __name((track) => playRemote(mixer(), track), "playRemote"),
+    duck: /* @__PURE__ */ __name((seconds) => mixer()?.duckMusic(seconds), "duck"),
+    positionOf,
+    every(ms, fn) {
+      const timer = setInterval(fn, ms);
+      return () => clearInterval(timer);
+    }
+  };
+}
+__name(browserVoiceDeps, "browserVoiceDeps");
+
 // core/network/NetworkSystem.ts
 var POSITION_EPSILON = 1e-3;
 var ROTATION_EPSILON = 5e-4;
@@ -211,9 +840,14 @@ var _NetworkSystem = class _NetworkSystem {
     this.listeners = /* @__PURE__ */ new Map();
     this.handles = /* @__PURE__ */ new Map();
     this.spawnedAvatar = false;
+    /** Voice chat, once connected with it on. */
+    this.voice = null;
   }
-  /** Join the shared world. Call after hydrating, so scene objects exist. */
-  connect(world, transport) {
+  /**
+   * Join the shared world. Call after hydrating, so scene objects exist.
+   * `voice: true` adds voice chat; the room still decides whether it's offered.
+   */
+  connect(world, transport, options = {}) {
     this.world = world;
     this.transport = transport;
     world.setNetwork(this);
@@ -226,7 +860,14 @@ var _NetworkSystem = class _NetworkSystem {
       for (const fn of this.listeners.get(name) ?? []) fn(payload, from);
     });
     transport.onCorrect((id, pose) => this.corrected(id, pose));
+    transport.onSound((sound) => this.heardSound(sound));
     transport.onClose(() => this.disconnected());
+    if (options.voice) {
+      this.voice = new VoiceChat(
+        transport,
+        options.voice === true ? browserVoiceDeps(world, (id) => this.positionOf(id)) : options.voice
+      );
+    }
     this.registerScene();
     this.spawnAvatar();
   }
@@ -270,11 +911,12 @@ var _NetworkSystem = class _NetworkSystem {
       }
     });
   }
-  track(id, entityId, owner, view2) {
+  track(id, entityId, owner, view2, prefab = "") {
     const entry = {
       id,
       entityId,
       owner,
+      prefab,
       buffer: new SnapshotBuffer(),
       sentAt: 0,
       sent: null,
@@ -307,7 +949,7 @@ var _NetworkSystem = class _NetworkSystem {
       this.entityChanged(view2);
       return;
     }
-    const entry = this.track(view2.id, null, view2.owner, view2);
+    const entry = this.track(view2.id, null, view2.owner, view2, view2.prefab);
     if (!view2.prefab || !this.world) return;
     euler.setFromQuaternion(quat.set(view2.qx, view2.qy, view2.qz, view2.qw));
     void spawnPrefab(this.world, view2.prefab, {
@@ -364,7 +1006,23 @@ var _NetworkSystem = class _NetworkSystem {
     if (transform) applyPose(transform, pose, true);
     entry.sent = pose;
   }
+  heardSound(sound) {
+    const { id, volume, x, y, z } = sound;
+    const placed = x !== void 0 && y !== void 0 && z !== void 0;
+    this.world?.getAudioSystem()?.playSlot(id, { volume, position: placed ? { x, y, z } : void 0 });
+  }
+  /** Where a player's character is: the first thing they spawned, which is their avatar. */
+  positionOf(peerId) {
+    for (const entry of this.tracked.values()) {
+      if (entry.owner !== peerId || !entry.prefab || entry.entityId === null) continue;
+      const position = this.world?.getComponent(entry.entityId, TransformComponent)?.position;
+      return position ? { x: position.x, y: position.y, z: position.z } : null;
+    }
+    return null;
+  }
   disconnected() {
+    this.voice?.dispose();
+    this.voice = null;
     this.transport = null;
     this.world?.setNetwork(null);
   }
@@ -408,6 +1066,8 @@ var _NetworkSystem = class _NetworkSystem {
     }
   }
   dispose() {
+    this.voice?.dispose();
+    this.voice = null;
     this.transport?.leave();
     this.transport = null;
     this.world?.setNetwork(null);
@@ -454,7 +1114,22 @@ var _NetworkSystem = class _NetworkSystem {
       get players() {
         return self.transport?.players ?? [];
       },
+      get voice() {
+        return self.voice;
+      },
       send: /* @__PURE__ */ __name((name, payload) => self.transport?.send(name, payload ?? null), "send"),
+      playSlot: /* @__PURE__ */ __name((id, options = {}) => {
+        const played = self.world?.getAudioSystem()?.playSlot(id, options) ?? false;
+        if (played) {
+          const { volume, position } = options;
+          self.transport?.sendSound({
+            id,
+            ...volume === void 0 ? {} : { volume },
+            ...position ? { x: position.x, y: position.y, z: position.z } : {}
+          });
+        }
+        return played;
+      }, "playSlot"),
       onMessage: /* @__PURE__ */ __name((name, fn) => {
         const set = self.listeners.get(name) ?? /* @__PURE__ */ new Set();
         self.listeners.set(name, set);
@@ -488,6 +1163,6 @@ var _NetworkSystem = class _NetworkSystem {
 __name(_NetworkSystem, "NetworkSystem");
 var NetworkSystem = _NetworkSystem;
 
-export { ColyseusTransport, NetworkSystem, SnapshotBuffer, withLatency };
+export { ColyseusTransport, NetworkSystem, SnapshotBuffer, VoiceChat, browserVoiceDeps, withLatency };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map