UE5-Modular-Game-Framework/docs/developer/10-adaptive-systems.md

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.