narraleaf-react 0.22.0 → 0.23.0

package/dist/game/nlcore/common/game.d.ts

@@ -3,9 +3,11 @@ import { GameState } from "../../player/gameState";
 import { Storable, Namespace } from "../elements/persistent/storable";
 import { LiveGame } from "../game/liveGame";
 import { Preference } from "../game/preference";
+import { AudioBusError, AudioBusMixer, AudioBusTree, DefaultAudioBusIds, MaxAudioBusDepth, acceptsAudioBus, getActiveAudioBusTree } from "../game/audioBus";
+import type { AudioBusDeclaration, AudioBusNode, AudioBusState } from "../game/audioBus";
 import type { StorableChange, StorableRestore } from "../elements/persistent/storable";
 import type { SavedGame } from "../gameTypes";
 import type { StackSnapshot, StackFrameSnapshot } from "../action/stackModel";
 import { KeyMap } from "../game/keyMap";
-export { LiveGame, GameState, Game, Storable, Namespace, Preference, KeyMap, };
-export type { SavedGame, StackSnapshot, StackFrameSnapshot, StorableChange, StorableRestore, };
+export { LiveGame, GameState, Game, Storable, Namespace, Preference, KeyMap, AudioBusError, AudioBusMixer, AudioBusTree, DefaultAudioBusIds, MaxAudioBusDepth, acceptsAudioBus, getActiveAudioBusTree, };
+export type { AudioBusDeclaration, AudioBusNode, AudioBusState, SavedGame, StackSnapshot, StackFrameSnapshot, StorableChange, StorableRestore, };

package/dist/game/nlcore/common/types.d.ts

@@ -9,9 +9,10 @@ import type { LayoutRouter } from "../../../game/player/lib/PageRouter/router";
 import { KeyBindingType, WebKeyboardKey } from "../game/types";
 import { KeyBindingValue } from "../game/keyMap";
 import { SoundType } from "../elements/sound";
+import type { SoundBusId } from "../elements/sound";
 import { StorableType } from "../elements/persistent/type";
 import { ScriptCtx } from "../elements/script";
 import { IStoryConfig } from "../elements/story";
 export * from "../elements/type";
-export type { GameHistory, IGamePluginRegistry, LiveGameEventToken, Origins, ServiceHandlerCtx, TransformDefinitions, GameConfig, SavedGame, NotificationToken, SavedGameMetaData, LayoutRouter, KeyBindingValue, WebKeyboardKey, StorableType, ScriptCtx, IStoryConfig };
+export type { GameHistory, IGamePluginRegistry, LiveGameEventToken, Origins, ServiceHandlerCtx, TransformDefinitions, GameConfig, SavedGame, NotificationToken, SavedGameMetaData, LayoutRouter, KeyBindingValue, WebKeyboardKey, StorableType, ScriptCtx, IStoryConfig, SoundBusId };
 export { KeyBindingType, SoundType, };

package/dist/game/nlcore/elements/sound.d.ts

@@ -7,6 +7,18 @@ export declare enum SoundType {
     Bgm = "bgm",
     Sound = "sound"
 }
+/**
+ * The audio bus a clip plays on.
+ *
+ * The three {@link SoundType} values are buses the engine always seeds and they mean exactly what
+ * they have always meant. Any other string is a bus the host declared in
+ * {@link import("../gameTypes").GameConfig.audioBuses} — `"alice"` under `"voice"`, `"ambience"`
+ * under `"bgm"`, as deep as makes sense.
+ *
+ * The `(string & {})` half is what widens this without giving up the completions: an editor still
+ * offers `"bgm" | "sound" | "voice"` first, and still narrows a `SoundType` where one is expected.
+ */
+export type SoundBusId = SoundType | (string & {});
 export type SoundDataRaw = {
     state: Record<string, any>;
 };
