# BPC_AtmosphereStateController — Atmosphere State Controller

## Blueprint Spec — UE 5.5–5.7

---

### Parent Class
`ActorComponent`

### Dependencies
- [`BPC_FearSystem`](90_BPC_FearSystem.md) — Fear state input
- [`BPC_DifficultyManager`](89_BPC_DifficultyManager.md) — Tuning bias
- [`BPC_LightEventController`](BPC_LightEventController.md) — Lighting response orchestration
- [`SS_AudioManager`](../10-adaptive/132_SS_AudioManager.md) — Audio ambience orchestration (via `PlayAmbient()`, `SetMusicLayer()`)
- [`BPC_NarrativeStateSystem`](../07-narrative/58_BPC_NarrativeStateSystem.md) — Story phase input
- [`BPC_PlayerMetricsTracker`](../02-player/15_BPC_PlayerMetricsTracker.md) — Player state input
- [`BPC_PerformanceScaler`](91_BPC_PerformanceScaler.md) — Performance budget input

### Purpose
Central atmosphere orchestrator. Manages the overall mood and tension of the environment by coordinating lighting, audio, VFX, and other atmospheric systems based on the current fear state, narrative phase, difficulty bias, and player context. Acts as the single decision point for all ambient presentation, decoupling individual media systems from game logic.

### Variables

| Name | Type | Description |
|------|------|-------------|
| `CurrentAtmosphereState` | EAtmosphereState | Active atmosphere preset |
| `AtmosphereIntensity` | Float (0.0–1.0) | Global intensity bias |
| `FearIntensityBias` | Float | From DifficultyManager |
| `NarrativeAtmosphereOverride` | EAtmosphereState | Story-forced atmosphere |
| `bAllowAtmosphereChanges` | Bool | Master toggle |
| `bHasNarrativeOverride` | Bool | Active story override |
| `AmbientTransitionTime` | Float | Seconds for crossfade between states |
| `CurrentLightingPreset` | FName | Active lighting key |
| `CurrentAudioPreset` | FName | Active ambient audio key |
| `CurrentVFXPreset` | FName | Active VFX preset key |
| `AtmosphereBlendWeight` | Float (0.0–1.0) | Current crossfade progress |
| `bIsInPanicMode` | Bool | Panic state active |
| `PanicModePreset` | FName | Preset for panic state |
| `SafeZonePreset` | FName | Preset for safe zones |
| `ExplorationPreset` | FName | Default exploration preset |
| `CombatPreset` | FName | Combat tension preset |
| `InvestigationPreset` | FName | Suspense/investigation preset |
| `AtmospherePresets` | TMap<FName, FAtmospherePreset> | All registered presets |

### Enums

| Enum | Values | Description |
|------|--------|-------------|
| `EAtmosphereState` | Exploration, Suspense, Combat, Panic, SafeZone, Cinematic, Custom | Atmosphere modes |

### Structs

| Struct | Fields | Description |
|--------|--------|-------------|
| `FAtmospherePreset` | State: EAtmosphereState, LightingKey: FName, AudioAmbienceKey: FName, VFXPresetKey: FName, Intensity: Float, TransitionTime: Float, bLoops: Bool | Complete atmosphere configuration |
| `FAtmosphereTransition` | FromState: EAtmosphereState, ToState: EAtmosphereState, Duration: Float, BlendCurve: UCurveFloat | Transition definition |

### Functions

| Name | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `Initialize` | — | — | Register presets, bind events |
| `SetAtmosphere` | State: EAtmosphereState | — | Transition to atmosphere state |
| `SetAtmosphereIntensity` | Intensity: Float | — | Override global intensity |
| `GetCurrentAtmosphere` | — | EAtmosphereState | Current state |
| `RegisterPreset` | Key: FName, Preset: FAtmospherePreset | — | Add custom preset |
| `ApplyNarrativeOverride` | State: EAtmosphereState | — | Story-forced atmosphere |
| `ClearNarrativeOverride` | — | — | Return to gameplay atmosphere |
| `TriggerPanicMode` | — | — | Immediate panic atmosphere |
| `EndPanicMode` | — | — | Restore previous atmosphere |
| `SetTuningBias` | Bias: Float | — | From DifficultyManager |
| `GetPresetForState` | State: EAtmosphereState | FAtmospherePreset | Lookup preset |
| `EvaluateAtmosphere` | — | — | Determine best state from inputs |
| `ApplyPreset` | Preset: FAtmospherePreset | — | Push to all subsystems |
| `BlendToAtmosphere` | TargetState: EAtmosphereState, Duration: Float | — | Smooth transition |

### Event Dispatchers

