# 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.*