UE5-Modular-Game-Framework/docs/developer/09-ai-systems.md

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.