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