import { Component } from "../components/component.js";
/**
* Validates finite number.
* @param {number} value
* @param {string} name
* @returns {number}
*/
function finiteNumber(value, name) {
if (typeof value !== "number" || !Number.isFinite(value)) {
throw new TypeError(`${name} must be a finite number`);
}
return value;
}
/**
* Validates non-empty string.
* @param {string} value
* @param {string} name
* @returns {string}
*/
function nonEmptyString(value, name) {
if (typeof value !== "string" || !value.trim()) {
throw new TypeError(`${name} must be a non-empty string`);
}
return value.trim();
}
/**
* Represents a single audio bus node in a hierarchical mixing tree.
*/
export class AudioBus {
/**
* @param {string} name
* @param {Object} [config]
* @param {AudioBus} [config.parent=null]
* @param {number} [config.volume=1.0]
* @param {boolean} [config.muted=false]
*/
constructor(name, { parent = null, volume = 1.0, muted = false } = {}) {
this.name = nonEmptyString(name, "bus name");
this.parent = parent;
this.volume = Math.max(0, Math.min(1, finiteNumber(volume, "volume")));
this.muted = Boolean(muted);
}
/**
* Compute composed effective volume through the ancestor chain.
* If this bus or any ancestor is muted, effective volume is 0.0.
* @returns {number} Composed volume in range [0, 1]
*/
getEffectiveVolume() {
if (this.muted) return 0;
if (!this.parent) return this.volume;
return this.volume * this.parent.getEffectiveVolume();
}
/**
* Check if this bus or any of its parents is muted.
* @returns {boolean}
*/
isEffectivelyMuted() {
if (this.muted) return true;
if (!this.parent) return false;
return this.parent.isEffectivelyMuted();
}
}
/**
* Hierarchical audio bus mixer managing master, music, sfx, and UI channels
* with composed gain calculation, volume clamping, and preference persistence.
*/
export class AudioBusSystem extends Component {
constructor() {
super();
this.buses = new Map();
this.listeners = new Set();
// Create standard hierarchy: master -> music, sfx, ui
this.createBus("master", { parent: null, volume: 1.0, muted: false });
this.createBus("music", { parent: "master", volume: 0.8, muted: false });
this.createBus("sfx", { parent: "master", volume: 1.0, muted: false });
this.createBus("ui", { parent: "master", volume: 0.9, muted: false });
}
/**
* Add change listener.
* @param {Function} listener
* @returns {Function} Unsubscribe
*/
onBusChanged(listener) {
if (typeof listener !== "function") throw new TypeError("Listener must be a function");
this.listeners.add(listener);
return () => this.listeners.delete(listener);
}
_emit(event) {
for (const listener of this.listeners) {
listener(event);
}
}
/**
* Create or retrieve an audio bus.
* @param {string} name
* @param {Object} [config]
* @param {string|AudioBus} [config.parent="master"]
* @param {number} [config.volume=1.0]
* @param {boolean} [config.muted=false]
* @returns {AudioBus}
*/
createBus(name, { parent = "master", volume = 1.0, muted = false } = {}) {
nonEmptyString(name, "name");
let parentBus = null;
if (parent) {
parentBus = typeof parent === "string" ? this.buses.get(parent) ?? null : parent;
}
const bus = new AudioBus(name, { parent: parentBus, volume, muted });
this.buses.set(name, bus);
return bus;
}
/**
* Get audio bus by name. Throws if missing.
* @param {string} name
* @returns {AudioBus}
*/
getBus(name) {
nonEmptyString(name, "name");
if (!this.buses.has(name)) {
throw new Error(`Audio bus "${name}" not found`);
}
return this.buses.get(name);
}
/**
* Set volume for a bus, clamped strictly between 0 and 1.
* Throws if volume is not a finite number.
* @param {string} name
* @param {number} volume
*/
setVolume(name, volume) {
finiteNumber(volume, "volume");
const bus = this.getBus(name);
bus.volume = Math.max(0, Math.min(1, volume));
this._emit({ type: "volume", bus: name, volume: bus.volume, effective: bus.getEffectiveVolume() });
}
/**
* Set mute state for a bus.
* @param {string} name
* @param {boolean} muted
*/
setMuted(name, muted) {
const bus = this.getBus(name);
bus.muted = Boolean(muted);
this._emit({ type: "mute", bus: name, muted: bus.muted, effective: bus.getEffectiveVolume() });
}
/**
* Toggle mute state for a bus.
* @param {string} name
* @returns {boolean} New mute state
*/
toggleMute(name) {
const bus = this.getBus(name);
this.setMuted(name, !bus.muted);
return bus.muted;
}
/**
* Get composed effective volume for a bus.
* If the bus or any of its parents is muted, returns 0.0.
* @param {string} name
* @returns {number}
*/
getEffectiveVolume(name) {
return this.getBus(name).getEffectiveVolume();
}
/**
* Check if a bus is muted directly or via any parent.
* @param {string} name
* @returns {boolean}
*/
isMuted(name) {
return this.getBus(name).isEffectivelyMuted();
}
/**
* Export user audio preferences separately from game progress saves.
* @returns {Object}
*/
exportPreferences() {
const prefs = {};
for (const [name, bus] of this.buses.entries()) {
prefs[name] = {
volume: bus.volume,
muted: bus.muted
};
}
return prefs;
}
/**
* Import user audio preferences. Can be called before audio unlock or scene loading.
* @param {Object} prefs
*/
importPreferences(prefs) {
if (!prefs || typeof prefs !== "object") return;
for (const [name, config] of Object.entries(prefs)) {
if (this.buses.has(name) && config && typeof config === "object") {
if (typeof config.volume === "number" && Number.isFinite(config.volume)) {
this.buses.get(name).volume = Math.max(0, Math.min(1, config.volume));
}
if (typeof config.muted === "boolean") {
this.buses.get(name).muted = config.muted;
}
}
}
this._emit({ type: "preferences-loaded" });
}
toJSON() {
return this.exportPreferences();
}
static fromJSON(data) {
const system = new AudioBusSystem();
system.importPreferences(data);
return system;
}
}