Skip to content

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.

feat(audio): a sound can be worth more than the one it silences

esenginefa5ddae7bc90
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b58eb8653..0d9e2ed5d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,15 @@ published separately; it ships inside the editor.
### Changed
+- **`AudioSource.priority` decides something now: there is a voice ceiling.**
+ Nothing limited how many sounds played at once, so the field described an
+ ordering that never happened. 32 voices by default (`features.audio.maxVoices`
+ in `project.esproject` sets your own; 0 = no cap). When the pool is full the
+ sound worth least is dropped for one worth more, ties go to the older voice —
+ which is what keeps a repeated sound audible — and a new sound worth less than
+ everything already playing is simply not started, returning a handle that
+ reports itself as not playing rather than throwing.
+
- **A particle can be drawn with a material, and the billboard it is drawn on is
one piece of arithmetic.** `ParticleEmitter.material` was the last authorable
material field with nothing reading it. A material is compiled per vertex
@@ -144,6 +153,13 @@ published separately; it ships inside the editor.
### Fixed
+- **An `AudioSource` in the scene was outside everything the audio API decides.**
+ It was played straight at the backend, so on a backend with no mixer graph —
+ WeChat, a device — the bus volume and mute the API folds into each voice never
+ reached it: turning the sfx bus down left every scene sound at full volume. It
+ goes through `Audio.playBuffer` now, the same door a scripted `playSFX` comes
+ through, which is also how it came to be counted against the voice cap.
+
- **A build with DragonBones but no Spine had no way to draw a skeleton.** The
binding every skeletal runtime submits its posed geometry through was compiled
only when `ES_ENABLE_SPINE` was on — so with Spine off, DragonBones handed its
diff --git a/docs/astro/src/content/docs/assets/audio.mdx b/docs/astro/src/content/docs/assets/audio.mdx
index f4ee1c0ce..d6a56a9da 100644
--- a/docs/astro/src/content/docs/assets/audio.mdx
+++ b/docs/astro/src/content/docs/assets/audio.mdx
@@ -313,7 +313,11 @@ const pan = calculatePanning(600, 0, 0, 0, 1000); // 0.6 — to the right
- **Separate buses** (`music` / `sfx` / `ui` / `voice`) so players can mix them,
and drive everything from `master`.
- **Cap simultaneous sounds** with `priority` on `AudioSource` so important sounds
- win when the voice pool is full.
+ win when the voice pool is full. The ceiling is 32 voices by default; set your
+ own with `features.audio.maxVoices` in `project.esproject` (0 = no cap). When
+ the pool is full the sound worth least is dropped for one worth more, ties go
+ to the older voice, and a new sound worth less than everything playing is
+ simply not started.
- **Use `AudioSource` (declarative)** for world/object sounds and `playSFX` for
fire-and-forget UI/gameplay one-shots.
diff --git a/docs/astro/src/content/docs/zh-cn/assets/audio.mdx b/docs/astro/src/content/docs/zh-cn/assets/audio.mdx
index 4b99e0395..0924780c9 100644
--- a/docs/astro/src/content/docs/zh-cn/assets/audio.mdx
+++ b/docs/astro/src/content/docs/zh-cn/assets/audio.mdx
@@ -292,6 +292,9 @@ const pan = calculatePanning(600, 0, 0, 0, 1000); // 0.6 — to the right
- **在手势上开始**——浏览器在第一次用户输入前会屏蔽音频。
- **分开总线**(`music` / `sfx` / `ui` / `voice`)让玩家能各自调节,并统一由 `master` 驱动。
- 用 `AudioSource` 上的 `priority` **限制同时播放的声音数**,声部池满时重要的声音才胜出。
+ 上限默认 32 个声部,可用 `project.esproject` 的 `features.audio.maxVoices` 自己定(0 = 不限)。
+ 池满时最不值钱的那个被让位给更重要的,同优先级让位给更早的;比场上任何一个都不值钱的新声音,
+ 则根本不会开始。
- 世界/物体声音**用 `AudioSource`(声明式)**,一次性的 UI/玩法音效用 `playSFX`。
## 参见
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 7d3b80d89..38d7a76d1 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -845,8 +845,10 @@ getSpectrum: (out: Uint8Array) => boolean
getUIVolume: () => number
invalidateBuffer: (url: string) => boolean
isBusMuted: (busName: string) => boolean
+maxVoices: number
muteBus: (busName: string, muted: boolean) => void
playBGM: (url: string, config?: { volume?: number; fadeIn?: number; crossFade?: number; }) => void
+playBuffer: (buffer: AudioBufferHandle, config?: PlayConfig) => AudioHandle
playSFX: (url: string, config?: { volume?: number; pitch?: number; pan?: number; priority?: number; }) => AudioHandle
playTrack: (url: string, config?: PlayConfig) => Promise<AudioHandle | null>
preload: (url: string) => Promise<void>
@@ -861,6 +863,7 @@ setBusDucking: (target: string, rule: BusDuckRule | null) => boolean
setBusEffects: (busName: string, effects: BusEffectDef[]) => boolean
setBusVolume: (busName: string, volume: number) => void
setMasterVolume: (volume: number) => void
+setMaxVoices: (max: number) => void
setMusicVolume: (volume: number) => void
setRefResolver: (resolver: ((ref: string) => string) | null) => void
setSFXVolume: (volume: number) => void
@@ -1013,6 +1016,7 @@ static prototype: AudioPool
## AudioProjectConfig — interface @experimental
```
buses: AudioBusDecl[] | undefined
+maxVoices: number | undefined
```
## AudioSource — const @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index a2a19533b..78aaca113 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -845,8 +845,10 @@ getSpectrum: (out: Uint8Array) => boolean
getUIVolume: () => number
invalidateBuffer: (url: string) => boolean
isBusMuted: (busName: string) => boolean
+maxVoices: number
muteBus: (busName: string, muted: boolean) => void
playBGM: (url: string, config?: { volume?: number; fadeIn?: number; crossFade?: number; }) => void
+playBuffer: (buffer: AudioBufferHandle, config?: PlayConfig) => AudioHandle
playSFX: (url: string, config?: { volume?: number; pitch?: number; pan?: number; priority?: number; }) => AudioHandle
playTrack: (url: string, config?: PlayConfig) => Promise<AudioHandle | null>
preload: (url: string) => Promise<void>
@@ -861,6 +863,7 @@ setBusDucking: (target: string, rule: BusDuckRule | null) => boolean
setBusEffects: (busName: string, effects: BusEffectDef[]) => boolean
setBusVolume: (busName: string, volume: number) => void
setMasterVolume: (volume: number) => void
+setMaxVoices: (max: number) => void
setMusicVolume: (volume: number) => void
setRefResolver: (resolver: ((ref: string) => string) | null) => void
setSFXVolume: (volume: number) => void
@@ -1013,6 +1016,7 @@ static prototype: AudioPool
## AudioProjectConfig — interface @experimental
```
buses: AudioBusDecl[] | undefined
+maxVoices: number | undefined
```
## AudioSource — const @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index ed2f8c0ee..2c35060fd 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -840,8 +840,10 @@ getSpectrum: (out: Uint8Array) => boolean
getUIVolume: () => number
invalidateBuffer: (url: string) => boolean
isBusMuted: (busName: string) => boolean
+maxVoices: number
muteBus: (busName: string, muted: boolean) => void
playBGM: (url: string, config?: { volume?: number; fadeIn?: number; crossFade?: number; }) => void
+playBuffer: (buffer: AudioBufferHandle, config?: PlayConfig) => AudioHandle
playSFX: (url: string, config?: { volume?: number; pitch?: number; pan?: number; priority?: number; }) => AudioHandle
playTrack: (url: string, config?: PlayConfig) => Promise<AudioHandle | null>
preload: (url: string) => Promise<void>
@@ -856,6 +858,7 @@ setBusDucking: (target: string, rule: BusDuckRule | null) => boolean
setBusEffects: (busName: string, effects: BusEffectDef[]) => boolean
setBusVolume: (busName: string, volume: number) => void
setMasterVolume: (volume: number) => void
+setMaxVoices: (max: number) => void
setMusicVolume: (volume: number) => void
setRefResolver: (resolver: ((ref: string) => string) | null) => void
setSFXVolume: (volume: number) => void
@@ -1008,6 +1011,7 @@ static prototype: AudioPool
## AudioProjectConfig — interface @experimental
```
buses: AudioBusDecl[] | undefined
+maxVoices: number | undefined
```
## AudioSource — const @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 52b1c1dfe..98c744aff 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -840,8 +840,10 @@ getSpectrum: (out: Uint8Array) => boolean
getUIVolume: () => number
invalidateBuffer: (url: string) => boolean
isBusMuted: (busName: string) => boolean
+maxVoices: number
muteBus: (busName: string, muted: boolean) => void
playBGM: (url: string, config?: { volume?: number; fadeIn?: number; crossFade?: number; }) => void
+playBuffer: (buffer: AudioBufferHandle, config?: PlayConfig) => AudioHandle
playSFX: (url: string, config?: { volume?: number; pitch?: number; pan?: number; priority?: number; }) => AudioHandle
playTrack: (url: string, config?: PlayConfig) => Promise<AudioHandle | null>
preload: (url: string) => Promise<void>
@@ -856,6 +858,7 @@ setBusDucking: (target: string, rule: BusDuckRule | null) => boolean
setBusEffects: (busName: string, effects: BusEffectDef[]) => boolean
setBusVolume: (busName: string, volume: number) => void
setMasterVolume: (volume: number) => void
+setMaxVoices: (max: number) => void
setMusicVolume: (volume: number) => void
setRefResolver: (resolver: ((ref: string) => string) | null) => void
setSFXVolume: (volume: number) => void
@@ -1008,6 +1011,7 @@ static prototype: AudioPool
## AudioProjectConfig — interface @experimental
```
buses: AudioBusDecl[] | undefined
+maxVoices: number | undefined
```
## AudioSource — const @experimental
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 15e30e913..88a2ae3a0 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -840,8 +840,10 @@ getSpectrum: (out: Uint8Array) => boolean
getUIVolume: () => number
invalidateBuffer: (url: string) => boolean
isBusMuted: (busName: string) => boolean
+maxVoices: number
muteBus: (busName: string, muted: boolean) => void
playBGM: (url: string, config?: { volume?: number; fadeIn?: number; crossFade?: number; }) => void
+playBuffer: (buffer: AudioBufferHandle, config?: PlayConfig) => AudioHandle
playSFX: (url: string, config?: { volume?: number; pitch?: number; pan?: number; priority?: number; }) => AudioHandle
playTrack: (url: string, config?: PlayConfig) => Promise<AudioHandle | null>
preload: (url: string) => Promise<void>
@@ -856,6 +858,7 @@ setBusDucking: (target: string, rule: BusDuckRule | null) => boolean
setBusEffects: (busName: string, effects: BusEffectDef[]) => boolean
setBusVolume: (busName: string, volume: number) => void
setMasterVolume: (volume: number) => void
+setMaxVoices: (max: number) => void
setMusicVolume: (volume: number) => void
setRefResolver: (resolver: ((ref: string) => string) | null) => void
setSFXVolume: (volume: number) => void
@@ -1008,6 +1011,7 @@ static prototype: AudioPool
## AudioProjectConfig — interface @experimental
```
buses: AudioBusDecl[] | undefined
+maxVoices: number | undefined
```
## AudioSource — const @experimental
diff --git a/sdk/src/audio/Audio.ts b/sdk/src/audio/Audio.ts
index d1e8fd9c7..dc23110b8 100644
--- a/sdk/src/audio/Audio.ts
+++ b/sdk/src/audio/Audio.ts
@@ -40,11 +40,36 @@ export interface AudioBufferStats {
* grab it with `app.getResource(Audio)` outside ECS code.
*/
/** A playing voice this API owns the volume of: base × bus gain × fade. */
+/**
+ * How many voices sound at once before `priority` decides. Beyond a couple of
+ * dozen a listener hears loudness, not sounds, and a phone pays for every one.
+ */
+const DEFAULT_MAX_VOICES = 32;
+
+/** The answer to "play this" when the pool is full and this voice lost: a handle
+ * that behaves like one whose sound already ended, so no caller special-cases it. */
+function silentHandle(): AudioHandle {
+ return {
+ id: 0,
+ stop() {}, pause() {}, resume() {},
+ setVolume() {}, setPan() {}, setLoop() {}, setPlaybackRate() {},
+ get isPlaying() { return false; },
+ get currentTime() { return 0; },
+ get duration() { return 0; },
+ };
+}
+
interface SoftVoice {
handle: AudioHandle;
bus: string;
base: number;
fade: number;
+ /** What this voice is worth when the pool is full — higher survives. */
+ priority: number;
+ /** Play order. A counter, not a clock: "older" has to be answered the same
+ * way twice for a test to pin the rule down, and two voices started in one
+ * frame share a timestamp. */
+ seq: number;
}
/** One volume ramp in flight: a linear interpolation the frame loop advances. */
@@ -85,6 +110,13 @@ export class AudioAPI {
private readonly softBuses_ = new Map<string, { volume: number; muted: boolean }>();
/** Voices whose volume this API computes: base × bus gain × fade. */
private softVoices_: SoftVoice[] = [];
+ /**
+ * How many voices may sound at once. There has to be a ceiling for
+ * `priority` to mean anything: without one nothing is ever dropped, and the
+ * field only describes an ordering that never happens.
+ */
+ private maxVoices_ = DEFAULT_MAX_VOICES;
+ private voiceSeq_ = 0;
// Handles mid fade-out. A cancelled fade RAF never reaches its handle.stop(),
// so a rapid crossfade would orphan the outgoing track (playing forever) —
// {@link cancelFades_} stops these when it tears the animations down.
@@ -530,17 +562,59 @@ export class AudioAPI {
/** Play through the backend as a tracked voice, so bus gain and fades have
* one place to act — on every platform, mixer graph or not. */
+ /**
+ * Play an already-resolved buffer. The one door every voice comes through —
+ * a scripted `playSFX`, a `playBGM`, an `AudioSource` in the scene — so the
+ * bus gain a backend without a mixer graph cannot apply, and the voice cap
+ * `priority` is measured against, are decided once for all of them.
+ */
+ playBuffer(buffer: AudioBufferHandle, config?: PlayConfig): AudioHandle {
+ if (config?.bus) this.ensureBus(config.bus);
+ return this.playVoice_(buffer, config ?? {});
+ }
+
+ /** The voice ceiling; 0 or less means no cap. @see playBuffer */
+ setMaxVoices(max: number): void {
+ this.maxVoices_ = Number.isFinite(max) ? Math.floor(max) : DEFAULT_MAX_VOICES;
+ }
+
+ get maxVoices(): number { return this.maxVoices_; }
+
private playVoice_(buffer: AudioBufferHandle, config: PlayConfig): AudioHandle {
const bus = config.bus ?? 'sfx';
const base = config.volume ?? 1;
+ const priority = config.priority ?? 0;
+ if (!this.makeRoomForVoice_(priority)) return silentHandle();
const handle = this.backend_.play(buffer, { ...config, volume: base * this.softGain_(bus) });
- this.softVoices_.push({ handle, bus, base, fade: 1 });
- if (this.softVoices_.length > 64) {
- this.softVoices_ = this.softVoices_.filter((v) => v.handle.isPlaying);
- }
+ this.softVoices_.push({ handle, bus, base, fade: 1, priority, seq: this.voiceSeq_++ });
return handle;
}
+ /**
+ * Drop the least valuable voice if the pool is full, so a new one of
+ * @p priority can sound. False when the new voice is the least valuable
+ * itself. Ties go to the OLDER voice, which is what keeps a repeated sound
+ * audible: every shot of a machine gun is worth the same.
+ */
+ private makeRoomForVoice_(priority: number): boolean {
+ this.softVoices_ = this.softVoices_.filter(
+ (v) => v.handle.isPlaying || this.fadeOf_(v) !== null,
+ );
+ if (this.maxVoices_ <= 0 || this.softVoices_.length < this.maxVoices_) return true;
+
+ let weakest: SoftVoice | null = null;
+ for (const v of this.softVoices_) {
+ if (!weakest || v.priority < weakest.priority
+ || (v.priority === weakest.priority && v.seq < weakest.seq)) {
+ weakest = v;
+ }
+ }
+ if (!weakest || weakest.priority > priority) return false;
+ weakest.handle.stop();
+ this.softVoices_ = this.softVoices_.filter((v) => v !== weakest);
+ return true;
+ }
+
muteBus(busName: string, muted: boolean): void {
if (!this.mixer_) {
this.setSoftBus_(busName, { muted });
@@ -665,7 +739,7 @@ export class AudioAPI {
private voiceOf_(handle: AudioHandle, base: number, bus: string): SoftVoice {
const found = this.softVoices_.find((v) => v.handle === handle);
if (found) return found;
- const voice: SoftVoice = { handle, bus, base, fade: 1 };
+ const voice: SoftVoice = { handle, bus, base, fade: 1, priority: 0, seq: this.voiceSeq_++ };
this.softVoices_.push(voice);
return voice;
}
diff --git a/sdk/src/audio/AudioPlugin.ts b/sdk/src/audio/AudioPlugin.ts
index c01ccaab9..35d93b5c6 100644
--- a/sdk/src/audio/AudioPlugin.ts
+++ b/sdk/src/audio/AudioPlugin.ts
@@ -129,11 +129,15 @@ export class AudioPlugin implements Plugin {
if (source.playOnAwake && !playedEntities.has(id) && !activeSourceHandles.has(id) && backend.isReady) {
const buffer = audioAPI.getBufferHandle(source.clip);
if (buffer) {
- const handle = backend.play(buffer, {
+ // Through the API, not straight at the backend: the
+ // voice cap and the soft bus gain are decided there,
+ // and a sound outside that door gets neither.
+ const handle = audioAPI.playBuffer(buffer, {
bus: source.bus,
volume: source.volume,
loop: source.loop,
playbackRate: source.pitch,
+ priority: source.priority,
});
activeSourceHandles.set(id, handle);
playedEntities.add(id);
diff --git a/sdk/src/audio/AudioProjectConfig.ts b/sdk/src/audio/AudioProjectConfig.ts
index 3c117af98..20260465e 100644
--- a/sdk/src/audio/AudioProjectConfig.ts
+++ b/sdk/src/audio/AudioProjectConfig.ts
@@ -25,6 +25,9 @@ export interface AudioBusDecl {
export interface AudioProjectConfig {
buses?: AudioBusDecl[];
+ /** How many voices may sound at once before `priority` decides which is
+ * dropped. 0 or less means no cap. */
+ maxVoices?: number;
}
const clamp01 = (v: number) => Math.max(0, Math.min(1, v));
@@ -54,7 +57,12 @@ export function parseAudioProjectConfig(raw: unknown): AudioProjectConfig {
}
buses.push(decl);
}
- return buses.length > 0 ? { buses } : {};
+ const config: AudioProjectConfig = buses.length > 0 ? { buses } : {};
+ const maxVoices = (raw as { maxVoices?: unknown } | undefined)?.maxVoices;
+ if (typeof maxVoices === 'number' && Number.isFinite(maxVoices)) {
+ config.maxVoices = Math.floor(maxVoices);
+ }
+ return config;
}
/**
@@ -63,6 +71,9 @@ export function parseAudioProjectConfig(raw: unknown): AudioProjectConfig {
* bus with no `duck` clears any prior rule, so the editor can re-apply live.
*/
export function applyAudioProjectConfig(audio: AudioAPI, config: AudioProjectConfig | undefined): void {
+ // Before the buses: the cap is the API's own and applies on every backend,
+ // while the loop below returns early where there is no mixer graph.
+ if (config?.maxVoices !== undefined) audio.setMaxVoices(config.maxVoices);
for (const bus of config?.buses ?? []) {
if (!audio.ensureBus(bus.name, bus.parent)) return; // no mixer: nothing applies
if (bus.volume !== undefined) audio.setBusVolume(bus.name, bus.volume);
diff --git a/sdk/tests/audio-project-config.test.ts b/sdk/tests/audio-project-config.test.ts
index f43f360dc..1374b8170 100644
--- a/sdk/tests/audio-project-config.test.ts
+++ b/sdk/tests/audio-project-config.test.ts
@@ -16,6 +16,7 @@ function mockAudioApi() {
muteBus: vi.fn(),
setBusEffects: vi.fn(() => true),
setBusDucking: vi.fn(() => true),
+ setMaxVoices: vi.fn(),
} as unknown as AudioAPI;
}
@@ -85,4 +86,19 @@ describe('applyAudioProjectConfig', () => {
applyAudioProjectConfig(audio, undefined);
expect(audio.ensureBus).not.toHaveBeenCalled();
});
+
+ // The cap is the API's own, not the mixer graph's — a project that declares
+ // one gets it on WeChat and on a device, where the bus loop returns early.
+ it('applies the voice cap even where there is no mixer to apply a bus with', () => {
+ const audio = mockAudioApi();
+ (audio.ensureBus as ReturnType<typeof vi.fn>).mockReturnValue(false);
+ applyAudioProjectConfig(audio, { maxVoices: 8, buses: [{ name: 'music', volume: 0.5 }] });
+ expect(audio.setMaxVoices).toHaveBeenCalledWith(8);
+ expect(audio.setBusVolume).not.toHaveBeenCalled();
+ });
+
+ it('reads a declared voice cap and ignores a junk one', () => {
+ expect(parseAudioProjectConfig({ maxVoices: 12 }).maxVoices).toBe(12);
+ expect(parseAudioProjectConfig({ maxVoices: 'lots' }).maxVoices).toBeUndefined();
+ });
});
diff --git a/sdk/tests/audio-source-through-api.test.ts b/sdk/tests/audio-source-through-api.test.ts
new file mode 100644
index 000000000..f821c2a84
--- /dev/null
+++ b/sdk/tests/audio-source-through-api.test.ts
@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file audio-source-through-api.test.ts
+ * @brief A scene's sound comes through the same door a scripted one does.
+ *
+ * An AudioSource that reached the backend directly was outside
+ * everything the API decides for a voice: the bus gain a backend with
+ * no mixer graph can only get from here (WeChat, a device), and the
+ * voice cap its `priority` is measured against.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { AudioHandle, PlatformAudioBackend } from '../src/audio/PlatformAudioBackend';
+
+const backend = {
+ name: 'Mock',
+ mixer: null,
+ isReady: true,
+ initialize: vi.fn().mockResolvedValue(undefined),
+ ensureResumed: vi.fn().mockResolvedValue(undefined),
+ loadBuffer: vi.fn().mockResolvedValue({ id: 1, duration: 1 }),
+ unloadBuffer: vi.fn(),
+ play: vi.fn(),
+ suspend: vi.fn(), resume: vi.fn(), dispose: vi.fn(),
+} as unknown as PlatformAudioBackend;
+
+vi.mock('../src/platform/base', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('../src/platform/base')>()),
+ platformCreateAudioBackend: () => backend,
+ platformOnMemoryWarning: () => () => {},
+}));
+
+const { App } = await import('../src/app/app');
+const { AudioPlugin } = await import('../src/audio/AudioPlugin');
+const { Audio } = await import('../src/audio/Audio');
+const { AudioSource } = await import('../src/audio/AudioComponents');
+
+function playingHandle(): AudioHandle {
+ return {
+ id: 1, stop: vi.fn(), pause: vi.fn(), resume: vi.fn(),
+ setVolume: vi.fn(), setPan: vi.fn(), setLoop: vi.fn(), setPlaybackRate: vi.fn(),
+ isPlaying: true, currentTime: 0, duration: 1,
+ };
+}
+
+/** An app with the plugin built and one clip already resident. */
+async function appWithClip() {
+ const app = App.new();
+ app.addPlugin(new AudioPlugin());
+ const audio = app.getResource(Audio);
+ await audio.preload('boom.wav');
+ return { app, audio };
+}
+
+describe('an AudioSource in the scene', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ (backend.play as ReturnType<typeof vi.fn>).mockImplementation(() => playingHandle());
+ });
+
+ it('is played through the API, so a soft bus reaches it', async () => {
+ const { app, audio } = await appWithClip();
+ audio.setSFXVolume(0.5);
+ const e = app.world.spawn();
+ app.world.insert(e, AudioSource, { clip: 'boom.wav', playOnAwake: true, volume: 1 });
+ await app.tick(1 / 60);
+ expect(backend.play).toHaveBeenCalledTimes(1);
+ // 1 (the source's own) x 0.5 (the sfx bus, folded in because there is no
+ // mixer graph to apply it). Straight at the backend this was 1.
+ expect((backend.play as ReturnType<typeof vi.fn>).mock.calls[0]![1].volume).toBeCloseTo(0.5, 6);
+ });
+
+ it('is counted against the voice cap, at the priority it declares', async () => {
+ const { app, audio } = await appWithClip();
+ audio.setMaxVoices(1);
+ const loud = app.world.spawn();
+ app.world.insert(loud, AudioSource, { clip: 'boom.wav', playOnAwake: true, priority: 9 });
+ await app.tick(1 / 60);
+ const quiet = app.world.spawn();
+ app.world.insert(quiet, AudioSource, { clip: 'boom.wav', playOnAwake: true, priority: 1 });
+ await app.tick(1 / 60);
+ // The second one is worth less than the voice already sounding, so it is
+ // refused rather than silencing it.
+ expect(backend.play).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/sdk/tests/audio-voice-cap.test.ts b/sdk/tests/audio-voice-cap.test.ts
new file mode 100644
index 000000000..017778e5e
--- /dev/null
+++ b/sdk/tests/audio-voice-cap.test.ts
@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file audio-voice-cap.test.ts
+ * @brief Which sound is dropped when they cannot all be heard.
+ *
+ * `priority` only means something where there is a ceiling: without one
+ * nothing is ever dropped and the field describes an ordering that never
+ * happens. These pin down the ordering itself — who survives, who is
+ * refused, and that a refusal is a handle rather than a crash.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { AudioAPI } from '../src/audio/Audio';
+import type { PlatformAudioBackend, AudioHandle, AudioBufferHandle } from '../src/audio/PlatformAudioBackend';
+
+function handleThatPlays(): AudioHandle {
+ let playing = true;
+ return {
+ id: 1,
+ stop: vi.fn(() => { playing = false; }),
+ pause: vi.fn(), resume: vi.fn(),
+ setVolume: vi.fn(), setPan: vi.fn(), setLoop: vi.fn(), setPlaybackRate: vi.fn(),
+ get isPlaying() { return playing; },
+ currentTime: 0,
+ duration: 1,
+ };
+}
+
+function backendCounting(): PlatformAudioBackend & { handles: AudioHandle[] } {
+ const handles: AudioHandle[] = [];
+ return {
+ name: 'Counting',
+ initialize: vi.fn().mockResolvedValue(undefined),
+ ensureResumed: vi.fn().mockResolvedValue(undefined),
+ loadBuffer: vi.fn(), loadBufferFromData: vi.fn(), unloadBuffer: vi.fn(),
+ play: vi.fn(() => { const h = handleThatPlays(); handles.push(h); return h; }),
+ suspend: vi.fn(), resume: vi.fn(), dispose: vi.fn(),
+ handles,
+ } as unknown as PlatformAudioBackend & { handles: AudioHandle[] };
+}
+
+const BUF = { id: 1, duration: 1, bytes: 0 } as AudioBufferHandle;
+
+describe('the voice cap', () => {
+ let backend: PlatformAudioBackend & { handles: AudioHandle[] };
+ let audio: AudioAPI;
+
+ beforeEach(() => {
+ backend = backendCounting();
+ audio = new AudioAPI(backend, null);
+ audio.setMaxVoices(3);
+ });
+
+ it('plays freely until the pool is full', () => {
+ for (let i = 0; i < 3; i++) expect(audio.playBuffer(BUF).isPlaying).toBe(true);
+ expect(backend.play).toHaveBeenCalledTimes(3);
+ });
+
+ it('refuses the sound worth least, rather than silencing what is worth more', () => {
+ for (let i = 0; i < 3; i++) audio.playBuffer(BUF, { priority: 5 });
+ const loser = audio.playBuffer(BUF, { priority: 1 });
+ expect(loser.isPlaying).toBe(false);
+ expect(backend.play).toHaveBeenCalledTimes(3);
+ for (const h of backend.handles) expect(h.stop).not.toHaveBeenCalled();
+ });
+
+ it('drops the weakest voice for one worth more', () => {
+ audio.playBuffer(BUF, { priority: 1 });
+ audio.playBuffer(BUF, { priority: 9 });
+ audio.playBuffer(BUF, { priority: 9 });
+ expect(audio.playBuffer(BUF, { priority: 5 }).isPlaying).toBe(true);
+ expect(backend.handles[0]!.stop).toHaveBeenCalled();
+ expect(backend.handles[1]!.stop).not.toHaveBeenCalled();
+ });
+
+ it('breaks a tie by age, so a repeated sound stays audible', () => {
+ for (let i = 0; i < 3; i++) audio.playBuffer(BUF, { priority: 5 });
+ audio.playBuffer(BUF, { priority: 5 });
+ expect(backend.handles[0]!.stop).toHaveBeenCalled();
+ expect(backend.handles[1]!.stop).not.toHaveBeenCalled();
+ });
+
+ it('lets a voice that already ended free its slot', () => {
+ for (let i = 0; i < 3; i++) audio.playBuffer(BUF, { priority: 9 });
+ backend.handles[1]!.stop(); // as if the sound ran out
+ expect(audio.playBuffer(BUF, { priority: 1 }).isPlaying).toBe(true);
+ });
+
+ it('has no ceiling at all when told so', () => {
+ audio.setMaxVoices(0);
+ for (let i = 0; i < 50; i++) audio.playBuffer(BUF, { priority: 0 });
+ expect(backend.play).toHaveBeenCalledTimes(50);
+ });
+});
diff --git a/tools/check-component-fields.mjs b/tools/check-component-fields.mjs
index 385adac97..f639ba38a 100644
--- a/tools/check-component-fields.mjs
+++ b/tools/check-component-fields.mjs
@@ -28,8 +28,6 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
* intended state: a field that earns an entry here is work, not permission.
*/
const DECLARED_GAPS = {
- 'AudioSource.priority': 'nothing limits how many sources play at once, so there is'
- + ' never a moment where one has to be dropped in favour of another',
'CacheAsBitmap.enabled': 'the component is declared and nothing renders a subtree to a'
+ ' texture to draw it as one quad — the four fields below are the same gap',
'CacheAsBitmap.dirty': 'see CacheAsBitmap.enabled',