# 10 — Adaptive Environment, Atmosphere & Audio Systems (Systems 89-101, 132-133)

**Category Purpose:** These 17 systems create the dynamic, reactive world — difficulty scaling, fear mechanics, performance optimization, procedural encounters, environment mutation, atmosphere control, lighting events, memory distortion, pacing direction, playstyle classification, rare/scare events, and the MetaSounds audio subsystem. The `BPC_AdaptiveEnvironmentDirector` is the central coordinator; `SS_AudioManager` is the sole audio entry point.

---

## System Index

| # | System | Asset Type | Role |
|---|--------|-----------|------|
| 89 | `BPC_DifficultyManager` | Component | Dynamic difficulty; metric-based scaling, adaptive tuning |
| 90 | `BPC_FearSystem` | Component | Fear system (AI + player); fear states, cower, flee |
| 91 | `BPC_PerformanceScaler` | Component | Performance scaling; LOD, spawn distance, effect quality |
| 92 | `BPC_ProceduralEncounter` | Component | Procedural encounter generation; difficulty-based spawn groups |
| 93 | `BPC_AdaptiveEnvironmentDirector` | Component | Adaptive environment; room mutation, event coordination |
| 94 | `BPC_AtmosphereStateController` | Component | Atmosphere state; room tone, tension, mood |
| 95 | `BPC_AudioAtmosphereController` | Component | [DEPRECATED] — superseded by SS_AudioManager |
| 96 | `BPC_LightEventController` | Component | Light events; flicker, dim, color shift, strobe |
| 97 | `BPC_MemoryDriftSystem` | Component | Memory drift; visual/audio/dialogue distortions |
| 98 | `BPC_PacingDirector` | Component | Pacing director; intensity bands, encounter frequency |
| 99 | `BPC_PlaystyleClassifier` | Component | Playstyle classification; Aggressive/Stealthy/Explorer |
| 100 | `BPC_RareEventSystem` | Component | Rare event system; weighted selection, cooldown |
| 101 | `BPC_ScareEventSystem` | Component | Scare event system; jump scares, anticipation, recovery |
| 132 | `SS_AudioManager` | Subsystem | Single audio entry point; 4 MetaSound buses, room zones |
| 133 | `BP_RoomAudioZone` | Actor (TriggerVolume) | Room audio zone; auto-switches reverb on overlap |

---

