diff --git a/AI%2C-Perception-%26-Encounters-Systems.md b/AI%2C-Perception-%26-Encounters-Systems.md new file mode 100644 index 0000000..617771b --- /dev/null +++ b/AI%2C-Perception-%26-Encounters-Systems.md @@ -0,0 +1,118 @@ +# 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. + +--- + +*Developer Reference v1.0 — 09 AI Systems. Companion to docs/blueprints/09-ai/ specs.*