From c07c4184e94d7be52b32e40be79bbe2ac26e978a Mon Sep 17 00:00:00 2001
From: Olivier Biot <olivier.biot@me.com>
Date: Wed, 7 Oct 2026 19:29:42 +0800
Subject: [PATCH 1/2] Spatial audio: a movable listener, sounds placed in world
 pixels

Positional audio could only be reached by doing the work the engine
should be doing. The listener was welded to the origin with no public
call to move it, so a game had to subtract the player's position from
every source, every frame, and re-express it in the listener's axes by
hand. The panner defaults were WebAudio's, which are metres, so a sound
given pixel coordinates went near silent a few tiles out. And the two
ways to place a sound quietly excluded each other.

Added:

- `follow`, `at` and `stopWithTarget` on `audio.play()`. A sound tracks a
  renderable's absolute position after every world update, or pins to a
  fixed point, and can end with the entity that owns it. `audio.unfollow`
  detaches one and leaves it playing.
- `audio.setListener(target)`, `audio.listener()` and
  `audio.listenerOrientation()`. A `Camera3d` target contributes its
  basis as well as its position. Source positions become absolute world
  coordinates rather than offsets from the player.
- `audio.setSpatialDefaults()` / `getSpatialDefaults()`, starting from
  `refDistance: 240`, `maxDistance: 10000` and `equalpower`.

Everything takes melonJS world coordinates, y measured down; the Y flip
into Web Audio's Y-up space happens in exactly one place.

Fixed, all found while building the above:

- `stereo()` and `position()` drive one panner node per voice, and the
  first call fixed which kind it was, making the other a silent no-op for
  that voice's life. The node follows the last writer now.
- `audio.panner(name, attrs)` with no id never wrote the clip's own
  defaults, so a call before the first `play()` was lost entirely and
  every later voice inherited construction-time values. It writes the
  group, and merges rather than replaces.
- Sound effects kept playing while the window was away, because pausing
  the game only ever reached the music track. The mix is muted on blur
  and restored on focus, gated by the existing `pauseOnBlur` and
  `stopOnBlur` settings rather than a new one.

Opt-in end to end: until a game asks for a listener or a placement, no
frame handler is installed and every existing call behaves as before.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NGvtaUNATVCVxD2qcbiY4t
---
 packages/melonjs/CHANGELOG.md                 |  10 +-
 .../melonjs/skills/melonjs-audio/SKILL.md     | 120 ++++-
 .../melonjs/src/application/application.ts    |  11 +
 packages/melonjs/src/audio/audio.ts           |  15 +
 packages/melonjs/src/audio/autopause.ts       |  96 ++++
 packages/melonjs/src/audio/backend/spatial.ts | 146 ++++--
 packages/melonjs/src/audio/playback.ts        |  35 ++
 packages/melonjs/src/audio/spatial.ts         | 494 ++++++++++++++++++
 packages/melonjs/src/audio/state.ts           |  66 +++
 packages/melonjs/src/audio/types.ts           |  46 +-
 packages/melonjs/src/index.ts                 |   5 +
 packages/melonjs/tests/audio-spatial.spec.js  | 488 +++++++++++++++++
 12 files changed, 1447 insertions(+), 85 deletions(-)
 create mode 100644 packages/melonjs/src/audio/autopause.ts
 create mode 100644 packages/melonjs/src/audio/spatial.ts
 create mode 100644 packages/melonjs/tests/audio-spatial.spec.js

diff --git a/packages/melonjs/CHANGELOG.md b/packages/melonjs/CHANGELOG.md
index 08587b2f42..4ff76b22a7 100644
--- a/packages/melonjs/CHANGELOG.md
+++ b/packages/melonjs/CHANGELOG.md
@@ -2,9 +2,17 @@
 
 ## [20.9.0] (melonJS 2) - _unreleased_
 
+### Added
+- **Spatial audio placed in world coordinates**: `audio.play(name, { follow: renderable })` tracks a sound to a renderable every frame, `{ at: { x, y } }` pins one to a fixed world point, and `{ stopWithTarget: true }` ends it when that renderable is destroyed. The numbers are world pixels with y measured down, the same ones already in `pos`, so a game converts nothing by hand. `audio.unfollow(id)` detaches a sound and leaves it playing where it is
+- **A movable listener**: `audio.setListener(target)` puts the ear on a renderable and keeps it there, while `audio.listener(x, y, z)` and `audio.listenerOrientation(fx, fy, fz, ux, uy, uz)` place it by hand and read it back when called with no arguments. Source positions become absolute world coordinates instead of offsets from the player, and a `Camera3d` target contributes orientation as well, taken from its own basis. It is opt-in end to end: until a game asks for a listener no frame handler is installed, and every existing `position` / `stereo` / `panner` call behaves exactly as it did
+- **Panner defaults shaped for pixels**: a placed sound now starts from `refDistance: 240`, `maxDistance: 10000`, `distanceModel: "inverse"` and `panningModel: "equalpower"`, so it carries across a screen instead of going near silent a few tiles out. `audio.setSpatialDefaults()` and `audio.getSpatialDefaults()` change what new voices inherit
+
 ### Fixed
+- Audio: `stereo()` and `position()` drive the same per-instance panner node, and the first of the two to be called decided what kind of node it was, which made the other a silent no-op for the life of that voice. The node now follows whichever was called last, so the order no longer matters
+- Audio: `audio.panner(name, attributes)` with no playback id wrote only the voices already playing and never the clip's own defaults, so a call before the first `play()` changed nothing at all, the getter read back construction-time values forever, and every later voice inherited those. It writes the group now, and merges rather than replaces, so setting one attribute leaves the others alone
+- Audio: sound effects kept playing while the window did not have focus, because pausing the game only ever reached the current music track. A looping effect such as an engine hum or an alarm played on over whatever the player had switched to. The mix is muted on blur and restored on focus, which covers `tone()` and `noise()` and anything a game hangs off `getMasterGain()` as well as ordinary clips, and it is gated by the existing `pauseOnBlur` and `stopOnBlur` settings so a game that deliberately keeps running in the background keeps its audio too
 - Skills: the UI skill listed `NineSliceSprite` panels among what it covers but never mentioned them. It now shows both ways to make one (`createSpriteFromName(name, { width, height }, true)` from an atlas, or the constructor from an image) and the three things that trip people up: `width` and `height` are the size to stretch to and are mandatory, `insetx` / `insety` default to a quarter of the image rather than its border, and the anchor is the centre
-- Skills: the audio skill now covers what positional sound needs and did not say: the listener is fixed at the origin with no public call to move it, so positions are relative to the player; the panner defaults assume metres, so a sound placed in pixels is near silent a few tiles out (`refDistance: 1` puts one 100 px away at about 1%); and `stereo()` and `position()` drive the same per-instance panner, so whichever runs first makes the other a silent no-op. It also shows how to put reverb, echo or a compressor on the whole mix through `getMasterGain()`, noting that a streamed clip bypasses it, and documents `hasAudio()`, `hasFormat()`, runtime `audio.load()`, and the `rate` and `fade` ranges
+- Skills: the audio skill now covers what positional sound needs and did not say. It documents the movable listener and the `follow` / `at` play options, the pixel-shaped panner defaults and how to widen them, and that every one of these calls takes world coordinates with y measured down. It also shows how to put reverb, echo or a compressor on the whole mix through `getMasterGain()`, noting that a streamed clip bypasses it, and documents `hasAudio()`, `hasFormat()`, runtime `audio.load()`, and the `rate` and `fade` ranges
 
 ## [20.8.0] (melonJS 2) - _2026-10-06_
 
diff --git a/packages/melonjs/skills/melonjs-audio/SKILL.md b/packages/melonjs/skills/melonjs-audio/SKILL.md
index 0e98eaf0f8..7a74d66b77 100644
--- a/packages/melonjs/skills/melonjs-audio/SKILL.md
+++ b/packages/melonjs/skills/melonjs-audio/SKILL.md
@@ -76,8 +76,9 @@ audio.play("sfx", { sprite: "jump" });
 
 The optional third element marks a region as looping. `play()`'s second argument
 takes either the original `loop` boolean or a `PlayOptions` object
-(`sprite`, `loop`, `onend`, `volume`) — both forms work. Object fields win over
-the positional `onend` / `volume` arguments when both are supplied.
+(`sprite`, `loop`, `onend`, `volume`, plus the spatial `follow`, `at` and
+`stopWithTarget`) — both forms work. Object fields win over the positional
+`onend` / `volume` arguments when both are supplied.
 
 ## Clip state
 
@@ -111,6 +112,14 @@ audio.muted();                  // global mute state
 `audio.unload(name)` / `audio.unloadAll()` free the decoded buffers; `unload`
 also clears the current-track pointer if it named that clip.
 
+### Losing focus mutes everything
+
+When the window loses focus the engine mutes all audio, and unmutes it on
+focus. That covers sound effects, procedural `tone` / `noise` and the mixer
+effects, not just the music track that `state.pause()` pauses. Set
+`pauseOnBlur: false` in the application settings if a clip has to keep playing
+in the background.
+
 ## Spatial audio
 
 ```js
@@ -126,44 +135,95 @@ Called with just the clip name, each of the four returns the current value —
 `stereo` gives `0` and `position` gives `[0, 0, 0]` before they have ever been
 set.
 
-### The listener is fixed at the origin
+### Let the engine place the sound: `follow` and `at`
+
+The shortest path to positional audio is a play option. Both take **world
+pixels**, the same numbers as `pos.x` / `pos.y`, and the engine converts to
+audio space for you:
+
+```js
+// tracks the renderable every frame, and stops when it is destroyed
+audio.play("ufo", { follow: this, stopWithTarget: true });
+
+// pinned to a fixed world point
+audio.play("portal", { at: { x: 1200, y: 480 } });
+```
+
+`follow` re-reads the target's **absolute** position each frame, so a renderable
+nested in a moving container is placed correctly. `stopWithTarget` is what you
+want for a sound that belongs to an entity: without it a looping clip on a
+destroyed renderable keeps playing from wherever it last was. `audio.unfollow(id)`
+detaches a sound and leaves it playing where it is.
 
-The ear sits at `(0, 0, 0)` facing `-z`, and **there is no public call to move
-it**. Positions are therefore *relative to the listener*: for a sound to come
-from the left of the player, pass the source's position minus the player's,
-every frame either one moves.
+### Move the listener, don't do the subtraction yourself
 
 ```js