@@ -84,23 +96,35 @@ export interface ISoundUserConfig {
      */
     loopStart?: number;
     /**
-     * The type of the sound
+     * The audio bus this clip plays on.
+     *
+     * One of the three seeded buses, or the id of any bus the host declared in
+     * {@link import("../gameTypes").GameConfig.audioBuses}. The bus decides which volume the
+     * player controls governs this clip, and nothing else — a clip on any bus can be played,
+     * stopped, faded and seeked the same way.
      * @default SoundType.Sound
      */
-    type: SoundType;
+    type: SoundBusId;
 }
 export declare class Sound extends Actionable<SoundDataRaw, Sound> {
     /**
      * Create a voice sound for dialog lines.
+     *
+     * `type` picks the bus and defaults to `voice`; pass one to put the line on a bus beneath it,
+     * which is how a game gives each member of its cast a volume of its own. It used to be
+     * overwritten and silently ignored here.
      * @param arg0 - Source or config for the voice clip.
      * @example
      * ```ts
      * Sound.voice({ src: "voice.mp3" });
+     * Sound.voice({ src: "alice-01.mp3", type: "alice" }); // a bus declared under `voice`
      * ```
      */
     static voice(arg0: Partial<ISoundUserConfig> | string): Sound;
     /**
      * Create background music that cannot be played via `play()`.
+     *
+     * `type` defaults to `bgm` and may name any bus beneath it.
      * @param arg0 - Source or config for the bgm clip.
      * @example
      * ```ts
@@ -110,6 +134,8 @@ export declare class Sound extends Actionable<SoundDataRaw, Sound> {
     static bgm(arg0: Partial<ISoundUserConfig> | string): Sound;
     /**
      * Create a one-off sound effect.
+     *
+     * `type` defaults to `sound` and may name any bus beneath it.
      * @param arg0 - Source or config for the sound effect.
      */
     static sound(arg0: Partial<ISoundUserConfig> | string): Sound;

package/dist/game/nlcore/game/audioBus.d.ts

@@ -0,0 +1,268 @@
+import { EventDispatcher } from "../../../util/data";
+/**
+ * The buses the engine seeds for every game, whatever the host declares.
+ *
+ * Their ids are the values of {@link import("../elements/sound").SoundType} — deliberately, and
+ * a test asserts the two never drift apart. Content written before buses existed, and every save
+ * ever written, references these three strings; they have to keep meaning what they meant.
+ */
+export declare const DefaultAudioBusIds: {
+    readonly bgm: "bgm";
+    readonly sound: "sound";
+    readonly voice: "voice";
+};
+/**
+ * How deep a declared tree may nest, counting the bus itself.
+ *
+ * Generous on purpose: `voice → cast → alice → alice-shouting` is four, and nothing sane needs
+ * eight. The cap exists so a malformed declaration fails at boot with a legible message instead
+ * of walking a chain nobody meant to build.
+ */
+export declare const MaxAudioBusDepth = 8;
+/**
+ * One bus, as a host declares it.
+ *
+ * Only `id` is required. `parentId` omitted (or `null`) hangs the bus directly off the master
+ * output; `volume` omitted is full.
+ */
+export type AudioBusDeclaration = {
+    /**
+     * Stable, unique across the whole tree, and the string a {@link import("../elements/sound").Sound}'s
+     * `type` names. Two buses may not share an id even under different parents — the engine
+     * addresses buses by id alone.
+     */
+    id: string;
+    /**
+     * The bus this one feeds into, or `null`/omitted for the master output.
+     */
+    parentId?: string | null;
+    /**
+     * **The author's mix position for this bus**, 0..1 — where it sits relative to the others
+     * before any player has touched anything. "SFX sits 40% down in my mix" is `volume: 0.6`.
+     *
+     * It is not the volume a clip plays at and it is not the player's slider. A player's control
+     * is a *separate* number that multiplies on top of this one and defaults to 1, so a player who
+     * has changed nothing hears the mix the author built, and a player who pushes a slider to
+     * maximum gets the author's intent rather than a bus at full gain. See
+     * {@link AudioBusMixer.getVolume}.
+     * @default 1
+     */
+    volume?: number;
+};
+/**
+ * A bus after the tree has been resolved: parent settled, depth known.
+ */
+export type AudioBusNode = {
+    id: string;
+    parentId: string | null;
+    /**
+     * The author's mix position, straight off the declaration. Fixed for the life of the game —
+     * what a player moves is a separate number on the mixer.
+     */
+    volume: number;
+    /**
+     * 1 for a bus directly under the master output.
+     */
+    depth: number;
+};
+/**
+ * A bus and both of its numbers.
+ *
+ * The two are kept apart on purpose. One gain node was being asked to be two things at once — the
+ * author's mix position and the player's slider — and whichever was written last silently erased
+ * the other. Splitting them makes the layering total and unambiguous:
+ * **declared × player = what is on the node**, and neither can overwrite the other.
+ */
+export type AudioBusState = {
+    id: string;
+    parentId: string | null;
+    /**
+     * The player's control, 0..1, default 1. **This is the one to persist** — it is the only half
+     * a player owns, and restoring it lets an author re-mix a shipped game without a returning
+     * player's saved settings pinning the old mix forever.
+     */
+    volume: number;
+    /**
+     * The author's mix position, from {@link AudioBusDeclaration.volume}. Comes from the game, not
+     * from storage; persisting it would be persisting the game's own content.
+     */
+    declaredVolume: number;
+    /**
+     * `declaredVolume * volume` — what is actually on the gain node.
+     */
+    effectiveVolume: number;
+};
+/**
+ * A declared bus tree that cannot be realized.
+ *
+ * Always the host's declaration at fault — an unknown parent, a cycle, a duplicate id, a chain
+ * past {@link MaxAudioBusDepth}. The audio backend cannot produce any of these by construction:
+ * it builds a child *from* its parent, so its graph is a tree or it does not exist. Everything
+ * that can go wrong goes wrong one layer up, here, which is why the validation is here too.
+ */
+export declare class AudioBusError extends Error {
+    constructor(message: string);
+}
+/**
+ * The resolved bus graph: every declared bus, in an order a consumer can walk front-to-back
+ * knowing each bus's parent has already been seen.
+ *
+ * Immutable. A tree is realized into audio channels once, at boot, and never re-shaped — removing
+ * a channel stops every sound in its subtree, so live re-parenting would cut the music off mid-bar.
+ */
+export declare class AudioBusTree {
+    private readonly nodes;
+    private readonly index;
+    /**
+     * Resolve a host declaration into a tree, seeding `bgm`/`sound`/`voice` first.
+     *
+     * A declaration may re-state a seeded id to move it or change its volume; it may not remove
+     * one. Forward references are fine — the whole declaration is collected before anything is
+     * validated, so `{id: "alice", parentId: "cast"}` may precede `{id: "cast", parentId: "voice"}`.
+     *
+     * @throws {AudioBusError} on a duplicate id, an unknown parent, a cycle, or a chain deeper
+     * than {@link MaxAudioBusDepth}.
+     */
+    static resolve(declarations?: readonly AudioBusDeclaration[]): AudioBusTree;
+    /**
+     * Whether an id is one the engine seeds itself.
+     */
+    static isSeeded(id: string): boolean;
+    /**
+     * Everything that can be wrong with a declaration, checked before a single node is built.
+     *
+     * Walking up from each bus with a visited set catches every shape of cycle at once — a bus
+     * parented to itself, a mutual pair, and a longer ring — because a tree walk that revisits a
+     * bus it has already stood on cannot terminate.
+     */
+    private static assertResolvable;
+    private constructor();
+    /**
+     * Every bus, parents before their children. Realize channels by walking this front to back.
+     */
+    getNodes(): readonly AudioBusNode[];
+    get(id: string): AudioBusNode | null;
+    has(id: string): boolean;
+    /**
+     * Whether `id` is `ancestorId` or feeds into it, however many buses down.
+     *
+     * Inclusive at the top on purpose: a clip on `voice` itself has always been a voice, and this
+     * replaces an equality test that said exactly that.
+     */
+    isUnder(id: string, ancestorId: string): boolean;
+}
+/**
+ * The bus tree the last {@link AudioBusMixer} to resolve produced.
+ */
+export declare function getActiveAudioBusTree(): AudioBusTree;
+/**
+ * Whether a clip on bus `busId` is allowed in a slot that accepts `ancestorIds` and their
+ * descendants.
+ *
+ * **An id the registry has never heard of is accepted.** The alternative is worse than the bug it
+ * would catch: a story module usually constructs its scenes before the host constructs its `Game`,
+ * so at check time a perfectly valid custom bus is routinely not yet declared. Rejecting unknown
+ * ids would fail story compile for correct games depending on module evaluation order, which is
+ * not something an author can see or control. What the check is actually for — catching
+ * `Sound.bgm()` dropped into a voice slot — still works in every ordering, because the three
+ * seeded ids are known from the moment this module loads.
+ *
+ * A misspelled bus is therefore caught later and more cheaply: at play time, where the manager
+ * warns once and routes the clip somewhere audible.
+ */
+export declare function acceptsAudioBus(busId: string, ancestorIds: readonly string[]): boolean;
+type AudioBusEvents = {
+    "event:audioBus.volumeChange": [string, number, number];
+};
+/**
+ * The per-game mixer: the declared tree, plus what the player has done to it.
+ *
+ * **Every bus carries two numbers, and they never overwrite each other.** The declaration holds
+ * the author's mix — where a bus sits relative to the others in the game as shipped. The mixer
+ * holds the player's control, which starts at 1 and means "leave the author's mix alone". What
+ * reaches the gain node is the product. There is exactly one gain node per bus, because two gain
+ * stages in series compute the same product a multiplication does.
+ *
+ * That split is what makes the layering total: declared value → persisted player override → live
+ * changes, each a strictly later writer of a *different* number, so none of them can silently
+ * erase the one before. It also means an author can re-mix a shipped game and the new mix reaches
+ * players who already have settings saved, which a single conflated number cannot do.
+ *
+ * It lives on {@link import("../game").Game} rather than on the audio manager because a player's
+ * bus volumes are a setting, not game state — they exist before the audio context unlocks, they
+ * survive an unmount, and a host restores them out of its own storage at whatever point it likes.
+ * Setting a volume before the tree has been realized is normal and is not an error: the value is
+ * recorded and applied the moment the channels exist.
+ */
+export declare class AudioBusMixer {
+    private readonly declarations;
+    static EventTypes: {
+        readonly "event:audioBus.volumeChange": "event:audioBus.volumeChange";
+    };
+    readonly events: EventDispatcher<AudioBusEvents>;
+    /** The player's half. Absent means "untouched", which is 1 — not 0, and not the declaration. */
+    private readonly overrides;
+    private tree;
+    /**
+     * @param declarations - Read lazily, so a host that calls `configure()` between constructing
+     * the `Game` and mounting the player still gets the tree it declared.
+     */
+    constructor(declarations: () => readonly AudioBusDeclaration[]);
+    /**
+     * The resolved tree, resolving it on first use and caching it afterwards.
+     *
+     * @throws {AudioBusError} if the declaration cannot be resolved.
+     */
+    getTree(): AudioBusTree;
+    /**
+     * Whether the tree has been resolved yet. Reading it is what resolves it, so this exists for
+     * callers that must not trigger validation as a side effect.
+     */
+    isResolved(): boolean;
+    /**
+     * Set **the player's** volume for a bus, 0..1. This is what a slider writes.
+     *
+     * 1 means "leave the author's mix alone" and is the value every bus starts at, so a game whose
+     * author put SFX at 0.6 plays SFX at 0.6 until a player says otherwise, and a player who drags
+     * the slider to maximum gets 0.6 back rather than a bus at full gain. The author's half is
+     * {@link getDeclaredVolume} and this cannot overwrite it.
+     *
+     * Applies to sounds that are **already playing**: a bus is a gain node every clip beneath it
+     * is routed through, so the change reaches them without touching a single token.
+     */
+    setVolume(id: string, volume: number): this;
+    /**
+     * Set many player volumes at once — what a host calls when restoring its saved mixer state.
+     * Ids the tree does not contain are recorded anyway, so restoring before the tree is resolved
+     * is safe.
+     */
+    setVolumes(volumes: Readonly<Record<string, number>>): this;
+    /**
+     * The player's volume for a bus — what was last set, else 1.
+     *
+     * Deliberately **not** the declared volume and deliberately **not** what is on the gain node.
+     * A bus the player has never touched reads 1 whatever the author declared, which is what makes
+     * a slider bound to this sit at maximum on a fresh install and what makes the persisted value
+     * mean "what the player did" rather than "what the game shipped with".
+     */
+    getVolume(id: string): number;
+    /**
+     * The author's mix position for a bus, from the declaration. Never written at runtime.
+     */
+    getDeclaredVolume(id: string): number;
+    /**
+     * What is actually on the bus's gain node: the author's mix times the player's control.
+     */
+    getEffectiveVolume(id: string): number;
+    /**
+     * Every bus with both of its numbers, parents first — the whole mixer.
+     */
+    list(): AudioBusState[];
+    /**
+     * Just the player's volumes, keyed by bus id — **the half a host persists**, and the shape
+     * {@link setVolumes} takes back. The author's mix is game content and comes back with the game.
+     */
+    getVolumes(): Record<string, number>;
+    onVolumeChange(listener: (id: string, volume: number, effectiveVolume: number) => void): import("../../../util/data").EventToken<import("../../../util/data").EventTypes>;
+}
+export {};

package/dist/game/nlcore/game/preference.d.ts

@@ -4,13 +4,22 @@ type PreferenceEventToken = {
 };
 type StringKeyof<T> = Extract<keyof T, string>;
 export declare class Preference<T extends Record<string, string | boolean | number | null | undefined>> {
-    private readonly settings;
     static EventTypes: {
         readonly "event:game.preference.change": "event:game.preference.change";
     };
     readonly events: EventDispatcher<{
         "event:game.preference.change": [StringKeyof<T>, any];
     }>;
+    private readonly settings;
+    /**
+     * @param settings - The initial values. **Copied, not adopted.**
+     *
+     * This used to keep the caller's object and write straight into it, and the only caller in the
+     * engine passes the module-level `Game.DefaultPreference`. So every `Game` ever constructed
+     * shared one settings object: a second game started with the first player's volume, and a
+     * player moving a slider permanently rewrote the framework's own defaults for the rest of the
+     * process. A shallow copy is enough - every preference value is a primitive.
+     */
     constructor(settings: T);
     setPreference<K extends StringKeyof<T>>(key: K, value: T[K]): void;
     getPreference<K extends StringKeyof<T>>(key: K): T[K];

package/dist/game/nlcore/game.d.ts

@@ -4,6 +4,7 @@ import { LogicAction } from "./action/logicAction";
 import { LiveGame } from "./game/liveGame";
 import { Preference } from "./game/preference";
 import { GameState } from "../player/gameState";
+import { AudioBusMixer } from "./game/audioBus";
 import { Plugins, IGamePluginRegistry } from "./game/plugin/plugin";
 import { PuppetBackend } from "./game/puppet/puppetBackend";
 import { LayoutRouter } from "../player/lib/PageRouter/router";
@@ -57,6 +58,37 @@ export declare class Game {
      * Game settings
      */
     preference: Preference<GamePreference>;
+    /**
+     * The audio bus mixer: the tree declared in {@link GameConfig.audioBuses}, and what the player
+     * has done to it.
+     *
+     * Every bus carries **two** numbers. The declaration holds the author's mix — where a bus sits
+     * relative to the others in the game as shipped. This mixer holds the player's control, which
+     * starts at 1 and means "leave the author's mix alone". The product is what reaches the gain
+     * node, so neither half can silently erase the other and the layering is total: declared →
+     * persisted player override → live change.
+     *
+     * It is on `Game` rather than on the audio manager because a bus volume is a player setting,
+     * not game state — it exists before the audio context unlocks, it survives the player
+     * unmounting, and a host restores it from its own storage whenever it likes. Setting a volume
+     * at any point after `new Game(...)` is safe; if the channels do not exist yet the value is
+     * applied the moment they do.
+     *
+     * The four volume preferences (`bgmVolume`, `soundVolume`, `voiceVolume`, `globalVolume`) are
+     * unchanged and keep working: the first three are aliases onto the seeded buses of the same
+     * name and write the *player's* half, so their default of 1 no longer overwrites a declared
+     * mix. Drive the seeded three through the preferences, and use this for buses the host
+     * declared.
+     *
+     * @example
+     * ```ts
+     * // persist the player's half only - the author's mix comes back with the game
+     * localStorage.setItem("mixer", JSON.stringify(game.audioBuses.getVolumes()));
+     * // restore, any time after `new Game(...)`
+     * game.audioBuses.setVolumes(JSON.parse(localStorage.getItem("mixer") ?? "{}"));
+     * ```
+     */
+    readonly audioBuses: AudioBusMixer;
     /**
      * Game key bindings
      */

package/dist/game/nlcore/gameTypes.d.ts

@@ -10,6 +10,7 @@ import { StackModel, StackModelRawData } from "./action/stackModel";
 import type { GameElementHistory } from "./action/gameHistory";
 import { MenuComponent, NotificationComponent, NvlDialogComponent, SayComponent } from "./common/player";
 import { LiveGameEventToken } from "./types";
+import type { AudioBusDeclaration } from "./game/audioBus";
 /**
  * Current save format version.
  *
@@ -187,6 +188,46 @@ export type GameConfig = {
      * @default 10
      */
     maxPreloadActions: number;
+    /**
+     * The audio bus tree, declared by the host at boot.
+     *
+     * A bus is a gain node every sound routed to it passes through, and buses nest: a clip on
+     * `alice` under `voice` is attenuated by `alice`, then by `voice`, then by the master volume.
+     * That is what lets a player turn one character down without touching the rest of the cast.
+     *
+     * A bus's `volume` here is **the author's mix position**, not the player's slider. The player's
+     * control is a separate number that starts at 1 and multiplies on top of this one — see
+     * {@link import("./game").Game.audioBuses} — so a mix declared here survives boot and
+     * survives a player who has never touched a slider.
+     *
+     * `bgm`, `sound` and `voice` are always present whether or not they appear here, so leaving
+     * this empty is exactly the behaviour every game had before buses existed. Naming one of them
+     * here moves it or changes its volume; nothing can remove it.
+     *
+     * Declaration order does not matter — a bus may name a parent declared after it. What is
+     * rejected, loudly and at boot, is an unknown parent, a duplicate id, a cycle of any length,
+     * or a chain nested deeper than
+     * {@link import("./game/audioBus").MaxAudioBusDepth}.
+     *
+     * **Read once, when the audio subsystem starts.** Re-parenting a live bus would mean removing
+     * a channel, which stops every sound in its subtree, so a `configure()` after the player has
+     * mounted does not re-shape the graph. Volumes, on the other hand, are live at all times —
+     * see {@link import("./game").Game.audioBuses}.
+     *
+     * @default []
+     * @example
+     * ```ts
+     * new Game({
+     *     audioBuses: [
+     *         {id: "ambience", parentId: "bgm", volume: 0.6},
+     *         {id: "cast", parentId: "voice"},
+     *         {id: "alice", parentId: "cast"},
+     *     ],
+     * });
+     * // Sound.voice({src: "alice-01.mp3", type: "alice"})
+     * ```
+     */
+    audioBuses: AudioBusDeclaration[];
     /**
      * Src of the cursor image, if null, the game will show the default cursor
      * @default null

package/dist/game/player/elements/player/PreferenceUpdateAnnouncer.d.ts

@@ -1,4 +1,12 @@
 import { GameState } from "../../../../game/nlcore/common/game";
+/**
+ * The three volume preferences drive the three seeded buses.
+ *
+ * This is the whole of the alias: a preference is what a player's slider writes to, a bus is what
+ * the audio graph reads, and one pushes into the other. Buses the host declared are not
+ * preferences and are driven through `game.audioBuses` instead - `GamePreference` is a closed
+ * object type and cannot grow a key per character.
+ */
 export default function PreferenceUpdateAnnouncer({ gameState }: Readonly<{
     gameState: GameState;
 }>): null;