UE5-Modular-Game-Framework/docs/game/enemies-index.md

# Enemies Index — All Enemy Types

**Game:** Project Void | **Build Phase:** 12
**Framework Systems:** 80_BP_EnemyBase, 82_BPC_AlertSystem, 83_BPC_AIStateMachine, 84_AI_BaseAgentController, 85_BB_AgentBoard, 86_BPC_AIMemorySystem, 87_BPC_AIPerceptionSystem, 88_BPC_BehaviourVariantSelector

---

## Purpose

Defines the 3 enemy types, their AI controllers, behavior trees, blackboards, and integration with the horror framework systems. Plus the friendly NPC survivor.

---

## Enemy Catalog

| # | Enemy | Threat Level | Speed | Damage | Killable? | Vulnerability | Spawn Areas |
|---|-------|:---:|:---:|:---:|:---:|------|-------------|
| 1 | Patient | Medium | Slow (250) | 20 melee | YES | Light distracts briefly | Entry, WardA, WardB, Basement |
| 2 | Orderly | High | Fast (500) | 15 melee | YES | Flashlight blinds (slows 50%) | WardB, WardensOffice |
| 3 | Shade | Extreme | Teleport | 100 (1-hit) | NO | Light delays approach | WardB², Basement, VoidSpace |

² Shade appears once in WardB (scripted courtyard) + randomly in morgue

---

## 1. BP_Enemy_Patient — "The Lost"

**Parent:** `BP_EnemyBase` (80)
**Description:** Former asylum patients, twisted by the void. Slow but persistent. Walk with jerky, unnatural gait. Moan occasionally. Attack by grabbing and slashing.

### Components

| Component | Purpose |
|-----------|---------|
| `BP_EnemyBase` components (inherited) | Health (100), movement, skeletal mesh |
| `BPC_AlertSystem` (82) | Suspicious→Alerted→Combat |
| `BPC_AIStateMachine` (83) | Patrol/Search/Combat/Flee |
| `BPC_AIPerceptionSystem` (87) | Sight (120° cone, 2000u), Hearing (1500u) |
| `BPC_AIMemorySystem` (86) | Last known player location |
| `BPC_BehaviourVariantSelector` (88) | Aggressive/Curious/Erratic variants |
| `BPC_DamageReceptionSystem` (72) | Receive damage, hit reaction |
| `BPC_HitReactionSystem` (75) | Flinch/stagger on hit |
| `BPC_DeathCauseTracker` (73) | Log killing blow |

### AI Controller: AI_PatientController
**Parent:** `AI_BaseAgentController` (84)

```
Behavior Tree: BT_PatientBehavior
  ├─ Root → Selector
  │    ├─ [Combat] Sequence
  │    │    ├─ MoveTo (player last known location)
  │    │    ├─ Wait (0.5s — "searching" animation)
  │    │    ├─ MoveTo (player current location) 
  │    │    └─ Melee Attack → BPC_MeleeSystem.Swing
  │    │
  │    ├─ [Search] Sequence (unseen player, heard sound)
  │    │    ├─ MoveTo (suspected location from BPC_AIMemorySystem)
  │    │    ├─ Wait (2.0s — "sniffing" animation)
  │    │    └─ Return to Patrol
  │    │
  │    └─ [Patrol] Sequence (default)
  │         ├─ MoveTo (next waypoint on BP_PatrolPath_Asylum)
  │         ├─ Wait (3-5s at each waypoint — random)
  │         └─ Loop
```

### Blackboard: BB_PatientData
**Parent:** `BB_AgentBoard` (85)

| Key | Type | Purpose |
|-----|------|---------|
| `TargetActor` | Actor | Current target (player) |
| `LastKnownLocation` | Vector | From BPC_AIMemorySystem |
| `AlertState` | Enum | Calm/Suspicious/Alerted/Combat |
| `PatrolIndex` | Int | Current patrol waypoint |
| `bHasSeenPlayer` | Bool | Player was sighted |
| `bHeardSound` | Bool | Sound stimulus received |
| `SoundLocation` | Vector | Where sound came from |

### Perception

