# BPC_AdaptiveEnvironmentDirector — Adaptive Environment Director

## Blueprint Spec — UE 5.5–5.7

---

### Parent Class
`ActorComponent`

### Dependencies
- **Requires:** [`BPC_PlaystyleClassifier`](BPC_PlaystyleClassifier.md) — Subscribes to `OnPlaystyleChanged` for routing
- **Required By:** [`BPC_AtmosphereStateController`](BPC_AtmosphereStateController.md) — Receives atmosphere change commands
- **Required By:** [`BPC_ScareEventSystem`](BPC_ScareEventSystem.md) — Coordinates scare scheduling with playstyle
- **Required By:** [`BPC_PacingDirector`](BPC_PacingDirector.md) — Receives pacing guidance
- **Required By:** [`BPC_MemoryDriftSystem`](BPC_MemoryDriftSystem.md) — Triggers room mutations based on adaptation rules
- **Required By:** [`SS_AudioManager`](../10-adaptive/132_SS_AudioManager.md) — 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`](../14-data-assets/DA_AdaptationRule.md) 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_PlaystyleClassifier`](BPC_PlaystyleClassifier.md)`OnPlaystyleChanged` 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

```mermaid
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`](BPC_PlaystyleClassifier.md) | Dispatcher (`OnPlaystyleChanged`) | `NewPlaystyleTag: GameplayTag` |
| [`BPC_AtmosphereStateController`](BPC_AtmosphereStateController.md) | Direct call | `SetAtmosphere(NewAtmosphereTag, BlendTime)` |
| [`BPC_ScareEventSystem`](BPC_ScareEventSystem.md) | Direct call | Scare scheduling parameters based on playstyle |
| [`BPC_PacingDirector`](BPC_PacingDirector.md) | Direct call | Tension adjustments |
| [`SS_AudioManager`](../10-adaptive/132_SS_AudioManager.md) | Direct call | `SetMusicLayer(LayerIndex, Sound, Intensity)` |
| [`BPC_MemoryDriftSystem`](BPC_MemoryDriftSystem.md) | Direct call | `TriggerDrift(Intensity)` |
| [`DA_AdaptationRule`](../14-data-assets/DA_AdaptationRule.md) | 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.*