## Adaptive Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                    ADAPTIVE SYSTEMS                               │
│                                                                  │
│  BPC_AdaptiveEnvironmentDirector (central coordinator)            │
│    │  Reads player state: stress, health, location               │
│    │  Coordinates subsystem responses:                           │
│    │                                                             │
│    ├─► BPC_AtmosphereStateController (mood/tension)              │
│    │     Room tone: Safe → Neutral → Tense → Danger → Terror     │
│    │     Drives: lighting, audio ambience, fog, post-process     │
│    │                                                             │
│    ├─► BPC_LightEventController (lighting events)                │
│    │     Flicker, dim, color shift, strobe, blackout             │
│    │     Triggered by: tension level, scare events, combat       │
│    │                                                             │
│    ├─► BPC_MemoryDriftSystem (psychological horror)              │
│    │     Visual distortions, audio glitches, false dialogue      │
│    │     Intensity driven by stress tier                         │
│    │                                                             │
│    ├─► BPC_ScareEventSystem (horror moments)                     │
│    │     Jump scares, atmospheric scares, dread build-up         │
│    │     Anticipation → Trigger → Payoff → Recovery              │
│    │                                                             │
│    └─► BPC_RareEventSystem (special occurrences)                 │
│          Weighted random events with long cooldowns              │
│          Ghost sightings, phone rings, TV static, whispers        │
│                                                                  │
│  BPC_PacingDirector (mission-level pacing)                       │
│    │  Intensity bands: Calm → Exploration → Tension → Combat     │
│    │  Controls: encounter frequency, music intensity,            │
│    │           scare event probability, ambient tension          │
│    └─► Feeds into AdaptiveEnvironmentDirector                    │
│                                                                  │
│  BPC_PlaystyleClassifier → BPC_DifficultyManager                 │
│    │  Classifies: Aggressive / Stealthy / Explorer / Balanced    │
│    └─► Difficulty adapts: enemy count, loot quality, AI skill    │
│                                                                  │
│  BPC_FearSystem (AI fear)                                        │
│    └─► AI enemies can feel fear: cower, flee, surrender          │
│                                                                  │
│  BPC_PerformanceScaler (technical)                               │
│    └─► Dynamically adjusts LOD, spawn distance, particle count   │
└──────────────────────────────────────────────────────────────────┘
```

---

## 132 — SS_AudioManager: MetaSounds Audio Subsystem

**What It Does:** The **single entry point for all audio** in the framework. A GameInstanceSubsystem that owns 4 MetaSound mix buses (SFX, Ambience, Music, Dialogue → Master Bus), handles room acoustic zone switching, dynamic gameplay parameters (heart rate, stress, fear), volume control integration with settings, and audio pooling.

**Mix Buses:**
- `MS_SFXBus`: weapon sounds, footsteps, UI sounds, impact FX
- `MS_AmbientBus`: environmental ambience, room tone, wind, water
- `MS_MusicBus`: background music, combat music, tension music
- `MS_DialogueBus`: NPC voices, radio chatter, narrator
- All feed into `MS_MasterBus` for final output

**Gameplay Parameters:** Heart rate, stress level, fear intensity, music intensity pushed as MetaSound float parameters from gameplay systems — not hardcoded in audio assets. Enables dynamic mixing: heart beats faster → heartbeat sound intensifies.

**Room Acoustic Zones:**
- `BP_RoomAudioZone` trigger volumes on overlap call `SS_AudioManager.SetRoomPreset(Preset)`
- Presets from `DA_RoomAcousticPreset`: SmallRoom, LargeRoom, Outdoor, Cave, Hallway, Bathroom, Cathedral
- Applies reverb, occlusion, reflection, and EQ settings
- Zone stack: push/pop allows nested zones (entering a closet inside a room)

**Settings Integration:**
- `WBP_SettingsMenu` sliders call `SetBusVolume(Category, Volume)` 
- Writes to the bus MetaSound patch directly
- Persistent settings loaded on init

**Deprecation:** `BPC_AudioAtmosphereController` (95) is phased out — all audio now routes through this subsystem.

---

## 133 — BP_RoomAudioZone: Room Audio Zone Trigger

**What It Does:** A trigger volume placed in levels. When the player overlaps it, the room's acoustic preset is applied. On exit, the previous zone is restored via a push/pop stack.

**Features:**
- Defines a `DA_RoomAcousticPreset` reference
- On overlap: pushes current zone, applies new preset
- On exit: pops back to previous zone
- Supports priority for overlapping zones
- Smooth blend time between acoustic transitions

---

## 89-101: Adaptive Subsystems Summary

- **89 BPC_DifficultyManager:** Reads player metrics (accuracy, deaths, completion time) and adjusts: enemy health/damage, loot quality/quantity, puzzle hint frequency, encounter intensity.
- **90 BPC_FearSystem:** AI fear mechanic — enemies can enter fear states (nervous → cowering → fleeing → surrendering) based on player power, ally deaths, supernatural events.
- **91 BPC_PerformanceScaler:** Dynamically adjusts LOD bias, spawn distance, particle count, shadow quality based on FPS target. Ensures smooth performance on varied hardware.
- **92 BPC_ProceduralEncounter:** Generates encounters from spawn groups weighted by difficulty. Selects enemy types, counts, and spawn locations.
- **93 BPC_AdaptiveEnvironmentDirector:** Central coordinator — reads all player state and directs atmosphere/light/scare systems. The "dungeon master" of the adaptive layer.
- **94 BPC_AtmosphereStateController:** Manages room tone and tension level. Drives lighting, fog, post-process, and ambient audio via Data Assets (`DA_AtmosphereProfile`).
- **95 BPC_AudioAtmosphereController:** [DEPRECATED] Replaced by `SS_AudioManager`. Do not use in new implementations.
- **96 BPC_LightEventController:** Dynamic light events: flicker (random/sine), dim (gradual), color shift (temperature), strobe (rapid), blackout (full dark). Triggered by adaptive systems.
- **97 BPC_MemoryDriftSystem:** Psychological horror — visual distortions (shimmer, double vision), audio glitches (reversed sounds, whispers), false dialogue events. Intensity from `BPC_StressSystem`.
- **98 BPC_PacingDirector:** Controls mission pacing: intensity bands (calm→exploration→tension→combat→climax→resolution). Manages encounter frequency, music, and scare probability.
- **99 BPC_PlaystyleClassifier:** Analyzes player behavior (weapon usage, stealth time, exploration percentage) and classifies as Aggressive/Stealthy/Explorer/Balanced.
- **100 BPC_RareEventSystem:** Special rare occurrences with weighted random selection and long cooldowns. Ghost sightings, environmental anomalies, hidden messages.
- **101 BPC_ScareEventSystem:** Horror scare management: anticipation phase (build-up), trigger (payoff), recovery (return to normal). Jump scares, atmospheric dread, slow-burn tension.

---

## Common Implementation Patterns in This Category

1. **Central Coordinator + Specialist Workers:** `BPC_AdaptiveEnvironmentDirector` coordinates; each subsystem (lighting, atmosphere, scares) is a specialist.
2. **Data-Driven Profiles:** `DA_AtmosphereProfile`, `DA_ScareEvent`, `DA_RoomMutation` — content teams configure atmosphere without touching Blueprints.
3. **Gameplay Parameters as Audio Inputs:** Heart rate, stress, fear are MetaSound float parameters — audio designers work in MetaSound editor, not Blueprint.
4. **Zone Stack for Audio:** Push/pop room presets enables nested acoustic spaces (a closet inside a room inside a building).
5. **Dynamic Difficulty as Metrics Response:** Difficulty doesn't use simple "easy/medium/hard" — it reads player performance and adapts continuously.
6. **Pacing Director Controls Everything:** Encounter frequency, music intensity, scare probability all derive from pacing band, not individual systems.

---

## Multiplayer Networking

### Category Authority Map
| System | Authority | Replication |
|--------|-----------|-------------|
| `BPC_AdaptiveEnvironmentDirector` | Server coordinates | Atmosphere state replicates |
| `BPC_AtmosphereStateController` | Server sets tier | Clients play local audio/lighting per tier |
| `BPC_DifficultyManager` | Server adjusts | Difficulty params replicate |
| `BPC_FearSystem` | Server-authoritative | AI fear behavior runs on server |
| `BPC_ScareEventSystem` | Server triggers → Multicast | All clients play scare FX simultaneously |
| `BPC_RareEventSystem` | Server selects → Multicast | All clients see rare event |
| `BPC_LightEventController` | Server triggers | Replicated for synchronized lighting |
| `BPC_MemoryDriftSystem` | **Local only** | Hallucinations are per-player experience |
| `BPC_PacingDirector` | Server controls | Intensity band replicates |
| `BPC_PlaystyleClassifier` | Server classifies | Classification replicates |
| `BPC_PerformanceScaler` | **Local only** | Per-client hardware adaptation |
| `SS_AudioManager` | **Local playback** | Gameplay parameters (heart rate, tension) sync from server |
| `BP_RoomAudioZone` | **Local only** | Each client applies room acoustics based on their position |
| `BPC_ProceduralEncounter` | Server generates | Spawned actors replicate normally |

### Key Patterns
- **Atmosphere is server-controlled, locally rendered.** Server sets atmosphere tier → clients play local audio/lighting/FX.
- **Scare events are synchronized via multicast** — all players experience the scare at the same moment.
- **Per-player systems** (MemoryDrift, PerformanceScaler) are strictly local.
- **Audio is local playback** — only gameplay parameters sync from server; sound assets loaded locally.

---

*Developer Reference v1.0 — 10 Adaptive Systems. Companion to docs/blueprints/10-adaptive/ specs.*
