# 09 — AI, Perception & Encounters Systems (Systems 80-88)

**Category Purpose:** These 9 systems form the enemy AI layer — base enemy character, patrol paths, alert state management, AI state machine, controller with behavior tree, blackboard definition, memory/last-known-location tracking, perception (sight/hearing/damage), and behavior variant selection. The `AI_BaseAgentController` runs behavior trees; all AI logic is data-driven via blackboard keys and behavior variants.

---

## System Index

| # | System | Asset Type | Role |
|---|--------|-----------|------|
| 80 | `BP_EnemyBase` | Actor (Character) | Enemy base character; health, combat, patrol, death |
| 81 | `BP_PatrolPath` | Actor | Patrol path spline; waypoints, wait times, loop |
| 82 | `BPC_AlertSystem` | Component | AI alert states: Suspicious → Alerted → Combat |
| 83 | `BPC_AIStateMachine` | Component | AI state machine: Patrol/Search/Combat/Flee |
| 84 | `AI_BaseAgentController` | Controller | Base AI controller; behavior tree runner, perception init |
| 85 | `BB_AgentBoard` | Blackboard | AI blackboard definition; all keys for enemy AI |
| 86 | `BPC_AIMemorySystem` | Component | AI memory; last known locations, threat history |
| 87 | `BPC_AIPerceptionSystem` | Component | AI perception; sight, hearing, damage sense |
| 88 | `BPC_BehaviourVariantSelector` | Component | Behavior variant selection; weighted random from dataset |

---

