narraleaf-react 0.22.0 → 0.23.0

package/dist/game/player/lib/AudioManager.d.ts

@@ -1,33 +1,119 @@
-import { Sound as SoundElement, SoundType } from "../../nlcore/elements/sound";
+import { Sound as SoundElement, SoundBusId } from "../../nlcore/elements/sound";
 import { SoundToken } from "@narraleaf/sound";
 import { FadeOptions } from "../../nlcore/elements/type";
 import { Awaitable } from "../../../util/data";
 import { GameState } from "../gameState";
 import { LogicAction } from "../../nlcore/action/logicAction";
+import { AudioBusState } from "../../nlcore/game/audioBus";
 export type AudioDataRaw = {
     isPlaying: boolean;
     position: number;
 };
 export type AudioManagerDataRaw = {
     sounds: [string, AudioDataRaw][];
-    groups: [SoundType, number][];
+    /**
+     * Bus volumes, keyed by bus id.
+     *
+     * The name is historical - these used to be the three fixed "groups". A save written before
+     * buses existed carries exactly `bgm`/`sound`/`voice`, which are still buses, so it restores
+     * unchanged.
+     */
+    groups: [string, number][];
 };
 export declare class AudioManager {
     private gameState;
+    /**
+     * How much of the backend's channel budget to ask for.
+     *
+     * `@narraleaf/sound` defaults to 128 *including* the master, and throws outright when a
+     * `createChannel` would cross it. Three buses never came close; a game that gives every member
+     * of a large voiced cast its own bus can, and the failure mode is a hard throw at boot. This is
+     * a per-channel `GainNode` and nothing else, so a generous ceiling costs effectively nothing.
+     */
+    private static readonly MaxChannels;
+    /**
+     * Time constant of the bus-volume ramp, in seconds. ~20ms: long enough to turn a step into a
+     * slew nobody hears, short enough that a slider still feels attached to the sound.
+     */
+    private static readonly BusRampTimeConstant;
+    /**
+     * When to pin the exact target after the ramp. `setTargetAtTime` approaches asymptotically and
+     * never lands, so five time constants in (within 0.7% - inaudible) the value is written
+     * outright. Without this a long drag would accumulate a drift the mixer's own bookkeeping does
+     * not have.
+     */
+    private static readonly BusRampSettle;
     private state;
     private channels;
-    private channelVolumes;
+    private busTree;
+    private busSubscription;
+    private unknownBuses;
     private globalVolume;
     private sound;
     private ready;
     private isReady;
     private isInitializing;
     constructor(gameState: GameState);
+    /**
+     * The volume of every bus, and the tree they are wired into.
+     *
+     * It lives on `Game`, not here: a bus volume is a player setting that exists before the audio
+     * context unlocks and outlives any one player mount. This manager is the thing that makes it
+     * audible, not the thing that remembers it.
+     */
+    private get mixer();
     /**
      * Must be called ONCE on the client side to prepare audio subsystem.
      * Doing it here avoids "AudioContext is not defined" on the server.
      */
     initialize(): void;
+    /**
+     * Build the host's declared bus tree into real channels, once.
+     *
+     * Walked front to back the tree hands every bus out after its parent, so a child always has a
+     * live parent channel to be created from - that is what nests the gain nodes, and cascading
+     * gain then falls out of the audio graph rather than out of any arithmetic here.
+     *
+     * Done once, at boot, and never re-shaped: `Channel.remove()` stops every token in its subtree,
+     * so re-parenting a bus while the game runs would cut the music off. Volumes stay live.
+     */
+    private realizeBusTree;
+    /**
+     * Write a bus's volume onto its gain node, ramping rather than stepping.
+     *
+     * `Channel.setVolume` assigns `gain.value` bare with no `cancelScheduledValues`, so a slider
+     * drag arrives as a staircase of discontinuities - the zipper. The backend exposes no ramping
+     * setter, only `getGainNode()`, so the ramp is driven from here.
+     *
+     * **Who owns the value.** `Channel.volume` remains authoritative bookkeeping and the
+     * `AudioParam` is authoritative for what is heard, and this method is the only writer of
+     * either, so the two can only disagree for the ~20ms a ramp is in flight. `channel.setVolume`
+     * is still called first and deliberately: it is what clamps to 0..1, what keeps
+     * `channel.getVolume()` truthful, and what `Channel.mute()`/`unmute()` re-read when they
+     * rewrite the gain themselves. Its bare write is then superseded in the same synchronous turn -
+     * `cancelScheduledValues` drops the implicit `setValueAtTime` that the assignment inserted at
+     * `currentTime`, and the ramp is scheduled from the value the parameter actually had. Nothing
+     * else in the engine touches a bus gain node, so there is no other automation to fight.
+     *
+     * Falls back to the plain assignment whenever the graph is not reachable - a backend without
+     * `getGainNode`, or a parameter without `setTargetAtTime`. Stepping is the behaviour that
+     * shipped; degrading to it is strictly no worse.
+     */
+    private applyBusVolume;
+    /**
+     * The value a bus's gain parameter has right now, or `null` when the graph cannot be reached.
+     */
+    private static readGain;
+    /**
+     * The channel a clip plays through.
+     *
+     * A bus id nothing declared is not fatal. Refusing to play would turn one typo in one clip's
+     * `type` into silence or a thrown action mid-scene; routing it to the always-seeded sfx bus
+     * keeps the game audible and says so once, per id, in the log. This is also where a bus name
+     * that {@link import("../../nlcore/game/audioBus").acceptsAudioBus} let through at story-build time is
+     * finally caught.
+     */
+    private channelFor;
     /**
      * The volume a clip started with no explicit target should reach.
      *
@@ -129,11 +215,67 @@ export declare class AudioManager {
      * as it did before.
      */
     preload(sound: SoundElement): Promise<void>;
+    /**
+     * Start a new game: stop everything and put the mixer back on the wire.
+     *
+     * The tree itself is **not** rebuilt - the channels are the same channels, because a bus is
+     * part of the game's declared shape, not part of its state. What is re-applied is every bus's
+     * current volume, read back off the mixer rather than off `SoundType`, which is what lets a
+     * host's own buses exist here at all.
+     *
+     * Note the seeded three are then immediately overwritten from the preferences, exactly as
+     * before; a bus the host declared keeps whatever volume the player left it at, because that is
+     * a setting and not something a new game should undo.
+     */
     reset(): void;
-    setGroupVolume(type: SoundType, volume: number): void;
+    /**
+     * Set **the player's** volume for a bus, 0..1, live. 1 means "leave the author's mix alone".
+     *
+     * Reaches sounds that are **already playing**: a bus is a gain node every clip beneath it is
+     * routed through, so nothing has to be found, stopped or restarted for the change to be heard.
+     * Setting a bus that has not been realized yet is fine - the value is kept and applied when the
+     * audio context unlocks.
+     *
+     * Equivalent to `game.audioBuses.setVolume(...)`, which is the surface a host should prefer:
+     * it exists before the player mounts.
+     */
+    setBusVolume(id: SoundBusId, volume: number): void;
+    /**
+     * The player's volume for a bus - what was last set, else 1. Not the author's declared mix
+     * (`game.audioBuses.getDeclaredVolume`) and not what is on the gain node
+     * (`getEffectiveVolume`).
+     */
+    getBusVolume(id: SoundBusId): number;
+    /**
+     * Every bus with its parent and both of its volumes, parents first. `volume` is the half a
+     * host persists.
+     */
+    getBuses(): AudioBusState[];
+    /**
+     * @deprecated Use {@link AudioManager.setBusVolume}. Kept because the three sound types are
+     * still bus ids and hosts call this with them.
+     */
+    setGroupVolume(type: SoundBusId, volume: number): void;
+    /**
+     * @deprecated Use {@link AudioManager.getBusVolume}.
+     */
+    getGroupVolume(type: SoundBusId): number;
     setGlobalVolume(volume: number): void;
     getGlobalVolume(): number;
-    getGroupVolume(type: SoundType): number;
     destroy(): void;
+    /**
+     * The three volume preferences are aliases onto the three seeded buses, and this is the alias.
+     *
+     * They stay the way a player's music/sfx/voice sliders are driven - widening the preference key
+     * union to cover arbitrary bus ids is not possible without reshaping `GamePreference`, and is
+     * not needed: a host bus is driven through {@link AudioManager.setBusVolume} instead.
+     *
+     * They write the **player's** half only. This used to write the bus's whole gain, and because
+     * these preferences default to 1 it meant that a host declaring `{id: "sound", volume: 0.6}`
+     * had its mix silently overwritten with 1 the moment the audio subsystem started - the author
+     * set SFX to 60% and every player heard 100%. Custom buses were unaffected because nothing
+     * aliases them, so the three buses every existing project uses were the only ones that ignored
+     * the declaration. Now `soundVolume: 1` means "do not attenuate further" and 0.6 survives.
+     */
     private setupGroupVolume;
 }