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): preserve controls on loading effect handles
yhh30ae08bedb93
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b16a3cc31..55ae9ad9e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,8 @@ published separately; it ships inside the editor.### Fixed+- **Loading sound-effect handles preserve playback controls.** Stopping before load completion prevents voice allocation and cannot be undone by Resume. Volume, pan, loop and playback rate apply to the initial backend play; queued Pause starts muted before pausing and restores the intended bus-adjusted gain. Resolved handles expose the real voice ID and forward completion callbacks, while later controls keep delegating normally.+- **Stop All stops every owned audio voice and pending start.** Scripted effects, explicit tracks, paused voices and outgoing music fades are stopped once, and stopped handles cannot resume outside the voice registry. Pending effects and tracks requested before Stop All cannot start on load completion; cached buffers and the device remain reusable, and disposal uses the same shutdown path.- **BGM playback follows the latest request instead of load completion order.** New requests and stop commands invalidate older pending starts, including when the replacement is already cached. An immediate stop also ends a track already fading out, while repeated positive fade-out requests preserve the existing ramp. Loaded buffers remain available for later playback.diff --git a/sdk/src/audio/Audio.ts b/sdk/src/audio/Audio.tsindex 597b4d23a..679056112 100644--- a/sdk/src/audio/Audio.ts+++ b/sdk/src/audio/Audio.ts@@ -400,12 +400,12 @@ export class AudioAPI {};const buffer = this.lookupBuffer_(url);if (!buffer) {- const pending = this.createDeferredHandle_();+ const pending = this.createDeferredHandle_(playConfig.volume ?? 1);this.preload(url).then(() => {- if (this.disposed_ || epoch !== this.playbackEpoch_) return;+ if (this.disposed_ || epoch !== this.playbackEpoch_ || pending.cancelled) return;const buf = this.lookupBuffer_(url);if (buf) {- pending.resolve(this.playVoice_(buf, playConfig));+ pending.resolve(overrides => this.playVoice_(buf, { ...playConfig, ...overrides }));}}).catch(err => {log.warn('audio', `Failed to preload audio: ${url}`, err);@@ -870,23 +870,45 @@ export class AudioAPI {this.fades_.push({ voice, from: voice.fade, to: 0, duration, elapsed: 0, stopAtEnd: true });}- private createDeferredHandle_(): AudioHandle & { resolve(real: AudioHandle): void } {+ private createDeferredHandle_(baseVolume: number): AudioHandle & {+ readonly cancelled: boolean;+ resolve(start: (overrides: PlayConfig) => AudioHandle): void;+ } {let real: AudioHandle | null = null;- const handle: AudioHandle & { resolve(r: AudioHandle): void } = {- id: -1,- stop() { real?.stop(); },- pause() { real?.pause(); },- resume() { real?.resume(); },- setVolume(v: number) { real?.setVolume(v); },- setPan(p: number) { real?.setPan(p); },- setLoop(l: boolean) { real?.setLoop(l); },- setPlaybackRate(r: number) { real?.setPlaybackRate(r); },+ let stopped = false, paused = false, endAssigned = false;+ let ended: (() => void) | undefined;+ const overrides: PlayConfig = {};+ return {+ get id() { return real?.id ?? -1; },+ get cancelled() { return stopped; },+ stop() { if (!stopped) { stopped = true; real?.stop(); } },+ pause() { if (!stopped) { paused = true; real?.pause(); } },+ resume() { if (!stopped) { paused = false; real?.resume(); } },+ setVolume(v) { if (!stopped) { overrides.volume = v; real?.setVolume(v); } },+ setPan(p) { if (!stopped) { overrides.pan = p; real?.setPan(p); } },+ setLoop(l) { if (!stopped) { overrides.loop = l; real?.setLoop(l); } },+ setPlaybackRate(r) { if (!stopped) { overrides.playbackRate = r; real?.setPlaybackRate(r); } },get isPlaying() { return real?.isPlaying ?? false; },get currentTime() { return real?.currentTime ?? 0; },get duration() { return real?.duration ?? 0; },- resolve(r: AudioHandle) { real = r; },+ get onEnd() { return real ? real.onEnd : ended; },+ set onEnd(callback) {+ ended = callback;+ endAssigned = true;+ if (real) real.onEnd = callback;+ },+ resolve(start) {+ if (stopped || real) return;+ const next = start(paused ? { ...overrides, volume: 0 } : overrides);+ if (stopped) { next.stop(); return; }+ real = next;+ if (endAssigned) real.onEnd = ended;+ if (paused) {+ real.pause();+ real.setVolume(overrides.volume ?? baseVolume);+ }+ },};- return handle;}}diff --git a/sdk/tests/audio-play-intent.test.ts b/sdk/tests/audio-play-intent.test.tsindex 4dd934548..7cc78259a 100644--- a/sdk/tests/audio-play-intent.test.ts+++ b/sdk/tests/audio-play-intent.test.ts@@ -114,3 +114,52 @@ it('does not send a new buffer voice to a disposed device', () => {expect(audio.playBuffer({ id: 1, duration: 1 }).isPlaying).toBe(false);expect(backend.play).not.toHaveBeenCalled();});++it('stopping a loading effect prevents backend allocation and later resume', async () => {+ const { audio, backend } = create();+ const handle = audio.playSFX('loading.wav');+ handle.stop();+ handle.resume();+ await finish(audio, 'loading.wav', 1);+ expect(backend.play).not.toHaveBeenCalled();+ expect(handle.isPlaying).toBe(false);+});++it('applies deferred controls at startup and exposes the resolved identity and completion callback', async () => {+ const { audio, backend } = create(), ended = vi.fn();+ const handle = audio.playSFX('loading.wav', { volume: 0.9, pitch: 1.1 });+ handle.setVolume(0.2);+ handle.setPan(-0.5);+ handle.setLoop(true);+ handle.setPlaybackRate(0.8);+ handle.onEnd = ended;+ await finish(audio, 'loading.wav', 1);+ const raw = backend.play.mock.results[0].value;+ expect(backend.play).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ volume: 0.2, pan: -0.5, loop: true, playbackRate: 0.8 }));+ expect(handle.id).toBe(raw.id);+ raw.onEnd?.();+ expect(ended).toHaveBeenCalledOnce();+ expect(handle.onEnd).toBe(ended);+ handle.setVolume(0.4);+ expect(raw.setVolume).toHaveBeenLastCalledWith(0.4);+});++it.each([false, true])('remembers pending pause/resume intent (resume before loading=%s)', async resumeBefore => {+ const { audio, backend } = create();+ audio.setSFXVolume(0.5);+ const handle = audio.playSFX('loading.wav', { volume: 0.8 });+ handle.pause();+ if (resumeBefore) handle.resume();+ await finish(audio, 'loading.wav', 1);+ const raw = backend.play.mock.results[0].value;+ expect(handle.isPlaying).toBe(resumeBefore);+ if (!resumeBefore) {+ expect(backend.play.mock.calls[0][1].volume).toBe(0);+ expect(raw.setVolume).toHaveBeenLastCalledWith(0.4);+ handle.resume();+ expect(handle.isPlaying).toBe(true);+ } else {+ expect(backend.play.mock.calls[0][1].volume).toBe(0.4);+ expect(raw.pause).not.toHaveBeenCalled();+ }+});diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex d206b6858..760d67775 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): preserve controls on loading effect handles':+ { note: 'Loading sound-effect handles preserve playback controls.' },'fix(audio): stop all owned voices and pending starts':{ note: 'Stop All stops every owned audio voice and pending start.' },'fix(audio): preserve latest BGM intent across loading':