# BPC_AudioAtmosphereController — Audio Atmosphere Controller

> **⚠️ DEPRECATED — Phase 14d**  
> This component is superseded by [`SS_AudioManager` (132)](../10-adaptive/132_SS_AudioManager.md), the single entry point for all MetaSounds audio playback.  
> - `PlayOneShotSFX()` → `SS_AudioManager.PlaySFX()`  
> - `PlayAmbientSound()` → `SS_AudioManager.PlayAmbient()`  
> - `SetMusicLayer()` → `SS_AudioManager.SetMusicLayer()`  
> - `PlayDialogue()` → `SS_AudioManager.PlayDialogue()`  
> - `SetReverb()` → `SS_AudioManager.SetRoomPreset()` via `BP_RoomAudioZone`  
> - `FearReactiveAudioUpdate()` → `SS_AudioManager.UpdateFearAudio()`  
> - Volume modifiers → `SS_AudioManager.SetBusVolume()` bound to `SS_SettingsSystem`  
> See [`metasounds-audio-system.md`](../../architecture/metasounds-audio-system.md) for full migration guide.

## Blueprint Spec — UE 5.5–5.7

---

### Parent Class
`ActorComponent`

### Dependencies
- [`BPC_AtmosphereStateController`](BPC_AtmosphereStateController.md) — Atmosphere state receiver
- [`BPC_FearSystem`](90_BPC_FearSystem.md) — Fear-driven audio modulation
- [`BPC_PlayerMetricsTracker`](../02-player/15_BPC_PlayerMetricsTracker.md) — Player state context
- [`UAudioComponent`] — UE built-in audio component
- [`UMetaSoundSource`] — UE 5.5 MetaSounds

### Purpose
Centralized audio controller that manages ambient soundscapes, fear-reactive audio modulation, dynamic music layers, spatial audio events, and dialogue playback. Receives atmosphere state changes from AtmosphereStateController and adjusts audio parameters accordingly. Supports MetaSounds for dynamic audio generation (UE 5.5+), real-time audio parameter modulation, and multi-layered audio blending.

### Variables

| Name | Type | Description |
|------|------|-------------|
| `ActiveAudioPreset` | FName | Current audio snapshot |
| `TargetAudioPreset` | FName | Audio preset being transitioned to |
| `MasterVolumeModifier` | Float (0.0–2.0) | Global volume multiplier |
| `SFXVolumeModifier` | Float (0.0–2.0) | Sound effects volume |
| `MusicVolumeModifier` | Float (0.0–2.0) | Music layer volume |
| `AmbientVolumeModifier` | Float (0.0–2.0) | Ambient layer volume |
| `DialogueVolumeModifier` | Float (0.0–2.0) | Dialogue volume |
| `FearAudioIntensity` | Float (0.0–1.0) | Fear-based audio effect amount |
| `CurrentAudioLayers` | TArray<FAudioLayerState> | Active audio layers |
| `AmbientAudioComp` | UAudioComponent | Main ambient sound |
| `MusicAudioComp` | UAudioComponent | Music layer |
| `SubMusicComp1` | UAudioComponent | Sub-music layer 1 |
| `SubMusicComp2` | UAudioComponent | Sub-music layer 2 |
| `ReverbEffect` | UReverbEffect | Current reverb setting |
| `OcclusionIntensity` | Float | Obstacle-based audio occlusion |
| `ReverbWetLevel` | Float | Reverb mix amount |
| `bUseMetaSounds` | Bool | Enable MetaSound support |
| `ActiveMetaSound` | UMetaSoundSource | Current active MetaSound |
| `AudioParameterMap` | TMap<FName, float> | Dynamic MetaSound parameters |

### Structs

**FAudioLayerState**

| Field | Type | Description |
|-------|------|-------------|
| LayerName | FName | Identifier |
| AudioComp | UAudioComponent | Assigned component |
| TargetVolume | Float | Desired volume |
| CurrentVolume | Float | Actual volume (lerped) |
| FadeSpeed | Float | Volume fade rate |
| bIsPlaying | Bool | Active state |
| Priority | Int32 | Layer priority (higher = more important) |

### Functions

