@woosh/meep-engine 3.3.0 → 3.4.0

package/src/engine/sound/SOUND_EMITTER_RETIREMENT_PLAN.md

@@ -0,0 +1,536 @@
+# SoundEmitter → AudioEmitter — retirement investigation & execution plan
+
+> Goal: retire the legacy `SoundEmitter` component + `SoundEmitterSystem` (and their hard dependents)
+> in favour of the native `AudioEmitter` path. Part I records what was verified in source on
+> 2026-08-27; Part II is the execution plan, written for an AI agent as the executor. Every file:line
+> below was opened and checked in this checkout (`H:\git\CompanyNamed\meep`, HEAD `9d3aa82b7`) or in
+> the consuming game checkout (`H:\git\moh`, HEAD `d71e70d9b`).
+
+---
+
+# Part I — Investigation
+
+## 1. Where the migration stands
+
+The strangler migration (sopra `IMPLEMENTATION_PLAN.md` §0, §9) is further along than "legacy vs new
+renderer" — **sopra is already the only renderer**. What remains legacy is a *data model and its
+translation layer*:
+
+- `SoundEmitter` (`ecs/emitter/SoundEmitter.js:20-24`) is `@deprecated`, a "deprecate-and-plumb compat
+  reader". `SoundEmitterSystem.link` builds a per-entity `SoundEmitterComponentContext` that translates
+  each `SoundTrack` into a sopra `EventInstance` via `sopra/legacy/soundEmitterToEventDescription.js`.
+  No WebAudio lives on the legacy classes anymore (the `nodes` getters throw).
+- `AudioEmitter` (`ecs/audio/AudioEmitter.js`) owns a full authored `EventDescription` directly (clip
+  graph, bus routing, 3D/attenuation, voice config) plus `volume`/`autoplay` and the acoustic trio
+  (`acoustic`, `sourceRadius`, `directivity`). `AudioEmitterSystem` adds the P5 spatial live/dormant
+  management (`LiveEmitterSet` + `SpatialAudioIndex`, 100k-emitter scaling), acoustic-simulation
+  driving, and probe reverb. It is **fully built and black-box tested, but constructed only in specs**.
+- Both systems share the one `SopraEngine` via `SoundEngine.obtainSopra` (`SoundEngine.js:81-87`,
+  idempotent), which is what makes the cut-over safe to do incrementally.
+
+The migration stalled exactly at the seam the duplication audit (`src/DUPLICATION_AUDIT_2026_08_07/F_sound.md`,
+"Strangler-migration debt") identified: **the game still registers only the legacy systems, and the
+native path has zero production consumers.** The sopra plan's own status line agrees
+(`sopra/IMPLEMENTATION_PLAN.md:5-7`): "the native `AudioEmitter`/`AudioEmitterSystem` is fully built
+and tested but registered only in tests, awaiting the cut-over".
+
+Owner decision #4 in that plan ("`SoundEmitter` endgame", §12) reads: *keep as a frozen compat reader
+through P3/P4; delete only after full migration + a tested save-translation path*. This document is
+the plan for that full migration and save-translation path.
+
+## 2. The two paths side by side
+
+| Concern | Legacy (`ecs/emitter/`) | Native (`ecs/audio/`) |
+|---|---|---|
+| Component | `SoundEmitter`: `tracks: List<SoundTrack>`, `channel` (free string), `flags` (Spatialization/Attenuation), `volume: Vector1`, `distanceMin/Max`, `attenuation` enum, `panningModel` | `AudioEmitter`: `event: EventDescription` (owns busId, is3D, panning, distances, attenuation curve, maxInstances, clip graph), `volume: Vector1`, `autoplay`, `acoustic`, `sourceRadius`, `directivity` |
+| Playback unit | one `EventInstance` per `SoundTrack`, reconciled live via `tracks.on.added/removed` | one `EventInstance` per emitter; three link-time routes: managed (looping 3D → `LiveEmitterSet` budget), direct (2D / finite 3D one-shot), inert (non-autoplay) |
+| Attenuation | 3-value enum → curve at translation (`attenuationFunctionToCurve`) | authored `AnimationCurve` on the event |
+| Channel/bus | `channel` string; unknown bus falls back to `effects` with `console.error` (`SoundEmitterComponentContext.#resolveBus:223-231`) | `event.busId`; **no fallback** — `BusGraph.getInput` throws on unknown id |
+| One-shot end | `track.on.ended` Signal → track removes itself from the list | instance self-releases; **no component-level ended signal** (`instanceFor(entity)` on the system is the only observation point) |
+| Fade/stop helpers | `fadeOutAllTracks` / `stopAllTracks` plumb via `__soundRuntime` back-ref | none on the component (by design); live `volume` writes plumb to instance gain on both routes |
+| Spatial scaling | none (every linked emitter plays; BVH far-cull was deleted with the old renderer) | `LiveEmitterSet` budget (default 64) + dormant BVH leaves |
+| Acoustic sim | not supported | `acoustic`/`sourceRadius`/`directivity`, driven by `AudioEmitterSystem.update` |
+| Binary serialization | `SoundEmitterSerializationAdapter` v2 + upgraders 0→1→2, **registered** in `populateEngineSerializationRegistry.js:185,261-262` | `AudioEmitterSerializationAdapter` v0 exists **with spec but is registered nowhere** |
+| Event-driven triggers | `SoundController`/`SoundControllerSystem` (writes `SoundTrack`s into the entity's `SoundEmitter`) | none — the replacement `AudioEventTrigger` is named in three docs but **does not exist** |
+| Editor | `SoundEmitterSymbolicDisplay` + positioned marker (`editor/process/SymbolicDisplayProcess.js:67,74`) | nothing |
+| Sound-asset loader | registers `SoundAssetLoader` unconditionally (ctor) | registers it only if absent (`AudioEmitterSystem.js:104-106`) — standalone-safe |
+
+Everything the legacy component can express, the native one can too (the translator proves it
+constructively). The reverse is not true — the native path is a superset.
+
+## 3. Full consumer inventory
+
+### 3.1 meep — the legacy cluster itself
+
+| File | Role |
+|---|---|
+| `src/engine/sound/ecs/emitter/SoundEmitter.js` | component (typeName `"SoundEmitter"` at `:380` — the save-format key) |
+| `src/engine/sound/ecs/emitter/SoundTrack.js` | track data + `on.ended` + live plumbing back-refs |
+| `src/engine/sound/ecs/emitter/SoundEmitterSystem.js` | system; also exports `SoundEmitterChannels` (`:14-18`) and the deprecated `get/setChannelVolume` bus proxies (`:91-102`) |
+| `src/engine/sound/ecs/emitter/SoundEmitterComponentContext.js` | per-entity translation record (track ⇄ instance reconciliation, bus fallback, gain composition) |
+| `src/engine/sound/ecs/emitter/SoundEmitterFlags.js`, `SoundTrackFlags.js`, `SoundAttenuationFunction.js`, `SoundPanningModelType.js` | enums |
+| `src/engine/sound/ecs/emitter/SoundEmitterSerializationAdapter.js` + `SoundEmitterSerializationUpgrader_0_1.js` / `_1_2.js` | save format v2 + history |
+| `src/engine/sound/ecs/SoundController.js` + `SoundControllerSystem.js` | event→track trigger layer; hard-depends on `SoundEmitter` (`SoundControllerSystem.js:50,72`) |
+| `src/engine/sound/sopra/legacy/soundEmitterToEventDescription.js` | the pure translator (this is the future save-converter core, not dead weight) |
+| Specs | `SoundEmitterSystem.spec.js` (+ `.listener.spec.js`, `.attenuation.spec.js`), `SoundEmitterSerializationAdapter.spec.js`, `soundEmitterToEventDescription.spec.js` |
+
+### 3.2 meep — engine-internal consumers (must be ported)
+
+| Site | What it does today |
+|---|---|
+| `src/engine/EntityCreator.js:24-71` `createSound` | fire-and-forget one-shot entity: single-track `SoundEmitter` + `Transform` + `Delay(timeout)+Die` backstop; destroys the entity early via `track.on.ended` (`:59-60`) |
+| `src/view/interaction/createInterfaceCommandButton.js:35-40` | UI click sounds via `createSound` (`positioned: false`, Effects channel); the `sound` payload is a `SoundTrack` |
+| `src/engine/animation/AnimationUtils.js:236-249` | effect helper: `createSound` + `whenAllEntitiesDestroyed([timer, sound])` — **relies on the early ended→destroy**, otherwise the promise waits the full 60 s timeout |
+| `src/engine/achievements/AchievementManager.js:327-345` | achievement jingle: builds a 2D `SoundEmitter` onto the banner entity (banner has its own lifecycle) |
+| `src/engine/animation/AnimatedActions.js:50-66` `stopSoundEmitterAndNotifyOnceFinished` | `fadeOutAllTracks(0.3)` + 0.3 s timer; composed into `stopEntityAndNotifyWhenStopped` |
+| `src/engine/ecs/util/hideEntityGracefully.js:126-166` | `addShutdown(SoundEmitter, …)`: tween `emitter.volume` → 0 (2.7 s inside a 3-ish s grace period) via `TweenVector1Behavior` |
+
+### 3.3 meep — editor
+
+- `editor/process/SymbolicDisplayProcess.js:7,19,67,74` — registers a positioned marker for
+  `SoundEmitter` and the `SoundEmitterSymbolicDisplay` (min/max wire spheres).
+- `editor/process/symbolic/SoundEmitterSymbolicDisplay.js` — reads `emitter.distanceMin/Max`.
+- `editor/process/symbolic/symbolic_displays.spec.js:35,309,641-676` — covers both.
+- There is **no component property editor** for `SoundEmitter` (`registerEngineComponentEditors` has
+  zero hits) — the editor surface is only these gizmos.
+
+### 3.4 meep — serialization wiring
+
+- `src/engine/ecs/storage/populateEngineSerializationRegistry.js` registers the `SoundEmitter` (v2),
+  `SoundController`, `SoundListener` adapters (`:185-187`) and both `SoundEmitter` upgraders
+  (`:261-262`). Its spec round-trips a dataset through the registry.
+- `AudioEmitterSerializationAdapter` (v0, `ecs/audio/`) is imported **only by its own spec**. Its
+  `initialize(context, objectAdapter)` needs an object adapter whose registry knows the sopra
+  definition types (see `AudioEmitterSerializationAdapter.spec.js:13-26` for the working recipe:
+  `populateSopraSerializationRegistry(registry)` first). The sopra and acoustic registries
+  (`populateSopraSerializationRegistry`, `populateAcousticSerializationRegistry`) are likewise not
+  called from the engine-level populate.
+
+### 3.5 The game (moh) — consumed via a two-level submodule chain
+
+```
+H:\git\moh                                   (game)
+  └─ app/src/mir-engine                      submodule (gitlab …/mir-engine.git)
+       └─ meep                               submodule (gitlab …/meep.git) — SECOND working copy,
+                                             currently 22 commits behind this checkout
+```
+
+Every moh import is a deep relative path into the submodule (`../../meep/src/engine/sound/…`), so any
+file deletion or move in meep **breaks moh at build time on the next submodule bump**. Registration
+happens in `app/src/mir-engine/model/game/makeMirEngineConfig.js`:
+
+```
+ 72  import { SoundEmitterSystem } from ".../emitter/SoundEmitterSystem.js";
+ 73  import SoundControllerSystem from ".../SoundControllerSystem.js";
+ 74  import SoundListenerSystem from ".../SoundListenerSystem.js";
+169      new SoundEmitterSystem(assetManager, sound),
+170      new SoundControllerSystem(),
+171      new SoundListenerSystem(sound.context),
+```
+
+No `AudioEmitterSystem` is registered anywhere in moh. Full consuming-site list (paths relative to
+`H:\git\moh\app\src\`):
+
+| moh site | Usage |
+|---|---|
+| `mir-engine/model/game/makeMirEngineConfig.js:72-74,169-171` | system registration (above) |
+| `mir-engine/model/game/GameClassRegistry.js:39,74` | registers `SoundEmitter` under `"component.SoundEmitter"` — save/editor class lookup |
+| `mir-engine/model/game/options/makeEngineOptionsModel.js:43-80` | **volume sliders**: `getSystem(SoundEmitterSystem).get/setChannelVolume` for Effects/Ambient/Music |
+| `mir-engine/model/game/options/DevelopmentOptions.js:22,332,368` | dev menu: reset tracks, traverse all `SoundEmitter`s |
+| `mir-engine/model/game/options/resetSoundEmitterTracks.js` | sets `track.time = 0` on Music emitters |
+| `mir-engine/model/game/scenes/GameSounds.js:8-32` | catalogue of UI/jingle `SoundTrack`s |
+| `mir-engine/model/game/scenes/strategy/gui/StrategySceneGUI.js:262-276` | UI transition one-shots |
+| `mir-engine/model/game/scenes/combat/CombatUnitEntityDecorator.js:449-452,580-583` | Effects emitters on combat units |
+| `mir-engine/model/game/scenes/combat/effects/CombatEndMusicProcess.js:38,49` | finds the Music emitter, swaps its track (crossfade via `fadeOutAllTracks(1)` + `tracks.add`) |
+| `mir-engine/model/game/logic/strategy/events/WorldEventManager.js:287-291` | world-event sting one-shot |
+| `mir-engine/model/game/story/dialogue/StoryManager.js:19-22,440-457` | dialogue voice emitter (2D), uses `stopSoundEmitterAndNotifyOnceFinished` |
+| `mir-engine/model/game/story/dialogue/StoryPage.js:49,161` + `story/action/processors/implementation/sound/SoundActionProcessor.js:19` | story data holds `SoundTrack`s |
+| `mir-engine/model/game/UnitMaker.js:156-160,205-210` | unit hurt sounds: empty `SoundEmitter` + `SoundController` rule `'health-reduced'` → random hurt track |
+| `mir-engine/model/game/util/behavior/SoundEmitterVolumeBehavior.js:30` | behavior animating `SoundEmitter.volume` |
+| `generator/theme/injectMusic.js:32-37,87-89` + `generator/theme/injectEnemies.js:239-245` | level generator authors Music/Ambient emitters into blueprints |
+| `TitleScene.js:283-286` | title-screen music emitter |
+| `mir-engine/test/testEffect.js:23,30` + two specs | test harness registration + API-surface assertions |
+| `prototype/probeShadeSymbolicDisplays.js:125-126,721` | editor-display probe |
+
+## 4. Serialized-data reality
+
+- **This repo contains zero serialized scene/level/prefab data.** The only tracked JSONs are configs;
+  `test_assets/` (gitignored) holds only the Sponza model. There is nothing in-tree to migrate.
+- The binary save format keys components by `typeName` — the string `"SoundEmitter"` — through
+  `populateEngineSerializationRegistry`. moh additionally keys `"component.SoundEmitter"` in its
+  `GameClassRegistry`.
+- Real serialized `SoundEmitter` data lives **out of tree**: moh game saves and untracked `.shade`
+  scenes. meep also ships as the published npm package `@woosh/meep-engine` (3.3.0), so unknown
+  downstream consumers may hold saves. **You cannot prove from this repo that no `SoundEmitter`
+  bytes exist in the wild** — retirement therefore needs a load-path story, not just deletion.
+- Expected shapes in such saves, judging from every authoring site found: 0-track emitters (UnitMaker
+  hurt emitters — the tracks arrive transiently via `SoundController`), 1-track emitters (music /
+  ambience / title / dialogue). Multi-track emitters can only occur if a save landed mid-crossfade or
+  mid-one-shot. Track `time` is serialized but is already **not** restored into playback on link
+  (`SoundEmitterComponentContext.addTrack` plays from 0), so dropping it loses nothing real.
+- `panningModel` is JSON-only — the v2 binary adapter never wrote it. Binary-sourced conversions
+  default to HRTF, which is what deserialization produces today anyway.
+
+## 5. Gaps blocking retirement
+
+- **G1 — `AudioEmitter` cannot be saved or loaded.** Its adapter is registered nowhere; the engine
+  registry doesn't include the sopra definition types the adapter's object-graph needs. Until this is
+  closed, `AudioEmitter` content cannot exist in a level, so nothing else can migrate.
+- **G2 — no `AudioEventTrigger`.** `SoundController`'s replacement is referenced in
+  `SoundControllerSystem.js:19-21`, `sopra/README.md:14` and the sopra plan, but no class exists.
+  `SoundController` writes into `SoundEmitter`, so it cannot outlive it.
+- **G3 — no native one-shot entity helper.** `createSound` (and its `track.on.ended → destroy`
+  contract) has no `AudioEmitter` equivalent. `AudioEmitter` has no ended-observation point except
+  `AudioEmitterSystem.instanceFor`, which entity-builder code can't reach.
+- **G4 — no editor display** for `AudioEmitter` (distances now live at `emitter.event.distanceMin/Max`).
+- **G5 — no graceful-shutdown handler** for `AudioEmitter` in `hideEntityGracefully`.
+- **G6 — channel enum**: engine + app import `SoundEmitterChannels` from the system file being
+  deleted. `SopraDefaultBus` (`sopra/SopraEngine.js:17-22`) is the id-identical native home (plus
+  `master`).
+- **G7 — the game wiring** (registration, sliders, ~19 moh files) is in another repo, coordinated
+  through two submodule pins.
+- **G8 — no save-translation path** (`SoundEmitter`/`SoundController` bytes → native components).
+  The pure translator exists (`soundEmitterToEventDescription.js`) but nothing applies it to a
+  loaded dataset.
+
+## 6. Constraints the plan must respect
+
+1. **meep is a published library.** Deleting exported classes is a breaking change: it lands in a
+   major/minor bump with the legacy *reader* kept for old saves (§Phase 5).
+2. **One renderer, always** — sopra. Nothing in this plan may create a second render path.
+3. **House testing rules**: black-box specs only (observable audio-graph outcomes, not call counts);
+   the harness is `MockAudioContext` + `StubBufferProvider`; the suite is **vitest** (`npm test` /
+   `npx vitest run src/engine/sound` — several older docs say jest; they are stale).
+4. **No string-keyed magic registries; typed, explicit code** (see the dismissed-leads notes in
+   `F_sound.md` for calibration).
+5. **Commits go directly to `master`** in meep (standing owner instruction), one coherent step per
+   commit, suite green at every commit.
+6. **moh must keep building at every meep submodule pin it actually takes.** All meep-side phases
+   before the deletion phase are strictly additive/back-compatible; the deletion phase ships only
+   after moh has been ported and re-pinned.
+
+## 7. Incidental findings (not blockers; fix or file while passing)
+
+- `AudioEmitter.fromJSON` defaulted `sourceRadius` to **0.5** while the field default is **0.05** — a
+  10× drift the adapter round-trip masked. **Fixed 2026-08-27** (owner picked 0.05): both sites now
+  share a module-level `DEFAULT_SOURCE_RADIUS` const, pinned by a `fromJSON({})` assertion in
+  `AudioEmitter.spec.js`.
+- `F_sound.md` finding 3 (both systems each resolve the listener + tick sopra) becomes moot the day
+  `SoundEmitterSystem` is unregistered — the double-tick concern dies with the legacy system, and
+  `AudioEmitterSystem` becomes the single tick owner. Finding 12 (play-spec duplication between
+  `#play`/`#promote`) is unaffected by this plan; leave it to the audit's own remediation.
+- Stale doc references: `F_sound.md` cites `makeMirEngineConfig.js:182` (now `:169`);
+  `editor/REWORK_PLAN_2026_08.md:181,442` references a `resetSoundEmitterTracks` in `Editor.js` that
+  no longer exists in meep (the live one is moh's `options/resetSoundEmitterTracks.js`).
+
+---
+
+# Part II — Execution plan
+
+> **Status 2026-08-27: Phases 0-3 and Phase 5 are landed on `master`** (hashes on each heading below).
+> The native path is registered, serializable, triggerable, editable, and fed by a tested converter;
+> meep-internal consumers are ported; the legacy behavioural path is deleted.
+>
+> **Phase 4 was skipped on the owner's instruction, and Phase 5 ran without it.** That inverts the
+> ordering constraint in §6.6: the game repo still imports `SoundEmitterSystem`,
+> `SoundControllerSystem`, `SoundEmitterChannels` and `ecs/emitter/*`, all of which are now gone or
+> moved, so **moh will not build against this meep until Phase 4 is done**. Do not bump the submodule
+> pin before porting it. Phase 4's step list below is unchanged and still the work to do.
+>
+> Deviations from the plan as written, and why:
+> - **Phase 2** uses `AnimationBehavior` over an `AnimationTrack` instead of the `TweenVector1Behavior`
+>   the plan named. That class lives in the game repo; `hideEntityGracefully`'s import of it is exactly
+>   why that file cannot be loaded from meep's own suite. Using it in `AnimatedActions` would have made
+>   that file, and `AnimationUtils` with it, untestable here.
+> - **1e** gives the `AudioEmitter` positioned marker its own colour rather than the legacy emitter's
+>   green: while both components exist, which one an entity carries is what a level author migrating
+>   content needs to see, and the marker spec's standing claim is that each type has its own colour.
+> - **1f** ships without a spec. `hideEntityGracefully` imports the game's own behavior classes through
+>   moh-only relative paths, so nothing in meep's suite can load it — which is also why the legacy
+>   handler beside it has never had one.
+> - **1c** also updated the two legacy `@deprecated` notes that called `AudioEventTrigger`
+>   "forthcoming", since it no longer is.
+>
+> Corrections to Part I found while executing:
+> - §3.2 describes `hideEntityGracefully`'s sound fade as "2.7 s inside a 3-ish s grace period". The
+>   grace period is 60 s (`SHUTDOWN_GRACE_PERIOD`); the fade is its last 2.7 s.
+> - §1d's note that the legacy `positioned: false` accident used a "flat-1" curve is loose: the curve is
+>   a *linear* irradiance falloff over 1…10000, which is flat to within a fraction of a percent at any
+>   distance a level reaches. The conclusion — that dropping it changes nothing audible — holds.
+> - `createTimer` and the `stopEmitterAndNotifyOnceFinished` timers were rewritten onto behaviours in
+>   `b68cd7eba` while these phases were being executed; the `Timer` component is gone.
+
+**You are the executing agent.** Work top to bottom; phases are ordered by dependency. For each
+phase: read the named files first, implement, run the named verification, commit to `master` with the
+suggested message shape. Do not begin a phase whose gate is not met. If any step reveals the code has
+drifted from Part I, re-verify the surrounding claims before proceeding — do not patch blind.
+
+Baseline commands (from repo root `H:\git\CompanyNamed\meep`):
+
+```bash
+npm test                                   # full suite
+npx vitest run src/engine/sound            # sound domain
+npx vitest run editor                      # editor suite
+```
+
+## Decision register
+
+Defaults below are pre-selected so you can execute without stopping; each is overridable by the owner.
+**D2 and D6 are owner sign-off gates** — confirm before executing their phases (they change public
+surface / delete data paths). D1/D3/D4/D5 are recommendations you may implement directly.
+
+| # | Decision | Default (recommended) | Alternatives |
+|---|---|---|---|
+| D1 | How entity-level code observes a one-shot's end (G3) | Add a non-serialized `on = { ended: Signal }` to `AudioEmitter`, fired by `AudioEmitterSystem` when a **direct** instance self-ends (managed emitters loop; never fire). Mirrors the `SoundTrack.on.ended` precedent; keeps builders system-free | (b) per-entity ECS event via `dataset.sendEvent` — decoupled but unreachable from `Entity` builders pre-build; (c) callers poll `instanceFor` — rejected, busy-wait |
+| D2 | Save-compat end state (G8) | **Delete the behavioural classes; keep a frozen reader.** `SoundEmitter`+`SoundTrack` survive only as data-only legacy classes (same `typeName`s) + the v2 adapter + both upgraders, relocated under `sopra/legacy/`; a post-load converter turns them into native components, then removes them from the dataset | (b) keep the full classes as frozen readers indefinitely (more surface, zero churn); (c) hard break — refuse old saves (rejected: published library, live game saves) |
+| D3 | `createSound` endgame | Keep the export, same call shape, reimplemented on `AudioEmitter`; accept `{url}` or `{event: EventDescription}`; keep accepting `{track}` until Phase 5, then drop it with `SoundTrack` | delete it and port all callers to raw builders (rejected: 3 engine + several moh callers, the facade is 40 lines) |
+| D4 | Multi-track (`N>1`) conversion policy | root = `BlendContainerAudioClip`, one child per track, constant unit gain curves (Blend plays all audible children simultaneously — the engine's parallel container); `console.warn` each occurrence so real-world frequency surfaces | first-track-only + warn (lossy); N sibling entities (rejected: entity identity/Transform ownership gets murky) |
+| D5 | moh volume-slider home | `getSystem(AudioEmitterSystem).sopra.getBusVolume/setBusVolume` with `SopraDefaultBus` ids (already linear-domain end to end, D6 in the sopra plan) | reach `engine.sound.sopra` directly (ordering-fragile before systems construct) |
+| D6 | The breaking release itself (Phase 5) | ship as the next **major** version of `@woosh/meep-engine` with a migration note | minor bump if the owner treats deep-path imports as non-API |
+
+## Phase 0 — preflight
+
+1. `git status` clean; `npm test` green. Record the baseline pass/skip counts in your working notes
+   (the sopra plan's "298 green, 2 skipped" figure is dated — re-baseline, don't trust it).
+2. Read, in full: `AudioEmitter.js`, `AudioEmitterSystem.js`, `SoundEmitterSystem.js`,
+   `SoundEmitterComponentContext.js`, `soundEmitterToEventDescription.js`,
+   `AudioEmitterSerializationAdapter.spec.js` (the registry recipe), `EntityCreator.js`.
+3. Confirm the Part I inventory still holds: `grep -rl "emitter/SoundEmitter" src editor` should
+   match §3.1–§3.3 and nothing new. Any new consumer joins the Phase 2 list.
+
+## Phase 1 — close the native gaps (meep, purely additive)
+
+Each sub-phase is one commit. Nothing here touches legacy behaviour; moh remains buildable against
+any commit in this phase.
+
+### 1a — serialization wiring (G1) — `feat(sound): register AudioEmitter serialization` — ✅ DONE — 7025b8e6e
+
+1. In `populateEngineSerializationRegistry.js`: call `populateSopraSerializationRegistry(registry)`
+   and `populateAcousticSerializationRegistry(registry)` (the `AudioEmitter` adapter's event graph
+   needs the sopra clip/effect types; `directivity` needs the acoustic adapter), then add
+   `new AudioEmitterSerializationAdapter()` to the component block. Engine registry stays the single
+   source of truth (its JSDoc `:166-171` already promises exactly that to hosts).
+2. Extend `populateEngineSerializationRegistry.spec.js`: add `AudioEmitter` to `COMPONENT_TYPES` with
+   a non-default fixture (an `EventDescription.from(...)` with a looping `SampleAudioClip`, non-default
+   distances, a `RandomContainer` child if cheap) and assert field-level equality after the round
+   trip — not just "adapter defined". The existing dataset round-trip test must stay green.
+3. Verify: `npx vitest run src/engine/ecs/storage src/engine/sound`. (The `sourceRadius` default
+   drift this step used to carry was already fixed — see §7.)
+
+### 1b — one-shot end observation (D1, G3) — `feat(sound): AudioEmitter.on.ended` — ✅ DONE — c52c7734d
+
+1. `AudioEmitter`: add `on = { ended: new Signal() }` (exclude from `toJSON`/`equals`/`hash` — it is
+   observation, not authored state; note that in the JSDoc).
+2. `AudioEmitterSystem.#play`: after a successful play, `instance.onEnded.addOne(() =>
+   emitter.on.ended.send1(emitter))`. Direct route only; document why managed emitters never fire
+   (looping by definition of the route).
+3. Spec (extend `AudioEmitterSystem.spec.js`, black-box): a finite 2D autoplay emitter fires
+   `on.ended` exactly once when the mock clock passes the clip end; a looping managed emitter never
+   fires; unlink before end does not fire (stop ≠ ended — match `EventInstance` semantics; if
+   `onEnded` fires on stop, filter in the handler and assert that behaviour explicitly).
+
+### 1c — `AudioEventTrigger` (G2) — `feat(sound): AudioEventTrigger replaces SoundController` — ✅ DONE — 1add0b467
+
+The native successor to `SoundController`, per the naming locked in `sopra/README.md:14`.
+
+1. `src/engine/sound/ecs/trigger/AudioEventTrigger.js` — serializable component:
+   `rules: [{ startEvent: string, stopEvent: string|null, event: EventDescription }]`, plus
+   `toJSON/fromJSON`, `equals/hash`, `typeName = "AudioEventTrigger"`. The legacy rule's
+   `tracks[]/loop/volume/channel` collapse into the `EventDescription` itself (random pick =
+   `RandomContainerAudioClip`, loop = clip loop flag, volume = clip `gainDb`, channel = `busId`) —
+   that is the point of the native model; do not carry the legacy rule shape.
+2. `AudioEventTriggerSystem.js` — `dependencies = [AudioEventTrigger, Transform]`; on link, register
+   `dataset.addEntityEventListener(entity, rule.startEvent, …)` handlers that `sopra.playEvent(rule.event,
+   { busId, position: transform.position, oneShot: !rule.event.rootClip.loops() })`; `stopEvent`
+   stops the instances that rule started; unlink tears listeners down and stops. Constructor takes
+   `(assetManager, soundEngine)` and `obtainSopra`s like `AudioEmitterSystem` (idempotent, guarded
+   loader registration). Model the listener-bookkeeping on `SoundControllerSystem`'s
+   `removers`-per-entity shape.
+3. `AudioEventTriggerSerializationAdapter` v0 (event graphs via the object adapter — copy the
+   `AudioEmitterSerializationAdapter` initialize pattern) + registration in
+   `populateEngineSerializationRegistry` + spec round trip.
+4. System spec, black-box: send the entity event → the right buffer plays on the right bus at the
+   entity's position; stopEvent stops it; unlink cleans listeners (send after unlink → silence).
+
+### 1d — native one-shot helper (D3, G3) — `feat(sound): createSound over AudioEmitter` — ✅ DONE — 669d2b878
+
+1. Rewrite `createSound` (`EntityCreator.js`) to build: `Transform` + `SerializationMetadata.Transient`
+   + `AudioEmitter` (`autoplay: true`, one-shot event) + the existing `Delay(timeout)+Die` backstop.
+   - `{url}` → `EventDescription.from(url, SampleAudioClip.from(url, { loop: false }), { busId:
+     channel, is3D: positioned, panningModel: positioned ? HRTF : None })`. Do **not** reproduce the
+     legacy accident where `positioned: false` still attenuated by distance (fromJSON defaulted the
+     Attenuation flag on; flat-1 at 1…10000 was inaudible, so behaviour is preserved in practice —
+     note this in the commit message).
+   - `{event}` → used as-is (new capability).
+   - `{track}` (legacy `SoundTrack`) → translate via `soundTrackToEventDescription`-equivalent inline
+     (url + loop flag + volume→`gainDb`); keep until Phase 5.
+   - Early destroy: `audioEmitter.on.ended.add(builder.destroy, builder)` — restores the
+     `AnimationUtils.whenAllEntitiesDestroyed` timing contract (without 1b this regresses to the full
+     60 s backstop; that is why 1b precedes 1d).
+   - Leave `EventDescription.maxInstances` at its default 32 with `stealMode Oldest` — content-equal
+     UI clicks share a polyphony bucket; 32 is ample and stealing degrades gracefully (the legacy
+     translator's 256 existed to emulate "play everything", which a UI click does not need).
+2. Port `createInterfaceCommandButton.js` and `AchievementManager.js` off `SoundEmitterChannels` →
+   `SopraDefaultBus` (G6) in the same commit — they only need the enum + `createSound`.
+   `AchievementManager` swaps its inline `SoundEmitter.fromJSON` for an `AudioEmitter` whose event is
+   the same wav as a 2D one-shot (`autoplay` on link; the banner's own behavior sequence still owns
+   entity lifetime).
+3. Spec: extend/replace the `createSound` coverage — one-shot destroys its entity on end AND on the
+   timeout path (asset never resolves); `positioned: false` produces a non-3D instance.
+
+### 1e — editor display (G4) — `feat(editor): AudioEmitter symbolic display` — ✅ DONE — dc3b834f0
+
+1. `editor/process/symbolic/AudioEmitterSymbolicDisplay.js`: traverse `[AudioEmitter, Transform]`,
+   draw the same two wire spheres from `emitter.event.distanceMin/Max` **only when `event.is3D`**
+   (a 2D emitter has no meaningful rolloff pair). Same colours — they encode the attenuation model,
+   not the renderer (the class comment in the SoundEmitter version says exactly this; keep it).
+2. Register it plus a `PositionedMarkerSymbolicDisplay(engine, AudioEmitter, …)` alongside the legacy
+   ones in `SymbolicDisplayProcess.js` (legacy rows are removed in Phase 5, not now).
+3. Extend `symbolic_displays.spec.js` mirroring the SoundEmitter cases (`:309`, `:641-676`) for
+   `AudioEmitter`, including the is3D=false → no spheres case.
+
+### 1f — graceful shutdown (G5) — `feat(ecs): AudioEmitter graceful shutdown` — ✅ DONE — 289402b46
+
+1. In `hideEntityGracefully.js`, `addShutdown(AudioEmitter, …)` mirroring the SoundEmitter handler:
+   if `volume > 0` (and, for fidelity to the old per-track guard, the emitter is actually audible —
+   `autoplay` is a good-enough proxy), tween `emitter.volume` → 0 with the same
+   `TweenVector1Behavior` timings; live `volume` writes already reach instance gain on both routes
+   (`AudioEmitterSystem.link` wires `onVolume` for managed and direct alike).
+2. Spec if the file has one; otherwise verify through the existing shutdown coverage.
+
+**Phase 1 gate:** full suite green; `grep -rn "AudioEmitterSerializationAdapter" src | grep -v spec`
+shows the registry import; no legacy file modified except the two enum-swap consumers in 1d.
+
+## Phase 2 — port the remaining meep-internal consumers — ✅ DONE — 7939a782d
+
+One commit — `refactor(sound): port engine internals off SoundEmitter`.
+
+1. `AnimatedActions.js`: add `stopAudioEmitterAndNotifyOnceFinished(entity, ecd)` — read
+   `AudioEmitter`, tween/step `volume` → 0 over 0.3 s (a `TweenVector1Behavior` on a throwaway
+   entity, as `hideEntityGracefully` does), await the existing 0.3 s timer. Wire it into
+   `stopEntityAndNotifyWhenStopped` **alongside** the legacy call (both components may exist during
+   the transition window; each helper no-ops when its component is absent). The legacy branch dies in
+   Phase 5.
+2. Re-grep the tree for stragglers: `grep -rln "SoundEmitter\|SoundTrack" src editor` must now match
+   only: the legacy cluster itself (§3.1), `hideEntityGracefully`'s legacy handler, the legacy branch
+   in `AnimatedActions`, the editor's legacy display rows, and docs. Anything else gets ported here.
+3. Full suite green.
+
+## Phase 3 — the save-translation path (G8, D2/D4) — ✅ DONE — 7555f1bfd
+
+One commit — `feat(sound): legacy save conversion to AudioEmitter`.
+
+1. `src/engine/sound/sopra/legacy/convertLegacySoundComponents.js` — a pure dataset pass:
+   - For each entity with `SoundEmitter`: build an `AudioEmitter` — `volume` copied; `autoplay = true`;
+     event from the track list per D4 (0 tracks → **no** `AudioEmitter`, just remove; 1 track →
+     `soundTrackToEventDescription(emitter, track)` **with `track.volume` baked into the clip's
+     `gainDb`** (the live translator deliberately leaves it out — P3.5's one-live-gain rule — but a
+     static conversion has no live track gain to compose, so it must bake); N>1 → Blend per D4).
+     Resolve unknown `channel` strings against the target bus set with the same
+     `LEGACY_FALLBACK_BUS_ID` + `console.error` contract as `SoundEmitterComponentContext.#resolveBus`
+     — a converted description must never throw at first play. Then remove the `SoundEmitter`.
+   - For each entity with `SoundController`: build an `AudioEventTrigger` (per rule: random track
+     list → `RandomContainerAudioClip` of `SampleAudioClip`s, `loop`, `volume`→child `gainDb`,
+     `channel`→`busId` with the same fallback), remove the `SoundController`.
+   - Drop `track.time` (Part I §4: it was never restored into playback anyway) and `panningModel`
+     from binary sources (never serialized).
+2. Spec, black-box: hand-author v2 bytes with the `SoundEmitterSerializationAdapter` (and a
+   `SoundController` payload), deserialize into a dataset, convert, assert the resulting
+   `AudioEmitter`/`AudioEventTrigger` field-by-field (busId, is3D from the two flags per the
+   translator's `Spatialization || Attenuation` rule, distances, curve samples at 3 distances,
+   baked gains) and that no legacy component remains. Include: 0-track, 1-track looping ambient,
+   1-track one-shot effects, stale-channel fallback, and one N=2 Blend case.
+3. Where it runs: meep exposes the function; the **consumer** calls it after dataset deserialization
+   (moh wires it in Phase 4 next to its load path; the editor shell can call it on scene load). Do
+   not auto-run it inside the deserializer — hosts own their load pipelines
+   (`populateEngineSerializationRegistry`'s contract).
+
+## Phase 4 — moh migration (separate repo: `H:\git\moh`) — ⏭ SKIPPED, STILL REQUIRED
+
+**Skipped on owner instruction; Phase 5 shipped ahead of it. This is now the blocking work before moh
+can take a new meep pin** — every site below is a build break, not a behaviour change. This work is in
+another repository with its own review flow — commit there per that repo's conventions, not meep's.
+Sequence:
+
+1. **Pin bump**: update the `mir-engine/meep` submodule to the Phase 3 meep commit; build moh —
+   nothing has been deleted yet, so this must compile clean before any moh edit.
+2. **Registration** (`makeMirEngineConfig.js`): construct `new AudioEmitterSystem(assetManager, sound)`
+   and `new AudioEventTriggerSystem(assetManager, sound)`; **remove** `SoundEmitterSystem` and
+   `SoundControllerSystem` rows (`:169-170`). Keep `SoundListenerSystem` (`:171`) — it owns the
+   WebAudio listener orientation and is untouched by this retirement. With the legacy system gone,
+   `AudioEmitterSystem` is the sole `sopra.setListener` + `sopra.update` owner (resolves the
+   double-tick concern, F_sound finding 3).
+3. **Class registry** (`GameClassRegistry.js:74`): register `AudioEmitter` (+ `AudioEventTrigger`);
+   keep `"component.SoundEmitter"` while the frozen reader exists.
+4. **Load path**: call `convertLegacySoundComponents(dataset)` after save/scene deserialization.
+5. **Sliders** (`makeEngineOptionsModel.js:43-80`, D5): swap
+   `getSystem(SoundEmitterSystem).get/setChannelVolume(name)` →
+   `getSystem(AudioEmitterSystem).sopra.getBusVolume/setBusVolume(SopraDefaultBus.…)`. Semantics are
+   identical — the legacy methods were already 1-line proxies onto these buses.
+6. **Per-file ports** (order free; each is small):
+   `GameSounds.js` → named `EventDescription`s (keep export names); `StrategySceneGUI`,
+   `WorldEventManager` → `createSound({event})`; `TitleScene`, `injectMusic`, `injectEnemies`,
+   `CombatUnitEntityDecorator` → author `AudioEmitter`s (looping 3D ambience becomes spatially
+   managed for free — set `maxInstances` generously on crowd ambience per the
+   `AudioEmitterSystem.js:24-28` budget note); `UnitMaker` → `AudioEventTrigger` (drop the empty
+   hurt `SoundEmitter` entirely); `CombatEndMusicProcess` → keep locating the music entity, swap by
+   removing/re-adding the `AudioEmitter` with the new event, or `sopra.crossfade` if it exists by
+   then (sopra plan §14.2#5); `StoryManager`/`StoryPage`/`SoundActionProcessor` → story audio as
+   `EventDescription`s + `createSound({event})` + `stopAudioEmitterAndNotifyOnceFinished`;
+   `SoundEmitterVolumeBehavior` → an `AudioEmitter.volume` variant;
+   `DevelopmentOptions`/`resetSoundEmitterTracks` → traverse `AudioEmitter` (a "restart" =
+   remove+re-add the component, which re-links cleanly per the `AudioEmitter.event` JSDoc);
+   `testEffect.js` + the two specs → native registrations/assertions;
+   `probeShadeSymbolicDisplays.js` → probe the `AudioEmitter` display.
+7. **Verification**: moh's own suite, then a manual playtest checklist — title music plays; sliders
+   move Effects/Music/Ambient audibly and persist; unit hurt sounds on `'health-reduced'`; combat-end
+   music swap; dialogue plays and stops on skip; an old save loads with music/ambience audible.
+
+## Phase 5 — deletion (meep, breaking — D2/D6, owner sign-off) — ✅ DONE
+
+**Ran ahead of Phase 4 on owner instruction.** One commit —
+`refactor(sound)!: retire SoundEmitter behavioural path` — plus a version bump.
+
+1. Delete: `SoundEmitterSystem.js` (move the `SoundEmitterChannels` enum's remaining users to
+   `SopraDefaultBus` first — after Phase 2/4 there should be none), `SoundEmitterComponentContext.js`,
+   `SoundControllerSystem.js`, `SoundController.js`, the three `SoundEmitterSystem.*spec.js`, the
+   editor's two legacy display registrations + `SoundEmitterSymbolicDisplay.js` + its spec cases, the
+   legacy branch in `AnimatedActions`, the `SoundEmitter` shutdown handler in `hideEntityGracefully`,
+   and `createSound`'s `{track}` branch.
+2. Reduce `SoundEmitter`/`SoundTrack` to frozen **data-only** readers per D2: strip `__soundRuntime`,
+   the fade/stop plumbing, the throwing `nodes` getters, `SoundTrack`'s live-seek/`on.ended` wiring —
+   keep fields + `fromJSON`/`toJSON` + `typeName`. Relocate them with the v2 adapter + both upgraders
+   next to the converter under `sopra/legacy/` (moh no longer deep-imports them after Phase 4; verify
+   with a grep in moh before moving). They stay **registered** in
+   `populateEngineSerializationRegistry` — old bytes must keep deserializing, feeding the converter.
+3. Sweep docs: mark §9's remaining items done in `sopra/IMPLEMENTATION_PLAN.md`; update
+   `sopra/README.md`, `SERIALIZATION_COVERAGE.md` (upgraders list), the `F_sound.md` strangler table;
+   update this file's status line.
+4. Bump `package.json` per D6 with a changelog note: what was deleted, the converter entry point, the
+   enum replacement (`SoundEmitterChannels` → `SopraDefaultBus`).
+5. Full suite + editor suite green; then the Definition of Done below.
+
+## Phase 6 — follow-ups (file, don't do)
+
+- `EventInstance`-level crossfade (`sopra.crossfade`) if Phase 4 chose the remove/re-add music swap.
+- `F_sound.md` finding 12 (unify `#play`/`#promote` play-spec) — now the only remaining play-options
+  duplication, entirely inside the native path.
+- Delete the dormant `material/` subsystem (audit D9) — unrelated surface, same "three generations"
+  root cause, now the last legacy generation standing.
+
+## Definition of done
+
+All of the following, from the meep root, must hold after Phase 5:
+
+```bash
+# no behavioural imports of the legacy cluster outside the quarantined legacy/ + converter
+grep -rn "ecs/emitter/SoundEmitter" src editor | grep -v "sopra/legacy" | grep -v "\.md"   # → empty
+grep -rn "SoundControllerSystem\|SoundEmitterSystem" src editor | grep -v "\.md"            # → empty
+# native path is the registered one
+grep -n "AudioEmitterSerializationAdapter\|AudioEventTriggerSerializationAdapter" src/engine/ecs/storage/populateEngineSerializationRegistry.js
+# suites green
+npm test && npx vitest run editor
+```
+
+…and in moh: no imports under `meep/src/engine/sound/ecs/emitter/` or of `SoundControllerSystem`
+anywhere in `app/src`, an old save loads and sounds, and the sliders work.

package/src/engine/sound/SoundEngine.d.ts

@@ -7,7 +7,7 @@ export default SoundEngine;
 declare class SoundEngine {
     /**
      * The sopra (FMOD/Wwise-style) engine, created and owned here once the AssetManager-backed
-     * buffer provider is available (see {@link obtainSopra}, called from SoundEmitterSystem).
+     * buffer provider is available (see {@link obtainSopra}, called from the sound systems).
      * @type {SopraEngine|null}
      */
     sopra: SopraEngine | null;
@@ -20,7 +20,7 @@ declare class SoundEngine {
      *
      * Idempotent: the SopraEngine is a singleton on the SoundEngine, so the first caller creates it and
      * later callers reuse it (the `bufferProvider` of later calls is ignored). This lets multiple
-     * systems — e.g. the legacy SoundEmitterSystem and the native AudioEmitterSystem — share one engine.
+     * systems — e.g. AudioEmitterSystem and AudioEventTriggerSystem — share one engine.
      * @param {BufferProvider} bufferProvider
      * @returns {SopraEngine}
      */