Replace sound effects and wire the full new audio delivery

src/client/ClientGameRunner.ts

@@ -84,6 +84,7 @@ import {
   trackGLInit,
 } from "./render/gl";
 import { ALL_UNIT_TYPES, UnitState } from "./render/types";
+import { audioMixer, initAudioMixer } from "./sound/AudioMixer";
 import { SoundManager } from "./sound/SoundManager";
 import { themeProvider } from "./theme/ThemeProvider";
 import { GameView, PlayerView } from "./view";
@@ -712,7 +713,12 @@ async function createClientGame(
   inputOverlay.style.touchAction = "none";
   document.body.appendChild(inputOverlay);
 
-  const soundManager = new SoundManager(eventBus, userSettings);
+  // Main.ts creates the mixer on page load; fall back for entry points that
+  // start a game without it (tests, embedded shells).
+  const soundManager = new SoundManager(
+    eventBus,
+    audioMixer() ?? initAudioMixer(userSettings),
+  );
   try {
     // Resolve render settings (defaults + user overrides) up front so the
     // renderer is built with the final values — no construct-with-defaults,

src/client/Main.ts

@@ -139,6 +139,8 @@ import "./components/BannedModal";
 import "./components/DesktopStatusBar";
 import "./components/MarketingConsentToast";
 import "./components/PurchaseNudgeModal";
+import { initAudioMixer } from "./sound/AudioMixer";
+import { startMenuMusic } from "./sound/MenuMusic";
 import {
   installCtrlWheelZoomBlocker,
   installDoubleTapZoomBlocker,
@@ -220,6 +222,7 @@ declare global {
     "session-cleared": CustomEvent;
     "leave-lobby": CustomEvent;
     "game-starting": CustomEvent;
+    "menu-restored": CustomEvent;
     "update-game-config": CustomEvent;
   }
 }
@@ -331,6 +334,10 @@ class Client {
     // prefill for an already-signed-in visitor hitting /c/CODE directly.
     consumeCreatorCodePath();
 
+    // One mixer for the page: the menu theme here and the SoundManager a game
+    // creates later both route through it, so the volume sliders reach both.
+    startMenuMusic(initAudioMixer(this.userSettings));
+
     // Snapshot the lapse-notice marker SYNCHRONOUSLY, before the first await.
     //
     // Reading it inside onUserMe is too late, and not by a little.
@@ -1680,6 +1687,11 @@ class Client {
     if (menuChromeIsTornDown()) {
       this.gameModeSelector?.start();
       restoreMenuChrome();
+      // The counterpart to "game-starting", and the only signal that the home
+      // page is live again without a navigation. MenuMusic tore its gesture
+      // listeners down at prestart and needs them back, or the menu theme is
+      // silent for the rest of the session.
+      document.dispatchEvent(new CustomEvent("menu-restored"));
     }
 
     if (this.joinModal.isOpen()) {

src/client/UserSettingModal.ts

@@ -34,6 +34,7 @@ import {
 import { isDesktopShell } from "./DesktopShell";
 import { pushMapLayerState } from "./MapLayerSettings";
 import { Platform } from "./Platform";
+import { playCue } from "./sound/CuePlayer";
 import {
   SetBackgroundMusicVolumeEvent,
   SetSoundEffectsVolumeEvent,
@@ -498,11 +499,13 @@ export class UserSettingModal extends BaseModal {
       return;
     }
     const volume = value / 100;
+    // Writing the setting is the whole job: AudioMixer follows
+    // USER_SETTINGS_CHANGED_EVENT, which reaches the menu theme on this page
+    // and a running game's music alike. The bus emit is kept only until the
+    // Audio tab lands and the legacy events are removed.
     this.userSettings.setBackgroundMusicVolume(volume);
-    // SoundManager reads UserSettings once at construction, so a running game
-    // only follows the slider through the bus. The page instance has no bus
-    // and nothing playing, where storing the value is the whole job.
     this.eventBus?.emit(new SetBackgroundMusicVolumeEvent(volume));
+    this.playSliderTick();
     this.requestUpdate();
   }
 
@@ -515,9 +518,26 @@ export class UserSettingModal extends BaseModal {
     const volume = value / 100;
     this.userSettings.setSoundEffectsVolume(volume);
     this.eventBus?.emit(new SetSoundEffectsVolumeEvent(volume));
+    this.playSliderTick();
     this.requestUpdate();
   }
 
+  // @change fires throughout a drag; rate-limit the tick so dragging sounds
+  // like a ratchet rather than a buzz. Re-homed from SettingsModal, which no
+  // longer owns the sliders.
+  private lastSliderTickMs = 0;
+
+  private playSliderTick() {
+    const now = Date.now();
+    if (now - this.lastSliderTickMs < 150) return;
+    this.lastSliderTickMs = now;
+    // Through the mixer, not the bus: this component is mounted twice, and
+    // the page instance has no bus, so a bus hop is silent exactly where the
+    // player is most likely to be dragging a slider. Via CuePlayer so the
+    // modal does not drag howler into every test that mounts it.
+    playCue("slider");
+  }
+
   private renderAudioSettings() {
     return html`
       <setting-slider

src/client/controllers/AmbienceController.ts

@@ -0,0 +1,97 @@
+import { EventBus } from "../../core/EventBus";
+import { UnitType } from "../../core/game/Game";
+import { Controller } from "../Controller";
+import { AmbienceTrack, SetAmbienceEvent } from "../sound/Sounds";
+import { TransformHandler } from "../TransformHandler";
+import { GameView } from "../view";
+
+// Only play ambience when zoomed in far enough that a single structure fills
+// a meaningful part of the view (scale is pixels per tile; default is 1.8,
+// clamped to [0.2, 20]).
+const AMBIENCE_ZOOM_SCALE = 8;
+const MAX_VIEW_SCALE = 20;
+// The sound designer's spec: -20 dB below the channel at the deepest zoom,
+// fading to silence as the player pulls back out. 10^(-20/20) = 0.1.
+const AMBIENCE_PEAK_GAIN = 0.1;
+// Re-emitting on every sub-perceptible step would put an event on the bus
+// each tick of a slow zoom; a step is roughly a quarter of a dB here.
+const GAIN_EPSILON = 0.003;
+// The structure must be this close (in tiles) to the center of the view.
+const AMBIENCE_RANGE_TILES = 20;
+
+const AMBIENCE_BY_TYPE = new Map<UnitType, AmbienceTrack>([
+  [UnitType.City, "city"],
+  [UnitType.Factory, "factory"],
+  [UnitType.MissileSilo, "missile-silo"],
+  [UnitType.SAMLauncher, "sam-silo"],
+]);
+
+const AMBIENT_STRUCTURE_TYPES: readonly UnitType[] = [
+  ...AMBIENCE_BY_TYPE.keys(),
+];
+
+/**
+ * Plays a structure's looping ambience when the player zooms in on it: the
+ * structure closest to the view center wins, and zooming back out fades the
+ * loop away (SoundManager owns the actual Howls and fading).
+ */
+export class AmbienceController implements Controller {
+  private current: AmbienceTrack | null = null;
+  private currentGain = 0;
+
+  constructor(
+    private readonly game: GameView,
+    private readonly eventBus: EventBus,
+    private readonly transformHandler: TransformHandler,
+  ) {}
+
+  tick(): void {
+    const next = this.desiredTrack();
+    const gain = next === null ? 0 : this.zoomGain();
+    if (
+      next === this.current &&
+      Math.abs(gain - this.currentGain) < GAIN_EPSILON
+    ) {
+      return;
+    }
+    this.current = next;
+    this.currentGain = gain;
+    this.eventBus.emit(new SetAmbienceEvent(next, gain));
+  }
+
+  /**
+   * Zoom envelope, 0 at the threshold rising to the designer's -20 dB ceiling
+   * at maximum zoom, so a structure fades up as the player leans into it
+   * rather than snapping on.
+   */
+  private zoomGain(): number {
+    const span = MAX_VIEW_SCALE - AMBIENCE_ZOOM_SCALE;
+    const t = (this.transformHandler.scale - AMBIENCE_ZOOM_SCALE) / span;
+    return AMBIENCE_PEAK_GAIN * Math.max(0, Math.min(1, t));
+  }
+
+  private desiredTrack(): AmbienceTrack | null {
+    if (this.transformHandler.scale < AMBIENCE_ZOOM_SCALE) return null;
+    // Despite the field names, screenCenter() returns world coordinates
+    // (see TransformHandler.goTo(), which compares it to a world Cell).
+    const { screenX, screenY } = this.transformHandler.screenCenter();
+    if (!this.game.isValidCoord(screenX, screenY)) return null;
+    const tile = this.game.ref(screenX, screenY);
+    let closest: { type: UnitType; distSquared: number } | null = null;
+    for (const nearby of this.game.nearbyUnits(
+      tile,
+      AMBIENCE_RANGE_TILES,
+      AMBIENT_STRUCTURE_TYPES,
+    )) {
+      if (closest === null || nearby.distSquared < closest.distSquared) {
+        closest = {
+          type: nearby.unit.type(),
+          distSquared: nearby.distSquared,
+        };
+      }
+    }
+    return closest === null
+      ? null
+      : (AMBIENCE_BY_TYPE.get(closest.type) ?? null);
+  }
+}