| Sense | Range | Angle | Notes |
|-------|:---:|:---:|-------|
| **Sight** | 2000u | 120° | Player flashlight increases detection range 50% |
| **Hearing** | 1500u | 360° | Running: detected at full range. Walking: 50%. Crouching: 25% |
| **Damage** | 3000u | 360° | Being shot alerts to player location instantly |
| **Touch** | 100u | 360° | Physical contact = immediate combat |

### Behaviour Variants (via DA_BehaviourVariant_Patient)

| Variant | Weight | Behavior |
|---------|:---:|----------|
| **Aggressive** | 40% | Charges directly, ignores hiding spots, attacks on sight |
| **Curious** | 35% | Approaches slowly, tilts head, investigates sounds first |
| **Erratic** | 25% | Randomly changes patrol path, sometimes stands still for 10s |

### Stress Impact on Player

- Patient visible: +3 stress/second
- Patient in combat: +5 stress/second
- Patient killed nearby: +10 stress (one-time spike)

---

## 2. BP_Enemy_Orderly — "The Wardens"

**Parent:** `BP_EnemyBase` (80)
**Description:** Former asylum staff. Fast, aggressive, but vulnerable to bright light. Walk with purposeful stride. Carry rusted medical tools as weapons.

### Key Differences from Patient

| Aspect | Patient | Orderly |
|--------|---------|---------|
| Speed | 250 (walk) | 500 (jog) |
| Health | 100 | 75 (weaker but faster) |
| Damage | 20 | 15 (faster attacks) |
| Attack Speed | 2.0s | 1.0s (rapid slashes) |
| Flashlight Effect | Distracts (looks away 2s) | Blinds (slows to 125 speed, misses attacks) |
| Hiding Detection | Can't detect hidden player | Can find hidden player if searched recently |
| Audio Cues | Moans, footsteps | Heavy breathing, keys jangling |

### Flashlight Vulnerability

```
Orderly enters player flashlight beam:
   ├─ BPC_AlertSystem.State == Combat?
   │    ├─ True:
   │    │    ├─ Set movement speed multiplier = 0.25 (slowed)
   │    │    ├─ Set attack accuracy multiplier = 0.3 (misses often)
   │    │    ├─ Play pained hiss sound
   │    │    └─ After 5 seconds in light: Flee state (runs away)
   │    │
   │    └─ False:
   │         ├─ Set AlertState = Suspicious
   │         └─ Shield eyes animation, back away slowly
   │
   └─ Flashlight battery drains 2x faster when blinding an Orderly
```

### AI Controller: AI_OrderlyController

Same structure as Patient but with:
- Faster patrol (jog between waypoints)
- Hiding spot investigation behavior (checks lockers)
- Flashlight avoidance task (path around light beams)

---

## 3. BP_Enemy_Shade — "The Void"

**Parent:** `BP_EnemyBase` (80)
**Description:** The primary antagonist. A shifting, semi-corporeal entity from the void. Cannot be killed, only delayed. Teleports between dark areas. One-hit kills the player.

### Components

Same as Patient/Orderly PLUS:
| Component | Purpose |
|-----------|---------|
| `BPC_FearSystem` (90) | Generates fear aura (player stress +8/sec within 800u) |
| `Timeline "PhaseShift"` | Visual: model fades in/out when teleporting |
| `PointLightComponent "VoidGlow"` | Purple-black light aura (grows brighter when close) |

### Special Rules

| Rule | Behavior |
|------|----------|
| **Immortal** | Cannot be killed. Damage only delays (stuns for 3-5 seconds) |
| **Teleport** | Moves between dark areas (illuminance < 0.1). Cannot enter lit rooms |
| **Light Delayed** | Flashlight aimed at Shade slows approach speed 60% |
| **Sound Tracking** | FULL hearing range (5000u). Any sound = instant investigation |
| **One-Hit Kill** | Contact causes instant death → Void Space |
| **Void Aura** | Radius 800u: player stress +8/sec, screen vignette darkens |
| **Persistence** | Remembers player across runs (session flag: "ShadeEncountered") |
| **Walls Don't Stop It** | Can phase through doors, walls (not during combat) |

### AI Controller: AI_ShadeController

