add blueprints

2026-05-19 13:22:27 +03:00
parent f71bc678b2
commit 411edea8ce
138 changed files with 23330 additions and 0 deletions
--- a/docs/blueprints/09-ai/84_AI_BaseAgentController.md
+++ b/docs/blueprints/09-ai/84_AI_BaseAgentController.md
@@ -0,0 +1,158 @@
+# AI_BaseAgentController — AI Controller
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`AIController`
+
+### Dependencies
+- [`BP_EnemyBase`](58_BP_EnemyBase.md) — Pawn
+- [`BPC_AIPerceptionSystem`](BPC_AIPerceptionSystem.md) — Sensing
+- [`BB_AgentBoard`](BB_AgentBoard.md) — Decision-making
+- [`BPC_AIStateMachine`](61_BPC_AIStateMachine.md) — High-level states
+- [`BPC_AlertSystem`](60_BPC_AlertSystem.md) — Threat awareness
+- [`BPC_HealthSystem`](../02-player/08_BPC_HealthSystem.md) — Self health
+- [`I_Damageable`](../01-core/03_I_InterfaceLibrary.md) — Damage reception
+- `DA_AIProfile` — AI configuration
+
+### Purpose
+Central brain for enemy AI characters. Manages perception, decision-making via Behavior Trees, high-level state machine transitions, alert level propagation, and combat coordination. Possesses `BP_EnemyBase` pawns and controls their actions through Blackboard values and Behavior Tree execution.
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `AIProfile` | DA_AIProfile | Configuration asset |
+| `PossessedEnemy` | BP_EnemyBase | Current pawn reference |
+| `BlackboardComp` | UBlackboardComponent | Blackboard instance |
+| `BehaviorTreeComp` | UBehaviorTreeComponent | Behavior tree runner |
+| `PerceptionComp` | BPC_AIPerceptionSystem | Sensory input |
+| `StateMachine` | BPC_AIStateMachine | State logic |
+| `AlertSystem` | BPC_AlertSystem | Threat level |
+| `bIsActive` | Bool | Enabled / disabled |
+| `AggressionRange` | Float | Engage distance |
+| `SuspicionRange` | Float | Investigate distance |
+| `CombatRange` | Float | Preferred combat distance |
+| `HomeLocation` | FVector | Spawn or patrol anchor |
+| `LastKnownPlayerLocation` | FVector | Blackboard updated |
+| `bHasLineOfSight` | Bool | LOS status |
+| `LostPlayerTimer` | Float | Seconds since last sighting |
+
+### Blackboard Keys
+
+| Key Name | Type | Description |
+|----------|------|-------------|
+| `SelfActor` | Object | Self reference |
+| `TargetActor` | Object | Current threat |
+| `TargetLocation` | Vector | Last known threat location |
+| `HomeLocation` | Vector | Patrol anchor |
+| `AIState` | Enum (EAIState) | Current state |
+| `AlertLevel` | Float | 0.0–1.0 awareness |
+| `bHasLOS` | Bool | Line of sight |
+| `bIsInvestigating` | Bool | Searching location |
+| `PatrolIndex` | Int | Current waypoint |
+| `CombatStance` | Enum | Aggressive / Defensive |
+| `StimulusLocation` | Vector | Sound/sight trigger point |
+
+### Enums
+
+| Enum | Values | Description |
+|------|--------|-------------|
+| `EAIState` | Idle, Patrol, Suspicious, Alerted, Combat, Searching, Fleeing, Disabled | AI behavior state |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `OnPossess` | Pawn: APawn | — | Bind blackboard, run BT |
+| `OnUnPossess` | — | — | Cleanup |
+| `InitializeAI` | Profile: DA_AIProfile | — | Set up components |
+| `SetAIState` | NewState: EAIState | — | State machine transition |
+| `UpdatePerception` | Stimulus: FAIStimulus | — | Process sensory input |
+| `SetTarget` | Target: AActor | — | Update blackboard target |
+| `ClearTarget` | — | — | Target lost |
+| `StartInvestigation` | Location: FVector | — | Move to investigate |
+| `RequestReinforcements` | — | — | Alert nearby allies |
+| `GetCombatReadiness` | — | Float | Based on health, ammo, alert |
+| `OnTakeDamage` | DamageResult: FDamageResult | — | React to being hit |
+| `CanSeeTarget` | — | Bool | LOS check |
+| `LostSightOfTarget` | — | — | Start search timer |
+| `ReturnToPatrol` | — | — | Reset to patrol state |
+| `GetHomeLocation` | — | FVector | Patrol anchor |
+| `SetFocalPoint` | Location: FVector | — | Aim facing direction |
+
+### Event Dispatchers
+
+| Name | Parameters | Fired When |
+|------|-----------|-----------|
+| `OnAIStateChanged` | OldState: EAIState, NewState: EAIState | State transition |
+| `OnTargetAcquired` | Target: AActor | New threat detected |
+| `OnTargetLost` | — | Target out of range/perception |
+| `OnAlertRaised` | AlertLevel: Float | Alert threshold crossed |
+| `OnReinforcementRequested` | Location: FVector | Call for backup |
+
+### Blueprint Flow
+
+```
+[OnPossess]
+  └─► PossessedEnemy = Cast<BP_EnemyBase>(Pawn)
+  └─► AIProfile = PossessedEnemy.AIProfile (or set from spawner)
+  └─► InitializeAI(AIProfile)
+  └─► RunBehaviorTree(AIProfile.BehaviorTree)
+  └─► SetHomeLocation(Pawn.GetActorLocation)
+
+[InitializeAI]
+  └─► Create BPC_AIPerceptionSystem if not exists
+  └─► Create BPC_AIStateMachine
+  └─► Create BPC_AlertSystem
+  └─► PerceptionComp.Initialize(AIProfile.PerceptionConfig)
+  └─► StateMachine.Initialize(EAIState.Patrol)
+  └─► AlertSystem.Initialize()
+  └─► Set AIState = Patrol in Blackboard
+
+[UpdatePerception — called by PerceptionComp dispatcher]
+  └─► If Stimulus.Type == Sight && Stimulus.bSuccess:
+         LastKnownPlayerLocation = Stimulus.StimulusLocation
+         AlertSystem.RaiseAlert(SightAlertValue)
+         If AlertSystem.AlertLevel >= AIProfile.CombatThreshold:
+             SetTarget(Stimulus.Instigator)
+             SetAIState(Combat)
+         Else:
+             SetAIState(Suspicious)
+  └─► If Stimulus.Type == Hearing && Stimulus.bSuccess:
+         AlertSystem.RaiseAlert(HearingAlertValue)
+         StartInvestigation(Stimulus.StimulusLocation)
+         SetAIState(Searching)
+  └─► If Stimulus.Type == Damage:
+         SetTarget(Stimulus.Instigator)
+         AlertSystem.RaiseAlert(DamageAlertValue)
+         SetAIState(Combat)
+         RequestReinforcements()
+
+[OnTakeDamage]
+  └─► AlertSystem.RaiseAlert(MaxAlertValue)
+  └─► SetTarget(DamageResult.Instigator)
+  └─► SetAIState(Combat)
+```
+
+### Communications With
+
+| Target | Method | Why |
+|--------|--------|-----|
+| [`BP_EnemyBase`](58_BP_EnemyBase.md) | Possessed pawn | Movement, animation, abilities |
+| [`BPC_AIPerceptionSystem`](BPC_AIPerceptionSystem.md) | Get Component | Sensory stimulus processing |
+| [`BB_AgentBoard`](BB_AgentBoard.md) | Get Component | Blackboard updates |
+| [`BPC_AIStateMachine`](61_BPC_AIStateMachine.md) | Get Component | State transitions |
+| [`BPC_AlertSystem`](60_BPC_AlertSystem.md) | Get Component | Threat level queries |
+| [`BPC_HealthSystem`](../02-player/08_BPC_HealthSystem.md) | Get on Pawn | Health events |
+| Nearby AI Controllers | Direct / Event | Reinforcement calls |
+
+### Reuse Notes
+- Designed as parent for all enemy types (humanoid, creature, drone)
+- Perception, alerts, and state machine are swappable components
+- Behavior tree is data-driven via AIProfile
+- All decision values (ranges, thresholds, speeds) come from data asset
+- Renamed from `BPC_AIControllerBase` to `AI_BaseAgentController` per Master naming convention.
+- Cross-references updated: `BPC_PerceptionComponent` → `BPC_AIPerceptionSystem`, `BPC_BehaviorTreeManager` → `BB_AgentBoard`, `BPC_HealthComponent` → `BPC_HealthSystem`.