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): apply live source parameters without restarting voices

yhhc58cbac7646e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d2e0c02c2..5b98e6a5f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Playing audio sources follow live parameter edits.** Volume, pitch and loop changes update the existing voice without restarting it. Switching spatial sound off restores base gain and centered pan; stable nonspatial sources do not resend unchanged parameters, and voice cleanup avoids copying its key list every frame.
+
- **UI ancestor walks terminate on malformed hierarchy adapters.** Depth counting and parent callbacks stop before repeating an entity or following an ancestor invalidated by a callback. Shallow chains use bounded array scans, deeper chains switch to a set, and long valid chains remain iterative with early callback termination preserved.
- **Unavailable dropdowns retire their open lists.** Disabling, hiding, deactivating or removing a dropdown closes its popup even when the owner drops out of component queries. Keyboard input and stale row clicks cannot change an unavailable control; availability is checked again after popup teardown callbacks.
diff --git a/sdk/src/audio/AudioPlugin.ts b/sdk/src/audio/AudioPlugin.ts
index b4024c0c9..629e73957 100644
--- a/sdk/src/audio/AudioPlugin.ts
+++ b/sdk/src/audio/AudioPlugin.ts
@@ -32,6 +32,10 @@ function worldPositionOf(t: WorldTransformData): Vec3 {
interface ActiveVoice {
handle: AudioHandle;
clip: string;
+ volume: number;
+ pitch: number;
+ loop: boolean;
+ spatial: boolean;
}
export interface AudioPluginConfig {
@@ -192,6 +196,10 @@ export class AudioPlugin implements Plugin {
// and a sound outside that door gets neither.
activeSourceHandles.set(id, {
clip: source.clip,
+ volume: source.volume,
+ pitch: source.pitch,
+ loop: source.loop,
+ spatial: source.spatial,
handle: audioAPI.playBuffer(buffer, {
bus: source.bus,
volume: source.volume,
@@ -234,6 +242,18 @@ export class AudioPlugin implements Plugin {
}
const sounding = activeSourceHandles.get(id);
+ if (sounding) {
+ if (sounding.pitch !== source.pitch) sounding.handle.setPlaybackRate(source.pitch);
+ if (sounding.loop !== source.loop) sounding.handle.setLoop(source.loop);
+ if (!source.spatial) {
+ if (sounding.volume !== source.volume || sounding.spatial) sounding.handle.setVolume(source.volume);
+ if (sounding.spatial) sounding.handle.setPan(0);
+ }
+ sounding.volume = source.volume;
+ sounding.pitch = source.pitch;
+ sounding.loop = source.loop;
+ sounding.spatial = source.spatial;
+ }
if (source.spatial && sounding) {
if (!hasListener && !spatialListenerWarned) {
log.warn('audio', 'spatial audio used but no AudioListener entity found');
@@ -262,7 +282,7 @@ export class AudioPlugin implements Plugin {
// Sources the pass above did not reach at all. Their voices are
// STOPPED, not just forgotten: a dropped handle is a sound
// nothing can reach any more.
- for (const entityId of [...activeSourceHandles.keys()]) {
+ for (const entityId of activeSourceHandles.keys()) {
if (!liveEntities.has(entityId)) stopVoice(entityId);
}
},
diff --git a/sdk/tests/audio-source-flag.test.ts b/sdk/tests/audio-source-flag.test.ts
index 79d80c091..090d481b4 100644
--- a/sdk/tests/audio-source-flag.test.ts
+++ b/sdk/tests/audio-source-flag.test.ts
@@ -200,4 +200,35 @@ describe('the AudioSource playing flag', () => {
expect(app.world.get(e, AudioSource).playing).toBe(false);
expect(backend.play).toHaveBeenCalledTimes(1);
});
+
+ it('applies volume, pitch and loop edits to the existing voice', async () => {
+ const app = await appWithClips(), e = app.world.spawn();
+ app.world.insert(e, AudioSource, { clip: 'boom.wav', playing: true }); await app.tick(1 / 60);
+ app.world.update(e, AudioSource, d => { d.volume = .25; d.pitch = 1.5; d.loop = true; });
+ await app.tick(1 / 60);
+ expect(voices[0]!.setVolume).toHaveBeenLastCalledWith(.25);
+ expect(voices[0]!.setPlaybackRate).toHaveBeenLastCalledWith(1.5);
+ expect(voices[0]!.setLoop).toHaveBeenLastCalledWith(true);
+ expect(backend.play).toHaveBeenCalledTimes(1);
+ });
+
+ it('restores ordinary gain and centered pan when spatial mode is switched off', async () => {
+ const app = await appWithClips(), e = app.world.spawn();
+ app.world.insert(e, AudioSource, { clip: 'boom.wav', playing: true, spatial: true, volume: .4 });
+ await app.tick(1 / 60);
+ vi.mocked(voices[0]!.setVolume).mockClear(); vi.mocked(voices[0]!.setPan).mockClear();
+ app.world.update(e, AudioSource, d => { d.spatial = false; }); await app.tick(1 / 60);
+ expect(voices[0]!.setVolume).toHaveBeenLastCalledWith(.4);
+ expect(voices[0]!.setPan).toHaveBeenLastCalledWith(0);
+ });
+
+ it('stable ordinary voices do not resend their parameters every frame', async () => {
+ const app = await appWithClips(), e = app.world.spawn();
+ app.world.insert(e, AudioSource, { clip: 'boom.wav', playing: true }); await app.tick(1 / 60);
+ const v = voices[0]!;
+ vi.mocked(v.setVolume).mockClear(); vi.mocked(v.setPlaybackRate).mockClear(); vi.mocked(v.setLoop).mockClear();
+ for (let i = 0; i < 100; i++) await app.tick(1 / 60);
+ expect(v.setVolume).not.toHaveBeenCalled(); expect(v.setPlaybackRate).not.toHaveBeenCalled();
+ expect(v.setLoop).not.toHaveBeenCalled();
+ });
});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 02052111a..e114f47a1 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): apply live source parameters without restarting voices':
+ { note: 'Playing audio sources follow live parameter edits.' },
'fix(ui): bound ancestor traversal across cyclic hierarchy adapters':
{ note: 'UI ancestor walks terminate on malformed hierarchy adapters.' },
'fix(ui): retire unavailable dropdown popups before selection':