```
Behavior Tree: BT_ShadeBehavior
  ├─ Root → Selector
  │    ├─ [Void Hunt] Sequence (player detected by sound/sight)
  │    │    ├─ Calculate "dark path" to player (avoid lit areas)
  │    │    ├─ Teleport to next dark node (max 3000u per teleport)
  │    │    ├─ Wait (1-3s — appears, stands still, watches)
  │    │    ├─ MoveTo (player — floating, no walk animation)
  │    │    ├─ On contact: KillPlayer → trigger void death
  │    │    └─ If flashlight hits: Stun 3s, teleport away
  │    │
  │    └─ [Stalk] Sequence (default)
  │         ├─ Teleport to dark location near player (800-1500u)
  │         ├─ Wait (5-10s — watching)
  │         ├─ SFX: whisper, breathing, or distant scream
  │         └─ If player stays still > 10s: teleport closer
```

### Blackboard: BB_ShadeData

| Key | Type | Purpose |
|-----|------|---------|
| `TargetPlayer` | Actor | Player reference |
| `DarkNodes` | Array\<Vector\> | All dark locations in level (pre-calculated) |
| `CurrentDarkNode` | Vector | Current teleport position |
| `bIsStunned` | Bool | Recently hit by flashlight |
| `StunTimer` | Float | Remaining stun duration |
| `bHasKilledPlayer` | Bool | Killed player this encounter |

### Shade Encounter Design

| Location | Type | Trigger | Duration |
|----------|------|---------|----------|
| WardB Courtyard | **Scripted Teaser** | Player enters courtyard | 10s (watches then vanishes) |
| WardB Morgue | **Void Shift Guardian** | Void shift event | 30s (pursues during shift) |
| Basement | **Persistent Hunter** | Always active in basement | Entire level |
| Void Space | **Final Chase** | Enter void | Until exit or caught |

---

## 4. BP_NPC_Survivor (Friendly)

**Parent:** `Character`
**Description:** A surviving asylum patient. Optional rescue NPC. If saved, appears in endings and grants lore.

### Interaction

```
BP_NPC_Survivor
  Implements: I_Interactable

Event Interact:
   │
   ├─ [Dialogue Choice]
   │    ├─ BPC_DialogueChoiceSystem.PresentChoices()
   │    ├─ Options:
   │    │    ├─ "Who are you? What happened here?" → Lore dump
   │    │    ├─ "Follow me. I'll get you out." → NPC follows player
   │    │    └─ "Stay here. It's safer." → NPC stays, gives item
   │    │
   │    ├─ Choice → BPC_BranchingConsequenceSystem.ExecuteConsequence()
   │    │    ├─ Follow: NPC becomes follower, can carry items
   │    │    └─ Stay: NPC gives Keycard Alpha (if not found yet)
   │    │
   │    └─ BPC_EndingAccumulator.RecordEvent("SurvivorSaved")
   │
   └─ Return True
```

### Survivor States

| State | Behavior |
|-------|----------|
| Idle | Sits in room, waits for player |
| Following | Walks behind player, stops when player stops |
| Hiding | If enemies near, finds hiding spot |
| Dead | If attacked by enemies during escort |
| Saved | Reaches safe room — ending flag set |

---

## Enemy Spawning & Difficulty

### BPC_ProceduralEncounter (92) Configuration

| Encounter | DA_EncounterData | Difficulty Scalar |
|-----------|-----------------|:---:|
| WardA Patrol | `DA_Encounter_WardA_Patrol` | ×1.0 |
| WardB Mixed | `DA_Encounter_WardB_Mixed` | ×1.2 |
| Basement Shade | `DA_Encounter_ShadeAmbush` | ×1.5 |

### BPC_DifficultyManager (89) Scaling

```
Player deaths in current chapter:
  0 deaths → Difficulty × 1.0 (normal)
  1 death  → Difficulty × 0.9 (slightly easier)
  2 deaths → Difficulty × 0.8 (noticeably easier)
  3+ deaths→ Difficulty × 0.7 (easier + extra checkpoints)

Difficulty affects:
  ├─ Enemy count: × Difficulty (rounded down)
  ├─ Enemy health: × Difficulty
  ├─ Enemy damage: × Difficulty
  ├─ Ammo spawn count: × (2.0 - Difficulty)  [more ammo when easier]
  ├─ Stress accumulation rate: × Difficulty
  └─ Scare event frequency: × Difficulty
```

