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): distinguish source completion from interrupted voices

yhhcc0d29db44bb
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bf336f96d..c0685d8dc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Audio sources distinguish interrupted voices from completed clips.** A refused or preempted voice lowers `playing` without setting the natural-completion latch. Only a backend end signal for a non-looping source marks it `finished`; existing backend completion callbacks remain attached and replays clear the latch.
+
- **Camera preview scheduling follows its current CPU budget.** A preview waiting on an old slow interval now rechecks the live budget, so cheaper recurring captures resume without waiting for the stale deadline. A slower budget also defers the next capture instead of overspending, and unmounting cancels refreshes.
- **Mini-game verification unregisters keyboard callbacks.** The launch host now removes the DOM listener belonging to each vendor keyboard callback. Repeated platform input binding no longer leaves retired keyboard subscribers active, and duplicate registrations do not multiply notifications.
diff --git a/sdk/src/audio/AudioPlugin.ts b/sdk/src/audio/AudioPlugin.ts
index 78de024aa..1f28930da 100644
--- a/sdk/src/audio/AudioPlugin.ts
+++ b/sdk/src/audio/AudioPlugin.ts
@@ -31,6 +31,7 @@ function worldPositionOf(t: WorldTransformData): Vec3 {
*/
interface ActiveVoice {
handle: AudioHandle;
+ completedNaturally: boolean;
clip: string;
volume: number;
pitch: number;
@@ -202,12 +203,13 @@ export class AudioPlugin implements Plugin {
// 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.
- activeSourceHandles.set(id, {
+ const voice: ActiveVoice = {
clip: source.clip,
volume: source.volume,
pitch: source.pitch,
loop: source.loop,
spatial: source.spatial,
+ completedNaturally: false,
handle: audioAPI.playBuffer(buffer, {
bus: source.bus,
volume: source.volume,
@@ -215,7 +217,13 @@ export class AudioPlugin implements Plugin {
playbackRate: source.pitch,
priority: source.priority,
}),
- });
+ };
+ const previousEnd = voice.handle.onEnd;
+ voice.handle.onEnd = () => {
+ voice.completedNaturally = !voice.loop;
+ previousEnd?.call(voice.handle);
+ };
+ activeSourceHandles.set(id, voice);
// Whoever raised the flag is asking for this clip
// from the top, so the latch from the last one goes.
if (source.finished) {
@@ -239,13 +247,13 @@ export class AudioPlugin implements Plugin {
} else if (!playing && voice) {
stopVoice(id);
} else if (playing && voice && !voice.handle.isPlaying) {
- // The voice ended by itself. Lowering the flag here is
+ // The voice is no longer active. Lowering the flag here is
// what makes it readable as "is this sounding" rather
// than "was it ever asked to sound".
activeSourceHandles.delete(id);
world.update(entity, AudioSource, draft => {
draft.playing = false;
- draft.finished = true;
+ draft.finished = voice.completedNaturally;
});
}
diff --git a/sdk/tests/audio-source-flag.test.ts b/sdk/tests/audio-source-flag.test.ts
index 090d481b4..8c18233e5 100644
--- a/sdk/tests/audio-source-flag.test.ts
+++ b/sdk/tests/audio-source-flag.test.ts
@@ -89,6 +89,7 @@ describe('the AudioSource playing flag', () => {
await app.tick(1 / 60);
voices[0]!.isPlaying = false;
+ voices[0]!.onEnd?.();
await app.tick(1 / 60);
const source = app.world.get(e, AudioSource);
@@ -105,6 +106,7 @@ describe('the AudioSource playing flag', () => {
app.world.insert(e, AudioSource, { clip: 'boom.wav', playing: true });
await app.tick(1 / 60);
voices[0]!.isPlaying = false;
+ voices[0]!.onEnd?.();
for (let i = 0; i < 5; i++) await app.tick(1 / 60);
@@ -117,6 +119,7 @@ describe('the AudioSource playing flag', () => {
app.world.insert(e, AudioSource, { clip: 'boom.wav', playing: true });
await app.tick(1 / 60);
voices[0]!.isPlaying = false;
+ voices[0]!.onEnd?.();
await app.tick(1 / 60);
app.world.update(e, AudioSource, d => { d.playing = true; });
diff --git a/sdk/tests/audio-source-through-api.test.ts b/sdk/tests/audio-source-through-api.test.ts
index 1f48481af..a4931567f 100644
--- a/sdk/tests/audio-source-through-api.test.ts
+++ b/sdk/tests/audio-source-through-api.test.ts
@@ -134,5 +134,34 @@ describe('an AudioSource in the scene', () => {
// The second one is worth less than the voice already sounding, so it is
// refused rather than silencing it.
expect(backend.play).toHaveBeenCalledTimes(1);
+ await app.tick(1 / 60);
+ expect(app.world.get(quiet, AudioSource).playing).toBe(false);
+ expect(app.world.get(quiet, AudioSource).finished).toBe(false);
+ });
+
+ it.each([false, true])('does not report natural completion when an interrupted source loses its voice (loop=%s)', async loop => {
+ const { app } = await appWithClip();
+ const entity = app.world.spawn();
+ app.world.insert(entity, AudioSource, { clip: 'boom.wav', playing: true, loop });
+ await app.tick(1 / 60);
+ const handle = vi.mocked(backend.play).mock.results[0].value as AudioHandle & { isPlaying: boolean };
+ handle.isPlaying = false;
+ await app.tick(1 / 60);
+ expect(app.world.get(entity, AudioSource).playing).toBe(false);
+ expect(app.world.get(entity, AudioSource).finished).toBe(false);
+ });
+
+ it('preserves a backend completion callback while latching natural source completion', async () => {
+ const { app } = await appWithClip();
+ const handle = playingHandle() as AudioHandle & { isPlaying: boolean };
+ const previousEnd = vi.fn(); handle.onEnd = previousEnd;
+ vi.mocked(backend.play).mockReturnValueOnce(handle);
+ const entity = app.world.spawn();
+ app.world.insert(entity, AudioSource, { clip: 'boom.wav', playing: true });
+ await app.tick(1 / 60);
+ handle.isPlaying = false; handle.onEnd?.();
+ await app.tick(1 / 60);
+ expect(previousEnd).toHaveBeenCalledOnce();
+ expect(app.world.get(entity, AudioSource).finished).toBe(true);
});
});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 9ab707c6c..81b143d4d 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): distinguish source completion from interrupted voices':
+ { note: 'Audio sources distinguish interrupted voices from completed clips.' },
'fix(editor): refresh camera previews against the live CPU budget':
{ note: 'Camera preview scheduling follows its current CPU budget.' },
'fix(test): unregister mini-game host keyboard subscribers':