| Name | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `Initialize` | — | — | Cache references, create audio components |
| `SetAudioPreset` | PresetKey: FName, TransitionTime: Float | — | Queue audio preset transition |
| `ApplyPresetDirect` | PresetKey: FName | — | Instant preset application |
| `PlayAmbientSound` | Sound: USoundBase, FadeInTime: Float | — | Crossfade ambient |
| `StopAmbientSound` | FadeOutTime: Float | — | Fade out ambient |
| `SetMusicLayer` | LayerIndex: Int32, Sound: USoundBase, TargetVolume: Float, FadeTime: Float | — | Set music layer with crossfade |
| `StopAllMusic` | FadeOutTime: Float | — | Fade out all music layers |
| `PlayOneShotSFX` | Sound: USoundBase, Location: FVector | — | Spatial sound effect |
| `PlayDialogue` | DialogueSound: USoundBase | — | Dialogue playback with prioritization |
| `StopDialogue` | FadeOutTime: Float | — | Stop current dialogue |
| `SetReverb` | Reverb: UReverbEffect, WetLevel: Float, TransitionTime: Float | — | Apply reverb effect |
| `SetOcclusion` | Intensity: Float | — | Obstacle audio occlusion |
| `SetAudioParameter` | ParameterName: FName, Value: Float | — | MetaSound parameter update |
| `FearReactiveAudioUpdate` | FearLevel: Float, Threshold: EFearThreshold | — | Per-tick fear audio modulation |
| `OnAtmosphereChanged` | NewState: EAtmosphereState | — | React to atmosphere change |
| `HandleRoomChange` | RoomAcousticPreset: FName | — | Room-based reverb switching |

### Blueprint Flow

```
[Tick]
  └─► For each FAudioLayerState:
         Lerp CurrentVolume toward TargetVolume at FadeSpeed
         Update AudioComp volume
  └─► FearReactiveAudioUpdate(CurrentFearLevel, CurrentThreshold)

[SetAudioPreset]
  └─► If TransitionTime > 0:
         Begin crossfade: lerp volumes from current to target
         Transition layers sequentially by priority
  └─► Else:
         ApplyPresetDirect(PresetKey)

[FearReactiveAudioUpdate]
  └─► Based on fear threshold:
         Calm:      Normal audio, no modulation
         Uneasy:    SubMusicLayer1 fade in (low drone), slight reverb increase
         Nervous:   Music pitch shift down, ambient filter low-pass, increased reverb
         Afraid:    Heartbeat layer, audio distortion, occlusion simulation, surround pan random
         Terrified: All audio layers active, dissonant harmony, heavy reverb + echo, random cuts
         Panic:     Audio stutter effect, high-frequency ringing, audio buffer glitch simulation
  └─► Apply fear modulation:
         Set MasterVolumeModifier based on fear: 1.0 at 0 fear, 1.2 at high fear
         Set SFX distortion/overtone shift
         Adjust reverb wet level proportional to fear

[OnAtmosphereChanged]
  └─► Exploration:   Normal ambient, no music, natural reverb
  └─► Suspense:       Low drone music, increased reverb, distant SFX
  └─► Combat:         High-energy music, aggressive SFX, reduced reverb
  └─► Panic:          Chaotic layers, distortion, stutter
  └─► SafeZone:       Calm music, no reverb, warm ambient
  └─► Cinematic:      Dialogue-priority mode, cinematic mix, wide soundstage

[HandleRoomChange]
  └─► Lookup room acoustic preset from data asset
  └─► Apply reverb, occlusion, filter settings
  └─► Fade transition over 1-2 seconds

[PlayDialogue]
  └─► If current dialogue priority >= incoming dialogue priority:
         Queue dialogue
  └─► Else:
         Stop current, play new
  └─► Duck (lower volume) all other audio layers during dialogue
  └─► Restore on dialogue complete

[PlayOneShotSFX]
  └─► Use UGameplayStatics::SpawnSoundAtLocation
  └─► Apply occlusion based on line-of-sight to player
  └─► Apply distance-based low-pass filter
```

### Communications With

| Target | Method | Why |
|--------|--------|-----|
| [`BPC_AtmosphereStateController`](BPC_AtmosphereStateController.md) | Called by | Receive atmosphere state changes |
| [`BPC_FearSystem`](90_BPC_FearSystem.md) | Get Owner Component | Fear level for reactive audio |
| [`BPC_PlayerMetricsTracker`](../02-player/15_BPC_PlayerMetricsTracker.md) | Direct call | Contextual audio (health low, hiding) |
| [`BPC_PerformanceScaler`](91_BPC_PerformanceScaler.md) | Direct call | Reduce audio quality on low spec |
| [`BP_Checkpoint`](../05-saveload/BP_Checkpoint.md) | Event | Restore audio state on load |
| [`BPC_DialoguePlaybackSystem`](../07-narrative/40_BPC_DialoguePlaybackSystem.md) | Direct call | Dialogue audio routing |

### Reuse Notes
- Audio layers allow stacking multiple ambiences
- MetaSound parameter map enables dynamic audio without new Blueprint logic
- Dialogue ducking is automatic; use priority for interruption rules
- Audio occlusion uses line trace from sound origin to player
- All audio preset transitions are smooth crossfades, never cuts
- PerformanceScaler can disable spatial audio and reduce layer count on low-end
- Renamed from `BPC_AudioManager` to `BPC_AudioAtmosphereController` per Master naming convention.
- Cross-references updated: `BPC_AtmosphereController` → `BPC_AtmosphereStateController`, `BPC_PlayerMetricsTracker` → updated path, `BPC_CheckpointSystem` → `BP_Checkpoint`, `BPC_DialoguePlayback` → `BPC_DialoguePlaybackSystem`.