Core Architecture

Documentation Unreal Engine AI Architecture

Understanding the StateTree + Behavior Tree hybrid architecture.

The StateTree + Behavior Tree Hybrid

The plugin separates strategic thinking from tactical execution. This avoids the common pitfall of a single massive Behavior Tree that mixes strategy and execution logic.

StateTree (The Brain) handles high-level decisions. Actions (The Hands) handle tactical execution. The two layers communicate through components, never directly.

StateTree: Strategic Layer

Evaluates combat context
Scores available actions
Manages state transitions
Controls movement strategy
Handles target acquisition

Action Execution: Tactical Layer

Option A: Gameplay Ability (simple: play montage, apply damage)
Option B: Behavior Tree Sequence (complex: multi-step, branching)

The StateTree drives decisions. Actions are executed through Gameplay Abilities or Behavior Tree sequences.

When to use each execution mode: Use Gameplay Abilities for straightforward attacks (play montage, apply damage). Use Behavior Tree sequences for complex multi-step actions that need conditional branches (charge attack, check stamina, branch to heavy or light version).

Controller Architecture

The plugin supports two controller setups:

Option A: EnemyControllerBase (Quick Start)

A pre-configured AI controller that creates all common SEC components as default subobjects. Best for getting started quickly.

AEnemyControllerBase (convenience wrapper)
├── SECCombatControllerComponent   ← handles AIConfig, combat roles, sync
├── MovementEvaluatorComponent     ← tactical positioning
├── ActionEvaluationComponent      ← action scoring and execution
├── ReactionEvaluationComponent    ← event-driven reaction selection
├── ThreatDetectionComponent       ← player attention tracking
├── BotStateTreeAIComponent        ← StateTree runner
└── BehaviorTreeComponent (helper) ← for action BT sequences

On top of the component setup, EnemyControllerBase also provides:

Smooth focus rotation with interpolation (SmoothFocusInterpSpeed)
Rotation lock for committed attacks (LockRotation, UnlockRotation, ForceUnlockRotation)
Team ID via ISECTeamInterface and Unreal's IGenericTeamAgentInterface (integrates with AI Perception and EQS)
K2 Blueprint events forwarded from the combat component (OnCombatRoleAssigned, OnCombatTargetLost)

Option B: Custom AAIController + SECCombatControllerComponent

Add SECCombatControllerComponent to any AAIController Blueprint. This is the minimal path for integrating with existing controllers.

YourCustomAIController
├── SECCombatControllerComponent   ← add this
├── (your own components)
└── (pick which SEC components you need)

When to use which: Use EnemyControllerBase for new projects where you want everything pre-wired. Use a custom controller + component when integrating into an existing project or when you need a different controller hierarchy.

SECCombatControllerComponent

This is the single source of truth for all combat system integration. It handles:

AIConfig resolution (from pawn via IEnemyAIConfigProvider, or from its own DefaultAIConfig)
Combat role registration and unregistration with AICombatRoleSubsystem
Role-based sync of action sets, reaction sets, and movement profiles
Action and reaction execution state delegation to pawn components for replication
Threat-to-movement auto-wiring (if both ThreatDetectionComponent and MovementEvaluatorComponent are present on the same controller)

All SEC subsystems and StateTree tasks communicate through this component. If an AI controller has it, the full combat system works.

Overridable Hooks (BlueprintNativeEvent):

You can subclass SECCombatControllerComponent in Blueprint and override these functions:

Function	Purpose
`SyncStateForCombatRole`	Called when role changes. Override to add custom sync logic (animation sets, VFX, StateTree swaps). Call parent to keep default action set and movement profile sync.
`HandleCombatTargetLost`	Called when combat target is destroyed or unregistered. Override to add custom fallback behavior (patrol, aggro switch).

Blueprint-Callable API:

Function	Purpose
`ApplyLocalCombatRole`	Adopt a combat role locally without subsystem registration. Syncs ActionSet and MovementProfile exactly like a subsystem-assigned role, but does not consume slots or participate in coordination. Designed for boss AI or solo enemies.

Delegates:

Delegate	When
`OnCombatRoleChanged`	Fires when the combat role changes (from subsystem assignment or local apply). Provides new and old role tags.
`OnCombatTargetLost`	Fires when the combat target is destroyed or unregistered.
`OnCombatRoleSystemReady`	Fires after successful registration with `AICombatRoleSubsystem`. Safe to call `ForceAssignRole` or read the initial role in this handler.

BotStateTreeAIComponent

This component extends Unreal's UStateTreeAIComponent and adds automatic StateTree initialization on possession.

How initialization works:

Controller possesses a pawn
Component resolves AIConfig (via SECCombatControllerComponent if present, or fallback)
Loads the StateTree from AIConfig.DefaultStateTree
Falls back to FallbackStateTree if no AIConfig or no StateTree is set

Property	Purpose
`bAutoInitializeFromConfig`	If true (default), automatically loads StateTree from AIConfig on possession. Disable for manual control.
`FallbackStateTree`	StateTree to use when no AIConfig is available. Useful for custom controller setups that do not use `EnemyAIConfig`.

Function	Purpose
`InitializeFromAIConfig`	Manually initialize StateTree from an AIConfig asset. Call this if `bAutoInitializeFromConfig` is disabled.
`AddLinkedStateTreeOverride`	Add a linked StateTree override for a specific gameplay tag. Useful for swapping sub-trees per enemy variant.

All controller-side components (SECCombatControllerComponent, BotStateTreeAIComponent, ActionEvaluationComponent, MovementEvaluatorComponent, ThreatDetectionComponent) follow the same lifecycle pattern:

OnRegister - Subscribe to AAIController::OnPossessedPawnChanged. If the controller already has a pawn, handle it immediately.
OnPossessedPawnChanged callback - Cache pawn reference, resolve ASC (if needed), initialize actions/state for the new pawn.
OnUnregister - Unsubscribe from OnPossessedPawnChanged.

This convention ensures components work correctly regardless of when the controller possesses the pawn relative to BeginPlay. It also handles re-possession (pawn swaps) cleanly.

Why not BeginPlay? Controller components' BeginPlay can fire before the controller possesses a pawn. Using OnRegister + the possession delegate guarantees the pawn is available when the component initializes.

StateTree drives the AI behavior loop using BotStateTreeAIComponent
ActionEvaluationComponent gathers context: distance, angle, health, threat, tags
ActionSet scores all available actions using:
- Distance and angle evaluations (FRangeEval)
- Health-based modifiers
- Cooldown status
- Context tags (player blocking, low health, etc.)
- Novelty decay (anti-repetition)
Best action selected and executed as:
- Gameplay Ability (via AbilitySystemComponent), or
- Behavior Tree sequence (via the helper BT component)
MovementEvaluatorComponent evaluates directions simultaneously:
- Scores each for distance, angle, avoidance
- Blends pathfinding with direct input
- Applies strafing, retreat, or approach behavior

Scope

What the plugin provides:

Enemy AI decision-making and tactical movement
Melee combat hit detection (can also be used for player characters)
Action scoring and execution framework
Event-driven reaction evaluation and execution
Pawn-side resolution components (SECActionSetComponent, SECReactionSetComponent) with full replication
Multi-enemy coordination with role-based behavior
Multiplayer support (listen server and dedicated server)
Modular component system: mix and match for different enemy types
Data-driven configuration with full Blueprint support
Working showcase enemy to study and extend

What you still need:

UI/HUD (health bars, lock-on indicators, damage numbers)
Level design and encounter placement
Progression and difficulty balancing