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): release runtime references from finished web voices
yhhe69d027ec047
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4af072798..3d377151b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -14,6 +14,10 @@ published separately; it ships inside the editor.## [Unreleased]+### Fixed++- **Finished Web audio handles release their runtime references.** Stopped and naturally completed voices drop decoded buffers, sources, pool nodes and contexts after releasing their pool slot. Retaining a finished handle keeps its ID and duration available without pinning PCM; terminal controls remain harmless, while paused voices retain the state needed to resume and natural completion still notifies once.+## [0.87.0] - 2026-10-15### Fixeddiff --git a/sdk/src/audio/WebAudioBackend.ts b/sdk/src/audio/WebAudioBackend.tsindex 91e3428fb..0ea4ffcf1 100644--- a/sdk/src/audio/WebAudioBackend.ts+++ b/sdk/src/audio/WebAudioBackend.ts@@ -10,11 +10,12 @@ class WebAudioHandle implements AudioHandle {readonly id: number;onEnd?: () => void;- private buffer_: AudioBuffer;- private source_: AudioBufferSourceNode;- private poolNode_: PooledAudioNode;- private pool_: AudioPool;- private context_: AudioContext;+ /** Runtime references exist until Stop or natural completion; Pause retains them. */+ private buffer_: AudioBuffer | null;+ private source_: AudioBufferSourceNode | null;+ private poolNode_: PooledAudioNode | null;+ private pool_: AudioPool | null;+ private context_: AudioContext | null;private playing_ = true;private stopped_ = false;private pausedAt_ = 0;@@ -22,6 +23,7 @@ class WebAudioHandle implements AudioHandle {private startOffset_: number;private playbackRate_: number;private loop_: boolean;+ private readonly duration_: number;constructor(id: number,@@ -35,6 +37,7 @@ class WebAudioHandle implements AudioHandle {this.id = id;this.source_ = source;this.buffer_ = buffer;+ this.duration_ = buffer.duration;this.poolNode_ = poolNode;this.pool_ = pool;this.context_ = context;@@ -49,9 +52,7 @@ class WebAudioHandle implements AudioHandle {private bindOnEnded_(source: AudioBufferSourceNode): void {source.onended = () => {if (!this.stopped_ && this.playing_ && source === this.source_ && !this.loop_) {- this.playing_ = false;- this.stopped_ = true;- this.pool_.release(this.poolNode_);+ this.release_();this.onEnd?.();}};@@ -59,37 +60,46 @@ class WebAudioHandle implements AudioHandle {stop(): void {if (this.stopped_) return;+ this.release_();+ }++ private release_(): void {this.stopped_ = true;this.playing_ = false;- this.source_.onended = null;- this.pool_.release(this.poolNode_);+ if (this.source_) this.source_.onended = null;+ this.pool_!.release(this.poolNode_!);+ this.buffer_ = null;+ this.source_ = null;+ this.poolNode_ = null;+ this.pool_ = null;+ this.context_ = null;}pause(): void {if (!this.playing_ || this.stopped_) return;this.playing_ = false;- const elapsed = (this.context_.currentTime - this.startedAt_) * this.playbackRate_;+ const elapsed = (this.context_!.currentTime - this.startedAt_) * this.playbackRate_;this.pausedAt_ = this.startOffset_ + elapsed;- if (this.loop_ && this.buffer_.duration > 0) {- this.pausedAt_ = this.pausedAt_ % this.buffer_.duration;+ if (this.loop_ && this.buffer_!.duration > 0) {+ this.pausedAt_ = this.pausedAt_ % this.buffer_!.duration;}- this.source_.onended = null;- try { this.source_.stop(); } catch (_) { /* already stopped */ }- this.source_.disconnect();+ this.source_!.onended = null;+ try { this.source_!.stop(); } catch (_) { /* already stopped */ }+ this.source_!.disconnect();}resume(): void {if (this.playing_ || this.stopped_) return;- const source = this.context_.createBufferSource();+ const source = this.context_!.createBufferSource();let startedAt: number;try {source.buffer = this.buffer_;source.loop = this.loop_;source.playbackRate.value = this.playbackRate_;- source.connect(this.poolNode_.gain);+ source.connect(this.poolNode_!.gain);this.bindOnEnded_(source);- startedAt = this.context_.currentTime;+ startedAt = this.context_!.currentTime;source.start(0, this.pausedAt_);} catch (error) {source.onended = null;@@ -99,7 +109,7 @@ class WebAudioHandle implements AudioHandle {}this.source_ = source;- this.poolNode_.source = source;+ this.poolNode_!.source = source;this.startOffset_ = this.pausedAt_;this.startedAt_ = startedAt;@@ -108,24 +118,26 @@ class WebAudioHandle implements AudioHandle {setVolume(volume: number): void {if (this.stopped_) return;- this.poolNode_.gain.gain.value = volume;+ this.poolNode_!.gain.gain.value = volume;}setPan(pan: number): void {if (this.stopped_) return;- this.poolNode_.panner.pan.value = pan;+ this.poolNode_!.panner.pan.value = pan;}setLoop(loop: boolean): void {+ if (this.stopped_) return;this.loop_ = loop;- this.source_.loop = loop;+ this.source_!.loop = loop;}setPlaybackRate(rate: number): void {+ if (this.stopped_) return;if (this.playing_) {- const now = this.context_.currentTime;+ const now = this.context_!.currentTime;const position = this.startOffset_ + (now - this.startedAt_) * this.playbackRate_;- this.source_.playbackRate.value = rate;+ this.source_!.playbackRate.value = rate;this.startOffset_ = position;this.startedAt_ = now;}@@ -139,12 +151,12 @@ class WebAudioHandle implements AudioHandle {get currentTime(): number {if (this.stopped_) return 0;if (!this.playing_) return this.pausedAt_;- const elapsed = (this.context_.currentTime - this.startedAt_) * this.playbackRate_;+ const elapsed = (this.context_!.currentTime - this.startedAt_) * this.playbackRate_;return this.startOffset_ + elapsed;}get duration(): number {- return this.buffer_.duration;+ return this.duration_;}}diff --git a/sdk/tests/web-audio-backend.test.ts b/sdk/tests/web-audio-backend.test.tsindex 3c3230af1..c8fa4d7ae 100644--- a/sdk/tests/web-audio-backend.test.ts+++ b/sdk/tests/web-audio-backend.test.ts@@ -369,6 +369,29 @@ describe('WebAudioBackend', () => {});describe('play', () => {+ it.each(['stop', 'ended', 'paused-stop'])('terminal %s handles release runtime ownership and preserve scalar metadata', async kind => {+ const { bufferHandle, mockCtx } = await initAndLoadBuffer(backend);+ const handle = backend.play(bufferHandle, {});+ const source = mockCtx.createBufferSource.mock.results.at(-1).value;+ const ended = source.onended;+ const onEnd = vi.fn();+ handle.onEnd = onEnd;+ if (kind === 'ended') ended();+ else { if (kind === 'paused-stop') handle.pause(); handle.stop(); }+ backend.unloadBuffer(bufferHandle);+ expect(handle.isPlaying).toBe(false);+ expect(handle.currentTime).toBe(0);+ expect(handle.duration).toBe(1);+ expect(source.onended).toBeNull();+ for (const field of ['buffer_', 'source_', 'context_', 'pool_', 'poolNode_']) {+ expect((handle as any)[field], field).toBeNull();+ }+ expect(() => {handle.pause();handle.resume();handle.stop();handle.setLoop(true);+ handle.setPlaybackRate(2);handle.setVolume(.4);handle.setPan(.3);}).not.toThrow();+ ended();+ expect(onEnd).toHaveBeenCalledTimes(kind === 'ended' ? 1 : 0);+ expect((backend as any).pool_.activeCount).toBe(0);+ });it.each(['stopped', 'ended'])('a %s handle cannot change gain or pan of a reused pool node', async kind => {const { bufferHandle, mockCtx } = await initAndLoadBuffer(backend);const old = backend.play(bufferHandle, {});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex fe56cf11b..83056c85a 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -30,6 +30,8 @@ export const NOTES_FLOOR = 'v0.65.0';export const NOTED = {'test(nav): cover authored workshop obstacle layouts':{ internal: 'Headless exported-workshop acceptance also loads a scene with authored obstacles enabled and verifies retained state and delivery after reopening.' },+ 'fix(audio): release runtime references from finished web voices':+ { note: 'Finished Web audio handles release their runtime references.' },'chore(release): classify v0.87 feature verification':{ internal: 'The shipped capability census maps v0.87 navigation features to the navigation corpus and names focused editor acceptance for viewport and inspector features.' },'ci(editor): install workshop acceptance browser':