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.

feat(audio): a spatial source you can hear, placed where it actually is

esengine633db2eff829
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fa0fdbfcd..869246114 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,7 +14,31 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Added
+
+- **A spatial source you can hear in the audio demo.** Nothing in the shipped
+ corpus had ever set `AudioSource.spatial`, and no scene anywhere carried an
+ `AudioListener` — so the warning the engine logs for a spatial sound with no
+ ear in the world had never been seen by anyone, and neither had the feature.
+ The demo now orbits one around the camera that carries the listener; the scene
+ authors the clip, the distances and `playOnAwake`, and the code only moves the
+ entity.
+
### Fixed
+
+- **A spatial source is heard where it IS.** Audio read `Transform.position` —
+ an entity's offset from its parent — while every other subsystem reads
+ `worldPosition`. A hum parented to anything stayed at its parent's origin, and
+ a listener on a child of the camera heard from the camera rig rather than the
+ camera: exactly the two arrangements a game reaches for first, and the only
+ ones that made the alias `WorldTransform` read like what it was not.
+
+- **An authored `playOnAwake` brings in its own clip.** The scene had already
+ said to play it, but the frame looked the buffer up once and gave up for good
+ if nothing had preloaded that url, leaving a component that silently did
+ nothing and one line in the log. It now loads the clip it names — once per
+ clip, not once a frame, and once only for a clip that cannot load at all.
+
- **A mini-game's canvas follows its window.** It was sized once at boot from
`getSystemInfoSync` and never again, so any later change — a rotation, a foldable,
split screen, or a host that opens in the other orientation from the one `game.json`
diff --git a/examples/audio-demo/README.md b/examples/audio-demo/README.md
index f957ce390..72e8cff47 100644
--- a/examples/audio-demo/README.md
+++ b/examples/audio-demo/README.md
@@ -2,7 +2,8 @@
A four-pad drum machine that shows off the engine's audio system: one-shot SFX
with per-hit variation, a looping beat on the music bus, per-bus volume control,
-and a **real** spectrum visualizer driven by the master-bus analyser.
+a **real** spectrum visualizer driven by the master-bus analyser, and a spatial
+source orbiting the listener.
## Controls
@@ -11,6 +12,7 @@ and a **real** spectrum visualizer driven by the master-bus analyser.
| `1` `2` `3` `4` / click a pad | Kick / Snare / Hi-Hat / Clap |
| **Beat** button | Toggle the looping beat (music bus) |
| **Master / Music / SFX** | Click to cycle that bus's volume |
+| *(nothing)* | The orbiting dot pans and swells on its own |
## What it shows
@@ -22,6 +24,11 @@ and a **real** spectrum visualizer driven by the master-bus analyser.
- **Volume** buttons step each bus through the mixer with `setMasterVolume` /
`setMusicVolume` / `setSFXVolume`, so you can hear the bus tree at work.
- **Visualizer** is a true frequency spectrum, not a canned animation.
+- **The teal dot** is an `AudioSource` with `spatial` on, authored in the scene
+ together with the `AudioListener` on the camera. Nothing in the code plays it
+ or touches its volume: `playOnAwake` starts it and the engine attenuates and
+ pans it from where the entity is, so it swells as it passes the centre and
+ moves between your ears as it swings by.
## How it works
@@ -43,16 +50,18 @@ than breaks.
```
assets/
- scenes/main.esscene # camera, pads, beat + volume buttons, spectrum bars
- audio/*.wav # kick / snare / hi-hat / clap samples
+ scenes/main.esscene # camera (+ AudioListener), pads, buttons, bars,
+ # and the spatial hum source
+ audio/*.wav # kick / snare / hi-hat / clap, plus the looping hum
src/
main.ts # registers the systems
- config.ts # pad samples, beat url, volume steps, spectrum bins
- components.ts # Pad, BeatToggle, VolumeKnob, VisualizerBar (+ labels)
+ config.ts # pad samples, volume steps, spectrum bins
+ components.ts # Pad, BeatToggle, VolumeKnob, VisualizerBar, Orbiting
systems/
preload.ts # warm the buffer cache at startup
sfx.ts # pads → playSFX with pitch/pan variation
beat.ts # toggle the looping music-bus beat
volume.ts # cycle per-bus volume, update labels
visualizer.ts # real spectrum → bar heights (audio.getSpectrum)
+ orbit.ts # moves the spatial source; the audio follows on its own
```
diff --git a/examples/audio-demo/assets/audio/hum.wav b/examples/audio-demo/assets/audio/hum.wav
new file mode 100644
index 000000000..be5818702
Binary files /dev/null and b/examples/audio-demo/assets/audio/hum.wav differ
diff --git a/examples/audio-demo/assets/audio/hum.wav.meta b/examples/audio-demo/assets/audio/hum.wav.meta
new file mode 100644
index 000000000..8cda94b52
--- /dev/null
+++ b/examples/audio-demo/assets/audio/hum.wav.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "b7c1d2e3-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
+ "version": "2.0",
+ "type": "audio",
+ "importer": {}
+}
diff --git a/examples/audio-demo/assets/scenes/main.esscene b/examples/audio-demo/assets/scenes/main.esscene
index fac8b16e1..5735b3c9b 100644
--- a/examples/audio-demo/assets/scenes/main.esscene
+++ b/examples/audio-demo/assets/scenes/main.esscene
@@ -6,7 +6,8 @@
"id": 0, "name": "Camera", "parent": null, "children": [], "visible": true,
"components": [
{ "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
- { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } },
+ { "type": "AudioListener", "data": { "enabled": true } }
]
},
{
@@ -330,7 +331,16 @@
"components": [
{ "type": "Transform", "data": {} },
{ "type": "UINode", "data": { "position": 1, "width": { "value": 640, "unit": 0 }, "height": { "value": 22, "unit": 0 }, "insetLeft": { "value": 50, "unit": 1 }, "marginLeft": { "value": -320, "unit": 0 }, "insetTop": { "value": 100, "unit": 1 }, "marginTop": { "value": -34, "unit": 0 } } },
- { "type": "Text", "data": { "content": "keys 1-4 or click the pads · Beat toggles the loop · click a bus to change its volume", "fontSize": 14, "color": { "r": 0.72, "g": 0.76, "b": 0.86, "a": 0.9 }, "align": 1, "verticalAlign": 1 } }
+ { "type": "Text", "data": { "content": "keys 1-4 or click the pads · Beat toggles the loop · click a bus to change its volume · the orbiting dot is a spatial source", "fontSize": 14, "color": { "r": 0.72, "g": 0.76, "b": 0.86, "a": 0.9 }, "align": 1, "verticalAlign": 1 } }
+ ]
+ },
+ {
+ "id": 36, "name": "SpatialHum", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": -160, "z": 0 } } },
+ { "type": "ShapeRenderer", "data": { "size": { "x": 40, "y": 40 }, "color": { "r": 0.36, "g": 0.86, "b": 0.78, "a": 1 } } },
+ { "type": "AudioSource", "data": { "clip": "@uuid:b7c1d2e3-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "bus": "sfx", "volume": 0.7, "loop": true, "playOnAwake": true, "spatial": true, "minDistance": 90, "maxDistance": 700 } },
+ { "type": "Orbiting", "data": { "radius": 320, "speed": 0.6 } }
]
}
]
diff --git a/examples/audio-demo/src/components.ts b/examples/audio-demo/src/components.ts
index 892f2ab17..1005a2ea3 100644
--- a/examples/audio-demo/src/components.ts
+++ b/examples/audio-demo/src/components.ts
@@ -14,3 +14,8 @@ export const VolumeLabel = defineComponent('VolumeLabel', { bus: 'master' });
// A spectrum bar: reads analyser bin `index` each frame to set its height.
export const VisualizerBar = defineComponent('VisualizerBar', { index: 0 });
+
+// The spatial source's orbit around the listener: `radius` its half-width,
+// `speed` radians per second. The AudioSource riding it is authored in the
+// scene — this only moves the entity, which is what makes the sound move.
+export const Orbiting = defineComponent('Orbiting', { radius: 320, speed: 0.6 });
diff --git a/examples/audio-demo/src/main.ts b/examples/audio-demo/src/main.ts
index 706421b04..7afdee1c7 100644
--- a/examples/audio-demo/src/main.ts
+++ b/examples/audio-demo/src/main.ts
@@ -1,21 +1,19 @@
-// Audio — a drum machine that shows off the engine's audio system: pad SFX with
-// per-hit pitch/pan, a looping beat on the music bus, per-bus volume control, and
-// a real spectrum visualizer fed by the master-bus analyser.
-//
-// • Keys 1-4 or click the pads — Kick / Snare / Hi-Hat / Clap
-// • Beat button — toggle the looping music-bus beat
-// • Master / Music / SFX buttons — cycle each bus's volume
+// Audio — a drum machine over the engine's audio system: one-shot pads, a looping
+// beat on the music bus, per-bus volume, a real spectrum visualizer, and a spatial
+// source orbiting the listener. Controls and what each part shows: README.md.
import { addStartupSystem, addSystemToSchedule, Schedule } from 'esengine';
import './components';
import { preloadSystem } from './systems/preload';
import { sfxSystem } from './systems/sfx';
import { beatSystem } from './systems/beat';
+import { orbitSystem } from './systems/orbit';
import { volumeSystem } from './systems/volume';
import { visualizerSystem } from './systems/visualizer';
addStartupSystem(preloadSystem);
addSystemToSchedule(Schedule.Update, sfxSystem);
addSystemToSchedule(Schedule.Update, beatSystem);
+addSystemToSchedule(Schedule.Update, orbitSystem);
addSystemToSchedule(Schedule.Update, volumeSystem);
addSystemToSchedule(Schedule.Update, visualizerSystem);
diff --git a/examples/audio-demo/src/systems/orbit.ts b/examples/audio-demo/src/systems/orbit.ts
new file mode 100644
index 000000000..1773796a6
--- /dev/null
+++ b/examples/audio-demo/src/systems/orbit.ts
@@ -0,0 +1,26 @@
+import { defineSystem, Query, Mut, Res, Time, Transform } from 'esengine';
+import type { TimeData } from 'esengine';
+import { Orbiting } from '../components';
+
+// How far the orbit dips below the listener, and how tall the ellipse is. Kept
+// clear of the pads and the spectrum bars above it.
+const CENTRE_Y = -150;
+const RISE = 90;
+
+// Carry the spatial source around the listener at the camera. Nothing here
+// touches audio: the volume you hear and the ear it arrives at are the engine's
+// answer to where this entity ended up.
+export const orbitSystem = defineSystem(
+ [Query(Mut(Transform), Orbiting), Res(Time)],
+ (orbiters, time: TimeData) => {
+ for (const [, transform, orbit] of orbiters) {
+ const angle = time.elapsed * orbit.speed;
+ transform.position = {
+ x: Math.cos(angle) * orbit.radius,
+ y: CENTRE_Y + Math.sin(angle) * RISE,
+ z: 0,
+ };
+ }
+ },
+ { name: 'OrbitSystem' },
+);
diff --git a/sdk/src/audio/AudioPlugin.ts b/sdk/src/audio/AudioPlugin.ts
index 35d93b5c6..0a26a6825 100644
--- a/sdk/src/audio/AudioPlugin.ts
+++ b/sdk/src/audio/AudioPlugin.ts
@@ -14,6 +14,16 @@ import type { AudioHandle } from './PlatformAudioBackend';
import { isEditor, isPlayMode } from '../ecs/env';
import { log } from '../util/logger';
+/**
+ * Where a transform IS, which for a parented entity is not where it says it is:
+ * `position` is the offset from its parent, and a footstep loop under a walking
+ * character would stay at the character's origin forever. The engine derives the
+ * world fields; the fallback is for a world running without them.
+ */
+function worldPositionOf(t: WorldTransformData): Vec3 {
+ return t.worldPosition ?? t.position;
+}
+
export interface AudioPluginConfig {
initialPoolSize?: number;
masterVolume?: number;
@@ -74,6 +84,9 @@ export class AudioPlugin implements Plugin {
playedEntities.delete(entity);
});
const liveEntities = new Set<number>();
+ /** Clips an authored playOnAwake is waiting on, and ones that will never arrive. */
+ const loadingClips = new Set<string>();
+ const unplayableClips = new Set<string>();
let spatialListenerWarned = false;
let wasPlayMode = false;
@@ -110,8 +123,8 @@ export class AudioPlugin implements Plugin {
const listener = world.get(entity, AudioListener) as AudioListenerData;
if (listener.enabled) {
const wt = world.get(entity, WorldTransform) as WorldTransformData;
- listenerAt = wt.position;
- listenerRight = q.rotate(wt.rotation, { x: 1, y: 0, z: 0 });
+ listenerAt = worldPositionOf(wt);
+ listenerRight = q.rotate(wt.worldRotation ?? wt.rotation, { x: 1, y: 0, z: 0 });
hasListener = true;
break;
}
@@ -141,15 +154,20 @@ export class AudioPlugin implements Plugin {
});
activeSourceHandles.set(id, handle);
playedEntities.add(id);
- } else {
- // playOnAwake is a one-shot at spawn; mark it done even
- // on a miss, or this re-looks-up and re-warns every frame
- // forever. (Preload the clip before spawning.)
- playedEntities.add(id);
- log.warn(
- 'audio',
- `playOnAwake: clip "${source.clip}" not preloaded`,
- );
+ } else if (!unplayableClips.has(source.clip)) {
+ // A scene setting playOnAwake has already said to play
+ // it; demanding a preload call beside it is a component
+ // that silently does nothing. Unplayed until it lands.
+ if (!loadingClips.has(source.clip)) {
+ const clip = source.clip;
+ loadingClips.add(clip);
+ void audioAPI.preload(clip)
+ .catch((err) => {
+ unplayableClips.add(clip);
+ log.warn('audio', `playOnAwake: cannot load clip "${clip}"`, err);
+ })
+ .finally(() => loadingClips.delete(clip));
+ }
}
}
@@ -166,7 +184,7 @@ export class AudioPlugin implements Plugin {
}
const wt = world.tryGet?.(entity, WorldTransform) as WorldTransformData | undefined;
- const sourceAt: Vec3 = wt?.position ?? { x: 0, y: 0, z: 0 };
+ const sourceAt: Vec3 = wt ? worldPositionOf(wt) : { x: 0, y: 0, z: 0 };
const distance = spatialDistance(sourceAt, listenerAt);
const spatialConfig: SpatialAudioConfig = {
diff --git a/sdk/tests/audio-source-through-api.test.ts b/sdk/tests/audio-source-through-api.test.ts
index f821c2a84..1f48481af 100644
--- a/sdk/tests/audio-source-through-api.test.ts
+++ b/sdk/tests/audio-source-through-api.test.ts
@@ -70,6 +70,58 @@ describe('an AudioSource in the scene', () => {
expect((backend.play as ReturnType<typeof vi.fn>).mock.calls[0]![1].volume).toBeCloseTo(0.5, 6);
});
+ it('brings in the clip it names, with no preload call beside it', async () => {
+ const app = App.new();
+ app.addPlugin(new AudioPlugin());
+ const e = app.world.spawn();
+ app.world.insert(e, AudioSource, { clip: 'unheard.wav', playOnAwake: true, volume: 1 });
+
+ await app.tick(1 / 60);
+ // Nothing to play yet — but the frame asked for it rather than giving up.
+ expect(backend.play).not.toHaveBeenCalled();
+ expect(backend.loadBuffer).toHaveBeenCalledTimes(1);
+
+ await vi.waitFor(() => expect(app.getResource(Audio).getBufferHandle('unheard.wav')).toBeTruthy());
+ await app.tick(1 / 60);
+ expect(backend.play).toHaveBeenCalledTimes(1);
+ });
+
+ it('asks for a loading clip once, not once a frame', async () => {
+ // Never resolves: the frames that follow are the ones a slow clip gets.
+ (backend.loadBuffer as ReturnType<typeof vi.fn>).mockReturnValueOnce(new Promise(() => {}));
+ const app = App.new();
+ app.addPlugin(new AudioPlugin());
+ const audio = app.getResource(Audio);
+ const preload = vi.spyOn(audio, 'preload');
+ const e = app.world.spawn();
+ app.world.insert(e, AudioSource, { clip: 'slow.wav', playOnAwake: true });
+
+ for (let i = 0; i < 4; i++) await app.tick(1 / 60);
+
+ // The buffer cache de-dupes the LOAD, so counting backend calls would pass
+ // either way; what is being held here is the plugin not asking again.
+ expect(preload).toHaveBeenCalledTimes(1);
+ expect(backend.play).not.toHaveBeenCalled();
+ });
+
+ it('stops asking for a clip that cannot load', async () => {
+ (backend.loadBuffer as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('404'));
+ const app = App.new();
+ app.addPlugin(new AudioPlugin());
+ const preload = vi.spyOn(app.getResource(Audio), 'preload');
+ const e = app.world.spawn();
+ app.world.insert(e, AudioSource, { clip: 'missing.wav', playOnAwake: true });
+
+ for (let i = 0; i < 3; i++) await app.tick(1 / 60);
+ await vi.waitFor(() => expect(backend.loadBuffer).toHaveBeenCalled());
+ for (let i = 0; i < 3; i++) await app.tick(1 / 60);
+
+ // Retrying every frame for the rest of the session is the reason the old
+ // code gave up after one look; giving up is not the only way to stop.
+ expect(preload).toHaveBeenCalledTimes(1);
+ expect(backend.play).not.toHaveBeenCalled();
+ });
+
it('is counted against the voice cap, at the priority it declares', async () => {
const { app, audio } = await appWithClip();
audio.setMaxVoices(1);
diff --git a/sdk/tests/spatial-audio-scene.test.ts b/sdk/tests/spatial-audio-scene.test.ts
new file mode 100644
index 000000000..0f19f9ec1
--- /dev/null
+++ b/sdk/tests/spatial-audio-scene.test.ts
@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file spatial-audio-scene.test.ts
+ * @brief A spatial source is heard where it IS, not where it is offset to.
+ *
+ * `calculateAttenuation` and `calculatePanning` have been tested as
+ * arithmetic since the day they were written. What nothing drove was
+ * the frame that feeds them: which entity is the listener, and which
+ * transform field a source's place comes from. Audio was the one
+ * subsystem reading `position` — the offset from a parent — while
+ * every other reads `worldPosition`, so a loop parented to a walking
+ * character stayed at the character's origin and nobody could hear it.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { AudioHandle, PlatformAudioBackend } from '../src/audio/PlatformAudioBackend';
+import type { Quat, Vec3 } from '../src/types';
+
+const handles: AudioHandle[] = [];
+function playingHandle(): AudioHandle {
+ const h = {
+ id: handles.length + 1, stop: vi.fn(), pause: vi.fn(), resume: vi.fn(),
+ setVolume: vi.fn(), setPan: vi.fn(), setLoop: vi.fn(), setPlaybackRate: vi.fn(),
+ isPlaying: true, currentTime: 0, duration: 1,
+ };
+ handles.push(h);
+ return h;
+}
+
+const backend = {
+ name: 'Mock',
+ mixer: null,
+ isReady: true,
+ initialize: vi.fn().mockResolvedValue(undefined),
+ ensureResumed: vi.fn().mockResolvedValue(undefined),
+ loadBuffer: vi.fn().mockResolvedValue({ id: 1, duration: 1 }),
+ unloadBuffer: vi.fn(),
+ play: vi.fn(),
+ suspend: vi.fn(), resume: vi.fn(), dispose: vi.fn(),
+} as unknown as PlatformAudioBackend;
+
+vi.mock('../src/platform/base', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('../src/platform/base')>()),
+ platformCreateAudioBackend: () => backend,
+ platformOnMemoryWarning: () => () => {},
+}));
+
+/**
+ * Transform is a C++ component, and a unit test has no engine behind it. The
+ * stand-in carries BOTH pairs of fields, which is the whole point: an assertion
+ * cannot tell `position` from `worldPosition` unless the two disagree.
+ */
+vi.mock('../src/ecs/component', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('../src/ecs/component')>();
+ return {
+ ...actual,
+ WorldTransform: actual.defineComponent('TestPose', {
+ position: { x: 0, y: 0, z: 0 },
+ rotation: { x: 0, y: 0, z: 0, w: 1 },
+ worldPosition: { x: 0, y: 0, z: 0 },
+ worldRotation: { x: 0, y: 0, z: 0, w: 1 },
+ }),
+ };
+});
+
+const { App } = await import('../src/app/app');
+const { AudioPlugin } = await import('../src/audio/AudioPlugin');
+const { Audio } = await import('../src/audio/Audio');
+const { AudioSource, AudioListener } = await import('../src/audio/AudioComponents');
+const { WorldTransform } = await import('../src/ecs/component');
+const { AttenuationModel } = await import('../src/audio/SpatialAudio');
+
+interface Pose { position: Vec3; rotation: Quat; worldPosition: Vec3; worldRotation: Quat }
+const IDENTITY: Quat = { x: 0, y: 0, z: 0, w: 1 };
+/** A quarter turn about +Y: the listener's right hand swings to face −Z. */
+const QUARTER_Y: Quat = { x: 0, y: Math.SQRT1_2, z: 0, w: Math.SQRT1_2 };
+
+function pose(local: Vec3, world: Vec3, worldRotation: Quat = IDENTITY): Pose {
+ return { position: local, rotation: IDENTITY, worldPosition: world, worldRotation };
+}
+
+async function appWithClip() {
+ const app = App.new();
+ app.addPlugin(new AudioPlugin());
+ await app.getResource(Audio).preload('hum.wav');
+ return app;
+}
+
+/** A spatial source that plays itself, as one authored in a scene does. */
+const SPATIAL = {
+ clip: 'hum.wav', playOnAwake: true, loop: true, spatial: true, volume: 1,
+ minDistance: 100, maxDistance: 1000, rolloff: 1,
+ attenuationModel: AttenuationModel.Linear,
+};
+
+describe('a spatial AudioSource in a scene', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ handles.length = 0;
+ (backend.play as ReturnType<typeof vi.fn>).mockImplementation(() => playingHandle());
+ });
+
+ it('is placed where the world puts it, not where its parent offset says', async () => {
+ const app = await appWithClip();
+ const ear = app.world.spawn();
+ app.world.insert(ear, AudioListener, { enabled: true });
+ app.world.insert(ear, WorldTransform, pose({ x: 0, y: 0, z: 0 }, { x: 0, y: 0, z: 0 }));
+
+ // Authored at its parent's origin and carried 550 units away by it — the
+ // shape of every loop attached to a character or a vehicle.
+ const source = app.world.spawn();
+ app.world.insert(source, AudioSource, SPATIAL);
+ app.world.insert(source, WorldTransform, pose({ x: 0, y: 0, z: 0 }, { x: 550, y: 0, z: 0 }));
+
+ await app.tick(1 / 60);
+ await app.tick(1 / 60);
+
+ const handle = handles[0]!;
+ const volume = (handle.setVolume as ReturnType<typeof vi.fn>).mock.calls.at(-1)![0] as number;
+ // Linear over [100, 1000]: half way out is half gain. Read from `position`
+ // the distance is 0 and this is 1 — audible at full volume from anywhere.
+ expect(volume).toBeCloseTo(0.5, 2);
+ });
+
+ it('is panned by where the listener is facing, in world space', async () => {
+ const app = await appWithClip();
+ const ear = app.world.spawn();
+ app.world.insert(ear, AudioListener, { enabled: true });
+ // Turned a quarter turn, so world +X is now BEHIND-right rather than right.
+ app.world.insert(ear, WorldTransform, pose({ x: 0, y: 0, z: 0 }, { x: 0, y: 0, z: 0 }, QUARTER_Y));
+
+ const source = app.world.spawn();
+ app.world.insert(source, AudioSource, SPATIAL);
+ app.world.insert(source, WorldTransform, pose({ x: 0, y: 0, z: 0 }, { x: 0, y: 0, z: -400 }));
+
+ await app.tick(1 / 60);
+ await app.tick(1 / 60);
+
+ const pan = (handles[0]!.setPan as ReturnType<typeof vi.fn>).mock.calls.at(-1)![0] as number;
+ // −Z is the turned listener's right, 400 of the 1000 units panning runs
+ // over. Unturned, the same source is dead ahead and this is 0.
+ expect(pan).toBeCloseTo(0.4, 2);
+ });
+
+ it("leaves a non-spatial source's volume alone", async () => {
+ const app = await appWithClip();
+ const ear = app.world.spawn();
+ app.world.insert(ear, AudioListener, { enabled: true });
+ app.world.insert(ear, WorldTransform, pose({ x: 0, y: 0, z: 0 }, { x: 0, y: 0, z: 0 }));
+
+ const source = app.world.spawn();
+ app.world.insert(source, AudioSource, { ...SPATIAL, spatial: false });
+ app.world.insert(source, WorldTransform, pose({ x: 0, y: 0, z: 0 }, { x: 900, y: 0, z: 0 }));
+
+ await app.tick(1 / 60);
+ await app.tick(1 / 60);
+
+ // A UI sound is placeless. Attenuating it would also fight every
+ // `setVolume` a script makes, every frame.
+ expect(handles[0]!.setVolume).not.toHaveBeenCalled();
+ expect(handles[0]!.setPan).not.toHaveBeenCalled();
+ });
+});
diff --git a/tools/check-corpus-authoring.mjs b/tools/check-corpus-authoring.mjs
index 1be6ff78d..2462a1dde 100644
--- a/tools/check-corpus-authoring.mjs
+++ b/tools/check-corpus-authoring.mjs
@@ -117,7 +117,6 @@ const DISPOSITION = {
// — owed: a creator-facing component nothing in the shipped corpus authors.
// Each reason names where the coverage belongs. —
- AudioListener: ['owed', 'spatial audio has no corpus at all: no scene sets AudioSource.spatial, so the listener every 3D mix needs is absent and the engine\'s "spatial audio used but no AudioListener entity found" warning has never been seen. audio-demo or third-person-3d'],
UIDialog: ['owed', 'the Create picker builds a Dialog in one click and its own header promises a prefab dialog works "without any code hookup" — ui-controls calls createDialog() from code instead, so the promise has no witness'],
UIToggle: ['owed', 'Create > UI > Toggle exists; ui-controls builds toggles with createToggle() and no scene carries one'],
UIToggleGroup: ['owed', 'exclusive toggles (tab bar, difficulty picker) sit on the common ancestor — a relationship only an authored hierarchy demonstrates'],