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): a sound can be worth more than the one it silences
esenginefa5ddae7bc90
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 isone piece of arithmetic.** `ParticleEmitter.material` was the last authorablematerial 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.** Thebinding every skeletal runtime submits its posed geometry through was compiledonly when `ES_ENABLE_SPINE` was on — so with Spine off, DragonBones handed itsdiff --git a/docs/astro/src/content/docs/assets/audio.mdx b/docs/astro/src/content/docs/assets/audio.mdxindex 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` forfire-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.mdxindex 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.mdindex 7d3b80d89..38d7a76d1 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -845,8 +845,10 @@ getSpectrum: (out: Uint8Array) => booleangetUIVolume: () => numberinvalidateBuffer: (url: string) => booleanisBusMuted: (busName: string) => boolean+maxVoices: numbermuteBus: (busName: string, muted: boolean) => voidplayBGM: (url: string, config?: { volume?: number; fadeIn?: number; crossFade?: number; }) => void+playBuffer: (buffer: AudioBufferHandle, config?: PlayConfig) => AudioHandleplaySFX: (url: string, config?: { volume?: number; pitch?: number; pan?: number; priority?: number; }) => AudioHandleplayTrack: (url: string, config?: PlayConfig) => Promise<AudioHandle | null>preload: (url: string) => Promise<void>@@ -861,6 +863,7 @@ setBusDucking: (target: string, rule: BusDuckRule | null) => booleansetBusEffects: (busName: string, effects: BusEffectDef[]) => booleansetBusVolume: (busName: string, volume: number) => voidsetMasterVolume: (volume: number) => void+setMaxVoices: (max: number) => voidsetMusicVolume: (volume: number) => voidsetRefResolver: (resolver: ((ref: string) => string) | null) => voidsetSFXVolume: (volume: number) => void@@ -1013,6 +1016,7 @@ static prototype: AudioPool## AudioProjectConfig — interface @experimental```buses: AudioBusDecl[] | undefined+maxVoices: number | undefined```## AudioSource — const @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex a2a19533b..78aaca113 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -845,8 +845,10 @@ getSpectrum: (out: Uint8Array) => booleangetUIVolume: () => numberinvalidateBuffer: (url: string) => booleanisBusMuted: (busName: string) => boolean+maxVoices: numbermuteBus: (busName: string, muted: boolean) => voidplayBGM: (url: string, config?: { volume?: number; fadeIn?: number; crossFade?: number; }) => void+playBuffer: (buffer: AudioBufferHandle, config?: PlayConfig) => AudioHandleplaySFX: (url: string, config?: { volume?: number; pitch?: number; pan?: number; priority?: number; }) => AudioHandleplayTrack: (url: string, config?: PlayConfig) => Promise<AudioHandle | null>preload: (url: string) => Promise<void>@@ -861,6 +863,7 @@ setBusDucking: (target: string, rule: BusDuckRule | null) => booleansetBusEffects: (busName: string, effects: BusEffectDef[]) => booleansetBusVolume: (busName: string, volume: number) => voidsetMasterVolume: (volume: number) => void+setMaxVoices: (max: number) => voidsetMusicVolume: (volume: number) => voidsetRefResolver: (resolver: ((ref: string) => string) | null) => voidsetSFXVolume: (volume: number) => void@@ -1013,6 +1016,7 @@ static prototype: AudioPool## AudioProjectConfig — interface @experimental```buses: AudioBusDecl[] | undefined+maxVoices: number | undefined```## AudioSource — const @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex ed2f8c0ee..2c35060fd 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -840,8 +840,10 @@ getSpectrum: (out: Uint8Array) => booleangetUIVolume: () => numberinvalidateBuffer: (url: string) => booleanisBusMuted: (busName: string) => boolean+maxVoices: numbermuteBus: (busName: string, muted: boolean) => voidplayBGM: (url: string, config?: { volume?: number; fadeIn?: number; crossFade?: number; }) => void+playBuffer: (buffer: AudioBufferHandle, config?: PlayConfig) => AudioHandleplaySFX: (url: string, config?: { volume?: number; pitch?: number; pan?: number; priority?: number; }) => AudioHandleplayTrack: (url: string, config?: PlayConfig) => Promise<AudioHandle | null>preload: (url: string) => Promise<void>@@ -856,6 +858,7 @@ setBusDucking: (target: string, rule: BusDuckRule | null) => booleansetBusEffects: (busName: string, effects: BusEffectDef[]) => booleansetBusVolume: (busName: string, volume: number) => voidsetMasterVolume: (volume: number) => void+setMaxVoices: (max: number) => voidsetMusicVolume: (volume: number) => voidsetRefResolver: (resolver: ((ref: string) => string) | null) => voidsetSFXVolume: (volume: number) => void@@ -1008,6 +1011,7 @@ static prototype: AudioPool## AudioProjectConfig — interface @experimental```buses: AudioBusDecl[] | undefined+maxVoices: number | undefined```## AudioSource — const @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 52b1c1dfe..98c744aff 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -840,8 +840,10 @@ getSpectrum: (out: Uint8Array) => booleangetUIVolume: () => numberinvalidateBuffer: (url: string) => booleanisBusMuted: (busName: string) => boolean+maxVoices: numbermuteBus: (busName: string, muted: boolean) => voidplayBGM: (url: string, config?: { volume?: number; fadeIn?: number; crossFade?: number; }) => void+playBuffer: (buffer: AudioBufferHandle, config?: PlayConfig) => AudioHandleplaySFX: (url: string, config?: { volume?: number; pitch?: number; pan?: number; priority?: number; }) => AudioHandleplayTrack: (url: string, config?: PlayConfig) => Promise<AudioHandle | null>preload: (url: string) => Promise<void>@@ -856,6 +858,7 @@ setBusDucking: (target: string, rule: BusDuckRule | null) => booleansetBusEffects: (busName: string, effects: BusEffectDef[]) => booleansetBusVolume: (busName: string, volume: number) => voidsetMasterVolume: (volume: number) => void+setMaxVoices: (max: number) => voidsetMusicVolume: (volume: number) => voidsetRefResolver: (resolver: ((ref: string) => string) | null) => voidsetSFXVolume: (volume: number) => void@@ -1008,6 +1011,7 @@ static prototype: AudioPool## AudioProjectConfig — interface @experimental```buses: AudioBusDecl[] | undefined+maxVoices: number | undefined```## AudioSource — const @experimentaldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 15e30e913..88a2ae3a0 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -840,8 +840,10 @@ getSpectrum: (out: Uint8Array) => booleangetUIVolume: () => numberinvalidateBuffer: (url: string) => booleanisBusMuted: (busName: string) => boolean+maxVoices: numbermuteBus: (busName: string, muted: boolean) => voidplayBGM: (url: string, config?: { volume?: number; fadeIn?: number; crossFade?: number; }) => void+playBuffer: (buffer: AudioBufferHandle, config?: PlayConfig) => AudioHandleplaySFX: (url: string, config?: { volume?: number; pitch?: number; pan?: number; priority?: number; }) => AudioHandleplayTrack: (url: string, config?: PlayConfig) => Promise<AudioHandle | null>preload: (url: string) => Promise<void>@@ -856,6 +858,7 @@ setBusDucking: (target: string, rule: BusDuckRule | null) => booleansetBusEffects: (busName: string, effects: BusEffectDef[]) => booleansetBusVolume: (busName: string, volume: number) => voidsetMasterVolume: (volume: number) => void+setMaxVoices: (max: number) => voidsetMusicVolume: (volume: number) => voidsetRefResolver: (resolver: ((ref: string) => string) | null) => voidsetSFXVolume: (volume: number) => void@@ -1008,6 +1011,7 @@ static prototype: AudioPool## AudioProjectConfig — interface @experimental```buses: AudioBusDecl[] | undefined+maxVoices: number | undefined```## AudioSource — const @experimentaldiff --git a/sdk/src/audio/Audio.ts b/sdk/src/audio/Audio.tsindex 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.tsindex 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.tsindex 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 appliesif (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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.mjsindex 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',