-// in the emitter's update()
-audio.position("engine", this.pos.x - player.pos.x, 0, -0.5, this.engineId);
+audio.setListener(player);                  // tracked every frame
+audio.listener(x, y, z);                    // or place it by hand
+audio.listener();                           // → [x, y, z] in world pixels
+audio.listenerOrientation(fx, fy, fz, ux, uy, uz);
+audio.setListener(null);                    // stop tracking
 ```
 
-### Distances are in the units you pass — and the defaults assume metres
+With a listener in the world, source positions are **absolute world
+coordinates**, not offsets. The older idiom — passing `source.pos.x -
+player.pos.x` every frame with the ear stuck at the origin — still works, but
+only if you leave the listener at `(0, 0, 0)`; mixing the two double-counts the
+player's position.
 
-The panner defaults are `distanceModel: "inverse"`, `refDistance: 1`,
-`rolloffFactor: 1`, `maxDistance: 10000`, `panningModel: "HRTF"`. With
-`refDistance: 1`, a source 100 units away plays at about **1%** volume, so a
-sound positioned in raw pixels is effectively silent a few tiles out. Either
-set `refDistance` to the distance in pixels at which it should still be at full
-volume, or scale positions down (divide by a tile size) before passing them:
+`setListener` places the ear at the target's absolute position after the world
+updates. It does not touch orientation, so a side-scroller keeps the default
+"facing into the screen" and gets left-right panning plus distance falloff with
+one call.
+
+**Y is down.** Every one of these calls takes and returns melonJS world
+coordinates, where y grows downward; the Y-up flip Web Audio wants happens
+inside the engine. Pass `pos.y` as it is.
+
+### The defaults are tuned for pixels
+
+`audio.setSpatialDefaults()` / `getSpatialDefaults()` set the panner attributes
+every new voice starts from, and the shipped defaults already assume a 2D game
+measured in pixels:
+
+| attribute | default | why |
+|---|---|---|
+| `refDistance` | `240` | full volume out to roughly a few tiles |
+| `maxDistance` | `10000` | inaudible past ~2000 px with the inverse model |
+| `panningModel` | `"equalpower"` | cheap, and it does not smear a 2D mix |
+| `distanceModel` | `"inverse"` | smooth rolloff |
+
+So `audio.play("ufo", { follow: ufo })` is audible at a sane range with no
+tuning. Widen or tighten the field once, globally:
 
 ```js
-audio.panner("engine", { refDistance: 200, rolloffFactor: 1 });
-// or: audio.position("engine", dx / 32, 0, -0.5);
+audio.setSpatialDefaults({ refDistance: 400, maxDistance: 20000 });
 ```
 
-### `stereo` and `position` are one or the other
+`audio.panner(name, attrs, id?)` still overrides per clip or per voice, and it
+merges over the current values rather than replacing them, so writing one field
+no longer resets the rest. Called without an `id` it writes the **group**
+defaults, which is what a clip-wide tuning call looks like.
+
+For a 3D scene where front-to-back matters, `panningModel: "HRTF"` is worth the
+cost; for a 2D one it mostly muddies the stereo image.
+
+### `stereo` and `position`: last writer wins
+
+Both drive the same per-instance panner node, and the engine swaps the node to
+match whichever you called **last**: `stereo()` after `position()` gives you
+plain left-right panning, and `position()` after `stereo()` gives you 3D
+falloff. Neither silently does nothing any more, and the order you call them in
+no longer matters.
 
-Both drive the same per-instance panner node, and **the first one called
-decides what that node is**: a stereo panner after `stereo()`, a 3D panner after
-`position()`. After that the other call silently does nothing on that instance.
-For a 2D game, left-right `stereo()` is usually all you want; reach for
-`position()` only when distance falloff matters, and then use it alone.
+Still pick one per voice and stay with it. A 2D game usually wants `stereo()`
+alone; reach for `position()` (or `follow` / `at`) when distance falloff
+matters.
 
 **Spatial audio is WebAudio-only.** On a clip loaded with `stream: true` (or
 `html5: true`) `stereo` / `position` / `orientation` return early and do
 nothing — which is exactly the case for the long music tracks people reach for
-first.
+first. `follow` and `at` are equally inert on a streamed clip.
 
 ## Procedural sound
 
@@ -327,10 +387,14 @@ either way — blank screen, empty console.
 | a streamed clip ignores `withCredentials` | `stream: true` plays through an `<audio>` element; preload it buffered instead |
 | `audio.tone(440, {...})` does nothing / errors | `tone` takes a single options object with a required `duration` |
 | `tone` / `noise` are silent with no error | no WebAudio context — `getAudioContext()` returned `null` |
-| a positioned sound is silent, or only audible right next to the player | positions in pixels with the default `refDistance: 1` — set `refDistance` in pixels, or scale positions down |
-| a positioned sound does not follow the player | the listener never moves — pass positions relative to the player, every frame |
-| `position()` does nothing on a clip that pans with `stereo()` (or the reverse) | the first call fixed the instance's panner type — use one or the other |
+| a positioned sound is silent, or only audible right next to the player | `refDistance` was narrowed below the pixel default — widen it with `audio.setSpatialDefaults({ refDistance })` |
+| a positioned sound does not follow the player | nothing is placing it — `audio.play(name, { follow: entity })`, and `audio.setListener(player)` once |
+| a followed sound pans to the wrong side as the player moves | the listener was moved **and** positions are still relative to the player — with a listener in the world, pass absolute world coordinates |
+| a looping sound outlives the entity that owns it | `follow` without `stopWithTarget: true` |
+| `audio.panner()` reset the attributes I set earlier | it merges now, so this is fixed; a stale build still replaces them |
+| `position()` does nothing on a clip that pans with `stereo()` (or the reverse) | fixed: the node follows whichever was called last. On a stale build the first call fixed it |
 | a reverb / compressor on the master gain does not affect the music | the music is `stream: true`, which bypasses the master gain — preload it buffered |
+| sound effects keep playing after the window loses focus | a build older than 20.9 — `state.pause()` only ever paused the music track; set `pauseOnBlur: false` if that was deliberate |
 
 ## Related skills
 
diff --git a/packages/melonjs/src/application/application.ts b/packages/melonjs/src/application/application.ts
index 6d4b08c550..4c0bd465ef 100644
--- a/packages/melonjs/src/application/application.ts
+++ b/packages/melonjs/src/application/application.ts
@@ -1,3 +1,4 @@
+import { muteOnBlur, unmuteOnFocus } from "../audio/autopause.ts";
 import type Camera2d from "./../camera/camera2d.ts";
 import { AUTO, CANVAS, WEBGL, WEBGPU } from "../const.ts";
 import type { PhysicsAdapter } from "../physics/adapter.ts";
@@ -1075,6 +1076,12 @@ export default class Application {
 		if (this.pauseOnBlur) {
 			state.pause(true);
 		}
+		if (this.stopOnBlur || this.pauseOnBlur) {
+			// `state.stop()` / `state.pause()` only reach the current music
+			// track, so without this a looping sound effect plays on over
+			// whatever the player switched to
+			muteOnBlur();
+		}
 	}
 
 	/**
@@ -1088,6 +1095,10 @@ export default class Application {
 		if (this.resumeOnFocus) {
 			state.resume(true);
 		}
+		// unconditional: it only undoes a mute this module itself applied, and
+		// a game that stops on blur without resuming on focus would otherwise
+		// be left silent for good
+		unmuteOnFocus();
 	}
 
 	/**
diff --git a/packages/melonjs/src/audio/audio.ts b/packages/melonjs/src/audio/audio.ts
index 75fdc73778..0da3036075 100644
--- a/packages/melonjs/src/audio/audio.ts
+++ b/packages/melonjs/src/audio/audio.ts
@@ -9,6 +9,9 @@
  *   `pause`, `resume`, `stop`, `fade`, `seek`, `rate`, `stereo`,
  *   `position`, `orientation`, `panner`).
  * - {@link ./procedural.ts} — procedural primitives (`tone`, `noise`).
+ * - {@link ./spatial.ts} — the world-space layer: a movable listener,
+ *   sounds that follow a renderable, and the pixel-shaped defaults.
+ * - {@link ./autopause.ts} — silencing the mix while the window is away.
  * - {@link ./types.ts} — public TypeScript shapes.
  *
  * This file owns the remaining lifecycle / track / mix / unload
@@ -16,6 +19,7 @@
  */
 
 import { play } from "./playback.ts";
+import { releaseSpatialClip } from "./spatial.ts";
 import {
 	state as audioState,
 	getGlobalVolume,
@@ -45,6 +49,15 @@ export {
 	stop,
 } from "./playback.ts";
 export { noise, tone } from "./procedural.ts";
+
+export {
+	getSpatialDefaults,
+	listener,
+	listenerOrientation,
+	setListener,
+	setSpatialDefaults,
+	unfollow,
+} from "./spatial.ts";
 // Public re-exports from the split modules.
 export {
 	getAudioContext,
@@ -275,6 +288,7 @@ export function muted(): boolean {
  * @category Audio
  */
 export function unload(sound_name: string): boolean {
+	releaseSpatialClip(sound_name);
 	const sound = audioState.tracks[sound_name];
 	if (!sound) {
 		return false;
@@ -303,6 +317,7 @@ export function unload(sound_name: string): boolean {
  * @category Audio
  */
 export function unloadAll(): void {
+	releaseSpatialClip();
 	for (const sound_name in audioState.tracks) {
 		if (Object.prototype.hasOwnProperty.call(audioState.tracks, sound_name)) {
 			unload(sound_name);
diff --git a/packages/melonjs/src/audio/autopause.ts b/packages/melonjs/src/audio/autopause.ts
new file mode 100644
index 0000000000..90619a496c
--- /dev/null
+++ b/packages/melonjs/src/audio/autopause.ts
@@ -0,0 +1,96 @@
+/**
+ * Silence the game's sound effects while the window does not have focus.
+ *
+ * `Application` pauses the game on blur and resumes it on focus (its
+ * `pauseOnBlur` / `resumeOnFocus` settings, both on by default), and
+ * `state.pause()` already pauses the MUSIC TRACK. Nothing ever silenced the
+ * sound effects, so a looping one — an engine hum, an alarm, ambience — kept
+ * playing over whatever the player switched to.
+ *
+ * Driven from `Application#_onBlur` / `_onFocus` rather than from
+ * `STATE_PAUSE`, deliberately. A state pause is not always a focus loss:
+ * `state.freeze()` forwards its `music` flag into `state.pause()` for a
+ * hit-stop measured in tens of milliseconds, and muting there would punch a
+ * hole in the very impact sound the freeze exists to emphasise. A game's own
+ * pause menu is the same story, and would lose its UI clicks. Focus loss is
+ * the case where silence is unambiguously right.
+ *
+ * Driving it from the application also means the existing `stopOnBlur` /
+ * `pauseOnBlur` / `resumeOnFocus` settings gate it, instead of a fourth
+ * setting that says almost the same thing. A game that opted out of pausing
+ * in the background is a game that wants to keep running there, audio
+ * included.
+ *
+ * MUTED rather than stopped or paused:
+ *
+ * - stopping discards playback ids, and an id is the handle a game holds to
+ *   reposition or fade a sound, so a loop could never be resumed in place;
+ * - per-voice pausing would have to be taught about every source in turn, and
+ *   would miss the procedural `tone` / `noise` primitives and anything a game
+ *   hangs off `getMasterGain()`;
+ * - muting zeroes the master gain, which everything routes through, and it
+ *   lets a short one-shot finish silently instead of queueing up to fire the
+ *   moment the player comes back.
+ */
+
+import { isGlobalMuted, setGlobalMuted } from "./state.ts";
+
+/**
+ * Whether this module is the reason audio is muted.
+ *
+ * A game that muted itself must come back muted: the player chose silence,
+ * and a focus round trip is not consent to undo that. Latched, so two blurs
+ * followed by one focus cannot capture the muted state we set ourselves and
+ * then restore it as though the game had asked for sound.
+ */
+let mutedByBlur = false;
+
+/**
+ * Mute the mix on blur, unless the game was already muted.
+ *
+ * Called by the application when the window loses focus and its settings say
+ * the game should not keep running in the background.
+ * @internal
+ * @ignore
+ */
+export function muteOnBlur(): void {
+	if (mutedByBlur || isGlobalMuted()) {
+		// already silent, by us or by the game: nothing to capture, and
+		// nothing to restore later
+		return;
+	}
+	mutedByBlur = true;
+	setGlobalMuted(true);
+}
+
+/**
+ * Restore the mix on focus, but only if we are the ones who muted it.
+ * @internal
+ * @ignore
+ */
+export function unmuteOnFocus(): void {
+	if (!mutedByBlur) {
+		return;
+	}
+	mutedByBlur = false;
+	setGlobalMuted(false);
+}
+
+/**
+ * Whether the mix is currently silenced because the window lost focus.
+ * @returns true while blur-muted
+ * @internal
+ * @ignore
+ */
+export function isMutedByBlur(): boolean {
+	return mutedByBlur;
+}
+
+/**
+ * Forget that we muted, without touching the mix. For tests and teardown.
+ * @internal
+ * @ignore
+ */
+export function resetAutoPause(): void {
+	mutedByBlur = false;
+}
diff --git a/packages/melonjs/src/audio/backend/spatial.ts b/packages/melonjs/src/audio/backend/spatial.ts
index ac50942831..7ccacb2eaf 100644
--- a/packages/melonjs/src/audio/backend/spatial.ts
+++ b/packages/melonjs/src/audio/backend/spatial.ts
@@ -274,6 +274,65 @@ export type SpatialSound = Sound &
 		): SpatialSound | PannerAttrOptions;
 	};
 
