UE5-Modular-Game-Framework/docs/blueprints/10-adaptive/93_BPC_AdaptiveEnvironmentDirector.md

BPC_AdaptiveEnvironmentDirector — Adaptive Environment Director

Blueprint Spec — UE 5.5–5.7

---

Parent Class

ActorComponent

Dependencies

• Requires: BPC_PlaystyleClassifier — Subscribes to OnPlaystyleChanged for routing
• Required By: BPC_AtmosphereStateController — Receives atmosphere change commands
• Required By: BPC_ScareEventSystem — Coordinates scare scheduling with playstyle
• Required By: BPC_PacingDirector — Receives pacing guidance
• Required By: BPC_MemoryDriftSystem — Triggers room mutations based on adaptation rules
• Required By: SS_AudioManager — Music state changes (via SetMusicLayer())
• Engine/Plugin Requirements: GameplayTags, DA_AdaptationRule data assets

Purpose

The master controller of all adaptive systems. Receives playstyle classification and orchestrates world responses — atmosphere changes, scare scheduling, pacing adjustments, and memory drift triggers. Enforces cooldowns between major adaptive changes to prevent overwhelming the player.

---

1. Enums

No new enums. Uses playstyle tags and atmosphere tags from dependent systems.

---

2. Structs

No new structs defined. Uses DA_AdaptationRule for rule definitions.

---

3. Variables

Configuration (Instance Editable, Expose On Spawn)

Variable	Type	Default	Category	Description
AdaptationRules	Array of DA_AdaptationRule	Empty	Adaptation	Rule set defining playstyle → adaptation mappings
AdaptationCooldown	Float	60.0	Adaptation	Minimum seconds between major adaptive changes

Internal (Private / Protected, No Expose)

Variable	Type	Default	Category	Description
LastAdaptationTime	Float	0.0	Internal	Game time of last adaptation trigger
ActiveAtmosphereTag	GameplayTag	None	Internal	Currently active atmosphere state
CooldownTimer	TimerHandle	—	Internal	Timer tracking cooldown expiry

---

4. Functions

Public Functions

EvaluateAndAdapt → void

• Description: Main entry point. Called when playstyle changes or on timer. Evaluates adaptation rules against current playstyle and triggers appropriate responses.
• Parameters:

  Param	Type	Description
  PlaystyleTag	GameplayTag	Current player playstyle

• Blueprint Authority: Any
• Flow: Check cooldown → iterate AdaptationRules → find matching rules → execute adaptation actions → update LastAdaptationTime

RequestAdaptation → void

• Description: Forces an immediate adaptation check bypassing cooldown. Used for scripted/boss encounters.
• Parameters:

  Param	Type	Description
  AdaptationTag	GameplayTag	Specific adaptation to trigger

• Blueprint Authority: Any

SetAdaptationRules → void

• Description: Replaces the active rule set (used when entering new chapters/zones).
• Parameters:

  Param	Type	Description
  NewRules	Array of DA_AdaptationRule	Replacement rule set

• Blueprint Authority: Any

GetActiveAtmosphere → GameplayTag

• Description: Returns the currently active atmosphere tag.
• Parameters: None
• Blueprint Authority: Any

DisableAdaptation → void

• Description: Disables all adaptive responses. Used during cutscenes, boss fights, or scripted sequences.
• Parameters:

  Param	Type	Description
  bDisabled	Bool	True = disable, False = re-enable

• Blueprint Authority: Any

---

5. Event Dispatchers

Dispatcher	Parameters	Bind Access	Description
OnAdaptationTriggered	RuleTag: GameplayTag, PlaystyleTag: GameplayTag	Public	An adaptation rule was executed
OnAtmosphereChangeRequested	NewAtmosphereTag: GameplayTag	Public	Atmosphere change needed
OnScareScheduleRequested	ScareTier: E_ScareTier	Public	Scare event should be considered
OnMemoryDriftRequested	DriftIntensity: Float	Public	Memory drift/room mutation suggested

---

6. Overridden Events / Custom Events

Event: BeginPlay

• Description: Subscribes to BPC_PlaystyleClassifierOnPlaystyleChanged dispatcher.
• Flow:
  1. Find BPC_PlaystyleClassifier and subscribe to OnPlaystyleChanged
  2. If classifier exists and has a current playstyle, perform initial EvaluateAndAdapt

Event: OnPlaystyleChanged

• Description: Called when playstyle classification changes. Triggers re-evaluation.
• Flow:
  1. If cooldown has elapsed → EvaluateAndAdapt(NewPlaystyleTag)
  2. Else → queue adaptation for after cooldown expiry

---

7. Blueprint Graph Logic Flow

flowchart TD
    A[BeginPlay] --> B[Subscribe to PlaystyleClassifier.OnPlaystyleChanged]
    B --> C[Idle]
    C --> D{OnPlaystyleChanged fires?}
    D --> E{AdaptationCooldown elapsed?}
    E -->|Yes| F[EvaluateAndAdapt NewPlaystyleTag]
    E -->|No| G[Queue for cooldown expiry]
    F --> H[Iterate AdaptationRules]
    H --> I{Rule matches playstyle?}
    I -->|Yes| J[Execute adaptation actions]
    I -->|No| K[Skip rule]
    J --> L[Route to sub-systems]
    L --> M[Atmosphere → BPC_AtmosphereStateController]
    L --> N[Scare → BPC_ScareEventSystem]
    L --> O[Pacing → BPC_PacingDirector]
    L --> P[Audio → SS_AudioManager.SetMusicLayer]
    L --> Q[Drift → BPC_MemoryDriftSystem]
    M --> R[Update LastAdaptationTime]
    N --> R
    O --> R
    P --> R
    Q --> R
    R --> S[Broadcast OnAdaptationTriggered]

---

8. Communication Matrix

Who Talks	How	What Is Sent
BPC_PlaystyleClassifier	Dispatcher (OnPlaystyleChanged)	NewPlaystyleTag: GameplayTag
BPC_AtmosphereStateController	Direct call	SetAtmosphere(NewAtmosphereTag, BlendTime)
BPC_ScareEventSystem	Direct call	Scare scheduling parameters based on playstyle
BPC_PacingDirector	Direct call	Tension adjustments
SS_AudioManager	Direct call	SetMusicLayer(LayerIndex, Sound, Intensity)
BPC_MemoryDriftSystem	Direct call	TriggerDrift(Intensity)
DA_AdaptationRule	Data asset read	Rule definition: conditions, targets, parameters

---

9. Validation / Testing Checklist

• AdaptationRules array is populated for the current level/chapter
• EvaluateAndAdapt respects AdaptationCooldown
• OnPlaystyleChanged triggers correct rule for the new playstyle
• RequestAdaptation bypasses cooldown for scripted events
• SetAdaptationRules swaps rule set cleanly on chapter transitions
• DisableAdaptation prevents all adaptive responses during cutscenes
• Edge case: no rules match current playstyle → no changes made
• Edge case: multiple rules match → all executed in order
• Edge case: adaptation cooldown during rapid playstyle changes → only last change applies

---

10. Reuse Notes

• AdaptationRules are defined per chapter/zone via DA_AdaptationRule data assets — swap rules on level load
• AdaptationCooldown prevents jarring rapid changes; tune per project for desired responsiveness
• This director is the single routing hub for all adaptive sub-systems — do NOT create direct cross-system links
• For non-adaptive games, leave AdaptationRules empty — all sub-systems run on their defaults
• Extend DA_AdaptationRule with new action types for project-specific adaptations

---

Specification based on Master Section 9.2, line 2737.