@relu-interactives/spatial-ecs 0.9.0 → 0.10.0

package/dist/{System-8D-XBDKZ.d.cts → System-BldSHxZV.d.cts}

@@ -127,6 +127,106 @@ declare class SlotChooser {
     choose(id: string, slot: SoundSlot, now: number): SoundTake | null;
 }
 
+/**
+ * The volume groups every sound plays through: each sound's output goes to its
+ * bus instead of straight to the listener, so a game can turn music down
+ * without touching a single sound, and music dips while a voice plays.
+ */
+declare class AudioMixer {
+    readonly listener: THREE.AudioListener;
+    private readonly buses;
+    private readonly volumes;
+    private readonly routed;
+    constructor(listener: THREE.AudioListener);
+    /** The node a sound connects to for this bus. */
+    input(bus: AudioBus): GainNode;
+    /** Send a three.js sound through a bus. Does nothing when it's already there. */
+    route(sound: THREE.Audio<GainNode> | THREE.PositionalAudio, bus: AudioBus): void;
+    setVolume(bus: AudioBus, volume: number): void;
+    getVolume(bus: AudioBus): number;
+    /** Dip the music for `seconds`, then bring it back. A later duck replaces this one. */
+    duckMusic(seconds: number): void;
+    dispose(): void;
+}
+
+/** Options for {@link AudioSystem.playSlot}. */
+type PlaySlotOptions = {
+    /** Multiplies the slot's volume. */
+    volume?: number;
+    /** Play from this point in the world instead of everywhere. */
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+/**
+ * Reconciles `AudioComponent` state with the underlying THREE.js audio objects
+ * each frame.
+ *
+ * **Playback** — drives `play()`, `pause()`, and `stop()` on the THREE.js
+ * audio node based on the `isPlaying` / `isPaused` flags set by
+ * `AudioComponent.play()`, `.pause()`, and `.stop()`.
+ *
+ * **Option sync** — detects changes to `loop`, `pitch`, `volume`,
+ * `refDistance`, `distanceModel`, and `rolloffFactor` and applies them live.
+ * Changes take effect on the next frame, so scripts and inspector edits during
+ * runtime are reflected without reloading the scene.
+ *
+ * **Mixing** — every sound plays through a bus (`sfx`, `voice`, `music`) with
+ * its own volume, and music dips while a voice plays.
+ *
+ * **Sound banks** — {@link loadSoundBank} and {@link playSlot} play named
+ * sounds from a `.soundbank.json` asset, as a random take.
+ *
+ * Only active in **preview** mode (`isEditor: true` makes every update a
+ * no-op so the editor is unaffected).
+ *
+ * @category Systems
+ */
+declare class AudioSystem implements EcsSystem {
+    private readonly isEditor;
+    /** THREE.js `isPlaying` state captured at the end of the previous frame. */
+    private readonly prevPlayingState;
+    /** Snapshot of options applied in the previous frame, for change detection. */
+    private readonly prevOptions;
+    /** Tracks entities that were stopped due to invisibility. */
+    private readonly stoppedDueToInvisibility;
+    private world;
+    private mixer;
+    private readonly slots;
+    private readonly buffers;
+    private readonly chooser;
+    private voice;
+    constructor({ isEditor }?: {
+        isEditor?: boolean;
+    });
+    /** Scripts can load a bank in `init`, before this system's first update. */
+    attachWorld(world: World): void;
+    /** The mixer, made with the listener on first use. */
+    getMixer(): AudioMixer | null;
+    /** Set a bus's volume (`0` silent, `1` as mixed). */
+    setBusVolume(bus: AudioBus, volume: number): void;
+    getBusVolume(bus: AudioBus): number;
+    /**
+     * Fetch a `.soundbank.json` and decode its recordings. Its slots add to any
+     * loaded before, and a slot id used twice takes the later one.
+     * @param source an asset path, or a script's `AssetInput` field
+     */
+    loadSoundBank(source: string | {
+        path: string;
+    }): Promise<void>;
+    /**
+     * Play a named sound from a loaded bank. Returns whether it sounded: a slot's
+     * chance, cooldown and priority can each keep it quiet, and that's normal.
+     */
+    playSlot(id: string, options?: PlaySlotOptions): boolean;
+    update(world: World, _deltaTime: number): void;
+    /** Apply any changed options from the component to the THREE.js audio node. */
+    private _syncOptions;
+    dispose(_world: World): void;
+}
+
 /** Skybox rendering modes. `none` disables skybox rendering entirely. */
 type EnvironmentSkyboxType = "gradient" | "color" | "image" | "none";
 /** Gradient distribution applied when {@link EnvironmentSkyboxState.type} is `"gradient"`. */
@@ -687,6 +787,67 @@ type NetEntityView = {
     props: Record<string, string>;
 };
 type NetPose = Pick<NetEntityView, "x" | "y" | "z" | "qx" | "qy" | "qz" | "qw">;
+/** A sound-bank slot one player plays for everyone. */
+type NetSound = {
+    id: string;
+    volume?: number;
+    x?: number;
+    y?: number;
+    z?: number;
+};
+/** What sets up a direct voice connection between two players. */
+type VoiceSignal = {
+    kind: "offer" | "answer";
+    sdp: string;
+} | {
+    kind: "ice";
+    candidate: RTCIceCandidateInit;
+};
+type VoiceToRoom = {
+    t: "hello";
+} | {
+    t: "join";
+} | {
+    t: "leave";
+} | {
+    t: "mic";
+    on: boolean;
+} | {
+    t: "signal";
+    to: string;
+    signal: VoiceSignal;
+};
+type VoiceFromRoom = {
+    t: "caps";
+    available: boolean;
+    maxPeers: number;
+} | {
+    t: "welcome";
+    peers: {
+        id: string;
+        mic: boolean;
+    }[];
+    iceServers: RTCIceServer[];
+    /** Send through the relay only, so players never see each other's addresses. */
+    relayOnly: boolean;
+} | {
+    t: "refused";
+    reason: "off" | "full";
+} | {
+    t: "joined";
+    id: string;
+} | {
+    t: "left";
+    id: string;
+} | {
+    t: "mic";
+    id: string;
+    on: boolean;
+} | {
+    t: "signal";
+    from: string;
+    signal: VoiceSignal;
+};
 /** What a shared-world connection must do. `ColyseusTransport` is the real one. */
 interface NetworkTransport {
     readonly sessionId: string;
@@ -702,6 +863,9 @@ interface NetworkTransport {
     onMessage(cb: (name: string, payload: unknown, from: string) => void): void;
     /** The server overruled the owner's pose. */
     onCorrect(cb: (id: string, pose: NetPose) => void): void;
+    /** Another player played a sound for everyone. */
+    onSound(cb: (sound: NetSound, from: string) => void): void;
+    onVoice(cb: (message: VoiceFromRoom) => void): void;
     onClose(cb: () => void): void;
     /** Tell the room about the scene's shared objects; the first client's copy wins. */
     registerScene(entities: (NetPose & {
@@ -716,6 +880,8 @@ interface 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;
 }
 /** Options for {@link NetworkHandle.spawn}. */
@@ -733,6 +899,42 @@ type NetSpawnOptions = {
     };
     props?: Record<string, NetValue>;
 };
+/** Someone else in voice chat. */
+interface VoicePeer {
+    readonly id: string;
+    /** The direct connection is up. */
+    readonly connected: boolean;
+    readonly talking: boolean;
+    /** They haven't muted their own mic. */
+    readonly micOn: boolean;
+    /** This player muted them. */
+    readonly muted: boolean;
+    readonly volume: number;
+}
+/** Voice chat: `this.network.voice`, `null` when the project doesn't have it on. */
+interface VoiceHandle {
+    /** The room offers voice and this page can use a mic. */
+    readonly available: boolean;
+    readonly state: "off" | "connecting" | "on";
+    readonly micMuted: boolean;
+    /** This player is talking right now. */
+    readonly talking: boolean;
+    /** Why the last attempt failed, in words for the player. */
+    readonly error: string;
+    readonly peers: VoicePeer[];
+    /** Hear each voice from its character, when there is one. On by default. */
+    positional: boolean;
+    /** Turn voice on. Call from a tap or key: that's what lets the browser ask for the mic. */
+    enable(): Promise<boolean>;
+    disable(): void;
+    setMicMuted(muted: boolean): Promise<void>;
+    /** Stop hearing someone. They aren't told. */
+    setPeerMuted(id: string, muted: boolean): void;
+    /** 0 to 2. */
+    setPeerVolume(id: string, volume: number): void;
+    /** Something above changed. Returns the way to stop listening. */
+    onChange(listener: () => void): () => void;
+}
 /** A Behaviour's view of the shared world: `this.network`, `null` in a single-player run. */
 interface NetworkHandle {
     readonly connected: boolean;
@@ -744,10 +946,17 @@ interface NetworkHandle {
     readonly isOwner: boolean;
     /** Everyone in the room, by session id. */
     readonly players: string[];
+    /** Voice chat, when the project has it on. */
+    readonly voice: VoiceHandle | null;
     /** Send to the room. Others hear it in `onMessage`, unless a server hook keeps it. */
     send(name: string, payload?: unknown): void;
     /** Listen for a message. Returns the way to stop. */
     onMessage(name: string, handler: (payload: unknown, from: string) => void): () => void;
+    /**
+     * Play a sound-bank slot here and for everyone in the room. Returns whether it
+     * sounded: a slot's chance and cooldown can keep it quiet, and then no one hears it.
+     */
+    playSlot(id: string, options?: PlaySlotOptions): boolean;
     /** Spawn a prefab everyone sees, owned by this client. */
     spawn(prefab: string | {
         path: string;
@@ -1402,84 +1611,6 @@ declare class TransformSyncSystem implements EcsSystem {
     update(world: World): void;
 }
 
-/** Options for {@link AudioSystem.playSlot}. */
-type PlaySlotOptions = {
-    /** Multiplies the slot's volume. */
-    volume?: number;
-    /** Play from this point in the world instead of everywhere. */
-    position?: {
-        x: number;
-        y: number;
-        z: number;
-    };
-};
-/**
- * Reconciles `AudioComponent` state with the underlying THREE.js audio objects
- * each frame.
- *
- * **Playback** — drives `play()`, `pause()`, and `stop()` on the THREE.js
- * audio node based on the `isPlaying` / `isPaused` flags set by
- * `AudioComponent.play()`, `.pause()`, and `.stop()`.
- *
- * **Option sync** — detects changes to `loop`, `pitch`, `volume`,
- * `refDistance`, `distanceModel`, and `rolloffFactor` and applies them live.
- * Changes take effect on the next frame, so scripts and inspector edits during
- * runtime are reflected without reloading the scene.
- *
- * **Mixing** — every sound plays through a bus (`sfx`, `voice`, `music`) with
- * its own volume, and music dips while a voice plays.
- *
- * **Sound banks** — {@link loadSoundBank} and {@link playSlot} play named
- * sounds from a `.soundbank.json` asset, as a random take.
- *
- * Only active in **preview** mode (`isEditor: true` makes every update a
- * no-op so the editor is unaffected).
- *
- * @category Systems
- */
-declare class AudioSystem implements EcsSystem {
-    private readonly isEditor;
-    /** THREE.js `isPlaying` state captured at the end of the previous frame. */
-    private readonly prevPlayingState;
-    /** Snapshot of options applied in the previous frame, for change detection. */
-    private readonly prevOptions;
-    /** Tracks entities that were stopped due to invisibility. */
-    private readonly stoppedDueToInvisibility;
-    private world;
-    private mixer;
-    private readonly slots;
-    private readonly buffers;
-    private readonly chooser;
-    private voice;
-    constructor({ isEditor }?: {
-        isEditor?: boolean;
-    });
-    /** Scripts can load a bank in `init`, before this system's first update. */
-    attachWorld(world: World): void;
-    /** The mixer, made with the listener on first use. */
-    private getMixer;
-    /** Set a bus's volume (`0` silent, `1` as mixed). */
-    setBusVolume(bus: AudioBus, volume: number): void;
-    getBusVolume(bus: AudioBus): number;
-    /**
-     * Fetch a `.soundbank.json` and decode its recordings. Its slots add to any
-     * loaded before, and a slot id used twice takes the later one.
-     * @param source an asset path, or a script's `AssetInput` field
-     */
-    loadSoundBank(source: string | {
-        path: string;
-    }): Promise<void>;
-    /**
-     * Play a named sound from a loaded bank. Returns whether it sounded: a slot's
-     * chance, cooldown and priority can each keep it quiet, and that's normal.
-     */
-    playSlot(id: string, options?: PlaySlotOptions): boolean;
-    update(world: World, _deltaTime: number): void;
-    /** Apply any changed options from the component to the THREE.js audio node. */
-    private _syncOptions;
-    dispose(_world: World): void;
-}
-
 /**
  * Runs each {@link IKComponent}'s chains after the animation: hands and feet
  * reach their target entities. Bones the animation doesn't drive would keep
@@ -1490,8 +1621,10 @@ declare class AudioSystem implements EcsSystem {
  */
 declare class IKSystem implements EcsSystem {
     private readonly runtimes;
-    private readonly reach;
-    /** How far a limb's end stayed from its target last frame, in metres (0 = reached). */
+    /**
+     * How far a limb's end stayed from its target last frame, in metres
+     * (0 = reached), or null if the limb's chain didn't run.
+     */
     getReachError(entityId: EntityId, limb: IKLimb): number | null;
     private restore;
     update(world: World): void;
@@ -1880,4 +2013,4 @@ interface EcsSystem {
     dispose?(world: World): void;
 }
 
-export { type AssetInput as $, type NetPose as A, type EcsSystem as B, Component as C, DEFAULT_ENVIRONMENT_LIGHTING as D, Environment as E, type NetworkService as F, type EntityId as G, type NetworkHandle as H, type IKChain as I, type NetSpawnOptions as J, type WorldEntityView$1 as K, type SpawnPrefabOptions as L, type PlaySlotOptions as M, type NetValue as N, type ComponentClass as O, ParentId as P, type ParentLookup as Q, type RenderBackend as R, type SpawnPrefabSource as S, TransformComponent as T, type EcsEntityKind as U, type Vec3$1 as V, World as W, ObjectManagementSystem as X, type SubtreeSnapshot as Y, type ExternalRefWarning as Z, type AudioBus as _, DEFAULT_ENVIRONMENT_STATE as a, AudioSystem as a0, type CheckboxInput as a1, type ChromaKeyOptions as a2, type ColorInput as a3, type ComponentFactory as a4, type ComponentInput as a5, type ComponentKind as a6, type DropdownInput as a7, type DropdownOption as a8, type EcsComponentFactoryKind as a9, SlotChooser as aA, type SoundBankAsset as aB, type SoundSlot as aC, type SoundTake as aD, type TextInput as aE, type ToggleInput as aF, TransformSyncSystem as aG, type Vec3 as aH, type Vector2Input as aI, type Vector3Input as aJ, clearPrefabCache as aK, despawnPrefab as aL, findModelBone as aM, listModelBones as aN, loadPrefab as aO, parsePrefabAsset as aP, prefabFileVersionFor as aQ, remapSnapshotEntityIds as aR, setPrefabAssetUrlResolver as aS, soundBankFiles as aT, spawnPrefab as aU, type AnyComponent as aV, DEBUG_CHANGE_IGNORED_SYSTEMS as aW, type WorldHistorySnapshot as aX, cloneHistoryValue as aY, normalizeDebugValue as aZ, type EcsEntityEditorKind as aa, type EcsRenderer as ab, type EntityInput as ac, type FloatInput as ad, IKSystem as ae, InputSystem as af, type IntersectionResult as ag, type KeyboardKey as ah, KeyboardKeys as ai, type ModelBoneInfo as aj, type MouseButton as ak, PREFAB_FILE_VERSION as al, PREFAB_FILE_VERSION_NESTED as am, type PostprocessingBuildContext as an, type PostprocessingPipeline as ao, type PrefabAsset as ap, type RemapSnapshotOptions as aq, RenderSystem as ar, type RendererKind as as, type ScriptErrorEvent as at, type ScriptErrorListener as au, type ScriptErrorPhase as av, type ScriptErrorReport as aw, type ScriptErrorSource as ax, type SelectionListener as ay, type SliderInput as az, DEFAULT_POSTPROCESSING_STATE as b, type EnvironmentFogState as c, type EnvironmentFogType as d, type EnvironmentGradientEffect as e, type EnvironmentLightingState as f, type EnvironmentSkyboxImageProjection as g, type EnvironmentSkyboxState as h, type EnvironmentSkyboxType as i, type EnvironmentState as j, type EnvironmentToneMapping as k, IKComponent as l, type IKLimb as m, type IKOptions as n, NetworkIdentityComponent as o, NetworkSpawnerComponent as p, NetworkTransformComponent as q, type NetworkTransformOptions as r, NetworkedPropsComponent as s, Postprocessing as t, type PostprocessingState as u, type TransformData as v, normalizeEnvironmentLighting as w, normalizeIKChain as x, type NetworkTransport as y, type NetEntityView as z };
+export { type RenderBackend as $, type NetPose as A, type NetSound as B, Component as C, DEFAULT_ENVIRONMENT_LIGHTING as D, Environment as E, type VoiceFromRoom as F, type VoiceToRoom as G, type VoiceHandle as H, type IKChain as I, type VoicePeer as J, type EcsSystem as K, type NetworkService as L, type EntityId as M, type NetValue as N, type NetworkHandle as O, ParentId as P, type NetSpawnOptions as Q, type VoiceSignal as R, type WorldEntityView$1 as S, TransformComponent as T, type SpawnPrefabSource as U, type Vec3$1 as V, World as W, type SpawnPrefabOptions as X, type PlaySlotOptions as Y, type ComponentClass as Z, type ParentLookup as _, DEFAULT_ENVIRONMENT_STATE as a, spawnPrefab as a$, type EcsEntityKind as a0, ObjectManagementSystem as a1, type SubtreeSnapshot as a2, type ExternalRefWarning as a3, type AssetInput as a4, type AudioBus as a5, AudioMixer as a6, AudioSystem as a7, type CheckboxInput as a8, type ChromaKeyOptions as a9, type ScriptErrorEvent as aA, type ScriptErrorListener as aB, type ScriptErrorPhase as aC, type ScriptErrorReport as aD, type ScriptErrorSource as aE, type SelectionListener as aF, type SliderInput as aG, SlotChooser as aH, type SoundBankAsset as aI, type SoundSlot as aJ, type SoundTake as aK, type TextInput as aL, type ToggleInput as aM, TransformSyncSystem as aN, type Vec3 as aO, type Vector2Input as aP, type Vector3Input as aQ, clearPrefabCache as aR, despawnPrefab as aS, findModelBone as aT, listModelBones as aU, loadPrefab as aV, parsePrefabAsset as aW, prefabFileVersionFor as aX, remapSnapshotEntityIds as aY, setPrefabAssetUrlResolver as aZ, soundBankFiles as a_, type ColorInput as aa, type ComponentFactory as ab, type ComponentInput as ac, type ComponentKind as ad, type DropdownInput as ae, type DropdownOption as af, type EcsComponentFactoryKind as ag, type EcsEntityEditorKind as ah, type EcsRenderer as ai, type EntityInput as aj, type FloatInput as ak, IKSystem as al, InputSystem as am, type IntersectionResult as an, type KeyboardKey as ao, KeyboardKeys as ap, type ModelBoneInfo as aq, type MouseButton as ar, PREFAB_FILE_VERSION as as, PREFAB_FILE_VERSION_NESTED as at, type PostprocessingBuildContext as au, type PostprocessingPipeline as av, type PrefabAsset as aw, type RemapSnapshotOptions as ax, RenderSystem as ay, type RendererKind as az, DEFAULT_POSTPROCESSING_STATE as b, type AnyComponent as b0, DEBUG_CHANGE_IGNORED_SYSTEMS as b1, type WorldHistorySnapshot as b2, cloneHistoryValue as b3, normalizeDebugValue as b4, type EnvironmentFogState as c, type EnvironmentFogType as d, type EnvironmentGradientEffect as e, type EnvironmentLightingState as f, type EnvironmentSkyboxImageProjection as g, type EnvironmentSkyboxState as h, type EnvironmentSkyboxType as i, type EnvironmentState as j, type EnvironmentToneMapping as k, IKComponent as l, type IKLimb as m, type IKOptions as n, NetworkIdentityComponent as o, NetworkSpawnerComponent as p, NetworkTransformComponent as q, type NetworkTransformOptions as r, NetworkedPropsComponent as s, Postprocessing as t, type PostprocessingState as u, type TransformData as v, normalizeEnvironmentLighting as w, normalizeIKChain as x, type NetworkTransport as y, type NetEntityView as z };