+/**
+ * Merge a partial panner-attribute object over a full one.
+ *
+ * Every field keeps the base's value unless the patch names it, which is what
+ * lets `pannerAttr({ refDistance })` leave the cone geometry alone.
+ * @param base - the attributes to start from
+ * @param patch - the fields the caller named
+ * @returns a new, complete attribute set
+ */
+function mergePannerAttr(
+	base: PannerAttrOptions,
+	patch: Partial<PannerAttrOptions>,
+): PannerAttrOptions {
+	return {
+		coneInnerAngle: patch.coneInnerAngle ?? base.coneInnerAngle,
+		coneOuterAngle: patch.coneOuterAngle ?? base.coneOuterAngle,
+		coneOuterGain: patch.coneOuterGain ?? base.coneOuterGain,
+		distanceModel: patch.distanceModel ?? base.distanceModel,
+		maxDistance: patch.maxDistance ?? base.maxDistance,
+		refDistance: patch.refDistance ?? base.refDistance,
+		rolloffFactor: patch.rolloffFactor ?? base.rolloffFactor,
+		panningModel: patch.panningModel ?? base.panningModel,
+	};
+}
+
+/**
+ * Make sure a voice's panner is the flavour being asked for.
+ *
+ * A voice has ONE panner, and the two kinds are mutually exclusive: a
+ * `StereoPannerNode` takes a pan, a `PannerNode` takes a position. The
+ * original code built one only if none existed and then guarded each updater
+ * with an `instanceof`, so whichever of `stereo()` / `pos()` ran first won and
+ * the other became a SILENT no-op, with nothing logged.
+ *
+ * Last writer wins instead: the wrong node is disconnected and rebuilt. The
+ * caller must clear whichever of `_stereo` / `_pos` it is not setting, or the
+ * voice's `reset()` resurrects the old flavour on the next play.
+ * @param sound - the voice to check
+ * @param want - the flavour the caller is about to write
+ * @returns true when the panner was rebuilt
+ */
+function ensurePannerType(
+	sound: Voice & SpatialVoiceState,
+	want: "stereo" | "spatial",
+): boolean {
+	const isStereo = sound._panner instanceof StereoPannerNode;
+	if (sound._panner !== undefined && isStereo === (want === "stereo")) {
+		return false;
+	}
+	if (sound._panner !== undefined) {
+		// leaving it connected would strand a live node between the source
+		// and the voice's gain. No need to clear the field: `setupPanner`
+		// assigns the replacement over it.
+		sound._panner.disconnect();
+	}
+	setupPanner(sound, want);
+	return true;
+}
+
 /**
  * Setup a panner node for a sound
  * @param sound - the sound the hook fires for
@@ -663,16 +722,18 @@ export function installSpatialOnSound(
 		for (let i = 0; i < ids.length; i++) {
 			const sound = self._soundById(ids[i]) as Voice & SpatialVoiceState;
 			if (sound) {
-				sound._stereo = pan ?? null;
-
-				// Create a new panner node if one doesn't already exist
-				if (!sound._panner) {
-					// Make sure we have a position to setup the node with
-					if (!sound._pos) {
-						sound._pos = self._pos || [0, 0, -0.5];
-					}
-					setupPanner(sound, pannerType);
-				} else if (
+				// Make sure we have a position to setup the node with
+				if (!sound._pos) {
+					sound._pos = self._pos || [0, 0, -0.5];
+				}
+				// `0` rather than `null`: `reset()` prefers `_stereo` over
+				// `_pos` and skips a null one, so a voice panned back to
+				// centre would come back as the OTHER flavour on its next play
+				sound._stereo = pan ?? 0;
+				// a position may have been set on this voice first, in which
+				// case the panner is the other flavour and has to be swapped
+				ensurePannerType(sound, pannerType);
+				if (
 					pannerType === "stereo" &&
 					sound._panner instanceof StereoPannerNode
 				) {
@@ -735,11 +796,15 @@ export function installSpatialOnSound(
 				const sound = self._soundById(ids[i]) as Voice & SpatialVoiceState;
 				if (sound) {
 					sound._pos = [x, y, z];
-
-					// Create a new panner node if one doesn't already exist
-					if (!sound._panner) {
-						setupPanner(sound, "spatial");
-					} else if (sound._panner instanceof PannerNode) {
+					// the mirror of the clear in `stereo()`: last writer wins,
+					// and `reset()` must not resurrect a stale stereo node
+					sound._stereo = null;
+
+					// a stereo pan may have been set on this voice first, in
+					// which case the panner is the other flavour; swap it
+					// rather than letting this call do nothing
+					ensurePannerType(sound, "spatial");
+					if (sound._panner instanceof PannerNode) {
 						// Update position
 						if (typeof sound._panner.positionX !== "undefined") {
 							sound._panner.positionX.setValueAtTime(
@@ -901,6 +966,18 @@ export function installSpatialOnSound(
 			id = parseInt(String(args[1]), 10);
 		}
 
+		// Update the GROUP too when no single voice was named. Upstream does
+		// this and the port dropped it, so `pannerAttr({...})` before the
+		// first play changed nothing at all, the getter read back
+		// construction-time defaults forever, and every new voice inherited
+		// those defaults rather than what the game had asked for.
+		if (id === undefined) {
+			self._pannerAttr = mergePannerAttr(
+				self._pannerAttr,
+				o as Partial<PannerAttrOptions>,
+			);
+		}
+
 		// Update the values of the specified sounds
 		const ids = self._getSoundIds(id);
 		for (let i = 0; i < ids.length; i++) {
@@ -908,41 +985,10 @@ export function installSpatialOnSound(
 
 			if (sound) {
 				// Merge the new values into the sound
-				const pa = sound._pannerAttr;
-				sound._pannerAttr = {
-					coneInnerAngle:
-						typeof o.coneInnerAngle !== "undefined"
-							? o.coneInnerAngle
-							: pa.coneInnerAngle,
-					coneOuterAngle:
-						typeof o.coneOuterAngle !== "undefined"
-							? o.coneOuterAngle
-							: pa.coneOuterAngle,
-					coneOuterGain:
-						typeof o.coneOuterGain !== "undefined"
-							? o.coneOuterGain
-							: pa.coneOuterGain,
-					distanceModel:
-						typeof o.distanceModel !== "undefined"
-							? o.distanceModel
-							: pa.distanceModel,
-					maxDistance:
-						typeof o.maxDistance !== "undefined"
-							? o.maxDistance
-							: pa.maxDistance,
-					refDistance:
-						typeof o.refDistance !== "undefined"
-							? o.refDistance
-							: pa.refDistance,
-					rolloffFactor:
-						typeof o.rolloffFactor !== "undefined"
-							? o.rolloffFactor
-							: pa.rolloffFactor,
-					panningModel:
-						typeof o.panningModel !== "undefined"
-							? o.panningModel
-							: pa.panningModel,
-				};
+				sound._pannerAttr = mergePannerAttr(
+					sound._pannerAttr,
+					o as Partial<PannerAttrOptions>,
+				);
 
 				// Create a new panner node if one doesn't already exist
 				let panner = sound._panner;
diff --git a/packages/melonjs/src/audio/playback.ts b/packages/melonjs/src/audio/playback.ts
index c8ee692269..c45fa45752 100644
--- a/packages/melonjs/src/audio/playback.ts
+++ b/packages/melonjs/src/audio/playback.ts
@@ -10,6 +10,11 @@ import { clamp } from "../math/math.ts";
 import { isDataUrl } from "../utils/string.ts";
 import { Sound } from "./backend/core.ts";
 import type { SpatialSound } from "./backend/spatial.ts";
+import {
+	applySpatialPlacement,
+	releaseSpatialClip,
+	releaseSpatialPlacement,
+} from "./spatial.ts";
 import {
 	state as audioState,
 	getGlobalVolume,
@@ -164,6 +169,10 @@ export function play(
 	// in its place so sprites (and anything added later) do not have to be
 	// appended after `volume` positionally. The positional form is unchanged.
 	const options: PlayOptions =
+		// the null test is not redundant at runtime: `typeof null` is "object",
+		// and a JS caller reaching for a later positional argument writes
+		// `play(name, null, onend)`
+		// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
 		typeof loopOrOptions === "object" && loopOrOptions !== null
 			? loopOrOptions
 			: { loop: loopOrOptions };
@@ -195,6 +204,22 @@ export function play(
 			sound.once("end", endCallback, id);
 		}
 	}
+	// Placed in the world only when the caller asked for it. Everything above
+	// is the path every existing call already took, unchanged.
+	if (options.follow !== undefined || options.at !== undefined) {
+		applySpatialPlacement(sound_name, id, options);
+		// a one-shot stops being tracked when it ends, so a scene full of
+		// short placed sounds does not grow the follow table forever
+		if (!loop) {
+			sound.once(
+				"end",
+				() => {
+					releaseSpatialPlacement(id);
+				},
+				id,
+			);
+		}
+	}
 	return id;
 }
 
@@ -466,6 +491,16 @@ export function panner(
  * @category Audio
  */
 export function stop(sound_name?: string, id?: number): void {
+	// a stopped sound is no longer somewhere, so it stops being followed.
+	// Without this the frame handler writes positions to a dead voice forever
+	// and the Map pins the renderable it was following.
+	if (sound_name === undefined) {
+		releaseSpatialClip();
+	} else if (id === undefined) {
+		releaseSpatialClip(sound_name);
+	} else {
+		releaseSpatialPlacement(id);
+	}
 	if (sound_name === undefined) {
 		stopAllPlayback();
 		return;
diff --git a/packages/melonjs/src/audio/spatial.ts b/packages/melonjs/src/audio/spatial.ts
new file mode 100644
index 0000000000..75ffbd4678
--- /dev/null
+++ b/packages/melonjs/src/audio/spatial.ts
@@ -0,0 +1,494 @@
+/**
+ * Spatial audio placed in WORLD coordinates.
+ *
+ * The backend speaks Web Audio's language: a listener at the origin, metres,
+ * and +Y UP. A 2D or 2.5D game speaks pixels with +Y DOWN and has a camera
+ * that moves. This module is the bridge.
+ *
+ * It is opt-in end to end. Until a game calls {@link setListener} or
+ * {@link listener}, the listener never moves, no frame handler is installed,
+ * and every existing `position` / `stereo` / `panner` call behaves exactly as
+ * it did.
+ */
+
+import type Camera3d from "../camera/camera3d.ts";
+import type Renderable from "../renderable/renderable.js";
+import { GAME_AFTER_UPDATE, off, on } from "../system/event.ts";
+import { position as setPosition, stop as stopSound } from "./playback.ts";
+import {
+	state as audioState,
+	getListenerOrientation,
+	getListenerPosition,
+	isAudioAvailable,
+	setListenerOrientation,
+	setListenerPosition,
+} from "./state.ts";
+import type { PannerAttributes } from "./types.ts";
+
+/**
+ * Defaults given to a sound placed through `follow` or `at`.
+ *
+ * Only two of these differ from what the backend already uses, and those two
+ * are the whole point:
+ *
+ * - `refDistance` is **240** rather than `1`. Web Audio's `1` describes one
+ *   METRE, so a sound a couple of tiles away in a game measured in pixels is
+ *   already near silent. This is the single most common reason positional
+ *   audio "does not work".
+ * - `panningModel` is `"equalpower"` rather than `"HRTF"`. Plain left/right
+ *   panning is what a flat scene wants, and it is markedly cheaper. A scene
+ *   with a posed {@link Camera3d}, where front-to-back is meaningful, wants
+ *   `setSpatialDefaults({ panningModel: "HRTF" })`.
+ *
+ * With `"inverse"` and a rolloff of 1 the curve never reaches zero: it is
+ * about 0.5 at 480 px, 0.2 at 1200 px and 0.11 at 2200 px, with
+ * `maxDistance` the far clamp. These are a starting point, not a measurement;
+ * a world much larger or smaller than a few screens wants
+ * {@link setSpatialDefaults}.
+ */
+const PIXEL_DEFAULTS: Readonly<PannerAttributes> = Object.freeze({
+	coneInnerAngle: 360,
+	coneOuterAngle: 360,
+	coneOuterGain: 0,
+	distanceModel: "inverse",
+	maxDistance: 10000,
+	panningModel: "equalpower",
+	refDistance: 240,
+	rolloffFactor: 1,
+});
+
+/** the attributes a spatially placed sound is given, until a game changes them */
+let spatialDefaults: PannerAttributes = { ...PIXEL_DEFAULTS };
+
+/** what the listener follows, or `null` for a listener that does not move */
+let listenerTarget: Renderable | null = null;
+
+/** one sound whose position is re-read every frame */
+interface FollowedSound {
+	name: string;
+	target: Renderable;
+	stopWithTarget: boolean;
+}
+
+/** followed sounds, keyed by the playback id `play()` returned */
+const followed = new Map<number, FollowedSound>();
+
+/** whether the per-frame handler is currently subscribed */
+let ticking = false;
+
+/** collects ids to drop, reused so a frame of tracking allocates nothing */
+const _dead: number[] = [];
+
+/**
+ * Whether a renderable has been destroyed.
+ *
+ * `Renderable#destroy()` sets `pos` to `undefined` and releases `_absPos` back
+ * to the pool, and `getAbsolutePosition()` dereferences `pos` with no guard of
+ * its own. So a destroyed target is not merely stale, it THROWS, and it would
+ * do so from inside the frame loop on every frame thereafter. There is no
+ * "finalized" flag on `Renderable` to ask instead.
+ * @param target - the renderable to test
+ * @returns true when the renderable has been destroyed
+ */
+function isDestroyed(target: Renderable): boolean {
+	// the type says `pos` is always a vector; `destroy()` says otherwise
+	// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+	return target.pos === undefined;
+}
+
+/**
+ * Where a renderable is, in WORLD coordinates.
+ *
+ * `getAbsolutePosition()` sums the ancestor chain, which is what a sound
+ * parented into a moving container needs.
+ * @param target - the renderable to locate
+ * @returns the world position, which is the renderable's own live vector
+ */
+function worldPositionOf(target: Renderable) {
+	return target.getAbsolutePosition();
+}
+
+/** Subscribe to the frame loop, but only once something needs it. */
+function startTicking() {
+	if (!ticking) {
+		on(GAME_AFTER_UPDATE, tick);
+		ticking = true;
+	}
+}
+
+/** Drop the frame handler as soon as nothing is being tracked. */
+function stopTickingIfIdle() {
+	if (ticking && listenerTarget === null && followed.size === 0) {
+		off(GAME_AFTER_UPDATE, tick);
+		ticking = false;
+	}
+}
+
+/**
+ * Re-read the listener and every followed sound.
+ *
+ * Hung off `GAME_AFTER_UPDATE` rather than `GAME_UPDATE` deliberately: the
+ * latter is emitted INSIDE the fixed-step catch-up loop and BEFORE the world
+ * updates, so it would sample last frame's positions and sample them several
+ * times over on a catch-up frame. After the update is where "where is
+ * everything now" is answerable.
+ *
+ * Nothing ticks while the game is paused, so a followed sound holds its last
+ * position until play resumes.
+ */
+function tick() {
+	if (listenerTarget !== null) {
+		if (isDestroyed(listenerTarget)) {
+			// the camera or renderable was destroyed under us; a stage that
+			// owns its camera destroys it on every state change
+			setListener(null);
+		} else {
+			const p = worldPositionOf(listenerTarget);
+			listener(p.x, p.y, p.z);
+			const camera = listenerTarget as Camera3d;
+			if (typeof camera.getBasis === "function") {
+				camera.getBasis(_right, _up, _forward);
+				listenerOrientation(
+					_forward.x,
+					_forward.y,
+					_forward.z,
+					_up.x,
+					_up.y,
+					_up.z,
+				);
+			}
+		}
+	}
+
+	for (const [id, entry] of followed) {
+		if (isDestroyed(entry.target)) {
+			_dead.push(id);
+			continue;
+		}
+		// the clip can be unloaded out from under a live follow, and
+		// `position()` throws on a name it cannot find
+		if (audioState.tracks[entry.name] === undefined) {
+			_dead.push(id);
+			continue;
+		}
+		const p = worldPositionOf(entry.target);
+		setPosition(entry.name, p.x, -p.y, p.z, id);
+	}
+	if (_dead.length > 0) {
+		for (const id of _dead) {
+			releaseFollow(id);
+		}
+		_dead.length = 0;
+	}
+	stopTickingIfIdle();
+}
+
+/**
+ * Stop tracking one followed sound, stopping the sound too if it asked.
+ * @param id - the playback id to release
+ */
+function releaseFollow(id: number) {
+	const entry = followed.get(id);
+	if (entry === undefined) {
+		return;
+	}
+	followed.delete(id);
+	if (entry.stopWithTarget && audioState.tracks[entry.name] !== undefined) {
+		stopSound(entry.name, id);
+	}
+	stopTickingIfIdle();
+}
+
+// scratch for the camera basis, reused every frame
+import { Vector3d } from "../math/vector3d.ts";
+
+const _right = new Vector3d();
+const _up = new Vector3d();
+const _forward = new Vector3d();
+
+/** @inheritDoc */
+export function listener(): [number, number, number];
+/** @inheritDoc */
+export function listener(x: number, y: number, z?: number): void;
+/**
+ * Get or set the listener's position, in WORLD coordinates.
+ *
+ * Called with no arguments it reads the position back. Called with
+ * coordinates it moves the listener, which is what makes a sound at a fixed
+ * world point pan and fade as the player moves past it.
+ *
+ * The listener starts at the origin and stays there until something moves it,
+ * so a game that never calls this sounds exactly as it did before.
+ * @param x - world x, or omitted to read
+ * @param y - world y, measured DOWN like every other melonJS coordinate
+ * @param z - world z, defaulting to 0
+ * @returns the current `[x, y, z]` when reading, otherwise nothing
+ * @example
+ * // follow the player by hand, if `setListener` is not wanted
+ * audio.listener(player.pos.x, player.pos.y);
+ * @category Audio
+ */
+export function listener(
+	x?: number,
+	y?: number,
+	z?: number,
+): [number, number, number] | void {
+	if (x === undefined) {
+		const read = getListenerPosition();
+		// back into world space, so what is read matches what was set
+		return read === null ? [0, 0, 0] : [read[0], -read[1], read[2]];
+	}
+	// the Y flip to Web Audio's +Y-up happens HERE and in
+	// `listenerOrientation`, and nowhere else
+	setListenerPosition(x, -(y ?? 0), z ?? 0);
+}
+
+/** @inheritDoc */
+export function listenerOrientation(): [
+	number,
+	number,
+	number,
+	number,
+	number,
+	number,
+];
+/** @inheritDoc */
+export function listenerOrientation(
+	fx: number,
+	fy: number,
+	fz: number,
+	ux: number,
+	uy: number,
+	uz: number,
+): void;
+/**
+ * Get or set which way the listener faces, in WORLD coordinates.
+ *
+ * Two vectors: the direction the listener looks along, and which way is up for
+ * it. This is what decides left from right, so a game that only moves the
+ * listener around a flat plane can leave it alone.
+ *
+ * World up in melonJS is `(0, -1, 0)`, because render space is Y-down, and
+ * that is what to pass here. The conversion to Web Audio's Y-up is applied
+ * for you, which matters: handing Web Audio a Y-down up vector mirrors the
+ * stereo image, since it derives right from `forward × up`.
+ * @param fx - forward x, or omitted to read
+ * @param fy - forward y
+ * @param fz - forward z
+ * @param ux - up x
+ * @param uy - up y
+ * @param uz - up z
+ * @returns the current `[fx, fy, fz, ux, uy, uz]` when reading
+ * @example
+ * // face the way the player is walking, with melonJS world up
+ * audio.listenerOrientation(dir.x, dir.y, 0, 0, -1, 0);
+ * @category Audio
+ */
+export function listenerOrientation(
+	fx?: number,
+	fy?: number,
+	fz?: number,
+	ux?: number,
+	uy?: number,
+	uz?: number,
+): [number, number, number, number, number, number] | void {
+	if (fx === undefined) {
+		const read = getListenerOrientation();
+		return read === null
+			? [0, 0, -1, 0, -1, 0]
+			: [read[0], -read[1], read[2], read[3], -read[4], read[5]];
+	}
+	setListenerOrientation(fx, -(fy ?? 0), fz ?? 0, ux ?? 0, -(uy ?? 0), uz ?? 0);
+}
+
+/**
+ * Have the listener follow a camera or a renderable, every frame.
+ *
+ * Pass `app.viewport` and world-placed sounds pan and fade around the view
+ * with nothing else to write. Pass the player and they are heard from the
+ * character rather than the camera, which is usually what a scrolling game
+ * with a lagging camera wants. Pass `null` to stop, leaving the listener
+ * where it was.
+ *
+ * A {@link Camera3d} also contributes its ORIENTATION, so turning the camera
+ * swings the stereo image. Anything else contributes position only.
+ *
+ * Following stops on its own if the target is destroyed, which a stage that
+ * owns its camera does on every state change.
+ * @param target - what to follow, or `null` to stop following
+ * @example
+ * audio.setListener(app.viewport); // hear from the camera
+ * audio.setListener(player); // hear from the player
+ * audio.setListener(null); // stop following
+ * @category Audio
+ */
+export function setListener(target: Renderable | null): void {
+	listenerTarget = target;
+	if (target !== null && !isDestroyed(target)) {
+		startTicking();
+		tick(); // place it now, so the first frame of audio is already right
+	} else {
+		listenerTarget = null;
+		stopTickingIfIdle();
+	}
+}
+
+/**
+ * Set the panner attributes new spatially placed sounds are given.
+ *
+ * Applies to sounds placed through `follow` or `at` from this point on.
+ * Sounds already playing keep what they were given, and `audio.panner()`
+ * still overrides per clip.
+ *
+ * The shipped defaults suit a world measured in pixels rather than metres. A
+ * world much larger or smaller than a few screens, or a posed 3D scene that
+ * wants `"HRTF"` back, says so here once.
+ * @param attributes - attributes to merge over the current defaults
+ * @example
+ * // a planet-scale scene, heard through a posed 3D camera
+ * audio.setSpatialDefaults({ refDistance: 900, panningModel: "HRTF" });
+ * @category Audio
+ */
+export function setSpatialDefaults(attributes: PannerAttributes): void {
+	spatialDefaults = { ...spatialDefaults, ...attributes };
+}
+
+/**
+ * Read back the defaults new spatially placed sounds are given.
+ * @returns a copy of the current defaults
+ * @category Audio
+ */
+export function getSpatialDefaults(): PannerAttributes {
+	return { ...spatialDefaults };
+}
+
+/**
+ * Stop tracking a followed sound, leaving it playing where it last was.
+ *
+ * `audio.stop()` releases tracking on its own; this is for keeping a sound
+ * going while detaching it from whatever it was following.
+ * @param id - the playback id to detach
+ * @example
+ * const id = audio.play("engine", { follow: car });
+ * audio.unfollow(id); // the hum stays where the car was
+ * @category Audio
+ */
+export function unfollow(id: number): void {
+	if (followed.delete(id)) {
+		stopTickingIfIdle();
+	}
+}
+
+/**
+ * Place a just-started sound in the world, and track it if asked.
+ * @param name - the clip name
+ * @param id - the playback id `play()` returned
+ * @param options - the placement the caller asked for
+ * @param options.follow - a renderable to track every frame
+ * @param options.at - a fixed world point to pin the sound to
+ * @param options.stopWithTarget - stop the sound when `follow` is destroyed
+ * @internal
+ * @ignore
+ */
+export function applySpatialPlacement(
+	name: string,
+	id: number,
+	options: {
+		follow?: Renderable | undefined;
+		at?: { x: number; y: number; z?: number } | undefined;
+		stopWithTarget?: boolean | undefined;
+	},
+): void {
+	const { follow, at, stopWithTarget } = options;
+	if (follow === undefined && at === undefined) {
+		return;
+	}
+	if (follow !== undefined && at !== undefined) {
+		throw new Error(
+			"melonJS: audio.play() takes `follow` or `at`, not both — `follow` " +
+				"tracks a renderable, `at` pins a fixed point",
+		);
+	}
+	if (!isAudioAvailable()) {
+		return;
+	}
+
+	// pixel-shaped attributes BEFORE the first position is written, so the
+	// sound is never briefly audible under metre defaults
+	applyPannerAttributes(name, id);
+
+	if (at !== undefined) {
+		setPosition(name, at.x, -at.y, at.z ?? 0, id);
+		return;
+	}
+	if (follow !== undefined) {
+		if (isDestroyed(follow)) {
+			return;
+		}
+		const p = worldPositionOf(follow);
+		setPosition(name, p.x, -p.y, p.z, id);
+		followed.set(id, {
+			name,
+			target: follow,
+			stopWithTarget: stopWithTarget === true,
+		});
+		startTicking();
+	}
+}
+
+/**
+ * Apply the current spatial defaults to one playing instance.
+ * @param name - the clip name
+ * @param id - the playback id
+ */
+function applyPannerAttributes(name: string, id: number) {
+	const sound = audioState.tracks[name];
+	// the backend's own typing lists a narrower `distanceModel` union than
+	// WebAudio accepts; the runtime takes all three
+	sound?.pannerAttr(
+		spatialDefaults as Parameters<NonNullable<typeof sound>["pannerAttr"]>[0],
+		id,
+	);
+}
+
+/**
+ * Forget a playback id, so a stopped or ended sound stops being tracked.
+ * @param id - the playback id that ended
+ * @internal
+ * @ignore
+ */
+export function releaseSpatialPlacement(id: number): void {
+	if (followed.delete(id)) {
+		stopTickingIfIdle();
+	}
+}
+
+/**
+ * Forget every followed sound belonging to one clip.
+ *
+ * Called when a clip is unloaded, so tracking cannot outlive the sound it
+ * writes positions to.
+ * @param name - the clip being unloaded, or omitted for all of them
+ * @internal
+ * @ignore
+ */
+export function releaseSpatialClip(name?: string): void {
+	for (const [id, entry] of followed) {
+		if (name === undefined || entry.name === name) {
+			followed.delete(id);
+		}
+	}
+	stopTickingIfIdle();
+}
+
+/**
+ * Drop every listener target and followed sound, and restore the defaults.
+ * @internal
+ * @ignore
+ */
+export function resetSpatialTracking(): void {
+	listenerTarget = null;
+	followed.clear();
+	spatialDefaults = { ...PIXEL_DEFAULTS };
+	stopTickingIfIdle();
+}
diff --git a/packages/melonjs/src/audio/state.ts b/packages/melonjs/src/audio/state.ts
index 35ce3582a0..4ac99ad5ab 100644
--- a/packages/melonjs/src/audio/state.ts
+++ b/packages/melonjs/src/audio/state.ts
@@ -213,6 +213,72 @@ export function setGlobalVolume(v: number): void {
  * @ignore
  * @internal
  */
+/**
+ * Move the Web Audio listener. Coordinates are AUDIO space (+Y up).
+ * @param x - audio-space x
+ * @param y - audio-space y
+ * @param z - audio-space z
+ * @ignore
+ * @internal
+ */
+export function setListenerPosition(x: number, y: number, z: number): void {
+	if (!isAudioAvailable()) return;
+	audioEngine.pos(x, y, z);
+}
+
+/**
+ * Read the Web Audio listener position, in AUDIO space.
+ * @returns a fresh `[x, y, z]`, or null when there is no context
+ * @ignore
+ * @internal
+ */
+export function getListenerPosition(): [number, number, number] | null {
+	if (!isAudioAvailable()) return null;
+	// the backend returns the engine itself when it has nothing to report,
+	// and otherwise hands back its own array by reference
+	const read = audioEngine.pos();
+	return Array.isArray(read) ? [read[0], read[1], read[2]] : null;
+}
+
+/**
+ * Aim the Web Audio listener. Vectors are AUDIO space (+Y up).
+ * @param fx - forward x
+ * @param fy - forward y
+ * @param fz - forward z
+ * @param ux - up x
+ * @param uy - up y
+ * @param uz - up z
+ * @ignore
+ * @internal
+ */
+export function setListenerOrientation(
+	fx: number,
+	fy: number,
+	fz: number,
+	ux: number,
+	uy: number,
+	uz: number,
+): void {
+	if (!isAudioAvailable()) return;
+	audioEngine.orientation(fx, fy, fz, ux, uy, uz);
+}
+
+/**
+ * Read the Web Audio listener orientation, in AUDIO space.
+ * @returns a fresh six-tuple, or null when there is no context
+ * @ignore
+ * @internal
+ */
+export function getListenerOrientation():
+	| [number, number, number, number, number, number]
+	| null {
+	if (!isAudioAvailable()) return null;
+	const read = audioEngine.orientation();
+	return Array.isArray(read)
+		? [read[0], read[1], read[2], read[3], read[4], read[5]]
+		: null;
+}
+
 export function setGlobalMuted(muted: boolean): void {
 	audioEngine.mute(muted);
 }
diff --git a/packages/melonjs/src/audio/types.ts b/packages/melonjs/src/audio/types.ts
index 3ccbdb77ba..5a1123393e 100644
--- a/packages/melonjs/src/audio/types.ts
+++ b/packages/melonjs/src/audio/types.ts
@@ -5,6 +5,8 @@
  * `me.audio` exactly as before.
  */
 
+import type Renderable from "../renderable/renderable.js";
+
 /**
  * Sound asset descriptor passed to `audio.load`.
  * @category Audio
@@ -133,13 +135,22 @@ export interface PannerAttributes {
 	 */
 	maxDistance?: number;
 	/**
-	 * Spatialization algorithm — `"equalpower"` (cheap, stereo-only) or
-	 * `"HRTF"` (head-related, full 3D). Defaults to `"HRTF"`.
+	 * Spatialization algorithm, `"equalpower"` (cheap, stereo-only) or
+	 * `"HRTF"` (head-related, full 3D).
+	 *
+	 * A voice placed through `follow` / `at` starts from `"equalpower"`, which
+	 * is what a 2D mix wants; a bare `audio.position()` keeps the WebAudio
+	 * default of `"HRTF"`. See `audio.setSpatialDefaults`.
 	 */
 	panningModel?: "HRTF" | "equalpower";
 	/**
-	 * Reference distance for the falloff curve — volume is `1` at this
-	 * distance from the listener. Defaults to `1`.
+	 * Reference distance for the falloff curve: volume is `1` at this distance
+	 * from the listener.
+	 *
+	 * A voice placed through `follow` / `at` starts from `240`, which is a
+	 * pixel distance a few tiles wide; a bare `audio.position()` keeps the
+	 * WebAudio default of `1`, which is one METRE and leaves a sound given
+	 * pixel coordinates near silent. See `audio.setSpatialDefaults`.
 	 */
 	refDistance?: number;
 	/**
@@ -275,7 +286,7 @@ export interface ToneOptions {
 }
 
 /**
- * Options accepted by {@link play} in place of the positional `loop` argument.
+ * Options accepted by {@link audio.play | `audio.play`} in place of the positional `loop` argument.
  *
  * Every field is optional, and the positional form
  * `play(name, loop, onend, volume)` continues to work unchanged.
@@ -293,13 +304,36 @@ export interface PlayOptions {
 	onend?: (() => void) | undefined;
 	/** Playback volume, `0.0..1.0`. Defaults to the current global volume. */
 	volume?: number | undefined;
+	/**
+	 * Place this sound at a renderable and keep it there, re-reading its world
+	 * position every frame. Tracking stops when the renderable is destroyed.
+	 *
+	 * Positions are WORLD pixels, with `+y` down like everything else in
+	 * melonJS; the Y flip Web Audio wants is applied for you. Sounds placed
+	 * this way are given the pixel-shaped panner defaults, which
+	 * `audio.setSpatialDefaults()` can change and `audio.panner()` overrides.
+	 */
+	follow?: Renderable | undefined;
+	/**
+	 * Place this sound at a fixed world point. Same coordinates and same
+	 * defaults as `follow`, for something that does not move.
+	 */
+	at?: { x: number; y: number; z?: number } | undefined;
+	/**
+	 * Stop the sound when the renderable it follows is destroyed, rather than
+	 * leaving it playing where the renderable was. Defaults to `false`.
+	 *
+	 * Note that stopping discards the playback id, so keep this `false` for a
+	 * looping sound you intend to reposition and resume later.
+	 */
+	stopWithTarget?: boolean | undefined;
 }
 
 /**
  * Lifecycle callbacks accepted by a {@link SoundAsset} under `on`.
  *
  * These fire for the clip as a whole. To react to a single instance, keep the
- * id returned by {@link play}.
+ * id returned by {@link audio.play | `audio.play`}.
  * @category Audio
  */
 export interface SoundEvents {
diff --git a/packages/melonjs/src/index.ts b/packages/melonjs/src/index.ts
index 76a917ed73..0a8753da9b 100644
--- a/packages/melonjs/src/index.ts
+++ b/packages/melonjs/src/index.ts
@@ -118,6 +118,11 @@ export * from "./application/scaleMethods.ts";
 export * from "./application/settings.ts";
 // export all utility function
 export * as audio from "./audio/audio.ts";
+export type {
+	PannerAttributes,
+	PlayOptions,
+	SoundEvents,
+} from "./audio/types.ts";
 // export all public constants
 export * from "./const.ts";
 export { Box3d } from "./geometries/box3d.ts";
diff --git a/packages/melonjs/tests/audio-spatial.spec.js b/packages/melonjs/tests/audio-spatial.spec.js
new file mode 100644
index 0000000000..1812ff910c
--- /dev/null
+++ b/packages/melonjs/tests/audio-spatial.spec.js
@@ -0,0 +1,488 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { resetAutoPause } from "../src/audio/autopause.ts";
+import { resetSpatialTracking } from "../src/audio/spatial.ts";
+import {
+	getListenerPosition,
+	getSoundOrThrow,
+	isGlobalMuted,
+} from "../src/audio/state.ts";
+import { Application, audio, Renderable } from "../src/index.js";
+import { emit, GAME_AFTER_UPDATE, on } from "../src/system/event.ts";
+
+/** a valid, silent WAV served as a data URL, so a clip really loads */
+const makeSilentWavDataUrl = (durationSec = 0.05) => {
+	const sampleRate = 8000;
+	const numSamples = Math.max(1, Math.floor(sampleRate * durationSec));
+	const dataSize = numSamples * 2;
+	const buf = new ArrayBuffer(44 + dataSize);
+	const view = new DataView(buf);
+	let p = 0;
+	const str = (s) => {
+		for (let i = 0; i < s.length; i++) {
+			view.setUint8(p++, s.charCodeAt(i));
+		}
+	};
+	const u32 = (v) => {
+		view.setUint32(p, v, true);
+		p += 4;
+	};
+	const u16 = (v) => {
+		view.setUint16(p, v, true);
+		p += 2;
+	};
+	str("RIFF");
+	u32(36 + dataSize);
+	str("WAVE");
+	str("fmt ");
+	u32(16);
+	u16(1);
+	u16(1);
+	u32(sampleRate);
+	u32(sampleRate * 2);
+	u16(2);
+	u16(16);
+	str("data");
+	u32(dataSize);
+	let bytes = "";
+	const all = new Uint8Array(buf);
+	for (let i = 0; i < all.length; i++) {
+		bytes += String.fromCharCode(all[i]);
+	}
+	return `data:audio/wav;base64,${btoa(bytes)}`;
+};
+
+const loadClip = (name, extra = {}) => {
+	audio.init("wav");
+	return new Promise((resolve, reject) => {
+		const t = setTimeout(() => {
+			return reject(new Error(`timeout ${name}`));
+		}, 2000);
+		audio.load(
+			{ name, src: makeSilentWavDataUrl(), ...extra },
+			() => {
+				clearTimeout(t);
+				resolve();
+			},
+			() => {
+				clearTimeout(t);
+				reject(new Error(`load failed ${name}`));
+			},
+		);
+	});
+};
+
+/**
+ * How many stops the engine has asked the backend for on this clip.
+ *
+ * Neither `audio.playing()` nor the clip's own `stop` lifecycle hook can answer
+ * "did this stop?" here. The test page has had no user gesture, so the context
+ * is suspended, `_playLock` stays true, and every voice reads `_paused: true`
+ * from the moment it starts; under that lock `stop()` pushes itself onto the
+ * backend's replay queue and returns before it emits anything. That queue entry
+ * IS the record of the request, and it is what will run the moment a real page
+ * unlocks.
+ * @param {string} name - the clip
+ * @returns {number} the number of queued stop requests
+ */
+const stopRequests = (name) => {
+	return getSoundOrThrow(name)._queue.filter((q) => {
+		return q.event === "stop";
+	}).length;
+};
+
+/** the voice's own panner node, which is where the truth is */
+const pannerOf = (name, id) => {
+	return getSoundOrThrow(name)._soundById(id)?._panner;
+};
+
+/**
+ * What the backend recorded for a voice.
+ *
+ * `AudioParam.value` is read rather than asserted on: a scheduled
+ * `setValueAtTime` does not settle into `.value` while the test context is
+ * suspended, so it reads 0 whatever was written. `_pos` / `_stereo` are what
+ * the engine actually stores, and what a voice `reset()` replays from.
+ * @param {string} name - the clip
+ * @param {number} id - the playback id
+ * @returns {object} the backend voice
+ */
+const voiceOf = (name, id) => {
+	return getSoundOrThrow(name)._soundById(id);
+};
+
+/**
+ * Blur and focus, as the application raises them.
+ *
+ * `Application#_onBlur` is called rather than the `BLUR` event, because the
+ * gate under test IS the application's settings: the handler is what decides
+ * whether a blur silences the mix. `state.pause()` reached from here is inert
+ * without a running stage, which is the point of only asserting on the mute.
+ * @param {object} settings - the app settings under test
+ * @returns {object} `blur` / `focus`, bound to those settings
+ */
+const focusPair = (settings = { pauseOnBlur: true, resumeOnFocus: true }) => {
+	const app = { stopOnBlur: false, ...settings };
+	return {
+		blur: () => {
+			return Application.prototype._onBlur.call(app);
+		},
+		focus: () => {
+			return Application.prototype._onFocus.call(app);
+		},
+	};
+};
+
+/** one frame of the engine's post-update hook */
+const frame = () => {
+	emit(GAME_AFTER_UPDATE, 16);
+};
+
+const at = (x, y, z = 0) => {
+	const r = new Renderable(x, y, 8, 8);
+	r.pos.z = z;
+	return r;
+};
+
+describe("spatial audio", () => {
+	beforeEach(() => {
+		resetSpatialTracking();
+		resetAutoPause();
+	});
+	afterEach(() => {
+		audio.setListener(null);
+		resetSpatialTracking();
+		resetAutoPause();
+	});
+
+	describe("listener", () => {
+		it("round-trips a world position", () => {
+			audio.listener(100, 250, -30);
+			expect(audio.listener()).toEqual([100, 250, -30]);
+		});
+
+		it("REGRESSION: a followed source and the listener agree on which way is down", async () => {
+			// A set/get round trip CANNOT catch this: the first version
+			// converted to audio space in `worldPositionOf` and converted AGAIN
+			// inside `listener()`, so reads and writes both flipped and matched
+			// each other while the SOURCE sat in the opposite hemisphere. The
+			// only honest check is listener against source.
+			await loadClip("down");
+			const player = at(0, 2000);
+			audio.setListener(player);
+			const id = audio.play("down", { follow: player });
+			frame();
+
+			// the public read is in WORLD space, where it was written
+			expect(audio.listener()[1]).toBeCloseTo(2000, 3);
+			// and BOTH must land in the same hemisphere once converted. Reading
+			// the listener in world space and the source in audio space would
+			// pass even with no conversion at all, which is how the double flip
+			// survived the first time: compare the two as the panner sees them.
+			const sourceY = voiceOf("down", id)._pos[1];
+			expect(getListenerPosition()[1]).toBeCloseTo(sourceY, 3);
+			// and that shared value is Web Audio's +Y-up, not melonJS's y-down
+			expect(sourceY).toBeCloseTo(-2000, 3);
+			audio.stop("down");
+		});
+
+		it("follows a renderable across frames, and releases when it dies", async () => {
+			const player = at(10, 20);
+			audio.setListener(player);
+			frame();
+			expect(audio.listener()[0]).toBeCloseTo(10, 5);
+
+			player.pos.set(400, 90, 0);
+			frame();
+			expect(audio.listener()[0]).toBeCloseTo(400, 5);
+
+			// a destroyed target must not throw from inside the frame loop
+			player.destroy();
+			expect(() => {
+				frame();
+			}).not.toThrow();
+			expect(() => {
+				frame();
+			}).not.toThrow();
+		});
+
+		it("takes orientation from a Camera3d, and only from a Camera3d", () => {
+			const plain = at(0, 0);
+			audio.listenerOrientation(0, 0, -1, 0, -1, 0);
+			const before = audio.listenerOrientation();
+			audio.setListener(plain);
+			frame();
+			// a plain renderable contributes position only
+			expect(audio.listenerOrientation()).toEqual(before);
+		});
+
+		it("does not install a frame handler until something is followed", () => {
+			// the manual `listener()` path writes straight through and
+			// subscribes to nothing, so a game using it pays no per-frame cost
+			let ticked = false;
+			const probe = () => {
+				ticked = true;
+			};
+			on(GAME_AFTER_UPDATE, probe);
+			audio.listener(1, 2, 3);
+			frame();
+			expect(ticked).toBe(true); // the probe itself runs
+			// and the listener did not move on its own afterwards
+			audio.listener(7, 8, 9);
+			frame();
+			expect(audio.listener()).toEqual([7, 8, 9]);
+		});
+	});
+
+	describe("placement", () => {
+		it("`at` pins a fixed world point, with Y flipped once", async () => {
+			await loadClip("pin");
+			const id = audio.play("pin", { at: { x: 300, y: 120 } });
+			expect(voiceOf("pin", id)._pos[0]).toBeCloseTo(300, 3);
+			expect(voiceOf("pin", id)._pos[1]).toBeCloseTo(-120, 3);
+			audio.stop("pin");
+		});
+
+		it("`follow` tracks its renderable every frame", async () => {
+			await loadClip("track");
+			const thing = at(0, 0);
+			const id = audio.play("track", { follow: thing });
+			thing.pos.set(640, 480, 0);
+			frame();
+			expect(voiceOf("track", id)._pos[0]).toBeCloseTo(640, 3);
+			expect(voiceOf("track", id)._pos[1]).toBeCloseTo(-480, 3);
+			audio.stop("track");
+		});
+
+		it("refuses `follow` and `at` together rather than silently picking one", async () => {
+			await loadClip("both");
+			expect(() => {
+				return audio.play("both", { at: { x: 1, y: 1 }, follow: at(0, 0) });
+			}).toThrow(/follow.*or.*at/i);
+		});
+
+		it("stops tracking on audio.stop, so a dead target cannot throw later", async () => {
+			await loadClip("released");
+			const thing = at(0, 0);
+			audio.play("released", { follow: thing, loop: true });
+			audio.stop("released");
+			thing.destroy();
+			expect(() => {
+				frame();
+			}).not.toThrow();
+		});
+
+		it("`stopWithTarget` stops the sound when its renderable dies", async () => {
+			await loadClip("owned");
+			const owner = at(0, 0);
+			const id = audio.play("owned", {
+				follow: owner,
+				loop: true,
+				stopWithTarget: true,
+			});
+			frame();
+			expect(stopRequests("owned")).toBe(0);
+			owner.destroy();
+			frame();
+			// a loop on a dead entity is the case this exists for: without it
+			// the sound plays on forever from wherever the entity last stood
+			expect(stopRequests("owned")).toBe(1);
+			expect(id).toBeGreaterThan(0);
+		});
+
+		it("without `stopWithTarget` a dead renderable only ends the tracking", async () => {
+			await loadClip("orphan");
+			const owner = at(0, 0);
+			audio.play("orphan", { follow: owner, loop: true });
+			frame();
+			owner.destroy();
+			frame();
+			// tracking is released, but the sound is the game's to end
+			expect(stopRequests("orphan")).toBe(0);
+			audio.stop("orphan");
+		});
+
+		it("`unfollow` detaches a sound and leaves it where it is", async () => {
+			await loadClip("detach");
+			const thing = at(300, 0);
+			const id = audio.play("detach", { follow: thing, loop: true });
+			frame();
+			expect(voiceOf("detach", id)._pos[0]).toBeCloseTo(300, 3);
+			audio.unfollow(id);
+			thing.pos.set(900, 0, 0);
+			frame();
+			// not stopped, and still at the position it was detached at
+			expect(stopRequests("detach")).toBe(0);
+			expect(voiceOf("detach", id)._pos[0]).toBeCloseTo(300, 3);
+			audio.stop("detach");
+		});
+
+		it("survives the clip being unloaded while followed", async () => {
+			await loadClip("unloaded");
+			const thing = at(0, 0);
+			audio.play("unloaded", { follow: thing, loop: true });
+			audio.unload("unloaded");
+			expect(() => {
+				frame();
+			}).not.toThrow();
+		});
+	});
+
+	describe("defaults", () => {
+		it("gives placed sounds pixel-shaped attributes, not metre ones", async () => {
+			await loadClip("defaults");
+			const id = audio.play("defaults", { at: { x: 0, y: 0 } });
+			const panner = pannerOf("defaults", id);
+			// the backend's own default is 1 metre and "HRTF"
+			expect(panner.refDistance).toBeGreaterThan(100);
+			expect(panner.panningModel).toBe("equalpower");
+			audio.stop("defaults");
+		});
+
+		it("applies to NEW sounds only", async () => {
+			await loadClip("newonly");
+			const first = audio.play("newonly", { at: { x: 0, y: 0 } });
+			const firstRef = pannerOf("newonly", first).refDistance;
+
+			audio.setSpatialDefaults({ refDistance: 777 });
+			const second = audio.play("newonly", { at: { x: 0, y: 0 } });
+
+			expect(pannerOf("newonly", first).refDistance).toBe(firstRef);
+			expect(pannerOf("newonly", second).refDistance).toBe(777);
+			audio.stop("newonly");
+		});
+
+		it("leaves a plain position() call on the backend defaults", async () => {
+			await loadClip("plain");
+			const id = audio.play("plain");
+			audio.position("plain", 1, 2, 3, id);
+			// untouched by the pixel defaults: this is the 20.x contract
+			expect(pannerOf("plain", id).refDistance).toBe(1);
+			audio.stop("plain");
+		});
+	});
+
+	describe("stereo and position in either order", () => {
+		it("position then stereo", async () => {
+			await loadClip("p-then-s");
+			const id = audio.play("p-then-s");
+			audio.position("p-then-s", 5, 0, 0, id);
+			expect(pannerOf("p-then-s", id)).toBeInstanceOf(PannerNode);
+			audio.stereo("p-then-s", -1, id);
+			// used to be a silent no-op, leaving a PannerNode in place
+			expect(pannerOf("p-then-s", id)).toBeInstanceOf(StereoPannerNode);
+			expect(voiceOf("p-then-s", id)._stereo).toBeCloseTo(-1, 5);
+			audio.stop("p-then-s");
+		});
+
+		it("stereo then position", async () => {
+			await loadClip("s-then-p");
+			const id = audio.play("s-then-p");
+			audio.stereo("s-then-p", 1, id);
+			expect(pannerOf("s-then-p", id)).toBeInstanceOf(StereoPannerNode);
+			audio.position("s-then-p", 9, 0, 0, id);
+			expect(pannerOf("s-then-p", id)).toBeInstanceOf(PannerNode);
+			expect(voiceOf("s-then-p", id)._pos[0]).toBeCloseTo(9, 3);
+			// and the stereo state is cleared, or `reset()` would resurrect
+			// the StereoPannerNode on the next play
+			expect(voiceOf("s-then-p", id)._stereo).toBeNull();
+			audio.stop("s-then-p");
+		});
+
+		it("REGRESSION: a group stereo does not make follow a silent no-op", async () => {
+			// `_stereo` is inherited from the GROUP at voice init and takes
+			// precedence over `_pos`, so one historical `audio.stereo(name, 0)`
+			// used to make every later voice a StereoPannerNode, and `follow`
+			// wrote positions into a node that has none.
+			await loadClip("poisoned");
+			audio.stereo("poisoned", 0);
+			const thing = at(500, 0);
+			const id = audio.play("poisoned", { follow: thing });
+			frame();
+			expect(pannerOf("poisoned", id)).toBeInstanceOf(PannerNode);
+			expect(voiceOf("poisoned", id)._pos[0]).toBeCloseTo(500, 3);
+			audio.stop("poisoned");
+		});
+	});
+
+	describe("panner attributes reach the group", () => {
+		it("REGRESSION: panner() before the first play is not a no-op", async () => {
+			// the documented example did nothing at all: the setter merged
+			// into live voices only, and there were none yet
+			await loadClip("group-attr");
+			audio.panner("group-attr", { refDistance: 42 });
+			expect(audio.panner("group-attr").refDistance).toBe(42);
+			const id = audio.play("group-attr");
+			audio.position("group-attr", 1, 1, 1, id);
+			expect(pannerOf("group-attr", id).refDistance).toBe(42);
+			audio.stop("group-attr");
+		});
+	});
+
+	describe("focus loss silences the mix", () => {
+		it("mutes on blur and restores on focus", () => {
+			const { blur, focus } = focusPair();
+			expect(isGlobalMuted()).toBe(false);
+			blur();
+			expect(isGlobalMuted()).toBe(true);
+			focus();
+			expect(isGlobalMuted()).toBe(false);
+		});
+
+		it("does not un-mute a game that muted itself", () => {
+			const { blur, focus } = focusPair();
+			audio.muteAll();
+			blur();
+			focus();
+			// the player chose silence; a focus round trip is not consent
+			expect(isGlobalMuted()).toBe(true);
+			audio.unmuteAll();
+		});
+
+		it("survives repeated blurs before a single focus", () => {
+			const { blur, focus } = focusPair();
+			blur();
+			blur();
+			focus();
+			expect(isGlobalMuted()).toBe(false);
+		});
+
+		it("silences procedural audio too, since it routes through the master gain", () => {
+			// `tone()` bypasses the voice machinery entirely; muting the master
+			// gain is the only approach that covers it without being told about
+			// it one source at a time
+			const { blur, focus } = focusPair();
+			blur();
+			expect(() => {
+				return audio.tone({ freq: 440, duration: 0.01 });
+			}).not.toThrow();
+			expect(isGlobalMuted()).toBe(true);
+			focus();
+		});
+
+		it("leaves the mix alone when the game opted out of pausing in the background", () => {
+			const { blur, focus } = focusPair({
+				pauseOnBlur: false,
+				resumeOnFocus: false,
+			});
+			blur();
+			expect(isGlobalMuted()).toBe(false);
+			focus();
+			expect(isGlobalMuted()).toBe(false);
+		});
+
+		it("restores on focus even for a game that stops on blur without resuming", () => {
+			// `stopOnBlur` restarts the stage from `_onFocus` regardless of
+			// `resumeOnFocus`, so the mute has to be lifted there too or the
+			// game comes back silent for good
+			const { blur, focus } = focusPair({
+				stopOnBlur: true,
+				pauseOnBlur: false,
+				resumeOnFocus: false,
+			});
+			blur();
+			expect(isGlobalMuted()).toBe(true);
+			focus();
+			expect(isGlobalMuted()).toBe(false);
+		});
+	});
+});

From f12a4eb4e1c49b35ea2cd268419ef9f43c34e1ac Mon Sep 17 00:00:00 2001
From: Olivier Biot <olivier.biot@me.com>
Date: Wed, 7 Oct 2026 19:40:35 +0800
Subject: [PATCH 2/2] Audio docs: correct the skill and the JSDoc against what
 shipped

A read-back of the prose against the code, which found four claims that
were wrong and one stray import.

- The spatial defaults apply to sounds placed through `follow` / `at`,
  NOT to every new voice. The skill said every voice, which would have
  sent a reader chasing a `refDistance` that never applied to their
  `audio.position()` call. The symptom table had lost the same cause.
- The falloff was described as "inaudible past ~2000 px", a number
  nothing measures. Replaced with what the inverse model actually does
  from `refDistance: 240`: full volume to 240, then halving per doubling,
  so 0.5 at 480, 0.25 at 960, 0.125 at 2000.
- `setListener` on a `Camera3d` contributes ORIENTATION as well as
  position, which is the whole of what a posed 3D scene needs and the
  skill did not mention at all.
- `follow` and `at` together throws. Undocumented in both the skill and
  `PlayOptions`.

Three symptom rows described bugs this line fixes rather than symptoms a
reader can still hit, so they are recast or dropped; a skill documents
the engine in front of the reader, not its history.

Also hoists a `Vector3d` import that had been left in the middle of
`spatial.ts`, which no linter flagged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NGvtaUNATVCVxD2qcbiY4t
---
 .../melonjs/skills/melonjs-audio/SKILL.md     | 55 ++++++++++++-------
 packages/melonjs/src/audio/spatial.ts         |  3 +-
 packages/melonjs/src/audio/types.ts           |  3 +
 3 files changed, 40 insertions(+), 21 deletions(-)

diff --git a/packages/melonjs/skills/melonjs-audio/SKILL.md b/packages/melonjs/skills/melonjs-audio/SKILL.md
index 7a74d66b77..f03665b69d 100644
--- a/packages/melonjs/skills/melonjs-audio/SKILL.md
+++ b/packages/melonjs/skills/melonjs-audio/SKILL.md
@@ -149,8 +149,9 @@ audio.play("ufo", { follow: this, stopWithTarget: true });
 audio.play("portal", { at: { x: 1200, y: 480 } });
 ```
 
-`follow` re-reads the target's **absolute** position each frame, so a renderable
-nested in a moving container is placed correctly. `stopWithTarget` is what you
+`follow` and `at` are mutually exclusive: passing both throws, rather than
+quietly picking one. `follow` re-reads the target's **absolute** position each
+frame, so a renderable nested in a moving container is placed correctly. `stopWithTarget` is what you
 want for a sound that belongs to an entity: without it a looping clip on a
 destroyed renderable keeps playing from wherever it last was. `audio.unfollow(id)`
 detaches a sound and leaves it playing where it is.
@@ -172,9 +173,18 @@ only if you leave the listener at `(0, 0, 0)`; mixing the two double-counts the
 player's position.
 
 `setListener` places the ear at the target's absolute position after the world
-updates. It does not touch orientation, so a side-scroller keeps the default
-"facing into the screen" and gets left-right panning plus distance falloff with
-one call.
+updates. A plain renderable contributes position only, so a side-scroller keeps
+the default "facing into the screen" and gets left-right panning plus distance
+falloff from the one call.
+
+A `Camera3d` target also contributes its **orientation**, taken from its own
+basis, so turning the camera swings the stereo image with it. That is the whole
+of what a posed 3D scene needs:
+
+```js
+audio.setListener(app.viewport);                 // in a 3D scene this is a Camera3d
+audio.play("drone", { follow: saucer });         // scene coordinates, directly
+```
 
 **Y is down.** Every one of these calls takes and returns melonJS world
 coordinates, where y grows downward; the Y-up flip Web Audio wants happens
@@ -183,18 +193,26 @@ inside the engine. Pass `pos.y` as it is.
 ### The defaults are tuned for pixels
 
 `audio.setSpatialDefaults()` / `getSpatialDefaults()` set the panner attributes
-every new voice starts from, and the shipped defaults already assume a 2D game
-measured in pixels:
+a sound placed through `follow` or `at` starts from, and the shipped values
+assume a 2D game measured in pixels:
+
+| attribute | default |
+|---|---|
+| `refDistance` | `240` |
+| `maxDistance` | `10000` |
+| `panningModel` | `"equalpower"` |
+| `distanceModel` | `"inverse"` |
+
+With those, a placed sound is at full volume out to 240 px and then halves
+each time the distance doubles: about half at 480, a quarter at 960, roughly
+an eighth at 2000. `maxDistance` is where it stops getting quieter.
 
-| attribute | default | why |
-|---|---|---|
-| `refDistance` | `240` | full volume out to roughly a few tiles |
-| `maxDistance` | `10000` | inaudible past ~2000 px with the inverse model |
-| `panningModel` | `"equalpower"` | cheap, and it does not smear a 2D mix |
-| `distanceModel` | `"inverse"` | smooth rolloff |
+**They apply to placed sounds only.** A plain `audio.play()` followed by a
+bare `audio.position()` keeps WebAudio's own defaults, where `refDistance` is
+`1` METRE and a source 100 px out is already near silent. That path is
+unchanged, which is what keeps old code working.
 
-So `audio.play("ufo", { follow: ufo })` is audible at a sane range with no
-tuning. Widen or tighten the field once, globally:
+Widen or tighten the field once, globally:
 
 ```js
 audio.setSpatialDefaults({ refDistance: 400, maxDistance: 20000 });
@@ -387,14 +405,13 @@ either way — blank screen, empty console.
 | a streamed clip ignores `withCredentials` | `stream: true` plays through an `<audio>` element; preload it buffered instead |
 | `audio.tone(440, {...})` does nothing / errors | `tone` takes a single options object with a required `duration` |
 | `tone` / `noise` are silent with no error | no WebAudio context — `getAudioContext()` returned `null` |
-| a positioned sound is silent, or only audible right next to the player | `refDistance` was narrowed below the pixel default — widen it with `audio.setSpatialDefaults({ refDistance })` |
+| a positioned sound is silent, or only audible right next to the player | placed by hand with `audio.position()`, which keeps WebAudio's metre defaults (`refDistance: 1`) — use `follow` / `at`, or set `refDistance` in pixels with `audio.panner()` |
 | a positioned sound does not follow the player | nothing is placing it — `audio.play(name, { follow: entity })`, and `audio.setListener(player)` once |
 | a followed sound pans to the wrong side as the player moves | the listener was moved **and** positions are still relative to the player — with a listener in the world, pass absolute world coordinates |
 | a looping sound outlives the entity that owns it | `follow` without `stopWithTarget: true` |
-| `audio.panner()` reset the attributes I set earlier | it merges now, so this is fixed; a stale build still replaces them |
-| `position()` does nothing on a clip that pans with `stereo()` (or the reverse) | fixed: the node follows whichever was called last. On a stale build the first call fixed it |
+| a voice panned with `stereo()` loses its 3D placement, or the reverse | one panner node per voice and last writer wins — pick one per voice and stay with it |
 | a reverb / compressor on the master gain does not affect the music | the music is `stream: true`, which bypasses the master gain — preload it buffered |
-| sound effects keep playing after the window loses focus | a build older than 20.9 — `state.pause()` only ever paused the music track; set `pauseOnBlur: false` if that was deliberate |
+| sound effects keep playing after the window loses focus | `pauseOnBlur` and `stopOnBlur` are both off, so the engine is deliberately leaving the game running in the background |
 
 ## Related skills
 
diff --git a/packages/melonjs/src/audio/spatial.ts b/packages/melonjs/src/audio/spatial.ts
index 75ffbd4678..610ff980af 100644
--- a/packages/melonjs/src/audio/spatial.ts
+++ b/packages/melonjs/src/audio/spatial.ts
@@ -12,6 +12,7 @@
  */
 
 import type Camera3d from "../camera/camera3d.ts";
+import { Vector3d } from "../math/vector3d.ts";
 import type Renderable from "../renderable/renderable.js";
 import { GAME_AFTER_UPDATE, off, on } from "../system/event.ts";
 import { position as setPosition, stop as stopSound } from "./playback.ts";
@@ -200,8 +201,6 @@ function releaseFollow(id: number) {
 }
 
 // scratch for the camera basis, reused every frame
-import { Vector3d } from "../math/vector3d.ts";
-
 const _right = new Vector3d();
 const _up = new Vector3d();
 const _forward = new Vector3d();
diff --git a/packages/melonjs/src/audio/types.ts b/packages/melonjs/src/audio/types.ts
index 5a1123393e..04bb74f386 100644
--- a/packages/melonjs/src/audio/types.ts
+++ b/packages/melonjs/src/audio/types.ts
@@ -317,6 +317,9 @@ export interface PlayOptions {
 	/**
 	 * Place this sound at a fixed world point. Same coordinates and same
 	 * defaults as `follow`, for something that does not move.
+	 *
+	 * Mutually exclusive with `follow`: passing both throws, rather than
+	 * quietly picking one and leaving the other looking broken.
 	 */
 	at?: { x: number; y: number; z?: number } | undefined;
 	/**