API Reference

Documentation Unreal Engine AI Reference

Controller-side C++ and Blueprint API: SECCombatControllerComponent, EnemyControllerBase, SECBrainComponent, and BotStateTreeAIComponent.

The controller-side classes and their public members. For building an enemy, start with Getting Started; this page is the reference you reach for when extending the system in Blueprint or C++.

SECCombatControllerComponent

The hub every setup needs. Add it to any AAIController and the combat system works. It resolves the AI config, registers combat roles, syncs role-based state, and orchestrates death.

To read the config or role from outside the component, call the static helpers instead of casting to AEnemyControllerBase. They work on any controller carrying the component.

Static helpers

Function	Returns
`ResolveAIConfig(Controller)`	The controller's cached config, or the pawn's config via `IEnemyAIConfigProvider`, or null
`ResolveCurrentCombatRole(Controller)`	The current combat role tag, or an empty tag

Instance accessors

Function	Returns
`GetCachedAIConfig()`	The resolved `UEnemyAIConfig` in use
`GetCurrentCombatRole()`	The current combat role tag

Overridable hooks (BlueprintNativeEvent, call the parent to keep default behavior)

Function	Purpose
`SyncStateForCombatRole(RoleTag)`	Runs when the role changes. Override to swap animation sets, trigger effects, or switch StateTree assets. Call Super to keep the action set, reaction set, weapon set and movement profile sync.
`HandleCombatTargetLost(LostTarget)`	Runs when the target is destroyed or unregistered. Override for fallback behavior (patrol, switch aggro). The default broadcasts `OnCombatTargetLost`.

Blueprint-callable

Function	Purpose
`ApplyLocalCombatRole(RoleTag)`	Adopt a role locally without registering with the subsystem. Syncs the action set and movement profile like a subsystem-assigned role, but consumes no slots and joins no coordination. For bosses and solo enemies.
`HandleDeath()`	Full SEC shutdown, idempotent. Cancels the in-flight action and reaction, stops the brain, stops melee tracing, disables threat detection, unregisters from the role subsystem, clears focus, then broadcasts `OnDeath`. Does not unpossess or destroy the pawn.
`HandleRevive()`	Brings a dead enemy back under AI control: releases the action block death took, restarts the brain, and turns threat detection, perception and role registration back on, then broadcasts `OnRevive`. Call it on a revive or when a pooled enemy is reused. A controller that died stays blocked from acting until it runs. The weapon death unequipped is not re-equipped, and perception returns only when the AI Config manages it.

Properties

Property	Default	Purpose
`DefaultAIConfig`	null	Fallback config when the pawn provides none via `IEnemyAIConfigProvider`
`bAutoRegisterForCombatRoles`	true	Register with the combat role subsystem on possession
`RoleRegistrationParams`	n/a	Registration parameters used when the pawn has no config
`bEnableThreatDetection`	true	Enable threat detection on BeginPlay when a `ThreatDetectionComponent` is present
`bAutoHandleDeathOnHealthDepleted`	true	Call `HandleDeath()` automatically when the pawn's health vital empties
`bDropWeaponOnDeath`	true	Ask the weapon to drop itself on death, with a suggested 10-second lifespan. The weapon's `On Unequipped` event turns on the physics

Delegates

Delegate	Fires
`OnCombatRoleChanged(NewRole, OldRole)`	When the role changes, from subsystem assignment or local apply
`OnCombatTargetLost(LostTarget)`	When the target is destroyed or unregistered
`OnCombatRoleSystemReady(Controller)`	After registration with the role subsystem. Safe to read the initial role here
`OnDeath()`	At the end of `HandleDeath()`, once every system is stopped. Safe to ragdoll, spawn VFX, or destroy
`OnRevive()`	At the end of `HandleRevive()`, once every system is running again

EnemyControllerBase

The convenience controller. It creates every combat component as a default subobject and adds facing and rotation behavior on top of SECCombatControllerComponent.

Rotation lock (freezes facing during a committed attack)

Function	Purpose
`LockRotationBy(LockOwner)`	Hold a rotation lock keyed to an owner. Releases when the owner is destroyed, or when an `InstancedPerActor` ability goes inactive. Defaults to the caller.
`UnlockRotationBy(LockOwner)`	Release that owner's lock
`LockRotation()` / `UnlockRotation()`	Keyless counter-based lock; balance each call
`ForceUnlockRotation()`	Clear both the counter and the owner set
`IsRotationLocked()`	True while any lock holds

UGameplayAbilityBase locks rotation through this API when bLockAIRotation is set, so montage-driven attacks commit without extra wiring.

Facing

Member	Default	Purpose
`GetDesiredFacingLocation(OutLocation)`	n/a	`BlueprintNativeEvent` returning the world location to face. Override for custom facing
`SmoothFocusInterpSpeed`	165.0	Interpolation speed for smooth focus rotation
`bFaceLastKnownWhenNotDetected`	true	Track the live target only while Detected; otherwise face its last-known location instead of through walls

Team

Member	Purpose
`USECTeamComponent`	Holds the team on the possessed pawn: `TeamId` (0 = player, 1 = enemy, 255 = neutral), Free-For-All, and the exclusion rules
`IGenericTeamAgentInterface`	Answers AI Perception and EQS by reading that component

Blueprint events (forwarded from the combat component)

Event	Fires
`K2_OnCombatRoleAssigned(NewRole, OldRole)`	On role assignment
`K2_OnCombatTargetLost(LostTarget)`	When the target is lost
`K2_OnReactionSetApplied(RoleTag, ReactionSet)`	When a reaction set is applied via role sync
`K2_OnDeath()`	After `HandleDeath()` completes; safe to ragdoll or play a death montage

HandleDeath() on the controller is a convenience wrapper around the component's HandleDeath(). Component accessors: GetCombatControllerComponent, GetHelperBTComponent, GetReactionEvaluationComponent, GetAwarenessComponent. Delegates: OnFocusSet, OnFocusCleared (fires only when there was a focus to clear), OnActionStateChanged.

SECBrainComponent

Chooses how the AI runs from its config: a StateTree when one is named, otherwise a native C++ combat loop.

Member	Default	Purpose
`RefreshBrain()`	n/a	Re-evaluate the config and switch brains if the StateTree choice changed. Call after changing the config at runtime without re-possessing
`IsRunningNativeBrain()`	n/a	True while the native loop drives the AI
`EvaluationCooldown`	0.1	Seconds between action evaluations in the native loop

In native mode the component holds the controller's brain slot, so HandleDeath stops it and the per-action behavior-tree swap restores it.

BotStateTreeAIComponent

Extends Unreal's UStateTreeAIComponent. SECBrainComponent creates it at runtime when the config names a StateTree. It resolves the config on possession in this order:

The controller's SECCombatControllerComponent cached config
A pawn implementing IEnemyAIConfigProvider
The FallbackStateTree on this component

Member	Default	Purpose
`InitializeFromAIConfig(AIConfig)`	n/a	Set and start the config's `StateTree`. Returns true on success
`AddLinkedStateTreeOverride(StateTag, StateTreeReference)`	n/a	Swap a sub-tree per gameplay tag, for enemy variants
`bAutoInitializeFromConfig`	true	Initialize from the config automatically on possession. Disable for manual control
`FallbackStateTree`	null	Used when no config is found or the config names no StateTree