@woosh/meep-engine 2.164.0 → 2.165.0

package/src/engine/sound/simulation/prototypeAcousticSolver.js

@@ -6,7 +6,6 @@ import {
     MeshStandardMaterial,
     SphereGeometry
 } from "three";
-import { AABB3 } from "../../../core/geom/3d/aabb/AABB3.js";
 import { Ray3 } from "../../../core/geom/3d/ray/Ray3.js";
 import { BoxShape3D } from "../../../core/geom/3d/shape/BoxShape3D.js";
 import { CapsuleShape3D } from "../../../core/geom/3d/shape/CapsuleShape3D.js";
@@ -33,9 +32,7 @@ import { ShadedGeometrySystem } from "../../graphics/ecs/mesh-v2/ShadedGeometryS
 import {
     AmbientOcclusionPostProcessEffect
 } from "../../graphics/render/buffer/simple-fx/ao/AmbientOcclusionPostProcessEffect.js";
-import { MaterialTransformer, ProbeResolutionStage } from "../../graphics/sh3/gi/material/MaterialTransformer.js";
-import { LightProbeVolume } from "../../graphics/sh3/lpv/LightProbeVolume.js";
-import { LightProbeVolumeBaker } from "../../graphics/sh3/lpv/LightProbeVolumeBaker.js";
+import { bake_lightmap_for_scene } from "../../graphics/sh3/lightmap/bake_lightmap_for_scene.js";
 import { setup_environment_sky_from_ecd } from "../../graphics/sh3/sky/hosek/setup_environment_sky_from_ecd.js";
 import {
     sampler2d_sample_equirectangular_direction
@@ -200,6 +197,8 @@ const SHACK_DOOR_HALF = 0.5, SHACK_DOOR_H = 2.0; // a 1 m doorway on the west wa
 // occluder index re-syncs on transform change) — closed it seals the opening, open it clears it.
 const DOOR_T = 0.2;                   // door slab thickness (sits within the opening)
 const DOOR_SLIDE_SPEED = 3.0;         // m/s vertical travel
+const DOOR_OPEN_CLEARANCE = 0.2;      // extra drop when open, so the lowered slab's top sinks clear of the floor
+                                      // (y=0) instead of sitting coplanar with it and z-fighting the seam
 
 // -- Orbiting external source (WorldMode layer), circling the scene from outside ------------------------
 const ORBIT_CLIP = "data/sounds/music/matsmusic/d1/Fiverr Alexgoldring WorldMode LAYER 1.ogg";
@@ -209,17 +208,18 @@ const ORBIT_HEIGHT = 5;               // a touch above the walls, so line-of-sig
 const ORBIT_SPEED = 0.18;             // rad/s (~35 s per lap)
 const ORBIT_DIST_MIN = 12, ORBIT_DIST_MAX = 90; // carries far — clearly audible from the centre with LoS
 
-// -- Light probe volume (baked diffuse GI). Baked once at startup by path-tracing each grid probe, so the probe
-// COUNT is the bake-cost knob. After the bake the IBL is switched off (scene.environment = null) so the LPV is
-// the only indirect light — the sky stays only as the backdrop.
+// -- Baked indirect lighting (a single shared lightmap). Baked once at startup by path-tracing the scene's
+// UV-atlas texels (mixed mode: indirect bounces + sky only — direct light stays realtime), so the atlas
+// resolution + samples/texel are the bake-cost knobs. After the bake the IBL is switched off
+// (scene.environment = null) so the baked lightmap is the only indirect light — the sky stays as the backdrop.
 //
-// The volume must ENCLOSE every rendered surface with margin: a surface sitting exactly on the hull boundary
-// makes the per-fragment tetrahedral-mesh lookup flip in/out across neighbouring pixels (salt-and-pepper noise
-// with the tet grid showing through). In particular the bottom is BELOW the platform (y0 = -4, platform top is
-// y=0) so the floor is INTERIOR; ny=5 over y∈[-4,12] lands a probe LAYER exactly on the floor (y = -4,0,4,8,12),
-// where it captures the floor's incident sky/sun light. The x/z bounds overhang the platform for the same reason.
-const LPV_BOUNDS = [-46, -4, -18, 18, 16, 18]; // x0,y0,z0, x1,y1,z1 — overhangs the platform; floor y=0 is interior
-const LPV_RESOLUTION = new Vector3(30, 10, 20);  // counts/axis; ny=5 over y∈[-4,12] → a layer at y=0
+// Unlike the old probe volume there are NO bounds to tune: the charter derives the atlas from the geometry
+// itself, so every ShadedGeometry surface is covered. The bake rewrites each mesh with a uv2 channel and points
+// its material at the shared lightmap; the acoustic occluder/collider shapes are untouched (lightmap is visuals
+// only), so the acoustic simulation is unaffected.
+const LIGHTMAP_RESOLUTION = 1024;     // shared atlas size (texels per side)
+const LIGHTMAP_SAMPLES = 1024;          // hemisphere gather samples per fully-baked texel
+const LIGHTMAP_MAX_BOUNCE = 4;        // path-tracer maximum bounce depth
 
 // -- Point lights co-located with each emissive source marker (a warm/cool glow in its room) -----------
 const SOURCE_LIGHT_INTENSITY = 6, SOURCE_LIGHT_DISTANCE = 12;
@@ -227,15 +227,18 @@ const SOURCE_LIGHT_INTENSITY = 6, SOURCE_LIGHT_DISTANCE = 12;
 // Wired in the configuration callback (needs the EngineConfiguration); baked against in main().
 let acousticSim = null;
 
-// Set in setupLightProbes() once the graphics MaterialManager exists. Lit scene materials are obtained THROUGH
-// it (see litMaterial) so the LPV MaterialTransformer compile-step actually patches them — a bare
-// `new MeshStandardMaterial(...)` never passes through the transform chain, so it would get NO probe GI.
+// The graphics MaterialManager, captured at the top of main(). Every lit scene material is obtained THROUGH it
+// (see litMaterial) so the engine's registered compile-steps patch it — in particular the forward+ clustered-
+// lighting transformer (registered by the LightSystem's forward+ plugin), which is what makes the per-source
+// POINT lights actually illuminate a surface. A bare `new MeshStandardMaterial(...)` skips the compile chain and
+// so receives NO clustered (point/spot) lighting — only the directional sun.
 let materialManager = null;
 
 /**
- * A managed lit material: routed through the {@link MaterialManager} so every registered compile-step (notably
- * the LPV {@link MaterialTransformer}) patches it. Use this for every lit surface instead of a bare
- * `new MeshStandardMaterial` — that is what makes the baked probe lighting visible.
+ * A managed lit material: routed through the {@link MaterialManager} so every registered compile-step patches it
+ * — notably the forward+ clustered-lighting transformer, so the per-source POINT lights light it. Use this for
+ * every lit surface instead of a bare `new MeshStandardMaterial`. The baked lightmap is applied on top by
+ * {@link bake_lightmap_for_scene}, which sets `material.lightMap` on the obtained material directly.
  *
  * @param {object} params MeshStandardMaterial parameters (color, roughness, emissive, …)
  * @returns {MeshStandardMaterial} the managed (compiled) material to hand to {@link ShadedGeometry.from}
@@ -273,31 +276,13 @@ function setupSound(config, engine) {
     config.addSystem(new SoundListenerSystem(engine.sound.context));
 }
 
-/**
- * Create the light probe volume + its material compile-step. MUST run before any scene geometry compiles — the
- * transformer injects the irradiance-sampling shader chunk into lit materials AT compile time — so it is called
- * at the very top of {@link main}. The bake itself runs later, once the geometry exists ({@link bakeLightProbes}).
- *
- * @param {Engine} engine
- * @returns {{volume:LightProbeVolume, transformer:MaterialTransformer}}
- */
-function setupLightProbes(engine) {
-    materialManager = engine.graphics.getMaterialManager();
-    const volume = new LightProbeVolume();
-    // Fragment (per-pixel) sampling: this scene is big flat boxes, so vertex sampling (only the 4 face corners)
-    // would barely read; fragment is costlier but shows the baked GI gradient across a wall/floor.
-    const transformer = new MaterialTransformer({ volume, stage: ProbeResolutionStage.Fragment });
-    materialManager.addCompileStep(transformer);
-    return { volume, transformer };
-}
-
 const _skyScratch = new Float32Array(4);
 
 /**
- * A path-tracer background sampler over the Hosek sky equirectangular texture, by ray direction (+Y up). The LPV
- * baker's path tracer otherwise has a BLACK background ({@link PathTracedScene} default), so without this the
- * bake captures only the sun bouncing off surfaces — no sky-dome fill. It samples the SAME sharp sky texture the
- * renderer applies, so the baked GI matches the visible sky.
+ * A path-tracer background sampler over the Hosek sky equirectangular texture, by ray direction (+Y up). The
+ * lightmap baker's path tracer otherwise has a BLACK background ({@link PathTracedScene} default), so without
+ * this the bake captures only the sun bouncing off surfaces — no sky-dome fill. It samples the SAME sharp sky
+ * texture the renderer applies, so the baked GI matches the visible sky.
  *
  * @param {THREE.DataTexture} skyTexture equirectangular Float32 RGBA sky (the return of setup_environment_sky_from_ecd)
  * @returns {function(out:number[], out_offset:number, direction:number[], direction_offset:number): void}
@@ -322,44 +307,118 @@ function makeSkyBackgroundSampler(skyTexture) {
 }
 
 /**
- * Bake the LPV against the now-populated scene (path-traces each grid probe — {@link LPV_RESOLUTION} drives the
- * cost), giving the path tracer the Hosek SKY as its background radiance (its default is black) so the bake picks
- * up sky-dome fill, not just the sun. Then switch the IBL OFF (`scene.environment = null`) so the baked diffuse
- * GI is the only indirect light; the sky stays as the visible backdrop (`scene.background`). Finally push the
- * baked irradiance into the already-compiled materials.
+ * Bake a single shared lightmap against the now-populated scene ({@link bake_lightmap_for_scene} charts every
+ * {@link ShadedGeometry} into one UV atlas and path-traces its texels — {@link LIGHTMAP_RESOLUTION} +
+ * {@link LIGHTMAP_SAMPLES} drive the cost), overriding the baker's default procedural sky with the Hosek SKY as
+ * its background radiance so the baked sky-dome fill matches the visible sky. The bake rewrites each mesh with a
+ * uv2 channel and points its material at the shared lightmap, so it lights itself once the texels resolve. Then
+ * switch the IBL OFF (`scene.environment = null`) so the baked lightmap is the only indirect light; the sky
+ * stays as the visible backdrop (`scene.background`).
  *
  * @param {Engine} engine
  * @param {EntityComponentDataset} ecd
- * @param {{volume:LightProbeVolume, transformer:MaterialTransformer}} lpv
  * @param {THREE.DataTexture} skyTexture the equirectangular sky to sample as the bake's background radiance
  */
-async function bakeLightProbes(engine, ecd, lpv, skyTexture) {
-    const b = LPV_BOUNDS;
-    // build_grid populates the probe positions AND the (grid) tetrahedral mesh the bake/interp need.
-    lpv.volume.build_grid(new AABB3(b[0], b[1], b[2], b[3], b[4], b[5]), LPV_RESOLUTION);
-
-    const baker = new LightProbeVolumeBaker();
-    // Give the path tracer the sky (its background defaults to black) — otherwise escaped rays return no
-    // radiance and the bake is sun-bounce only, so surfaces in shadow / facing away go dark.
-    baker._ren.scene.__background_sampler = makeSkyBackgroundSampler(skyTexture);
-
-    // Path-trace each probe (via the executor's task group) and wait for the whole bake to finish.
-    const task = baker.bake(lpv.volume, ecd);
-    engine.executor.runGroup(task);
-    await task.promise();
-
-    engine.graphics.scene.environment = null; // IBL off — only the LPV contributes indirect light now
-    lpv.transformer.update();
+async function bakeLightmap(engine, ecd, skyTexture) {
+    const group = bake_lightmap_for_scene({
+        ecd,
+        lightmap_resolution: LIGHTMAP_RESOLUTION,
+        samples_per_texel: LIGHTMAP_SAMPLES,
+        max_bounce: LIGHTMAP_MAX_BOUNCE,
+        // Sample the Hosek sky as the bake's background (its default is the procedural RTIW sky) — escaped rays
+        // then return the SAME sky the renderer shows, so the baked fill matches the visible sky.
+        background: makeSkyBackgroundSampler(skyTexture),
+    });
+
+    // Run the bake on the executor (incremental — the partial atlas uploads each cycle) and wait for it to finish.
+    // While it runs, poll the group's progress each frame to drive an unobtrusive corner progress bar + ETA.
+    const progress = makeBakeProgressBar();
+    const start = performance.now();
+    let running = true;
+
+    engine.executor.runGroup(group);
+
+    (function poll() {
+        if (!running) {
+            return;
+        }
+        progress.set(group.computeProgress(), performance.now() - start);
+        requestAnimationFrame(poll);
+    })();
+
+    await group.promise();
+
+    running = false;
+    progress.remove();
+
+    engine.graphics.scene.environment = null; // IBL off — only the baked lightmap contributes indirect light now
+}
+
+/**
+ * A small, unobtrusive lightmap-bake progress bar pinned to the bottom-left corner, showing percent done + a
+ * live ETA. The ETA is a linear extrapolation from elapsed time (`elapsed × (1 − p) / p`), reading "estimating…"
+ * until there is enough progress to extrapolate. Returns a handle to drive + dismiss it.
+ *
+ * @returns {{set: function(fraction:number, elapsedMs:number): void, remove: function(): void}}
+ */
+function makeBakeProgressBar() {
+    const container = document.createElement("div");
+    Object.assign(container.style, {
+        position: "absolute", left: "10px", bottom: "10px", zIndex: "1000",
+        width: "210px", padding: "8px 10px",
+        font: "12px sans-serif", color: "#cfe6ff",
+        background: "rgba(18,26,34,0.85)", border: "1px solid #3a6ea5", borderRadius: "4px",
+        pointerEvents: "none", userSelect: "none",
+    });
+
+    const label = document.createElement("div");
+    label.style.marginBottom = "6px";
+    label.style.letterSpacing = "0.3px";
+    label.textContent = "Baking lightmap…";
+
+    const track = document.createElement("div");
+    Object.assign(track.style, {
+        height: "6px", width: "100%", background: "rgba(255,255,255,0.12)", borderRadius: "3px", overflow: "hidden",
+    });
+
+    const fill = document.createElement("div");
+    Object.assign(fill.style, { height: "100%", width: "0%", background: "#5fa8ff", transition: "width 0.1s linear" });
+
+    track.appendChild(fill);
+    container.appendChild(label);
+    container.appendChild(track);
+    document.body.appendChild(container);
+
+    return {
+        set(fraction, elapsedMs) {
+            const p = Math.max(0, Math.min(1, fraction));
+            fill.style.width = `${(p * 100).toFixed(1)}%`;
+            const eta = p > 0.02 ? formatDuration((elapsedMs / p) * (1 - p)) : "estimating…";
+            label.textContent = `Baking lightmap… ${(p * 100).toFixed(0)}% · ETA ${eta}`;
+        },
+        remove() {
+            container.remove();
+        },
+    };
+}
+
+/** Format a millisecond duration as a compact "Xm Ys" / "Ys" string for the bake ETA. */
+function formatDuration(ms) {
+    const totalSeconds = Math.max(0, Math.round(ms / 1000));
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
 }
 
 async function main(engine) {
     const em = engine.entityManager;
     const ecd = em.dataset;
 
-    // Light probe volume — create the volume + its material compile-step BEFORE any geometry compiles (the
-    // transformer injects the irradiance-sampling shader chunk at material-compile time). Baked + the IBL
-    // switched off later, once the scene exists (see bakeLightProbes, after the acoustic bake).
-    const lpv = setupLightProbes(engine);
+    // Capture the MaterialManager up front: every lit material is obtained through it (see litMaterial) so the
+    // engine's compile-steps patch it — notably the forward+ clustered-lighting transformer that lights surfaces
+    // with the per-source POINT lights. (That transformer is registered by the LightSystem's forward+ plugin,
+    // acquired in buildLights below; the obtain() calls happen later, as the world geometry is built.)
+    materialManager = engine.graphics.getMaterialManager();
 
     // -- Systems ---------------------------------------------------------
     EngineHarness.addFpsCounter(engine);
@@ -416,17 +475,21 @@ async function main(engine) {
     buildScatteredOccluders(ecd);
     buildSmallShack(ecd);
     buildSlidingDoors(ecd); // house door + cathedral entrance, built OPEN (so the bake sees the openings clear)
-    // The audio sources are spawned on the FIRST click (setupInteraction), once the context has resumed —
-    // the engine starts ticking inside EngineHarness.initialize, so a source built here would be promoted
-    // and play on the still-suspended context (the autoplay-policy warning). Deferring the spawn to the
-    // gesture means its first playEvent always lands on a running context.
+
+    // The three fixed sources' MARKERS (emissive sphere + point light) are built now, before the bake, so the
+    // lightmap captures their glow + the rooms they light. Only their AudioEmitter is deferred to the first
+    // click (startSources): the engine ticks inside EngineHarness.initialize, so an autoplay emitter built here
+    // would link + play on the still-suspended context (the autoplay-policy warning); attaching it on the
+    // gesture means its first playEvent lands on a running context. The moving orbiter source is spawned whole
+    // on that click (its light moves, so it is not baked).
+    const staticSources = buildStaticSourceMarkers(ecd);
 
     // -- Player ----------------------------------------------------------
     const player = buildPlayerEntity(ecd);
     fpsSystem.groundResolver = makePhysicsGroundResolver(physicsSystem, player.entity);
     motion.playerEntity = player.entity; // door-proximity overlap tests against the player capsule
     buildInputBindings(ecd, player, motion);
-    setupInteraction(engine, ecd);
+    setupInteraction(engine, ecd, staticSources);
 
     // -- Bake the probe field against the now-populated occluder index ----
     // The acoustic entities above linked into acousticSim.occluderIndex on build; bake the visibility
@@ -459,13 +522,14 @@ async function main(engine) {
 
     logHelp();
 
-    // -- Light probe volume: bake the diffuse GI against the populated scene, then switch the IBL off so the LPV
-    // is the only indirect light. Done LAST (after the audio path is fully wired) — it path-traces ≈240 probes,
-    // a few seconds; the scene renders IBL-lit until it finishes, then switches to the baked GI. --------------
-    console.log("%c[lpv] baking light probes…", "color:#ffcc66;font-weight:bold");
-    console.time("[lpv] bake");
-    await bakeLightProbes(engine, ecd, lpv, skyTexture);
-    console.timeEnd("[lpv] bake");
+    // -- Lightmap: bake the indirect GI into a shared atlas against the populated scene, then switch the IBL off
+    // so the baked lightmap is the only indirect light. Done LAST (after the audio path is fully wired) — it
+    // path-traces the atlas texels over a few seconds; the scene renders IBL-lit and uploads the partial atlas
+    // each cycle, then switches to the fully-baked GI when it finishes. -------------------------------------
+    console.log("%c[lightmap] baking…", "color:#ffcc66;font-weight:bold");
+    console.time("[lightmap] bake");
+    await bakeLightmap(engine, ecd, skyTexture);
+    console.timeEnd("[lightmap] bake");
 }
 
 /**
@@ -838,7 +902,9 @@ function spawnSlidingDoor(ecd, { center, size, zoneCenter, zoneHalf, label }) {
     const collider = new Collider();
     collider.shape = BoxShape3D.from_size(size.x, size.y, size.z);
 
-    const openY = center.y - size.y; // slid fully below the floor → the opening is clear
+    // slid fully below the floor → the opening is clear; the extra DOOR_OPEN_CLEARANCE sinks the slab's top
+    // past the floor seam (its open top lands at y = -DOOR_OPEN_CLEARANCE) so it doesn't z-fight the floor.
+    const openY = center.y - size.y - DOOR_OPEN_CLEARANCE;
 
     // START open (slid down): the doors begin open AND, since the acoustic bake runs after the world is built,
     // it sees the openings clear rather than sealed. E closes them.
@@ -1017,12 +1083,13 @@ class PrototypeMotionSystem extends System {
 // The MainMenu loop, shared by the house, cathedral and shack sources (same clip, different rooms/acoustics).
 const MAIN_MENU_CLIP = "data/sounds/music/matsmusic/d1/Fiverr Alexgoldring MainMenu.ogg";
 
-/** Sources spawned on the first click. House, cathedral and the little SHACK all play the SAME MainMenu loop (so
- * the difference you hear is purely the room acoustics); a fourth source orbits the scene from outside. (The
- * paths have spaces — the browser percent-encodes them on fetch, and the dev server serves it straight from
- * `app/`.) */
-function buildSources(ecd) {
-    spawnAudioSource(ecd, {
+// The three FIXED sources — house, cathedral and the little SHACK — all play the SAME MainMenu loop (so the
+// difference you hear is purely the room acoustics). Their markers (an emissive sphere + a co-located point
+// light) are built at world time so the lightmap BAKES them — both the marker's glow and the room each one
+// lights. Only the AudioEmitter is deferred to the first click (see startSources). (The paths have spaces — the
+// browser percent-encodes them on fetch, and the dev server serves it straight from `app/`.)
+const STATIC_SOURCE_SPECS = [
+    {
         id: "house-mainmenu",
         clipPath: MAIN_MENU_CLIP,
         position: SRC,
@@ -1031,8 +1098,8 @@ function buildSources(ecd) {
         markerColor: 0xffcc66,
         markerEmissive: 0xff8800,
         lightDistance: SOURCE_LIGHT_DISTANCE / 2, // a tighter orange glow in the small dead room
-    });
-    spawnAudioSource(ecd, {
+    },
+    {
         id: "cathedral-mainmenu",
         clipPath: MAIN_MENU_CLIP,
         position: CATH_SRC,
@@ -1040,8 +1107,8 @@ function buildSources(ecd) {
         distanceMax: CATH_SRC_DIST_MAX,
         markerColor: 0x99ccff,
         markerEmissive: 0x3388ff,
-    });
-    spawnAudioSource(ecd, {
+    },
+    {
         id: "shack-mainmenu",
         clipPath: MAIN_MENU_CLIP,
         position: new Vector3(SHACK_X, 1.2, SHACK_Z),
@@ -1049,22 +1116,59 @@ function buildSources(ecd) {
         distanceMax: SRC_DIST_MAX,
         markerColor: 0xcc99ff,
         markerEmissive: 0x8844cc,
-    });
+    },
+];
 
-    // A third source ORBITS the whole scene from outside (a WorldMode layer). Acoustic + a long max distance,
-    // so from the centre you hear it swing in and out as buildings break the line of sight. The
-    // PrototypeMotionSystem drives its position each frame around (ORBIT_CX, ORBIT_CZ).
-    const orbiter = spawnAudioSource(ecd, {
-        id: "orbit-worldmode",
-        clipPath: ORBIT_CLIP,
+/**
+ * Build the three FIXED sources' visual markers (an emissive sphere + a co-located point light each). Called at
+ * world-build time, BEFORE the lightmap bake, so the bake captures each source's glow and the room it lights.
+ * The audio is attached later, on the first click ({@link startSources}).
+ *
+ * @param {EntityComponentDataset} ecd
+ * @returns {{entity:number, spec:object}[]} one record per static source, consumed by {@link startSources}
+ */
+function buildStaticSourceMarkers(ecd) {
+    return STATIC_SOURCE_SPECS.map((spec) => ({ entity: buildSourceMarker(ecd, spec), spec }));
+}
+
+/**
+ * Start the audio on the first click, once the context has resumed: attach a (3D, looping, autoplay)
+ * {@link AudioEmitter} to each pre-built static marker — so it links and autoplays on a RUNNING context (routing
+ * is fixed at link, so the emitter must first appear on a resumed context) — and spawn the moving orbiter whole.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {{entity:number, spec:object}[]} staticSources the markers built by {@link buildStaticSourceMarkers}
+ */
+function startSources(ecd, staticSources) {
+    for (const { entity, spec } of staticSources) {
+        addSourceEmitter(ecd, entity, spec);
+    }
+    spawnOrbiter(ecd);
+}
+
+/**
+ * A fourth source that ORBITS the whole scene from outside (a WorldMode layer): acoustic + a long max distance,
+ * so from the centre you hear it swing in and out as buildings break the line of sight. Spawned whole on the
+ * first click (marker + emitter + {@link PrototypeMover}, which drives its position each frame around
+ * (ORBIT_CX, ORBIT_CZ)); because its light MOVES it is deliberately not baked into the lightmap.
+ *
+ * @param {EntityComponentDataset} ecd
+ */
+function spawnOrbiter(ecd) {
+    const entity = buildSourceMarker(ecd, {
         position: new Vector3(ORBIT_CX + ORBIT_RADIUS, ORBIT_HEIGHT, ORBIT_CZ),
-        distanceMin: ORBIT_DIST_MIN,
-        distanceMax: ORBIT_DIST_MAX,
         markerColor: 0x99ff99,
         markerEmissive: 0x33cc55,
         lightIntensity: 9,
         lightDistance: 15, // ~30% smaller than the other markers' default reach
     });
+    addSourceEmitter(ecd, entity, {
+        id: "orbit-worldmode",
+        clipPath: ORBIT_CLIP,
+        distanceMin: ORBIT_DIST_MIN,
+        distanceMax: ORBIT_DIST_MAX,
+    });
+
     const mover = new PrototypeMover();
     mover.kind = "orbit";
     mover.cx = ORBIT_CX;
@@ -1072,42 +1176,22 @@ function buildSources(ecd) {
     mover.radius = ORBIT_RADIUS;
     mover.height = ORBIT_HEIGHT;
     mover.speed = ORBIT_SPEED;
-    ecd.addComponentToEntity(orbiter.entity, mover); // PrototypeMotionSystem links it via (PrototypeMover, Transform)
+    ecd.addComponentToEntity(entity, mover); // PrototypeMotionSystem links it via (PrototypeMover, Transform)
 }
 
 /**
- * Spawn one 3D looping {@link AudioEmitter} (acoustic on) with a small emissive marker sphere so it's visible.
- * Looping + 3D + autoplay → the emitter is "managed": it sounds once the listener (player) exists and is
- * within `distanceMax`, after the context resumes on the first click.
+ * Build a source's visual: a small emissive marker sphere + a co-located point light (its colour taken from the
+ * marker's emissive tint, so each source casts a coloured glow into its room). No {@link AudioEmitter} — that is
+ * attached separately ({@link addSourceEmitter}), so a static marker can be baked into the lightmap while its
+ * audio waits for the first click. Not an acoustic occluder (no {@link AcousticBody}).
  *
  * @param {EntityComponentDataset} ecd
- * @param {{id:string, clipPath:string, position:Vector3, distanceMin:number, distanceMax:number,
- *          markerColor:number, markerEmissive:number, lightIntensity?:number, lightDistance?:number}} p
- * @returns {{entity:number, transform:Transform}} the spawned entity + its transform (so a mover can drive it)
+ * @param {{position:Vector3, markerColor:number, markerEmissive:number, lightIntensity?:number,
+ *          lightDistance?:number}} p
+ * @returns {number} the spawned entity id (so an emitter / mover can be attached later)
  */
-function spawnAudioSource(ecd, { id, clipPath, position, distanceMin, distanceMax, markerColor, markerEmissive,
-                                 lightIntensity = SOURCE_LIGHT_INTENSITY, lightDistance = SOURCE_LIGHT_DISTANCE }) {
-    const event = EventDescription.from(
-        id,
-        SampleAudioClip.from(clipPath, { loop: true }),
-        {
-            is3D: true,
-            distanceMin,
-            distanceMax,
-            // Physically-based (sound-pressure-fitted) rolloff, sampled across [min, max] in metres: full
-            // volume within distanceMin, a natural log-ish falloff to silence at distanceMax. Reuses the
-            // engine's own falloff + curve builder rather than a hand-rolled line.
-            attenuation: buildAttenuationCurve(distanceMin, distanceMax, interpolate_irradiance_smith),
-        },
-    );
-
-    const emitter = new AudioEmitter();
-    emitter.event = event;
-    emitter.acoustic = true;   // occlusion / transmission / pathing
-    emitter.sourceRadius = 0.3; // a little volume so occlusion fades in/out rather than popping
-    emitter.autoplay = true;
-    emitter.volume.set(1);
-
+function buildSourceMarker(ecd, { position, markerColor, markerEmissive,
+                                  lightIntensity = SOURCE_LIGHT_INTENSITY, lightDistance = SOURCE_LIGHT_DISTANCE }) {
     const markerGeom = new SphereGeometry(0.3, 16, 16);
     const markerMat = litMaterial({
         color: markerColor,
@@ -1119,8 +1203,6 @@ function spawnAudioSource(ecd, { id, clipPath, position, distanceMin, distanceMa
     sg.setFlag(ShadedGeometryFlags.Visible);
     sg.setFlag(ShadedGeometryFlags.CastShadow);
 
-    // A point light co-located with the marker — the markers were already emissive, this lets each one cast a
-    // coloured glow into its room (the light colour is taken from the marker's emissive tint).
     const light = new Light();
     light.type.set(Light.Type.POINT);
     light.color.setRGBUint8((markerEmissive >> 16) & 0xff, (markerEmissive >> 8) & 0xff, markerEmissive & 0xff);
@@ -1131,7 +1213,6 @@ function spawnAudioSource(ecd, { id, clipPath, position, distanceMin, distanceMa
     transform.position.copy(position);
 
     const eb = new Entity()
-        .add(emitter)
         .add(sg)
         .add(light)
         .add(Tag.fromJSON(["AudioSource"]))
@@ -1139,7 +1220,43 @@ function spawnAudioSource(ecd, { id, clipPath, position, distanceMin, distanceMa
         .add(transform);
     eb.build(ecd);
 
-    return { entity: eb.id, transform };
+    return eb.id;
+}
+
+/**
+ * Attach a 3D looping, acoustic, autoplay {@link AudioEmitter} to a pre-built source marker entity. Done on the
+ * first click, once the context has resumed, so the emitter links (and autoplays) on a RUNNING context — the
+ * autoplay-policy-safe path. It shares the marker's Transform, so it sounds from the marker and tracks it if a
+ * mover drives it.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {number} entity the marker built by {@link buildSourceMarker}
+ * @param {{id:string, clipPath:string, distanceMin:number, distanceMax:number}} p
+ */
+function addSourceEmitter(ecd, entity, { id, clipPath, distanceMin, distanceMax }) {
+    const event = EventDescription.from(
+        id,
+        SampleAudioClip.from(clipPath, { loop: true }),
+        {
+            is3D: true,
+            distanceMin,
+            distanceMax,
+            // Physically-based (sound-pressure-fitted) rolloff, sampled across [min, max] in metres: full
+            // volume within distanceMin, a natural log-ish falloff to silence at distanceMax. Reuses the
+            // engine's own falloff + curve builder rather than a hand-rolled line.
+            attenuation: buildAttenuationCurve(distanceMin, distanceMax, interpolate_irradiance_smith),
+        },
+    );
+
+    const emitter = new AudioEmitter();
+    emitter.event = event;
+    emitter.acoustic = true;   // occlusion / transmission / pathing
+    emitter.sourceRadius = 0.3; // a little volume so occlusion fades in/out rather than popping
+    emitter.autoplay = true;
+    emitter.volume.set(1);
+
+    // (AudioEmitter, Transform) completes on this add → AudioEmitterSystem links it (and autoplays) immediately.
+    ecd.addComponentToEntity(entity, emitter);
 }
 
 /**
@@ -1311,15 +1428,16 @@ function buildInputBindings(ecd, player, motion) {
  * Wire the canvas click to (a) start audio and (b) capture the mouse.
  *
  * The autoplay policy requires a user gesture before audio: the engine creates the context suspended and
- * starts ticking immediately, so we must not let the source play before the first click. On that click we
- * resume the context and — only once `resume()` has actually resolved — spawn the source, so its first
- * `playEvent` lands on a running context (no autoplay warning). Pointer lock is (re)requested every click;
- * ESC (browser default) releases it.
+ * starts ticking immediately, so we must not let a source play before the first click. On that click we resume
+ * the context and — only once `resume()` has actually resolved — start the sources (attach emitters to the
+ * pre-built markers + spawn the orbiter), so their first `playEvent` lands on a running context (no autoplay
+ * warning). Pointer lock is (re)requested every click; ESC (browser default) releases it.
  *
  * @param {Engine} engine
  * @param {EntityComponentDataset} ecd
+ * @param {{entity:number, spec:object}[]} staticSources the static source markers to attach emitters to
  */
-function setupInteraction(engine, ecd) {
+function setupInteraction(engine, ecd, staticSources) {
     const el = engine.graphics.domElement;
     const captureEl = engine.viewStack.el;
 
@@ -1328,9 +1446,9 @@ function setupInteraction(engine, ecd) {
     captureEl.addEventListener("click", () => {
         if (!audioStarted) {
             audioStarted = true;
-            // resume() returns the context.resume() promise — spawn the sources only after it resolves, so the
-            // first playEvent lands on a running context.
-            engine.sound.resumeContext().then(() => buildSources(ecd));
+            // resume() returns the context.resume() promise — start the sources (attach emitters to the pre-built
+            // markers + spawn the orbiter) only after it resolves, so the first playEvent lands on a running context.
+            engine.sound.resumeContext().then(() => startSources(ecd, staticSources));
         }
 
         if (document.pointerLockElement === el || !el.requestPointerLock) return;