Performance

Documentation Unreal Engine AI Performance

Cost model, profiling with stat SEC, and tuning knobs for large enemy counts.

MovementEvaluatorComponent direction sampling dominates SEC CPU time. Role assignment, action polling, awareness, and avoidance run on timers or only while a feature is active.

Cost Model

The slider below shows linear scaling from illustrative per-enemy costs (~0.0035 ms movement, ~0.0004 ms threat). It is a planning aid, not a profile of your map. Run stat SEC in PIE to read real numbers on your hardware.

Output Log

Active SEC enemies20 enemies

1 duel50 horde150 stress

Illustrative scaling — run stat SEC in your level for real numbers

MovementEvaluator - Total

0.070 ms

MovementEvaluator - Direction Scoring

0.063 ms

MovementEvaluator - Avoidance

0.004 ms

RoleSubsystem - Role Distribution

0.001 ms

ThreatDetection - Tick

0.008 ms

Estimated SEC overhead

0.083 ms

Share of 60 fps frame budget (16.6 ms)0.50%

Low share at this count

At 60 fps you have 16.6 ms per frame. Even at 150 active SEC enemies, this model lands near 4% of frame budget for the plugin slice alone (animation, rendering, and game logic sit on top).

What Runs When

System	Cadence	Cost driver
Movement evaluator	Every tick while `EvaluateAndMove` / AI Movement runs	`NumSamples` direction loop (default 16)
Avoidance	Overlap refresh at 10 Hz (`0.1 s`)	`bEnableAvoidance`, radius
Nav sampling	Cache refresh at `NavCheckInterval` (default 0.1 s), staggered by `NavStaggerStride`	`bEnableNavAwareSampling`, probe count
Detour queries	On detour recheck interval while hybrid movement is active	Nav path length vs straight line
Action evaluation	`EvaluationCooldown` (default 0.1 s on native brain / Poll Action)	Scorer count per action
Action execution tick	Only while an action runs and a hook sets `bWantsTick`	Custom hook work
Role subsystem	`RoleReassignmentInterval` (project default 8 s)	Combatant × role candidate count
Threat detection	Every tick by default; throttle with `SetTickInterval`	Dot product on focus actor
Awareness	`EvaluationInterval` on config (default 0.1 s)	Perceived actor count
Melee trace	Tick only between `StartTracing` and `StopTracing`	Active socket count

Tuning for Scale

Details

Movement Evaluator Component (MovementEvaluatorComponent)

Movement Evaluator

Num Samples

Enable Avoidance

Enable Nav Aware Sampling

Nav Sampling

Nav Check Interval

0.1

Num Samples scales the direction-scoring loop. Avoidance and nav sampling both refresh at 10 Hz by default.

Num Samples: Range 4–32. Halving samples roughly halves direction-scoring work. Start at 8 for horde crowds if strafing still looks acceptable.

bEnableAvoidance: Turn off when enemies never pack tightly (solo bosses, sparse open fields).

bEnableNavAwareSampling: Turn off only when you accept ledge/hazard blind spots. Keeps NavCheckInterval and NavStaggerStride from doing nav probes.

Hybrid movement: Distant enemies pathfind; close enemies use tactical sampling. HybridSwitchDistance (default 800 cm) controls the handoff. See Movement System.

Project-wide timers

Role and target timing live in Project Settings → Soulslike Enemy Combat → Combat Roles → Timing:

Timing

Role Reassignment Interval

Min Time In Role

Re-evaluate Targets On Reassignment

Role Reassignment Interval: How often UAICombatRoleSubsystem re-runs global assignment. Default 8 s. Set 0 to drive reassignment manually.

Native brain / Poll Action: EvaluationCooldown on USECBrainComponent or STTask_PollAction (default 0.1 s) spaces action picks. Raise it for background grunts that do not need 10 Hz decisions.

Threat: Call SetTickInterval on UThreatDetectionComponent to skip frames when you only need coarse player-look reactions.

Built-in Profiling

Open the console (~) and run:

stat SEC

Registered cycle stats (from STATGROUP_SEC):

Stat	Scope
MovementEvaluator - Total	Full per-AI movement pass
MovementEvaluator - Direction Scoring	Sample loop over `NumSamples`
MovementEvaluator - Avoidance	Throttled overlap scoring
MovementEvaluator - Nav Sampling	Nav validity cache refresh
MovementEvaluator - Detour Query	Path-length detour check
RoleSubsystem - Role Distribution	Global role assignment pass
ThreatDetection - Tick	Per-tick threat level

Unreal Insights: filter CPU trace events SEC_MovementEvaluator, SEC_DirectionScoring, SEC_Avoidance, SEC_NavSampling, SEC_DetourQuery, SEC_RoleDistribution, SEC_ThreatDetection.

For log-based diagnosis, see Debugging & Troubleshooting.

Optimizations Already in Code

Unit-circle sample cache: trigonometry for direction samples is precomputed when NumSamples changes.
Throttled avoidance: overlap queries run at 10 Hz, not every frame.
Throttled nav cache: NavCheckInterval plus NavStaggerStride spread nav sweeps across frames in a pack.
Timer-based roles: reassignment runs on RoleReassignmentInterval, not per frame.
Hybrid movement: strategic pathfinding only past HybridSwitchDistance (or while detour escalation is active).
Conditional melee tick: USECMeleeTraceComponent starts with tick disabled; tracing enables tick only for active swings.
Conditional action tick: ActionEvaluationComponent ticks only during action execution (hook dispatch), not while idle.

Scaling Guide

Rough totals from the cost model above (movement + threat + small avoidance/role share). Measure your encounter in PIE before shipping horde modes.

Scenario	Active SEC enemies	Estimated plugin CPU
Soulslike duel	1–5	< 0.02 ms
Action RPG pack	10–20	~0.05–0.1 ms
Horde	50–100	~0.2–0.4 ms
Stress test	150+	~0.6 ms+

Cost scales roughly linearly with enemies that run movement + threat every frame. Idle or off-mesh actors cost less.