| Name | Parameters | Fired When |
|------|-----------|-----------|
| `OnAtmosphereChanged` | NewState: EAtmosphereState, Intensity: Float | Atmosphere state changes |
| `OnAtmosphereIntensityChanged` | NewIntensity: Float | Intensity bias changes |
| `OnPanicAtmosphereStarted` | — | Panic mode activated |
| `OnPanicAtmosphereEnded` | — | Panic mode deactivated |
| `OnNarrativeOverrideApplied` | State: EAtmosphereState | Story override |

### Blueprint Flow

```
[Tick]
  └─► If bAllowAtmosphereChanges AND not bHasNarrativeOverride:
         EvaluateAtmosphere()
  └─► If atmosphere state should change:
         BlendToAtmosphere(TargetState, AmbientTransitionTime)

[EvaluateAtmosphere — main decision logic]
  └─► Inputs: Current fear level, player metrics, narrative phase
  └─► Priority order:
         1. If bIsInPanicMode: Return Panic preset
         2. If narrative override active: Return narrative preset
         3. If player in combat with fear > Terrified: Return Combat preset
         4. If player in combat: Return Combat preset
         5. If player investigating or suspicious: Return Suspense preset
         6. If player in safe zone: Return SafeZone preset
         7. If player exploring: Return Exploration preset
  └─► Apply FearIntensityBias to preset intensity
  └─► Return selected preset

[SetAtmosphere — direct override]
  └─► Lookup or get preset for state
  └─► ApplyPreset(Preset)
  └─► CurrentAtmosphereState = State
  └─► Broadcast OnAtmosphereChanged

[ApplyPreset — push to subsystems]
  └─► BPC_LightEventController.SetLightingPreset(Preset.LightingKey, TransitionTime)
  └─► SS_AudioManager.PlayAmbient(Preset.AudioAmbienceKey, TransitionTime)
  └─► Apply preset intensity modifiers to each subsystem
  └─► BlendWeight = 0.0 → lerp to 1.0 over TransitionTime

[TriggerPanicMode]
  └─► bIsInPanicMode = true
  └─► ApplyPreset(AtmospherePresets[PanicModePreset])
  └─► Broadcast OnPanicAtmosphereStarted

[EndPanicMode]
  └─► bIsInPanicMode = false
  └─► EvaluateAtmosphere()
  └─► Broadcast OnPanicAtmosphereEnded

[ApplyNarrativeOverride]
  └─► bHasNarrativeOverride = true
  └─► NarrativeAtmosphereOverride = State
  └─► SetAtmosphere(State)
  └─► Broadcast OnNarrativeOverrideApplied

[ClearNarrativeOverride]
  └─► bHasNarrativeOverride = false
  └─► EvaluateAtmosphere()
```

### Communications With

| Target | Method | Why |
|--------|--------|-----|
| [`BPC_FearSystem`](90_BPC_FearSystem.md) | Get Owner Component | Fear state for atmosphere selection |
| [`BPC_DifficultyManager`](89_BPC_DifficultyManager.md) | Get Owner Component | Intensity bias, fear modifier |
| [`BPC_LightEventController`](BPC_LightEventController.md) | Direct call | Set lighting preset |
| [`SS_AudioManager`](../10-adaptive/132_SS_AudioManager.md) | Direct call | Set ambient audio, music layers |
| [`BPC_NarrativeStateSystem`](../07-narrative/58_BPC_NarrativeStateSystem.md) | Get Owner Component | Narrative phase for override |
| [`BPC_PlayerMetricsTracker`](../02-player/15_BPC_PlayerMetricsTracker.md) | Get Owner Component | Player context metrics |
| [`BPC_PerformanceScaler`](91_BPC_PerformanceScaler.md) | Direct call | Scale quality based on performance |
| [`SS_UIManager`](../06-ui/44_SS_UIManager.md) | Subsystem | UI atmosphere indicators |
| [`BP_NarrativeTriggerVolume`](../07-narrative/BP_NarrativeTriggerVolume.md) | Overlap event | Atmosphere cue from volume |

### Reuse Notes
- Single instance on player character or persistent game actor
- All atmosphere presets are data-driven (can be expanded via Data Assets)
- Presets are keyed by FName for extensibility without enum changes
- Narrative overrides take priority over gameplay atmosphere
- Panic mode is a temporary atmosphere state; EndPanicMode restores evaluation
- Subsystems (Lighting, Audio, VFX) are decoupled; AtmosphereStateController only sets keys and intensities
- Blend curves control crossfade smoothness between states
- Renamed from `BPC_AtmosphereController` to `BPC_AtmosphereStateController` per Master naming convention.
- Cross-references updated: `BPC_LightingManager` → `BPC_LightEventController`, `BPC_AudioManager` → `BPC_AudioAtmosphereController` → `SS_AudioManager` (132 — deprecated), `BPC_VFXManager` removed (not in Master).