UE5-Modular-Game-Framework/docs/blueprints/10-adaptive/94_BPC_AtmosphereStateController.md

BPC_AtmosphereStateController — Atmosphere State Controller

Blueprint Spec — UE 5.5–5.7

---

Parent Class

ActorComponent

Dependencies

• BPC_FearSystem — Fear state input
• BPC_DifficultyManager — Tuning bias
• BPC_LightEventController — Lighting response orchestration
• SS_AudioManager — Audio ambience orchestration (via PlayAmbient(), SetMusicLayer())
• BPC_NarrativeStateSystem — Story phase input
• BPC_PlayerMetricsTracker — Player state input
• BPC_PerformanceScaler — 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	Get Owner Component	Fear state for atmosphere selection
BPC_DifficultyManager	Get Owner Component	Intensity bias, fear modifier
BPC_LightEventController	Direct call	Set lighting preset
SS_AudioManager	Direct call	Set ambient audio, music layers
BPC_NarrativeStateSystem	Get Owner Component	Narrative phase for override
BPC_PlayerMetricsTracker	Get Owner Component	Player context metrics
BPC_PerformanceScaler	Direct call	Scale quality based on performance
SS_UIManager	Subsystem	UI atmosphere indicators
BP_NarrativeTriggerVolume	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).