A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(audio): per-bus DSP inserts + sidechain ducking
esenginee106208a6b9e
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex f3f8fbda5..807d1ecf1 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1144 stable · 17 beta · 1 deprecated+Symbols: 1150 stable · 17 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -554,6 +554,8 @@ bufferBudget: numberdispose: () => voidgetBufferHandle: (url: string) => AudioBufferHandle | undefinedgetBufferStats: () => AudioBufferStats+getBusDucking: (target: string) => BusDuckRule | null+getBusEffects: (busName: string) => BusEffectDef[]getSpectrum: (out: Uint8Array) => booleaninvalidateBuffer: (url: string) => booleanmuteBus: (busName: string, muted: boolean) => void@@ -566,6 +568,9 @@ releaseBuffer: (url: string) => voidretainBuffer: (url: string) => booleansetAssetResolver: (resolver: (url: string) => ArrayBuffer | null) => voidsetBufferBudget: (bytes: number | null) => void+setBusDucking: (target: string, rule: BusDuckRule | null) => boolean+setBusEffects: (busName: string, effects: BusEffectDef[]) => boolean+setBusVolume: (busName: string, volume: number) => voidsetMasterVolume: (volume: number) => voidsetMusicVolume: (volume: number) => voidsetRefResolver: (resolver: ((ref: string) => string) | null) => void@@ -574,6 +579,7 @@ setUIVolume: (volume: number) => voidstopAll: () => voidstopBGM: (fadeOut?: number) => voidtrimBufferCache: () => number+updateDucking: () => voidstatic new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPIstatic prototype: AudioAPI```@@ -595,9 +601,13 @@ id: number```addChild: (child: AudioBus) => voidconnect: (destination: AudioBus | AudioNode) => void+duckTo: (level: number, timeConstant: number) => void+effects: BusEffectDef[]+input: GainNodemuted: booleanname: stringnode: GainNode+setEffects: (defs: BusEffectDef[]) => voidvolume: numberstatic new (context: AudioContext, config: AudioBusConfig): AudioBusstatic prototype: AudioBus@@ -639,12 +649,16 @@ enabled: boolean## AudioMixer — class```+busNames: () => string[]createBus: (config: AudioBusConfig) => AudioBusgetBus: (name: string) => AudioBus | undefined+getDucking: (target: string) => BusDuckRule | nullmaster: AudioBusmusic: AudioBus+setDucking: (target: string, rule: BusDuckRule | null) => booleansfx: AudioBusui: AudioBus+updateDucking: () => voidvoice: AudioBusstatic new (context: AudioContext, config?: AudioMixerConfig): AudioMixerstatic prototype: AudioMixer@@ -1017,6 +1031,20 @@ source: string'local' | 'lazy' | 'remote'```+## BusDuckRule — interface+```+amount: number+attack: number | undefined+release: number | undefined+threshold: number | undefined+trigger: string+```++## BusEffectDef — type+```+FilterEffectDef | ReverbEffectDef | CompressorEffectDef+```+## Button — const```(...bindings: Binding[]) => ActionDef@@ -1432,6 +1460,16 @@ spineFields: SpineFieldMeta | undefinedtransient: boolean | undefined```+## CompressorEffectDef — interface+```+attack: number | undefined+kneeDb: number | undefined+ratio: number | undefined+release: number | undefined+thresholdDb: number | undefined+type: "compressor"+```+## CookedAtlasInfo — interface```frame: { x: number; y: number; width: number; height: number; }@@ -2375,6 +2413,15 @@ Right = 1Top = 3```+## FilterEffectDef — interface+```+filter: "lowpass" | "highpass" | "bandpass" | "lowshelf" | "highshelf" | "peaking" | "notch"+frequency: number+gainDb: number | undefined+q: number | undefined+type: "filter"+```+## FilterExpr — type```| { readonly kind: 'with'; readonly component: AnyComponentDef }@@ -4879,6 +4926,14 @@ textureEvictableCount: numbervertexBufferCount: number```+## ReverbEffectDef — interface+```+decay: number | undefined+seconds: number | undefined+type: "reverb"+wet: number | undefined+```+## RevoluteJoint — const```ComponentDef<RevoluteJointData>@@ -8206,6 +8261,11 @@ NavPlugin(raw: any): TimelineAsset```+## parseBusEffects — function+```+(raw: unknown): BusEffectDef[]+```+## parseLocaleTable — function```(text: string, path: string): LocaleTableAssetdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 773bfb812..c63689d02 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1143 stable · 19 beta · 1 deprecated+Symbols: 1149 stable · 19 beta · 1 deprecated## ANCHOR_AXES — const```@@ -549,6 +549,8 @@ bufferBudget: numberdispose: () => voidgetBufferHandle: (url: string) => AudioBufferHandle | undefinedgetBufferStats: () => AudioBufferStats+getBusDucking: (target: string) => BusDuckRule | null+getBusEffects: (busName: string) => BusEffectDef[]getSpectrum: (out: Uint8Array) => booleaninvalidateBuffer: (url: string) => booleanmuteBus: (busName: string, muted: boolean) => void@@ -561,6 +563,9 @@ releaseBuffer: (url: string) => voidretainBuffer: (url: string) => booleansetAssetResolver: (resolver: (url: string) => ArrayBuffer | null) => voidsetBufferBudget: (bytes: number | null) => void+setBusDucking: (target: string, rule: BusDuckRule | null) => boolean+setBusEffects: (busName: string, effects: BusEffectDef[]) => boolean+setBusVolume: (busName: string, volume: number) => voidsetMasterVolume: (volume: number) => voidsetMusicVolume: (volume: number) => voidsetRefResolver: (resolver: ((ref: string) => string) | null) => void@@ -569,6 +574,7 @@ setUIVolume: (volume: number) => voidstopAll: () => voidstopBGM: (fadeOut?: number) => voidtrimBufferCache: () => number+updateDucking: () => voidstatic new (backend: PlatformAudioBackend, mixer?: AudioMixer | null): AudioAPIstatic prototype: AudioAPI```@@ -590,9 +596,13 @@ id: number```addChild: (child: AudioBus) => voidconnect: (destination: AudioBus | AudioNode) => void+duckTo: (level: number, timeConstant: number) => void+effects: BusEffectDef[]+input: GainNodemuted: booleanname: stringnode: GainNode+setEffects: (defs: BusEffectDef[]) => voidvolume: numberstatic new (context: AudioContext, config: AudioBusConfig): AudioBusstatic prototype: AudioBus@@ -634,12 +644,16 @@ enabled: boolean## AudioMixer — class```+busNames: () => string[]createBus: (config: AudioBusConfig) => AudioBusgetBus: (name: string) => AudioBus | undefined+getDucking: (target: string) => BusDuckRule | nullmaster: AudioBusmusic: AudioBus+setDucking: (target: string, rule: BusDuckRule | null) => booleansfx: AudioBusui: AudioBus+updateDucking: () => voidvoice: AudioBusstatic new (context: AudioContext, config?: AudioMixerConfig): AudioMixerstatic prototype: AudioMixer@@ -1012,6 +1026,20 @@ source: string'local' | 'lazy' | 'remote'```+## BusDuckRule — interface+```+amount: number+attack: number | undefined+release: number | undefined+threshold: number | undefined+trigger: string+```++## BusEffectDef — type+```+FilterEffectDef | ReverbEffectDef | CompressorEffectDef+```+## Button — const```(...bindings: Binding[]) => ActionDef@@ -1427,6 +1455,16 @@ spineFields: SpineFieldMeta | undefinedtransient: boolean | undefined```+## CompressorEffectDef — interface+```+attack: number | undefined+kneeDb: number | undefined+ratio: number | undefined+release: number | undefined+thresholdDb: number | undefined+type: "compressor"+```+## CookedAtlasInfo — interface```frame: { x: number; y: number; width: number; height: number; }@@ -2370,6 +2408,15 @@ Right = 1Top = 3```+## FilterEffectDef — interface+```+filter: "lowpass" | "highpass" | "bandpass" | "lowshelf" | "highshelf" | "peaking" | "notch"+frequency: number+gainDb: number | undefined+q: number | undefined+type: "filter"+```+## FilterExpr — type```| { readonly kind: 'with'; readonly component: AnyComponentDef }@@ -4874,6 +4921,14 @@ textureEvictableCount: numbervertexBufferCount: number```+## ReverbEffectDef — interface+```+decay: number | undefined+seconds: number | undefined+type: "reverb"+wet: number | undefined+```+## RevoluteJoint — const```ComponentDef<RevoluteJointData>@@ -8211,6 +8266,11 @@ NodePlatformAdapter(raw: any): TimelineAsset```+## parseBusEffects — function+```+(raw: unknown): BusEffectDef[]+```+## parseLocaleTable — function```(text: string, path: string): LocaleTableAssetdiff --git a/sdk/src/audio/Audio.ts b/sdk/src/audio/Audio.tsindex a5ec109d9..711ffa5fb 100644--- a/sdk/src/audio/Audio.ts+++ b/sdk/src/audio/Audio.ts@@ -1,7 +1,8 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport type { PlatformAudioBackend, AudioBufferHandle, AudioHandle } from './PlatformAudioBackend';-import type { AudioMixer } from './AudioMixer';+import type { AudioMixer, BusDuckRule } from './AudioMixer';+import type { BusEffectDef } from './BusEffects';import { defineResource } from '../resource';import { RuntimeConfig } from '../defaults';import { log } from '../logger';@@ -375,6 +376,41 @@ export class AudioAPI {}}+ setBusVolume(busName: string, volume: number): void {+ const bus = this.mixer_?.getBus(busName);+ if (bus) {+ bus.volume = volume;+ }+ }++ /** Replace a bus's DSP insert chain. No-op (false) on backends without a+ * WebAudio graph (WeChat/Null) — same degradation as the volume APIs. */+ setBusEffects(busName: string, effects: BusEffectDef[]): boolean {+ const bus = this.mixer_?.getBus(busName);+ if (!bus) return false;+ bus.setEffects(effects);+ return true;+ }++ getBusEffects(busName: string): BusEffectDef[] {+ return this.mixer_?.getBus(busName)?.effects ?? [];+ }++ /** Install (or clear with null) sidechain ducking on `target` — e.g. duck+ * 'music' to 30% while 'voice' carries signal. */+ setBusDucking(target: string, rule: BusDuckRule | null): boolean {+ return this.mixer_?.setDucking(target, rule) ?? false;+ }++ getBusDucking(target: string): BusDuckRule | null {+ return this.mixer_?.getDucking(target) ?? null;+ }++ /** Advance duck envelopes (driven per-frame by AudioUpdateSystem). */+ updateDucking(): void {+ this.mixer_?.updateDucking();+ }+getBufferHandle(url: string): AudioBufferHandle | undefined {return this.lookupBuffer_(url);}diff --git a/sdk/src/audio/AudioBus.ts b/sdk/src/audio/AudioBus.tsindex f2dd63995..864905b54 100644--- a/sdk/src/audio/AudioBus.ts+++ b/sdk/src/audio/AudioBus.ts@@ -1,5 +1,16 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file AudioBus.ts+ * @brief One mixer bus: input → [effect inserts…] → duck → gain(volume) → parent.+ *+ * Sources and child buses connect to `input`; `node` is the OUTPUT gain (what+ * volume/mute act on, and what parents/analysers tap). The duck stage is a+ * separate gain so sidechain ducking never fights the user's volume setting.+ */++import { buildEffectNodes, type BusEffectDef, type EffectNodes } from './BusEffects';+export interface AudioBusConfig {name: string;volume?: number;@@ -11,20 +22,33 @@ const SMOOTHING_TIME_CONSTANT = 0.015;export class AudioBus {private readonly name_: string;+ private readonly context_: AudioContext;+ private readonly inputNode_: GainNode;+ private readonly duckNode_: GainNode;private readonly gainNode_: GainNode;private muted_: boolean = false;private volume_: number = 1.0;private children_: AudioBus[] = [];+ private effectDefs_: BusEffectDef[] = [];+ private effectNodes_: EffectNodes[] = [];constructor(context: AudioContext, config: AudioBusConfig) {this.name_ = config.name;+ this.context_ = context;+ this.inputNode_ = context.createGain();+ this.duckNode_ = context.createGain();this.gainNode_ = context.createGain();+ this.inputNode_.connect(this.duckNode_);+ this.duckNode_.connect(this.gainNode_);this.volume_ = Math.max(0, Math.min(1, config.volume ?? 1.0));this.muted_ = config.muted ?? false;this.gainNode_.gain.value = this.muted_ ? 0 : this.volume_;}get name(): string { return this.name_; }+ /** Entry node — sources and child buses connect HERE. */+ get input(): GainNode { return this.inputNode_; }+ /** Output gain (volume/mute stage) — parents and analyser taps connect FROM here. */get node(): GainNode { return this.gainNode_; }get volume(): number { return this.volume_; }@@ -49,9 +73,35 @@ export class AudioBus {);}+ /** The declarative insert chain currently realized on this bus. */+ get effects(): BusEffectDef[] { return this.effectDefs_.map(e => ({ ...e })); }++ /** Idempotently replace the insert chain: input → e1 → … → duck. */+ setEffects(defs: BusEffectDef[]): void {+ this.inputNode_.disconnect();+ for (const fx of this.effectNodes_) fx.output.disconnect();+ this.effectDefs_ = defs.map(e => ({ ...e }));+ this.effectNodes_ = defs.map(d => buildEffectNodes(this.context_, d));+ let prev: AudioNode = this.inputNode_;+ for (const fx of this.effectNodes_) {+ prev.connect(fx.input);+ prev = fx.output;+ }+ prev.connect(this.duckNode_);+ }++ /** Sidechain duck stage: ramp toward `level` with the given time constant. */+ duckTo(level: number, timeConstant: number): void {+ this.duckNode_.gain.setTargetAtTime(+ Math.max(0, Math.min(1, level)),+ this.duckNode_.context.currentTime,+ Math.max(0.001, timeConstant)+ );+ }+connect(destination: AudioBus | AudioNode): void {if (destination instanceof AudioBus) {- this.gainNode_.connect(destination.node);+ this.gainNode_.connect(destination.input);} else {this.gainNode_.connect(destination);}diff --git a/sdk/src/audio/AudioMixer.ts b/sdk/src/audio/AudioMixer.tsindex 1d968e689..6b300d89b 100644--- a/sdk/src/audio/AudioMixer.ts+++ b/sdk/src/audio/AudioMixer.ts@@ -10,6 +10,28 @@ export interface AudioMixerConfig {voiceVolume?: number;}+/**+ * Sidechain ducking rule: while `trigger` carries signal, the target bus's+ * duck stage ramps to `amount`; when it falls silent, it ramps back to 1.+ */+export interface BusDuckRule {+ trigger: string;+ /** Duck level 0..1 while the trigger bus is active. */+ amount: number;+ /** Ramp-down time constant in seconds (default 0.05). */+ attack?: number;+ /** Ramp-up time constant in seconds (default 0.4). */+ release?: number;+ /** RMS level (0..1) above which the trigger counts as active (default 0.003). */+ threshold?: number;+}++interface DuckState {+ rule: BusDuckRule;+ analyser: AnalyserNode;+ data: Uint8Array;+}+const DEFAULT_MUSIC_VOLUME = 0.8;export class AudioMixer {@@ -51,6 +73,11 @@ export class AudioMixer {return this.buses_.get(name);}+ /** Registered bus names, in creation order (master first). */+ busNames(): string[] {+ return [...this.buses_.keys()];+ }+createBus(config: AudioBusConfig): AudioBus {const bus = new AudioBus(this.context_, config);const parent = config.parent ? this.buses_.get(config.parent) : this.master;@@ -60,4 +87,57 @@ export class AudioMixer {this.buses_.set(config.name, bus);return bus;}++ // -- sidechain ducking ----------------------------------------------------++ private ducks_ = new Map<string, DuckState>();++ /** Install (or clear with null) the duck rule targeting `target`. */+ setDucking(target: string, rule: BusDuckRule | null): boolean {+ const targetBus = this.buses_.get(target);+ if (!targetBus) return false;+ const existing = this.ducks_.get(target);+ if (existing) {+ existing.analyser.disconnect();+ this.ducks_.delete(target);+ targetBus.duckTo(1, existing.rule.release ?? 0.4);+ }+ if (!rule) return true;+ const trigger = this.buses_.get(rule.trigger);+ if (!trigger) return false;+ // Sink-only tap on the trigger's OUTPUT (post-volume), so a muted+ // trigger bus stops ducking.+ const analyser = this.context_.createAnalyser();+ analyser.fftSize = 256;+ trigger.node.connect(analyser);+ this.ducks_.set(target, { rule: { ...rule }, analyser, data: new Uint8Array(analyser.fftSize) });+ return true;+ }++ getDucking(target: string): BusDuckRule | null {+ const d = this.ducks_.get(target);+ return d ? { ...d.rule } : null;+ }++ /** Per-frame: measure each trigger's RMS and ramp its target's duck stage. */+ updateDucking(): void {+ for (const [target, d] of this.ducks_) {+ const targetBus = this.buses_.get(target);+ if (!targetBus) continue;+ // lib.dom narrowed getByteTimeDomainData to Uint8Array<ArrayBuffer> in+ // TS 5.7; ours is a plain Uint8Array (ArrayBufferLike) — safe to cast.+ d.analyser.getByteTimeDomainData(d.data as Uint8Array<ArrayBuffer>);+ let sum = 0;+ for (let i = 0; i < d.data.length; i++) {+ const v = (d.data[i] - 128) / 128;+ sum += v * v;+ }+ const rms = Math.sqrt(sum / d.data.length);+ const active = rms > (d.rule.threshold ?? 0.003);+ targetBus.duckTo(+ active ? d.rule.amount : 1,+ active ? (d.rule.attack ?? 0.05) : (d.rule.release ?? 0.4)+ );+ }+ }}diff --git a/sdk/src/audio/AudioPlugin.ts b/sdk/src/audio/AudioPlugin.tsindex bc320ae18..bbd1dedb2 100644--- a/sdk/src/audio/AudioPlugin.ts+++ b/sdk/src/audio/AudioPlugin.ts@@ -91,6 +91,8 @@ export class AudioPlugin implements Plugin {}wasPlayMode = true;+ audioAPI.updateDucking();+const world = app.world;let listenerX = 0;diff --git a/sdk/src/audio/BusEffects.ts b/sdk/src/audio/BusEffects.tsnew file mode 100644index 000000000..0a69009c8--- /dev/null+++ b/sdk/src/audio/BusEffects.ts@@ -0,0 +1,154 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file BusEffects.ts+ * @brief Declarative per-bus DSP inserts — the serializable effect vocabulary+ * and its WebAudio realization. Defs are pure data (the project audio+ * config and the editor Mixer speak the same shape); non-WebAudio+ * backends never see them (AudioAPI gates on a live mixer).+ */++export interface FilterEffectDef {+ type: 'filter';+ filter: 'lowpass' | 'highpass' | 'bandpass' | 'lowshelf' | 'highshelf' | 'peaking' | 'notch';+ frequency: number;+ /** Q factor; meaningful for all but the shelf filters. */+ q?: number;+ /** Boost/cut in dB; meaningful for shelf/peaking filters. */+ gainDb?: number;+}++export interface ReverbEffectDef {+ type: 'reverb';+ /** Impulse length in seconds (tail size). */+ seconds?: number;+ /** Exponential decay rate of the impulse (higher = tighter room). */+ decay?: number;+ /** Wet mix 0..1 (dry is 1 - wet). */+ wet?: number;+}++export interface CompressorEffectDef {+ type: 'compressor';+ thresholdDb?: number;+ ratio?: number;+ attack?: number;+ release?: number;+ kneeDb?: number;+}++export type BusEffectDef = FilterEffectDef | ReverbEffectDef | CompressorEffectDef;++/** A realized effect: a sub-graph with one input and one output node. */+export interface EffectNodes {+ input: AudioNode;+ output: AudioNode;+}++const clamp01 = (v: number) => Math.max(0, Math.min(1, v));++/**+ * Procedural impulse response: stereo noise with an exponential decay tail.+ * Good-enough room ambience with zero asset dependencies; a convolution IR+ * asset can slot in later without changing the def shape.+ */+export function makeImpulseResponse(context: BaseAudioContext, seconds: number, decay: number): AudioBuffer {+ const rate = context.sampleRate;+ const length = Math.max(1, Math.floor(rate * Math.max(0.05, seconds)));+ const buffer = context.createBuffer(2, length, rate);+ for (let ch = 0; ch < 2; ch++) {+ const data = buffer.getChannelData(ch);+ for (let i = 0; i < length; i++) {+ data[i] = (Math.random() * 2 - 1) * Math.pow(1 - i / length, decay);+ }+ }+ return buffer;+}++function buildFilter(context: BaseAudioContext, def: FilterEffectDef): EffectNodes {+ const node = context.createBiquadFilter();+ node.type = def.filter;+ node.frequency.value = Math.max(10, def.frequency);+ if (def.q !== undefined) node.Q.value = def.q;+ if (def.gainDb !== undefined) node.gain.value = def.gainDb;+ return { input: node, output: node };+}++function buildReverb(context: BaseAudioContext, def: ReverbEffectDef): EffectNodes {+ const input = context.createGain();+ const output = context.createGain();+ const wet = clamp01(def.wet ?? 0.35);++ const dryGain = context.createGain();+ dryGain.gain.value = 1 - wet;+ input.connect(dryGain);+ dryGain.connect(output);++ const convolver = context.createConvolver();+ convolver.buffer = makeImpulseResponse(context, def.seconds ?? 1.5, def.decay ?? 3.0);+ const wetGain = context.createGain();+ wetGain.gain.value = wet;+ input.connect(convolver);+ convolver.connect(wetGain);+ wetGain.connect(output);++ return { input, output };+}++function buildCompressor(context: BaseAudioContext, def: CompressorEffectDef): EffectNodes {+ const node = context.createDynamicsCompressor();+ if (def.thresholdDb !== undefined) node.threshold.value = def.thresholdDb;+ if (def.ratio !== undefined) node.ratio.value = Math.max(1, def.ratio);+ if (def.attack !== undefined) node.attack.value = Math.max(0, def.attack);+ if (def.release !== undefined) node.release.value = Math.max(0, def.release);+ if (def.kneeDb !== undefined) node.knee.value = Math.max(0, def.kneeDb);+ return { input: node, output: node };+}++/** Realize one effect def as a WebAudio sub-graph. */+export function buildEffectNodes(context: BaseAudioContext, def: BusEffectDef): EffectNodes {+ switch (def.type) {+ case 'filter': return buildFilter(context, def);+ case 'reverb': return buildReverb(context, def);+ case 'compressor': return buildCompressor(context, def);+ }+}++/** Normalize arbitrary JSON into a valid effect list (tolerant; drops junk). */+export function parseBusEffects(raw: unknown): BusEffectDef[] {+ if (!Array.isArray(raw)) return [];+ const out: BusEffectDef[] = [];+ for (const e of raw) {+ if (!e || typeof e !== 'object') continue;+ const t = (e as { type?: unknown }).type;+ if (t === 'filter') {+ const f = e as FilterEffectDef;+ const kinds = ['lowpass', 'highpass', 'bandpass', 'lowshelf', 'highshelf', 'peaking', 'notch'];+ if (!kinds.includes(f.filter) || typeof f.frequency !== 'number') continue;+ out.push({+ type: 'filter', filter: f.filter, frequency: f.frequency,+ ...(typeof f.q === 'number' ? { q: f.q } : {}),+ ...(typeof f.gainDb === 'number' ? { gainDb: f.gainDb } : {}),+ });+ } else if (t === 'reverb') {+ const r = e as ReverbEffectDef;+ out.push({+ type: 'reverb',+ ...(typeof r.seconds === 'number' ? { seconds: r.seconds } : {}),+ ...(typeof r.decay === 'number' ? { decay: r.decay } : {}),+ ...(typeof r.wet === 'number' ? { wet: clamp01(r.wet) } : {}),+ });+ } else if (t === 'compressor') {+ const c = e as CompressorEffectDef;+ out.push({+ type: 'compressor',+ ...(typeof c.thresholdDb === 'number' ? { thresholdDb: c.thresholdDb } : {}),+ ...(typeof c.ratio === 'number' ? { ratio: c.ratio } : {}),+ ...(typeof c.attack === 'number' ? { attack: c.attack } : {}),+ ...(typeof c.release === 'number' ? { release: c.release } : {}),+ ...(typeof c.kneeDb === 'number' ? { kneeDb: c.kneeDb } : {}),+ });+ }+ }+ return out;+}diff --git a/sdk/src/audio/WebAudioBackend.ts b/sdk/src/audio/WebAudioBackend.tsindex 7e461f501..cf8e1c8a1 100644--- a/sdk/src/audio/WebAudioBackend.ts+++ b/sdk/src/audio/WebAudioBackend.ts@@ -272,7 +272,7 @@ export class WebAudioBackend implements PlatformAudioBackend {const busName = config.bus ?? 'sfx';const bus = this.mixer_.getBus(busName) ?? this.mixer_.sfx;- poolNode.panner.connect(bus.node);+ poolNode.panner.connect(bus.input);const startOffset = config.startOffset ?? 0;source.start(0, startOffset);diff --git a/sdk/src/audio/index.ts b/sdk/src/audio/index.tsindex d37736bde..e2aae95f7 100644--- a/sdk/src/audio/index.ts+++ b/sdk/src/audio/index.ts@@ -2,7 +2,12 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamexport { Audio, AudioAPI } from './Audio';export { AudioBus, type AudioBusConfig } from './AudioBus';-export { AudioMixer, type AudioMixerConfig } from './AudioMixer';+export { AudioMixer, type AudioMixerConfig, type BusDuckRule } from './AudioMixer';+export {+ buildEffectNodes, makeImpulseResponse, parseBusEffects,+ type BusEffectDef, type FilterEffectDef, type ReverbEffectDef, type CompressorEffectDef,+ type EffectNodes,+} from './BusEffects';export { AudioPool, type PooledAudioNode } from './AudioPool';export { AudioPlugin, audioPlugin, type AudioPluginConfig } from './AudioPlugin';export { AudioSource, AudioListener, type AudioSourceData, type AudioListenerData } from './AudioComponents';diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 50ef95047..2553e48ee 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -294,6 +294,12 @@ export {AudioBus,AudioMixer,AudioPool,+ parseBusEffects,+ type BusEffectDef,+ type FilterEffectDef,+ type ReverbEffectDef,+ type CompressorEffectDef,+ type BusDuckRule,AttenuationModel,calculateAttenuation,calculatePanning,diff --git a/sdk/tests/audio-bus-effects.test.ts b/sdk/tests/audio-bus-effects.test.tsnew file mode 100644index 000000000..8c92b8bca--- /dev/null+++ b/sdk/tests/audio-bus-effects.test.ts@@ -0,0 +1,183 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * Bus DSP inserts + sidechain ducking: chain topology (input → effects → duck →+ * gain), idempotent rebuild, the ducking RMS loop, and tolerant def parsing.+ */+import { describe, it, expect, beforeEach, vi } from 'vitest';+import { AudioBus } from '../src/audio/AudioBus';+import { AudioMixer } from '../src/audio/AudioMixer';+import { parseBusEffects, makeImpulseResponse } from '../src/audio/BusEffects';++function mockParam(v = 0): any {+ return { value: v, setTargetAtTime: vi.fn() };+}++function createMockContext(): any {+ const ctx: any = {+ currentTime: 0,+ sampleRate: 48000,+ destination: {},+ createGain: vi.fn(() => ({ gain: mockParam(1), connect: vi.fn(), disconnect: vi.fn(), context: ctx })),+ createBiquadFilter: vi.fn(() => ({+ type: '', frequency: mockParam(), Q: mockParam(1), gain: mockParam(),+ connect: vi.fn(), disconnect: vi.fn(), context: ctx,+ })),+ createConvolver: vi.fn(() => ({ buffer: null, connect: vi.fn(), disconnect: vi.fn(), context: ctx })),+ createDynamicsCompressor: vi.fn(() => ({+ threshold: mockParam(-24), ratio: mockParam(12), attack: mockParam(0.003),+ release: mockParam(0.25), knee: mockParam(30),+ connect: vi.fn(), disconnect: vi.fn(), context: ctx,+ })),+ createAnalyser: vi.fn(() => ({+ fftSize: 0, connect: vi.fn(), disconnect: vi.fn(),+ getByteTimeDomainData: vi.fn(),+ })),+ createBuffer: vi.fn((channels: number, length: number, rate: number) => {+ const data = Array.from({ length: channels }, () => new Float32Array(length));+ return { length, sampleRate: rate, getChannelData: (c: number) => data[c] };+ }),+ };+ return ctx;+}++describe('AudioBus effect chain', () => {+ let ctx: any;+ let bus: AudioBus;++ beforeEach(() => {+ ctx = createMockContext();+ bus = new AudioBus(ctx, { name: 'music' });+ });++ it('wires input → duck → gain with no effects', () => {+ // Constructor gains: [0]=input, [1]=duck, [2]=output.+ const input = ctx.createGain.mock.results[0].value;+ const duck = ctx.createGain.mock.results[1].value;+ expect(input.connect).toHaveBeenCalledWith(duck);+ expect(duck.connect).toHaveBeenCalledWith(bus.node);+ });++ it('splices a filter between input and duck', () => {+ bus.setEffects([{ type: 'filter', filter: 'lowpass', frequency: 800, q: 2 }]);+ const input = ctx.createGain.mock.results[0].value;+ const duck = ctx.createGain.mock.results[1].value;+ const filter = ctx.createBiquadFilter.mock.results[0].value;+ expect(input.disconnect).toHaveBeenCalled();+ expect(input.connect).toHaveBeenLastCalledWith(filter);+ expect(filter.connect).toHaveBeenCalledWith(duck);+ expect(filter.type).toBe('lowpass');+ expect(filter.frequency.value).toBe(800);+ expect(filter.Q.value).toBe(2);+ });++ it('rebuilds idempotently and reports stored defs', () => {+ bus.setEffects([{ type: 'filter', filter: 'lowpass', frequency: 800 }]);+ bus.setEffects([{ type: 'compressor', ratio: 4 }]);+ expect(bus.effects).toEqual([{ type: 'compressor', ratio: 4 }]);+ // The replaced filter's output must have been disconnected.+ const filter = ctx.createBiquadFilter.mock.results[0].value;+ expect(filter.disconnect).toHaveBeenCalled();+ const comp = ctx.createDynamicsCompressor.mock.results[0].value;+ expect(comp.ratio.value).toBe(4);+ });++ it('reverb builds a parallel wet/dry graph feeding one output', () => {+ bus.setEffects([{ type: 'reverb', seconds: 0.5, wet: 0.25 }]);+ const conv = ctx.createConvolver.mock.results[0].value;+ expect(conv.buffer).not.toBeNull();+ // Gains: 0-2 bus, then reverb creates input/output/dry/wet (4 more).+ const gains = ctx.createGain.mock.results.map((r: any) => r.value);+ const dry = gains.find((g: any) => Math.abs(g.gain.value - 0.75) < 1e-6);+ const wet = gains.find((g: any) => Math.abs(g.gain.value - 0.25) < 1e-6);+ expect(dry).toBeDefined();+ expect(wet).toBeDefined();+ });+});++describe('AudioMixer ducking', () => {+ let ctx: any;+ let mixer: AudioMixer;++ beforeEach(() => {+ ctx = createMockContext();+ mixer = new AudioMixer(ctx);+ });++ const duckGainOf = (bus: any) => {+ // Per-bus gains are created input,duck,gain — find music's duck node by+ // walking creation order: 5 buses × 3 gains; music is the 2nd bus.+ return ctx.createGain.mock.results[1 * 3 + 1].value;+ };++ it('installs an analyser tap on the trigger bus output', () => {+ expect(mixer.setDucking('music', { trigger: 'voice', amount: 0.3 })).toBe(true);+ const analyser = ctx.createAnalyser.mock.results[0].value;+ expect(mixer.voice.node.connect).toHaveBeenCalledWith(analyser);+ expect(mixer.getDucking('music')).toEqual({ trigger: 'voice', amount: 0.3 });+ });++ it('rejects unknown buses', () => {+ expect(mixer.setDucking('nope', { trigger: 'voice', amount: 0.3 })).toBe(false);+ expect(mixer.setDucking('music', { trigger: 'nope', amount: 0.3 })).toBe(false);+ });++ it('ducks on signal and releases on silence', () => {+ mixer.setDucking('music', { trigger: 'voice', amount: 0.3, attack: 0.05, release: 0.4 });+ const analyser = ctx.createAnalyser.mock.results[0].value;+ const musicDuck = duckGainOf(mixer.music);++ // Loud trigger: time-domain bytes far from the 128 midline.+ analyser.getByteTimeDomainData.mockImplementation((buf: Uint8Array) => buf.fill(200));+ mixer.updateDucking();+ expect(musicDuck.gain.setTargetAtTime).toHaveBeenLastCalledWith(0.3, 0, 0.05);++ // Silence: bytes at the midline.+ analyser.getByteTimeDomainData.mockImplementation((buf: Uint8Array) => buf.fill(128));+ mixer.updateDucking();+ expect(musicDuck.gain.setTargetAtTime).toHaveBeenLastCalledWith(1, 0, 0.4);+ });++ it('clearing the rule disconnects the tap and restores the duck stage', () => {+ mixer.setDucking('music', { trigger: 'voice', amount: 0.3 });+ const analyser = ctx.createAnalyser.mock.results[0].value;+ mixer.setDucking('music', null);+ expect(analyser.disconnect).toHaveBeenCalled();+ expect(mixer.getDucking('music')).toBeNull();+ });+});++describe('parseBusEffects', () => {+ it('keeps valid defs and drops junk', () => {+ const parsed = parseBusEffects([+ { type: 'filter', filter: 'lowpass', frequency: 500 },+ { type: 'filter', filter: 'wave', frequency: 500 }, // bad filter kind+ { type: 'reverb', wet: 2 }, // wet clamps+ { type: 'unknown' },+ null,+ { type: 'compressor', ratio: 8 },+ ]);+ expect(parsed).toEqual([+ { type: 'filter', filter: 'lowpass', frequency: 500 },+ { type: 'reverb', wet: 1 },+ { type: 'compressor', ratio: 8 },+ ]);+ });++ it('returns [] for non-arrays', () => {+ expect(parseBusEffects(undefined)).toEqual([]);+ expect(parseBusEffects({})).toEqual([]);+ });+});++describe('makeImpulseResponse', () => {+ it('builds a stereo buffer with a decaying tail', () => {+ const ctx = createMockContext();+ const ir = makeImpulseResponse(ctx, 0.1, 3);+ expect(ctx.createBuffer).toHaveBeenCalledWith(2, 4800, 48000);+ const ch0 = ir.getChannelData(0);+ // Tail decays: late samples are bounded by early envelope.+ expect(Math.abs(ch0[ch0.length - 1])).toBeLessThanOrEqual(Math.abs(1));+ expect(ch0.length).toBe(4800);+ });+});diff --git a/sdk/tests/audio-bus.test.ts b/sdk/tests/audio-bus.test.tsindex 9556da39d..629ee6caf 100644--- a/sdk/tests/audio-bus.test.ts+++ b/sdk/tests/audio-bus.test.ts@@ -101,7 +101,7 @@ describe('AudioBus', () => {const busA = new AudioBus(context, { name: 'a' });const busB = new AudioBus(context, { name: 'b' });busA.connect(busB);- expect(busA.node.connect).toHaveBeenCalledWith(busB.node);+ expect(busA.node.connect).toHaveBeenCalledWith(busB.input);});it('should connect to a raw AudioNode', () => {@@ -117,7 +117,7 @@ describe('AudioBus', () => {const parent = new AudioBus(context, { name: 'parent' });const child = new AudioBus(context, { name: 'child' });parent.addChild(child);- expect(child.node.connect).toHaveBeenCalledWith(parent.node);+ expect(child.node.connect).toHaveBeenCalledWith(parent.input);});});});diff --git a/sdk/tests/audio-mixer.test.ts b/sdk/tests/audio-mixer.test.tsindex f0058eda4..db533fc54 100644--- a/sdk/tests/audio-mixer.test.ts+++ b/sdk/tests/audio-mixer.test.ts@@ -49,10 +49,10 @@ describe('AudioMixer', () => {it('should connect child buses to master', () => {const mixer = new AudioMixer(context);- expect(mixer.music.node.connect).toHaveBeenCalledWith(mixer.master.node);- expect(mixer.sfx.node.connect).toHaveBeenCalledWith(mixer.master.node);- expect(mixer.ui.node.connect).toHaveBeenCalledWith(mixer.master.node);- expect(mixer.voice.node.connect).toHaveBeenCalledWith(mixer.master.node);+ expect(mixer.music.node.connect).toHaveBeenCalledWith(mixer.master.input);+ expect(mixer.sfx.node.connect).toHaveBeenCalledWith(mixer.master.input);+ expect(mixer.ui.node.connect).toHaveBeenCalledWith(mixer.master.input);+ expect(mixer.voice.node.connect).toHaveBeenCalledWith(mixer.master.input);});it('should apply custom volumes', () => {@@ -101,13 +101,13 @@ describe('AudioMixer', () => {const custom = mixer.createBus({ name: 'ambient', volume: 0.6 });expect(custom.name).toBe('ambient');expect(custom.volume).toBe(0.6);- expect(custom.node.connect).toHaveBeenCalledWith(mixer.master.node);+ expect(custom.node.connect).toHaveBeenCalledWith(mixer.master.input);});it('should create a custom bus connected to specified parent', () => {const mixer = new AudioMixer(context);const custom = mixer.createBus({ name: 'ambient', parent: 'sfx' });- expect(custom.node.connect).toHaveBeenCalledWith(mixer.sfx.node);+ expect(custom.node.connect).toHaveBeenCalledWith(mixer.sfx.input);});it('should be retrievable via getBus', () => {diff --git a/sdk/tests/web-audio-backend.test.ts b/sdk/tests/web-audio-backend.test.tsindex 50fef9e23..1d19d86b6 100644--- a/sdk/tests/web-audio-backend.test.ts+++ b/sdk/tests/web-audio-backend.test.ts@@ -161,9 +161,11 @@ describe('WebAudioBackend', () => {const analyser = mockCtx.createAnalyser.mock.results[0].value;expect(analyser.fftSize).toBe(128);expect(analyser.smoothingTimeConstant).toBe(0.7);- // The master gain connects INTO the analyser (a side-branch sink).- const master = mockCtx.createGain.mock.results[0].value;- expect(master.connect).toHaveBeenCalledWith(analyser);+ // The master OUTPUT gain connects INTO the analyser (a side-branch+ // sink). A bus creates input/duck/gain in order, so master's output+ // is the third gain the context vended.+ const masterOut = mockCtx.createGain.mock.results[2].value;+ expect(masterOut.connect).toHaveBeenCalledWith(analyser);});});