## AI Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                         AI PIPELINE                              │
│                                                                  │
│  AI_BaseAgentController (AIController)                           │
│    │  Runs Behavior Tree defined in BB_AgentBoard                │
│    │  Initializes perception system                              │
│    │                                                             │
│    ├─► BPC_AIPerceptionSystem (senses)                           │
│    │     Sight: vision cone, distance, light level               │
│    │     Hearing: sound events (gunshots, footsteps)             │
│    │     Damage: takes damage → knows attacker location          │
│    │     Team awareness: allies share detection                  │
│    │                                                             │
│    ├─► BPC_AIMemorySystem (memory)                               │
│    │     Last known player location                              │
│    │     Threat history (who damaged me?)                        │
│    │     Investigation points (where to search)                  │
│    │     Forgets old data after configurable time                │
│    │                                                             │
│    ├─► BPC_AlertSystem (alert level)                             │
│    │     Suspicious → (investigate) → Alerted → (engage)         │
│    │     → Combat → (player lost) → Search → (timeout) → Patrol │
│    │     Flee: low health threshold triggers retreat             │
│    │                                                             │
│    └─► BPC_AIStateMachine (behavior state)                       │
│          Patrol → Search → Combat → Flee                         │
│          State transitions driven by alert level + memory        │
│                                                                  │
│  BPC_BehaviourVariantSelector                                    │
│    │  Selects behavior variant at spawn:                         │
│    │  Attack patterns (aggressive, defensive, flanking)          │
│    │  Patrol style (predictable, random, stationary)             │
│    │  Aggression level (cautious, balanced, reckless)            │
│    └─► Weighted random from DA_BehaviourVariant dataset          │
│                                                                  │
│  BP_PatrolPath                                                   │
│    └─► Spline-based path with waypoints and wait times           │
└──────────────────────────────────────────────────────────────────┘
```

---

## 82 — BPC_AlertSystem: Alert States

**What It Does:** Manages the enemy's alert progression — how aware they are of the player's presence. Drives behavior tree transitions and audio/visual feedback.

**Alert Levels:**
- `None`: Unaware, patrolling normally
- `Suspicious`: Heard something, saw a glimpse — investigates last known location
- `Alerted`: Confirmed player presence — moves to engage
- `Combat`: Actively fighting — shooting, chasing, flanking
- `Search`: Lost sight of player — searches last known area
- `Flee`: Health critical — retreats to safety

**Escalation:** Suspicion meter fills based on perception events. Partial sight = slow fill, full sight = fast fill, loud noise = burst fill. De-escalation: meter decays over time when no stimuli.

---

## 87 — BPC_AIPerceptionSystem: AI Senses

**What It Does:** Wraps UE5's AI Perception system with game-specific logic. Handles sight (vision cone + distance + light level), hearing (sound event radius + type priority), damage sense (instant alert on hit), and team awareness (nearby allies share detection).

**Sight:** Vision cone angle, max distance, peripheral vision penalty, light level modifier (harder to see in darkness), obstruction (line of sight trace)

**Hearing:** Gunshot > footstep > door creak. Louder sounds have larger radius. Running is louder than walking. Silenced weapons have reduced radius.

**Team Awareness:** If one enemy in a group detects the player, all nearby allies are alerted to the player's approximate position.

---

## 80-88: Remaining Systems

- **80 BP_EnemyBase:** Character with health component, combat capability, patrol behavior, and death handling. Implements `I_Damageable`.
- **81 BP_PatrolPath:** Spline component with waypoints. Each waypoint has wait time, look direction, and optional animation.
- **83 BPC_AIStateMachine:** Discrete state machine: Patrol→Search→Combat→Flee. Transitions driven by blackboard values set by AlertSystem and PerceptionSystem.
- **84 AI_BaseAgentController:** Custom AIController that runs the behavior tree, initializes perception, and manages the blackboard.
- **85 BB_AgentBoard:** Blackboard Data Asset defining all keys: TargetActor, LastKnownLocation, AlertLevel, CurrentState, PatrolPath, HomeLocation, etc.
- **86 BPC_AIMemorySystem:** Stores last known player location, threat sources, investigation points. Data decays over configurable time. Behavior tree queries memory to decide search patterns.
- **88 BPC_BehaviourVariantSelector:** At spawn, selects a behavior variant from `DA_BehaviourVariant` with weighted random. Determines attack patterns, patrol style, and aggression. Creates enemy variety without separate classes.

---

## Common Implementation Patterns in This Category

1. **Behavior Tree + Blackboard:** All decision-making in behavior trees reading blackboard keys. Components write to blackboard; trees read and act.
2. **Alert Cascade:** Suspicious → Alerted → Combat → Search → Patrol. Each state has different behavior tree branches.
3. **Memory with Decay:** AI doesn't have infinite memory — last known locations are forgotten after time. Forces re-investigation.
4. **Perception Sharing:** Team awareness prevents "why didn't his friend react?" — nearby allies share detection.
5. **Behavior Variants for Variety:** Weighted random selection at spawn means enemies of the same class behave differently — no hardcoded enemy types.

---

## Multiplayer Networking

### AI is Server-Only

**All AI logic runs on the server.** Behavior trees, perception, memory, and state machines execute on the server only. Clients receive:
- **Position/Rotation/Animation:** via standard Actor replication
- **Alert level:** replicated for client awareness UI (detection meter, investigation icon)
- **Health:** replicated for client health bars
- **Perception events:** replicated for client awareness indicators only (cosmetic)

### Category Authority Map
| System | Runs On | Replicated To Clients |
|--------|---------|----------------------|
| `AI_BaseAgentController` | Server | Position, rotation, animation |
| `BP_EnemyBase` | Server | Health, state, mesh |
| `BPC_AlertSystem` | Server | Alert level enum for UI |
| `BPC_AIStateMachine` | Server | Current state for animation |
| `BPC_AIPerceptionSystem` | Server | Detection events → client awareness indicators |
| `BPC_AIMemorySystem` | Server | LastKnownLocation → client investigation UI |
| `BPC_BehaviourVariantSelector` | Server (at spawn) | Variant choice for client animation matching |
| `BP_PatrolPath` | Read-only | Spline data is static; identical on all clients |

### Client Awareness
- Clients receive perception events (enemy detected player, heard sound) as **cosmetic indicators** — red detection bar, investigation icon, audio cue.
- The actual AI behavior (investigate, engage, flee) runs on server only.
- Clients never run behavior trees — they only display the results.

---

*Developer Reference v1.0 — 09 AI Systems. Companion to docs/blueprints/09-ai/ specs.*
