Add Adaptive Environment, Atmosphere & Audio Systems

Adaptive-Environment%2C-Atmosphere-%26-Audio-Systems.md

@@ -0,0 +1,149 @@
+# 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.
+
+---
+
+*Developer Reference v1.0 — 10 Adaptive Systems. Companion to docs/blueprints/10-adaptive/ specs.*