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.

fix(audio): release failed starts and preserve paused retries

yhh6ed03847aad2
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 175cb9279..8cf357b73 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Web audio startup failures release pooled nodes and keep resumes retryable.** Source creation, configuration and start errors return the acquired node before propagating the error, preventing failed plays from growing the pool. Failed resumes disconnect the rejected source while preserving the paused voice and playback offset; successful retries commit playback state only after startup succeeds.
+
- **Tilemap rectangle fills clip safely across integer coordinate bounds.** Finite layers intersect the requested rectangle before visiting cells, avoiding work outside the map. Wide endpoint arithmetic preserves unsigned extents and clips infinite writes to representable coordinates; empty intersections return immediately. Negative chunk division avoids signed overflow, preserving tile storage and chunk import at both integer edges.
- **Paused sprite motions wait for actual completion before exit transitions.** Animator exit-time checks require the matching SpriteAnimator completion latch and stopped playback. Pausing or seeking to a stopped frame preserves the current state; resumed one-shot playback can complete normally, while a pending replay does not count as an ended clip.
diff --git a/sdk/src/audio/WebAudioBackend.ts b/sdk/src/audio/WebAudioBackend.ts
index 796819499..698e21888 100644
--- a/sdk/src/audio/WebAudioBackend.ts
+++ b/sdk/src/audio/WebAudioBackend.ts
@@ -80,21 +80,30 @@ class WebAudioHandle implements AudioHandle {
resume(): void {
if (this.playing_ || this.stopped_) return;
- this.playing_ = true;
const source = this.context_.createBufferSource();
- source.buffer = this.buffer_;
- source.loop = this.loop_;
- source.playbackRate.value = this.playbackRate_;
- source.connect(this.poolNode_.gain);
+ let startedAt: number;
+ try {
+ source.buffer = this.buffer_;
+ source.loop = this.loop_;
+ source.playbackRate.value = this.playbackRate_;
+ source.connect(this.poolNode_.gain);
+ this.bindOnEnded_(source);
+ startedAt = this.context_.currentTime;
+ source.start(0, this.pausedAt_);
+ } catch (error) {
+ source.onended = null;
+ try { source.stop(); } catch (_) { /* not started */ }
+ source.disconnect();
+ throw error;
+ }
this.source_ = source;
this.poolNode_.source = source;
this.startOffset_ = this.pausedAt_;
- this.startedAt_ = this.context_.currentTime;
+ this.startedAt_ = startedAt;
- this.bindOnEnded_(source);
- source.start(0, this.pausedAt_);
+ this.playing_ = true;
}
setVolume(volume: number): void {
@@ -319,23 +328,28 @@ export class WebAudioBackend implements PlatformAudioBackend {
throw new Error(`Buffer ${buffer.id} not found`);
}
- const poolNode = this.pool_.acquire();
- const source = this.context_.createBufferSource();
- source.buffer = audioBuffer;
- source.loop = config.loop ?? false;
- source.playbackRate.value = config.playbackRate ?? 1.0;
- source.connect(poolNode.gain);
- poolNode.source = source;
-
- poolNode.gain.gain.value = config.volume ?? 1.0;
- poolNode.panner.pan.value = config.pan ?? 0;
-
- const busName = config.bus ?? 'sfx';
- const bus = this.mixer_.getBus(busName) ?? this.mixer_.sfx;
- poolNode.panner.connect(bus.input);
-
const startOffset = config.startOffset ?? 0;
- source.start(0, startOffset);
+ const poolNode = this.pool_.acquire();
+ let source: AudioBufferSourceNode;
+ try {
+ source = this.context_.createBufferSource();
+ poolNode.source = source;
+ source.buffer = audioBuffer;
+ source.loop = config.loop ?? false;
+ source.playbackRate.value = config.playbackRate ?? 1.0;
+ source.connect(poolNode.gain);
+
+ poolNode.gain.gain.value = config.volume ?? 1.0;
+ poolNode.panner.pan.value = config.pan ?? 0;
+
+ const busName = config.bus ?? 'sfx';
+ const bus = this.mixer_.getBus(busName) ?? this.mixer_.sfx;
+ poolNode.panner.connect(bus.input);
+ source.start(0, startOffset);
+ } catch (error) {
+ this.pool_.release(poolNode);
+ throw error;
+ }
const handleId = ++this.nextHandleId_;
const handle = new WebAudioHandle(
diff --git a/sdk/tests/web-audio-backend.test.ts b/sdk/tests/web-audio-backend.test.ts
index 0d3088f4b..685d50807 100644
--- a/sdk/tests/web-audio-backend.test.ts
+++ b/sdk/tests/web-audio-backend.test.ts
@@ -598,6 +598,36 @@ describe('WebAudioBackend', () => {
});
});
+ it('returns a pooled node when source startup fails repeatedly', async () => {
+ const { bufferHandle, mockCtx } = await initAndLoadBuffer(backend);
+ const pool = (backend as any).pool_;
+ const capacity = pool.capacity;
+ const sources: any[] = [];
+ mockCtx.createBufferSource.mockImplementation(() => {
+ const source = createMockBufferSource();sources.push(source);
+ source.start.mockImplementation(() => { throw new RangeError('negative offset'); });return source;
+ });
+ for (let i = 0; i < 40; i++) expect(() => backend.play(bufferHandle, { startOffset: -1 })).toThrow('negative offset');
+ expect(pool.activeCount).toBe(0);expect(pool.capacity).toBe(capacity);
+ for (const source of sources) { expect(source.disconnect).toHaveBeenCalled();expect(source.onended).toBeNull(); }
+ mockCtx.createBufferSource.mockImplementation(createMockBufferSource);
+ const voice = backend.play(bufferHandle, {});expect(pool.activeCount).toBe(1);
+ voice.stop();expect(pool.activeCount).toBe(0);expect(pool.capacity).toBe(capacity);
+ });
+
+ it('keeps a failed resume paused and retries from the same offset', async () => {
+ const { bufferHandle, mockCtx } = await initAndLoadBuffer(backend);
+ const voice = backend.play(bufferHandle, {});mockCtx.currentTime = .25;voice.pause();
+ const rejected = createMockBufferSource();rejected.start.mockImplementation(() => { throw new Error('resume rejected'); });
+ mockCtx.createBufferSource.mockReturnValueOnce(rejected);
+ expect(() => voice.resume()).toThrow('resume rejected');expect(voice.isPlaying).toBe(false);
+ expect(voice.currentTime).toBeCloseTo(.25);expect(rejected.disconnect).toHaveBeenCalled();expect(rejected.onended).toBeNull();
+ mockCtx.currentTime = 10;voice.resume();expect(voice.isPlaying).toBe(true);
+ const accepted = mockCtx.createBufferSource.mock.results.at(-1).value;
+ expect(accepted.start).toHaveBeenCalledWith(0, .25);
+ voice.stop();expect((backend as any).pool_.activeCount).toBe(0);
+ });
+
describe('dispose', () => {
it('should close AudioContext and clear state', async () => {
await backend.initialize();
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index bb082e991..a637430c5 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): release failed starts and preserve paused retries':
+ { note: 'Web audio startup failures release pooled nodes and keep resumes retryable.' },
'fix(tilemap): clip fills and preserve signed coordinate edges':
{ note: 'Tilemap rectangle fills clip safely across integer coordinate bounds.' },
'fix(animation): keep paused sprite motions out of exit transitions':