@relu-interactives/spatial-ecs 0.9.0 → 0.11.0

package/dist/network/index.d.cts

@@ -1,5 +1,5 @@
-import { y as NetworkTransport, z as NetEntityView, A as NetPose, B as EcsSystem, F as NetworkService, W as World, G as EntityId, H as NetworkHandle } from '../System-8D-XBDKZ.cjs';
-export { J as NetSpawnOptions } from '../System-8D-XBDKZ.cjs';
+import { y as NetworkTransport, z as NetEntityView, A as NetPose, B as NetSound, F as VoiceFromRoom, G as VoiceToRoom, H as VoiceHandle, J as VoicePeer, K as EcsSystem, L as NetworkService, W as World, M as EntityId, O as NetworkHandle } from '../System-BldSHxZV.cjs';
+export { Q as NetSpawnOptions, R as VoiceSignal } from '../System-BldSHxZV.cjs';
 import 'three';
 import '@dimforge/rapier3d-compat';
 import '../animation/index.cjs';
@@ -25,6 +25,8 @@ declare class ColyseusTransport implements NetworkTransport {
     onPlayerLeave(cb: (id: string) => void): void;
     onMessage(cb: (name: string, payload: unknown, from: string) => void): void;
     onCorrect(cb: (id: string, pose: NetPose) => void): void;
+    onSound(cb: (sound: NetSound, from: string) => void): void;
+    onVoice(cb: (message: VoiceFromRoom) => void): void;
     onClose(cb: () => void): void;
     registerScene(entities: Parameters<NetworkTransport["registerScene"]>[0]): void;
     spawn(request: Parameters<NetworkTransport["spawn"]>[0]): void;
@@ -32,6 +34,8 @@ declare class ColyseusTransport implements NetworkTransport {
     sendPose(id: string, pose: NetPose): void;
     setProp(id: string, key: string, json: string): void;
     send(name: string, payload: unknown): void;
+    sendSound(sound: NetSound): void;
+    sendVoice(message: VoiceToRoom): void;
     leave(): void;
 }
 
@@ -41,6 +45,110 @@ declare class ColyseusTransport implements NetworkTransport {
  */
 declare function withLatency(transport: NetworkTransport, ms: number): NetworkTransport;
 
+interface VoiceMeter {
+    level(): number;
+    close(): void;
+}
+/** One person's voice coming out of the speakers. */
+interface RemoteVoice {
+    setVolume(volume: number): void;
+    /** Where they are, or `null` to hear them everywhere. */
+    setPosition(position: {
+        x: number;
+        y: number;
+        z: number;
+    } | null): void;
+    stop(): void;
+}
+/** Everything voice needs from a browser, so the rest runs under test with fakes. */
+interface VoiceDeps {
+    /** Whether this page can do voice at all: a mic needs https. */
+    supported(): boolean;
+    createConnection(config: RTCConfiguration): RTCPeerConnection;
+    getMic(constraints: MediaStreamConstraints): Promise<MediaStream>;
+    /** The mic is being taken or let go. iOS needs a different audio session while it's held. */
+    setCapture(on: boolean): void;
+    analyse(source: MediaStream | MediaStreamTrack): VoiceMeter | null;
+    playRemote(track: MediaStreamTrack): RemoteVoice;
+    /** Dip the music for this long. Called again while someone keeps talking. */
+    duck(seconds: number): void;
+    /** Where this player's character is, when they have one. */
+    positionOf(peerId: string): {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    /** Run `fn` on a timer, and return how to stop it. */
+    every(ms: number, fn: () => void): () => void;
+}
+/**
+ * Voice chat between the players in a room: a direct connection to each other
+ * player, so the game server never carries audio, only the messages that set
+ * those connections up. Nothing is captured until the player turns it on, and
+ * only others who turned it on can hear them. Direct connections cost everyone
+ * upload per person, so rooms stop at the size the server says (8 by default).
+ */
+declare class VoiceChat implements VoiceHandle {
+    private readonly transport;
+    private readonly deps;
+    available: boolean;
+    state: VoiceHandle["state"];
+    micMuted: boolean;
+    talking: boolean;
+    error: string;
+    /** Hear each voice from its character, when there is one. Off, everyone's in your ear. */
+    positional: boolean;
+    private readonly peersById;
+    private readonly listeners;
+    private config;
+    private track;
+    private meter;
+    private level;
+    private goodMs;
+    private stopTimers;
+    private disposed;
+    constructor(transport: Pick<NetworkTransport, "sendVoice" | "onVoice">, deps: VoiceDeps);
+    get peers(): VoicePeer[];
+    onChange(listener: () => void): () => void;
+    private changed;
+    /** Turn voice on. Call from a tap or key: that's what lets the browser ask for the mic. */
+    enable(): Promise<boolean>;
+    private acquire;
+    private release;
+    /** The mic stopped by itself: the phone took it for a call, or the device went away. */
+    private lost;
+    /** Turn voice off. The mic stops at once. */
+    disable(): void;
+    private shutDown;
+    /** Mute or unmute this player's mic. Everyone in voice sees it. */
+    setMicMuted(muted: boolean): Promise<void>;
+    /** Stop hearing someone. They aren't told. */
+    setPeerMuted(id: string, muted: boolean): void;
+    setPeerVolume(id: string, volume: number): void;
+    private fromRoom;
+    private addPeer;
+    private signal;
+    private hear;
+    private connectionChanged;
+    private call;
+    private offer;
+    private onSignal;
+    private sendMic;
+    private sendMicToAll;
+    private applyBitrate;
+    private setLevel;
+    /** Someone came or went: the rate each connection gets changes with it. */
+    private retune;
+    private closePeer;
+    private startTimers;
+    /** Who's talking, where they are, and the music under them. */
+    private poll;
+    /** Step quality to what the connections can carry. */
+    private tick;
+    /** The room is going: stop everything. There's no one left to tell. */
+    dispose(): void;
+}
+
 /**
  * Keeps a world in step with a shared room: spawns what others spawned, sends
  * what this client owns, and plays back what it doesn't. Add it to
@@ -58,9 +166,16 @@ declare class NetworkSystem implements EcsSystem, NetworkService {
     private readonly listeners;
     private readonly handles;
     private spawnedAvatar;
+    /** Voice chat, once connected with it on. */
+    voice: VoiceChat | null;
     constructor(now?: () => number);
-    /** Join the shared world. Call after hydrating, so scene objects exist. */
-    connect(world: World, transport: NetworkTransport): void;
+    /**
+     * 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: World, transport: NetworkTransport, options?: {
+        voice?: boolean | VoiceDeps;
+    }): void;
     /** Scene objects: every client hydrates the same scene, so their ids already match. */
     private registerScene;
     private spawnAvatar;
@@ -72,6 +187,9 @@ declare class NetworkSystem implements EcsSystem, NetworkService {
     private entityRemoved;
     private applyProps;
     private corrected;
+    private heardSound;
+    /** Where a player's character is: the first thing they spawned, which is their avatar. */
+    private positionOf;
     private disconnected;
     /** Call a Behaviour hook: on one entity's scripts, or every script. */
     private dispatch;
@@ -95,4 +213,7 @@ declare class SnapshotBuffer {
     sample(at: number): NetPose | null;
 }
 
-export { ColyseusTransport, NetEntityView, NetPose, NetworkHandle, NetworkService, NetworkSystem, NetworkTransport, SnapshotBuffer, withLatency };
+/** Voice on a real page. */
+declare function browserVoiceDeps(world: World, positionOf: VoiceDeps["positionOf"]): VoiceDeps;
+
+export { ColyseusTransport, NetEntityView, NetPose, NetSound, NetworkHandle, NetworkService, NetworkSystem, NetworkTransport, SnapshotBuffer, VoiceChat, type VoiceDeps, VoiceFromRoom, VoiceHandle, VoicePeer, VoiceToRoom, browserVoiceDeps, withLatency };

package/dist/network/index.d.ts

@@ -1,5 +1,5 @@
-import { G as NetworkTransport, H as NetEntityView, J as NetPose, K as EcsSystem, L as NetworkService, W as World, M as EntityId, O as NetworkHandle } from '../System-DPMAW30g.js';
-export { Q as NetSpawnOptions } from '../System-DPMAW30g.js';
+import { G as NetworkTransport, H as NetEntityView, J as NetPose, K as NetSound, L as VoiceFromRoom, M as VoiceToRoom, O as VoiceHandle, Q as VoicePeer, S as EcsSystem, U as NetworkService, W as World, X as EntityId, Y as NetworkHandle } from '../System-CADhPyQs.js';
+export { Z as NetSpawnOptions, _ as VoiceSignal } from '../System-CADhPyQs.js';
 import 'three';
 import '@dimforge/rapier3d-compat';
 import '../animation/index.js';
@@ -25,6 +25,8 @@ declare class ColyseusTransport implements NetworkTransport {
     onPlayerLeave(cb: (id: string) => void): void;
     onMessage(cb: (name: string, payload: unknown, from: string) => void): void;
     onCorrect(cb: (id: string, pose: NetPose) => void): void;
+    onSound(cb: (sound: NetSound, from: string) => void): void;
+    onVoice(cb: (message: VoiceFromRoom) => void): void;
     onClose(cb: () => void): void;
     registerScene(entities: Parameters<NetworkTransport["registerScene"]>[0]): void;
     spawn(request: Parameters<NetworkTransport["spawn"]>[0]): void;
@@ -32,6 +34,8 @@ declare class ColyseusTransport implements NetworkTransport {
     sendPose(id: string, pose: NetPose): void;
     setProp(id: string, key: string, json: string): void;
     send(name: string, payload: unknown): void;
+    sendSound(sound: NetSound): void;
+    sendVoice(message: VoiceToRoom): void;
     leave(): void;
 }
 
@@ -41,6 +45,110 @@ declare class ColyseusTransport implements NetworkTransport {
  */
 declare function withLatency(transport: NetworkTransport, ms: number): NetworkTransport;
 
+interface VoiceMeter {
+    level(): number;
+    close(): void;
+}
+/** One person's voice coming out of the speakers. */
+interface RemoteVoice {
+    setVolume(volume: number): void;
+    /** Where they are, or `null` to hear them everywhere. */
+    setPosition(position: {
+        x: number;
+        y: number;
+        z: number;
+    } | null): void;
+    stop(): void;
+}
+/** Everything voice needs from a browser, so the rest runs under test with fakes. */
+interface VoiceDeps {
+    /** Whether this page can do voice at all: a mic needs https. */
+    supported(): boolean;
+    createConnection(config: RTCConfiguration): RTCPeerConnection;
+    getMic(constraints: MediaStreamConstraints): Promise<MediaStream>;
+    /** The mic is being taken or let go. iOS needs a different audio session while it's held. */
+    setCapture(on: boolean): void;
+    analyse(source: MediaStream | MediaStreamTrack): VoiceMeter | null;
+    playRemote(track: MediaStreamTrack): RemoteVoice;
+    /** Dip the music for this long. Called again while someone keeps talking. */
+    duck(seconds: number): void;
+    /** Where this player's character is, when they have one. */
+    positionOf(peerId: string): {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    /** Run `fn` on a timer, and return how to stop it. */
+    every(ms: number, fn: () => void): () => void;
+}
+/**
+ * Voice chat between the players in a room: a direct connection to each other
+ * player, so the game server never carries audio, only the messages that set
+ * those connections up. Nothing is captured until the player turns it on, and
+ * only others who turned it on can hear them. Direct connections cost everyone
+ * upload per person, so rooms stop at the size the server says (8 by default).
+ */
+declare class VoiceChat implements VoiceHandle {
+    private readonly transport;
+    private readonly deps;
+    available: boolean;
+    state: VoiceHandle["state"];
+    micMuted: boolean;
+    talking: boolean;
+    error: string;
+    /** Hear each voice from its character, when there is one. Off, everyone's in your ear. */
+    positional: boolean;
+    private readonly peersById;
+    private readonly listeners;
+    private config;
+    private track;
+    private meter;
+    private level;
+    private goodMs;
+    private stopTimers;
+    private disposed;
+    constructor(transport: Pick<NetworkTransport, "sendVoice" | "onVoice">, deps: VoiceDeps);
+    get peers(): VoicePeer[];
+    onChange(listener: () => void): () => void;
+    private changed;
+    /** Turn voice on. Call from a tap or key: that's what lets the browser ask for the mic. */
+    enable(): Promise<boolean>;
+    private acquire;
+    private release;
+    /** The mic stopped by itself: the phone took it for a call, or the device went away. */
+    private lost;
+    /** Turn voice off. The mic stops at once. */
+    disable(): void;
+    private shutDown;
+    /** Mute or unmute this player's mic. Everyone in voice sees it. */
+    setMicMuted(muted: boolean): Promise<void>;
+    /** Stop hearing someone. They aren't told. */
+    setPeerMuted(id: string, muted: boolean): void;
+    setPeerVolume(id: string, volume: number): void;
+    private fromRoom;
+    private addPeer;
+    private signal;
+    private hear;
+    private connectionChanged;
+    private call;
+    private offer;
+    private onSignal;
+    private sendMic;
+    private sendMicToAll;
+    private applyBitrate;
+    private setLevel;
+    /** Someone came or went: the rate each connection gets changes with it. */
+    private retune;
+    private closePeer;
+    private startTimers;
+    /** Who's talking, where they are, and the music under them. */
+    private poll;
+    /** Step quality to what the connections can carry. */
+    private tick;
+    /** The room is going: stop everything. There's no one left to tell. */
+    dispose(): void;
+}
+
 /**
  * Keeps a world in step with a shared room: spawns what others spawned, sends
  * what this client owns, and plays back what it doesn't. Add it to
@@ -58,9 +166,16 @@ declare class NetworkSystem implements EcsSystem, NetworkService {
     private readonly listeners;
     private readonly handles;
     private spawnedAvatar;
+    /** Voice chat, once connected with it on. */
+    voice: VoiceChat | null;
     constructor(now?: () => number);
-    /** Join the shared world. Call after hydrating, so scene objects exist. */
-    connect(world: World, transport: NetworkTransport): void;
+    /**
+     * 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: World, transport: NetworkTransport, options?: {
+        voice?: boolean | VoiceDeps;
+    }): void;
     /** Scene objects: every client hydrates the same scene, so their ids already match. */
     private registerScene;
     private spawnAvatar;
@@ -72,6 +187,9 @@ declare class NetworkSystem implements EcsSystem, NetworkService {
     private entityRemoved;
     private applyProps;
     private corrected;
+    private heardSound;
+    /** Where a player's character is: the first thing they spawned, which is their avatar. */
+    private positionOf;
     private disconnected;
     /** Call a Behaviour hook: on one entity's scripts, or every script. */
     private dispatch;
@@ -95,4 +213,7 @@ declare class SnapshotBuffer {
     sample(at: number): NetPose | null;
 }
 
-export { ColyseusTransport, NetEntityView, NetPose, NetworkHandle, NetworkService, NetworkSystem, NetworkTransport, SnapshotBuffer, withLatency };
+/** Voice on a real page. */
+declare function browserVoiceDeps(world: World, positionOf: VoiceDeps["positionOf"]): VoiceDeps;
+
+export { ColyseusTransport, NetEntityView, NetPose, NetSound, NetworkHandle, NetworkService, NetworkSystem, NetworkTransport, SnapshotBuffer, VoiceChat, type VoiceDeps, VoiceFromRoom, VoiceHandle, VoicePeer, VoiceToRoom, browserVoiceDeps, withLatency };