---

## Enemy Death & Persistence

When an enemy is killed:

```
Enemy Health = 0
   │
   ├─ [Death Animation] Montage plays (GASP death state)
   ├─ [Ragdoll] Enable physics on skeletal mesh
   ├─ [Corpse Persistence]
   │    ├─ BPC_PersistentCorpseSystem.SaveCorpse()
   │    └─ Corpse remains in world until:
   │         ├─ Player leaves level (transition)
   │         ├─ Save/Load cycle (corpse ID saved)
   │         └─ Manual "clear corpses" via Void shift
   │
   ├─ [Loot Drop] (30% chance)
   │    └─ Spawn random item at corpse location:
   │         ├─ Patient: Battery (40%), MedKit (30%), Ammo (20%), Nothing (10%)
   │         └─ Orderly: Ammo (40%), Key item hint (30%), Battery (20%), Nothing (10%)
   │
   ├─ [Metrics]
   │    ├─ BPC_PlayerMetricsTracker.RecordKill(EnemyType, WeaponUsed)
   │    └─ BPC_ProgressStatTracker.IncrementEnemiesKilled()
   │
   ├─ [Stress Effect]
   │    └─ Player BPC_StressSystem.AddStress(10) — "killing a former human"
   │
   └─ [Achievement Check]
        └─ SS_AchievementSystem.Check("FirstKill", "Pacifist", "Exterminator")
```

---

## Blueprint Wiring Checklist

### Patient Enemy
- [ ] Create `BP_Enemy_Patient` — child of `BP_EnemyBase`
- [ ] Add alert, AI state machine, perception, memory, behavior variant, damage reception, hit reaction components
- [ ] Create `AI_PatientController` — child of `AI_BaseAgentController`
- [ ] Create `BT_PatientBehavior` — Patrol/Search/Combat branches
- [ ] Create `BB_PatientData` — all blackboard keys
- [ ] Create `DA_BehaviourVariant_Patient` with 3 variants + weights
- [ ] Set max health = 100, walk speed = 250, damage = 20

### Orderly Enemy
- [ ] Create `BP_Enemy_Orderly` — child of `BP_EnemyBase`
- [ ] Same components as Patient
- [ ] Add flashlight vulnerability logic in AI controller (OnPerceptionUpdated → check light)
- [ ] Create `AI_OrderlyController`, `BT_OrderlyBehavior`, `BB_OrderlyData`
- [ ] Set max health = 75, walk speed = 500, damage = 15

### Shade Enemy
- [ ] Create `BP_Enemy_Shade` — child of `BP_EnemyBase`
- [ ] Add Teleport, VoidGlow, PhaseShift components
- [ ] Add `BPC_FearSystem` (fear aura)
- [ ] Create `AI_ShadeController` with dark-node pathfinding
- [ ] Create `BT_ShadeBehavior` — VoidHunt/Stalk branches
- [ ] Create `BB_ShadeData` — DarkNodes array, stunned state
- [ ] Set health = invulnerable, damage = 100 (one-hit)

### NPC Survivor
- [ ] Create `BP_NPC_Survivor` — child of `Character`
- [ ] Implement `I_Interactable`
- [ ] Wire dialogue choices via `BPC_DialogueChoiceSystem`
- [ ] Wire follow/hide behaviors

---

## Notes for Expansion

- Add **boss encounters**: Void Entity manifestation (multi-phase boss fight)
- Add **stealth kill mechanic**: sneak behind Patient → silent takedown (no stress penalty)
- Add **enemy variants**: "Blind Patient" (hearing-only), "Crawler" (ceiling enemy)
- Add **dynamic music**: combat music intensity scales with number of alert enemies
- Add **enemy faction system**: Patients flee from Shade, Orderlies protect Shade
- Multiplayer: server-authoritative AI, perception events replicated to all clients
- Consider **Procedural placement**: spawn points randomized each new game for replayability

---

*Enemies Index for Project Void. See [GAMEINDEX.md](GAMEINDEX.md) for full game structure. See [80_BP_EnemyBase.md](../blueprints/09-ai/80_BP_EnemyBase.md) for base enemy spec.*