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
fix(audio): isolate plugin cleanup by app
yhh0acc3ca1a562
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9d0fa3b54..80d921ac8 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,8 @@ published separately; it ships inside the editor.### Fixed+- **Audio plugin cleanup belongs to each App.** Shared plugin instances release the quitting App's voices, backend, and memory/despawn subscriptions without stopping another App. Released systems stay inactive, and repeated preview shutdowns release every backend once.+- **Retired WebAudio handles cannot modify reused pool nodes.** Gain and pan writes from stopped or completed handles are ignored, preserving the next voice's mix. Completion callbacks are checked against the currently playing source, so an old source cannot release the pool slot of a resumed voice.- **Paused voices remain owned by the audio API.** Paused handles retain their voice-budget slot, bus volume and mute updates, and disposal cleanup; stolen paused voices cannot resume outside the budget. Handle volume edits update the tracked base gain, fades stay associated with managed handles, and ended ramps stop writing to released backend voices.diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex f7aed501d..8c2add121 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1262,7 +1262,7 @@ voiceVolume: number | undefined## AudioPlugin — class @experimental```build: (app: App) => void-cleanup: () => void+cleanup: (app?: App) => voidname: stringstopAllSources: () => voidstatic new (config?: AudioPluginConfig): AudioPlugindiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex f039db7af..940e767fc 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1262,7 +1262,7 @@ voiceVolume: number | undefined## AudioPlugin — class @experimental```build: (app: App) => void-cleanup: () => void+cleanup: (app?: App) => voidname: stringstopAllSources: () => voidstatic new (config?: AudioPluginConfig): AudioPlugindiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex c9b3071d9..284bddc22 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1257,7 +1257,7 @@ voiceVolume: number | undefined## AudioPlugin — class @experimental```build: (app: App) => void-cleanup: () => void+cleanup: (app?: App) => voidname: stringstopAllSources: () => voidstatic new (config?: AudioPluginConfig): AudioPlugindiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 98024f95b..06acdfe1f 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1257,7 +1257,7 @@ voiceVolume: number | undefined## AudioPlugin — class @experimental```build: (app: App) => void-cleanup: () => void+cleanup: (app?: App) => voidname: stringstopAllSources: () => voidstatic new (config?: AudioPluginConfig): AudioPlugindiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 0fe2d5388..c14b696ed 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1257,7 +1257,7 @@ voiceVolume: number | undefined## AudioPlugin — class @experimental```build: (app: App) => void-cleanup: () => void+cleanup: (app?: App) => voidname: stringstopAllSources: () => voidstatic new (config?: AudioPluginConfig): AudioPlugindiff --git a/sdk/src/audio/AudioPlugin.ts b/sdk/src/audio/AudioPlugin.tsindex 629e73957..78de024aa 100644--- a/sdk/src/audio/AudioPlugin.ts+++ b/sdk/src/audio/AudioPlugin.ts@@ -38,6 +38,15 @@ interface ActiveVoice {spatial: boolean;}+interface AudioPluginState {+ activeSourceHandles: Map<number, ActiveVoice>;+ playedEntities: Set<number>;+ audio: AudioAPI;+ released: boolean;+ offMemoryWarning: () => void;+ offDespawn: () => void;+}+export interface AudioPluginConfig {initialPoolSize?: number;masterVolume?: number;@@ -48,17 +57,15 @@ export interface AudioPluginConfig {export class AudioPlugin implements Plugin {name = 'audio';private config_: AudioPluginConfig;- private activeSourceHandles_: Map<number, ActiveVoice> | null = null;- private playedEntities_: Set<number> | null = null;- private audio_: AudioAPI | null = null;- private offMemoryWarning_: (() => void) | null = null;- private offDespawn_: (() => void) | null = null;+ private readonly states_ = new WeakMap<App, AudioPluginState>();+ private latestState_: AudioPluginState | null = null;constructor(config: AudioPluginConfig = {}) {this.config_ = config;}build(app: App): void {+ this.cleanup(app);const backend = platformCreateAudioBackend();const config = this.config_;@@ -68,12 +75,11 @@ export class AudioPlugin implements Plugin {const mixer = backend.mixer;const audio = new AudioAPI(backend, mixer);- this.audio_ = audio;app.insertResource(Audio, audio);// OS memory pressure → drop the decoded-buffer warm cache. Held// buffers keep playing; re-fetch cost returns only for evicted ones.- this.offMemoryWarning_ = platformOnMemoryWarning(() => {+ const offMemoryWarning = platformOnMemoryWarning(() => {const freed = audio.trimBufferCache();if (freed > 0) log.info('audio', `memory warning: trimmed ${freed} cached buffer(s)`);});@@ -85,11 +91,9 @@ export class AudioPlugin implements Plugin {}const activeSourceHandles = new Map<number, ActiveVoice>();- this.activeSourceHandles_ = activeSourceHandles;const playedEntities = new Set<number>();- this.playedEntities_ = playedEntities;- this.offDespawn_ = app.world.onDespawn((entity: Entity) => {+ const offDespawn = app.world.onDespawn((entity: Entity) => {const voice = activeSourceHandles.get(entity);if (voice) {voice.handle.stop();@@ -97,6 +101,9 @@ export class AudioPlugin implements Plugin {}playedEntities.delete(entity);});+ const state = { activeSourceHandles, playedEntities, audio, offMemoryWarning, offDespawn, released: false };+ this.states_.set(app, state);+ this.latestState_ = state;const stopVoice = (id: number): void => {const voice = activeSourceHandles.get(id);if (!voice) return;@@ -115,6 +122,7 @@ export class AudioPlugin implements Plugin {defineSystem([Res(Time), Res(Audio)],(time: TimeData, audioAPI: AudioAPI) => {+ if (state.released) return;const playMode = !isEditor() || isPlayMode();if (!playMode) {@@ -291,24 +299,26 @@ export class AudioPlugin implements Plugin {);}+ private stopSources_(state: AudioPluginState): void {+ for (const voice of state.activeSourceHandles.values()) voice.handle.stop();+ state.activeSourceHandles.clear();+ state.playedEntities.clear();+ }+stopAllSources(): void {- if (this.activeSourceHandles_) {- for (const voice of this.activeSourceHandles_.values()) {- voice.handle.stop();- }- this.activeSourceHandles_.clear();- }- this.playedEntities_?.clear();+ if (this.latestState_) this.stopSources_(this.latestState_);}- cleanup(): void {- this.offMemoryWarning_?.();- this.offMemoryWarning_ = null;- this.offDespawn_?.();- this.offDespawn_ = null;- this.stopAllSources();- this.audio_?.dispose();- this.audio_ = null;+ cleanup(app?: App): void {+ const state = app ? this.states_.get(app) : this.latestState_;+ if (!state || state.released) return;+ state.released = true;+ if (app) this.states_.delete(app);+ if (state === this.latestState_) this.latestState_ = null;+ state.offMemoryWarning();+ state.offDespawn();+ this.stopSources_(state);+ state.audio.dispose();}}diff --git a/sdk/tests/audio-plugin-lifecycle.test.ts b/sdk/tests/audio-plugin-lifecycle.test.tsnew file mode 100644index 000000000..b1a89a869--- /dev/null+++ b/sdk/tests/audio-plugin-lifecycle.test.ts@@ -0,0 +1,75 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { afterEach, expect, it, vi } from 'vitest';+import type { PlatformAudioBackend, AudioHandle } from '../src/audio/PlatformAudioBackend';+const backends: PlatformAudioBackend[] = [], listeners = new Set<() => void>();+vi.mock('../src/platform/base', async original => ({+ ...await original<typeof import('../src/platform/base')>(),+ platformCreateAudioBackend: () => {+ 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(),+ suspend: vi.fn(), resume: vi.fn(), dispose: vi.fn(),+ play: vi.fn(() => { let playing = true; return { id: 1, get isPlaying() { return playing; }, currentTime: 0, duration: 1,+ stop: vi.fn(() => { playing = false; }), pause: vi.fn(), resume: vi.fn(),+ setVolume: vi.fn(), setPan: vi.fn(), setLoop: vi.fn(), setPlaybackRate: vi.fn() } satisfies AudioHandle; }),+ } as unknown as PlatformAudioBackend;+ backends.push(backend); return backend;+ },+ platformOnMemoryWarning: (callback: () => void) => { listeners.add(callback); return () => listeners.delete(callback); },+}));+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');+const apps: ReturnType<typeof App.new>[] = [];+function build(plugin: InstanceType<typeof AudioPlugin>) { const app=App.new(); apps.push(app); app.addPlugin(plugin); return app; }+afterEach(() => { for(const app of apps.splice(0)) app.quit(); backends.length=0; listeners.clear(); });+it('quitting an older app releases its backend and preserves the newer app voice and subscription', async () => {+ const plugin=new AudioPlugin(), first=build(plugin), second=build(plugin);+ const a=first.getResource(Audio), b=second.getResource(Audio);+ await a.preload('a.wav'); await b.preload('b.wav');+ const firstVoice=a.playSFX('a.wav')!, secondVoice=b.playSFX('b.wav')!;+ const callbacks=[...listeners]; first.quit();+ expect(backends[0].dispose).toHaveBeenCalledOnce(); expect(backends[1].dispose).not.toHaveBeenCalled();+ expect(firstVoice.isPlaying).toBe(false); expect(secondVoice.isPlaying).toBe(true);+ expect(listeners.has(callbacks[0])).toBe(false); expect(listeners.has(callbacks[1])).toBe(true);+ second.quit(); expect(backends[1].dispose).toHaveBeenCalledOnce(); expect(listeners.size).toBe(0);+});+it('releases exactly one backend per preview while keeping the main app alive', () => {+ const plugin=new AudioPlugin(), main=build(plugin);+ for(let i=0;i<100;i++) { const preview=build(plugin); expect(listeners.size).toBe(2); preview.quit(); expect(listeners.size).toBe(1); }+ expect(backends[0].dispose).not.toHaveBeenCalled(); main.quit();+ for(const backend of backends) expect(backend.dispose).toHaveBeenCalledOnce(); expect(listeners.size).toBe(0);+});+it('parameterless cleanup releases the latest app only and remains idempotent', () => {+ const plugin=new AudioPlugin(), first=build(plugin); build(plugin);+ plugin.cleanup(); plugin.cleanup();+ expect(backends[0].dispose).not.toHaveBeenCalled(); expect(backends[1].dispose).toHaveBeenCalledOnce();+ first.quit(); expect(backends[0].dispose).toHaveBeenCalledOnce(); expect(listeners.size).toBe(0);+});+it('quitting the newer app first leaves older source updates available', async () => {+ const plugin=new AudioPlugin(), first=build(plugin), second=build(plugin);+ await first.getResource(Audio).preload('a.wav');+ second.quit();+ const entity=first.world.spawn(); first.world.insert(entity,AudioSource,{clip:'a.wav',playing:true});+ await first.tick(1/60); expect(backends[0].play).toHaveBeenCalledOnce();+ first.quit(); expect(backends[0].dispose).toHaveBeenCalledOnce();+});+it('cleanup withdraws the owning world despawn listener and prevents later source playback', async () => {+ const plugin=new AudioPlugin(), app=App.new(); apps.push(app);+ const off=vi.fn(), subscribe=vi.spyOn(app.world,'onDespawn').mockReturnValue(off);+ app.addPlugin(plugin); expect(subscribe).toHaveBeenCalledOnce();+ await app.getResource(Audio).preload('a.wav');+ const entity=app.world.spawn(); app.world.insert(entity,AudioSource,{clip:'a.wav',playing:true});+ plugin.cleanup(app); await app.tick(1/60);+ expect(off).toHaveBeenCalledOnce(); expect(backends[0].play).not.toHaveBeenCalled();+ app.quit(); expect(off).toHaveBeenCalledOnce(); expect(backends[0].dispose).toHaveBeenCalledOnce();+});+it('stopAllSources silences the latest source and resets its playOnAwake trigger', async () => {+ const plugin=new AudioPlugin(), app=build(plugin); await app.getResource(Audio).preload('a.wav');+ const entity=app.world.spawn(); app.world.insert(entity,AudioSource,{clip:'a.wav',playOnAwake:true});+ await app.tick(1/60); const old=vi.mocked(backends[0].play).mock.results[0].value;+ plugin.stopAllSources(); expect(old.isPlaying).toBe(false);+ await app.tick(1/60); expect(backends[0].play).toHaveBeenCalledTimes(2);+});diff --git a/sdk/tests/audio-plugin.test.ts b/sdk/tests/audio-plugin.test.tsindex 7d1ddee0e..2c4b72f17 100644--- a/sdk/tests/audio-plugin.test.ts+++ b/sdk/tests/audio-plugin.test.ts@@ -90,75 +90,10 @@ describe('AudioPlugin', () => {expect(plugin.name).toBe('audio');});- describe('stopAllSources', () => {- it('should stop all active handles and clear the map', () => {- const plugin = new AudioPlugin();- const handle1 = createMockHandle({ id: 1 });- const handle2 = createMockHandle({ id: 2 });-- // The plugin records a voice as the handle AND the clip it is a play- // of, which is how one source can be given a second sound.- const handles = new Map<number, { handle: AudioHandle; clip: string }>();- handles.set(10, { handle: handle1, clip: 'a.wav' });- handles.set(20, { handle: handle2, clip: 'b.wav' });- (plugin as any).activeSourceHandles_ = handles;-- plugin.stopAllSources();-- expect(handle1.stop).toHaveBeenCalled();- expect(handle2.stop).toHaveBeenCalled();- expect(handles.size).toBe(0);- });-- it('should clear playedEntities so playOnAwake can retrigger', () => {- const plugin = new AudioPlugin();- const played = new Set<number>([10, 20]);- (plugin as any).playedEntities_ = played;- (plugin as any).activeSourceHandles_ = new Map();-- plugin.stopAllSources();-- expect(played.size).toBe(0);- });-- it('should be safe to call when not built', () => {- const plugin = new AudioPlugin();- expect(() => plugin.stopAllSources()).not.toThrow();- });- });-- describe('cleanup', () => {- it('should call stopAllSources then dispose the owned AudioAPI instance', () => {- const plugin = new AudioPlugin();- const backend = createMockBackend();- const audio = new AudioAPI(backend, backend.mixer);- (plugin as any).audio_ = audio;- (plugin as any).activeSourceHandles_ = new Map();- (plugin as any).playedEntities_ = new Set();-- const stopSpy = vi.spyOn(plugin, 'stopAllSources');- const disposeSpy = vi.spyOn(audio, 'dispose');-- plugin.cleanup();-- expect(stopSpy).toHaveBeenCalled();- expect(disposeSpy).toHaveBeenCalled();- const stopOrder = stopSpy.mock.invocationCallOrder[0];- const disposeOrder = disposeSpy.mock.invocationCallOrder[0];- expect(stopOrder).toBeLessThan(disposeOrder);- });-- it('should clear the audio_ reference after dispose', () => {- const plugin = new AudioPlugin();- const backend = createMockBackend();- (plugin as any).audio_ = new AudioAPI(backend, backend.mixer);- (plugin as any).activeSourceHandles_ = new Map();- (plugin as any).playedEntities_ = new Set();-- plugin.cleanup();-- expect((plugin as any).audio_).toBeNull();- });+ it('stopping and cleaning up an unbuilt plugin remains safe', () => {+ const plugin = new AudioPlugin();+ expect(() => plugin.stopAllSources()).not.toThrow();+ expect(() => plugin.cleanup()).not.toThrow();});});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 230b867d2..e0e1cbeda 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'fix(audio): isolate plugin cleanup by app':+ { note: 'Audio plugin cleanup belongs to each App.' },'fix(audio): guard reused pool nodes from retired handles':{ note: 'Retired WebAudio handles cannot modify reused pool nodes.' },'fix(audio): retain paused voice ownership and tracked base gains':