158 lines
6.8 KiB
Markdown
158 lines
6.8 KiB
Markdown
# 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`. |