Debugging & Troubleshooting

Documentation Unreal Engine AI FAQ

Debug logging, visual debugging, FAQs, and common issue solutions.

Enable Debug Logging

In AI Controller Blueprint:

ActionEvaluation → bDebugLog: true
MovementEvaluator → bDebugLog: true
ThreatDetection → bDebugLog: true
Output Log Messages:
LogEvaluation: Evaluating 3 actions...
LogEvaluation: [LightAttack] Dist:180 Angle:15 Score:0.95 SELECTED
LogEvaluation: [HeavyAttack] Dist:180 Angle:15 Score:0.60 (cooldown:1.2s)

Visual Debugging

Console Commands:
// Show debug for entire SEC system
Evaluator.Debug.DrawAvoidance 0-1
Evaluator.Debug.DrawScoring 0-1
Evaluator.Debug.LogAvoidance 0-1
Evaluator.Debug.LogMovement 0-1
Evaluator.Debug.LogScoring 0-1
Evaluator.Debug.LogStrafeState 0-1
Evaluator.Debug.LogStrafeSwap 0-1
 
Melee.Debug.DrawTracing 0-1

Common Issues

Logs handle most issues. For specific cases:

AI doesn't attack

Possible Causes:
  • Ability not granted to ASC and ExecuteAbility is not marked with GrantAbilityIfMissing.
  • AbilityTag mismatch, update ability tags on the DataAssets if you changed them somewhere else.
  • Action on cooldown, check your cooldowns and cooldown randomization
  • No valid actions in ActionSet
  • Custom character class missing IAbilitySystemInterface - if your pawn doesn't implement this interface, ActionEvaluationComponent cannot find the ASC and all ability-based actions will silently fail.
  • ByEvent mode: Ability missing Trigger entry - when using ActivationMode = ByEvent, the ability class must have a Trigger entry in its class defaults with the matching tag and source set to Gameplay Event. Without it, HandleGameplayEvent fires but no ability reacts.
Solutions:
  • Check ASC grants ability with correct tag
  • Verify ActionSet AbilityTag matches ability's tags
  • Enable bDebugLog to see why action isn't selected
  • Check distance/angle ranges in ActionSet
  • If using a custom character class, ensure it implements IAbilitySystemInterface and returns a valid UAbilitySystemComponent from GetAbilitySystemComponent(). See the Getting Started guide for details.
  • For ByEvent abilities, open the ability class defaults, go to Triggers, add an entry with your event tag and set Trigger Source to Gameplay Event.

ByEvent activation silently falls back to ByTag (BehaviorTree mode)

Cause: The SEC_ActivationMode key is missing from your Blackboard Data Asset. When the Action System writes "ByEvent" to this key and the key does not exist in the asset, the write is silently ignored. The BT task reads an empty value and falls back to ByTag.
Solution: Open your Blackboard Data Asset and add a Name key called SEC_ActivationMode. Also verify that all other SEC_ keys exist: SEC_ActionId (Name), SEC_AbilityTag (String), SEC_AbilityEndTag (String), SEC_TargetActor (Object), SEC_SelfActor (Object), SEC_Distance (Float).

AI gets stuck after attacking

Cause: End event not sent
Solution:
  • Verify that you are using GameplayAbilityBase, it is necessary for end ability to be detected by SEC components.
  • Check ability sends event on completion, cancellation, AND interruption
  • Look for "Waiting for action to complete..." in log (means no end event received)

Weapon doesn't deal damage

Possible Causes:
  • Socket ID mismatch
  • Trace channel not configured
  • Damage config not set
  • No MeleeTraceComponent on character
Solutions:
  • Verify notify state Socket IDs match weapon TraceSockets IDs exactly
  • Check trace channel, debug and see if it actually hits
  • Assign DamageConfig to weapon
  • Ensure character has USECMeleeTraceComponent (inherited from base)

AI doesn't move

Possible Causes:
  • Movement task not ticking
  • NavMesh not present (tactical sampling reads it below the hybrid range, strategic pathfinding above it)
  • DirectControlThreshold too high/low
Solutions:
  • Verify STTask_AIMovement is in root state with [Tick]
  • Press P in viewport to show NavMesh
  • Adjust DirectControlThreshold (try 500-700)
  • Enable MovementEvaluator debug logging

AI walks off ledges or into hazards

Possible Causes:
  • No NavMesh over the combat area, so navmesh-aware sampling stays inert
  • NavMesh extends past the visual edge, so the AI reads the drop as walkable
  • bEnableNavAwareSampling disabled, or NavScoreWeight set to 0
  • Hazard painted as a high-cost area with no Hazard Areas entry (cost alone does not stop close-range strafing)
Solutions:
  • Press P in viewport and confirm the NavMesh stops before the ledge
  • Enable SEC.Debug.Movement.DrawNav 1 (blue spheres mark blocked directions)
  • Lower NavProbeDistance (~60) in tight spaces; raise it for fast enemies
  • For a hazard the AI should still cross, mark a Nav Modifier Volume with a NavArea subclass and add it to the component's Hazard Areas (see Movement System)

AI grinds against a wall instead of going around it

The target slipped behind a wall or around a corner. The AI sits close to it in a straight line but a long walk away on the navmesh, so it strafes into the wall trying to reach a target it cannot orbit to.
Possible Causes:
  • bEnableDetourEscalation disabled on the movement component
  • No NavMesh over the area, so there is no route to measure
  • The target is just past a tight corner, so the route is barely longer than the straight line and the ratio test can't see it. This is the reactive (stall) case: if bDetourEscalateOnStall is off or DetourStallSpeed is too low, the grind isn't caught
  • DetourEnterRatio or DetourMinExcess set too high, so a longer detour reads as minor
  • The target has no complete path (walled off, or on a separate navmesh island), so the AI stays tactical rather than walking to a dead end
Solutions:
  • Confirm bEnableDetourEscalation is on (movement component, Hybrid Movement > Detour)
  • Press P in viewport and confirm a NavMesh routes around the obstacle
  • For a tight corner: keep bDetourEscalateOnStall on and raise DetourStallSpeed so a slow grind counts as stalled
  • For a longer detour: lower DetourEnterRatio (try 1.4) or DetourMinExcess
  • Enable SEC.Debug.Movement.LogMovement 1 and watch for Detour escalation ENGAGED / CLEARED (it notes (stalled at cover) when the tight-corner path fired)
  • See Detour Escalation for the full tuning guide

FAQ

Can I use this with my existing character?

Yes. Add SECCombatControllerComponent to your AI controller and the necessary pawn components to your character. Create an ActionSet, configure an AIConfig, and set up a StateTree. The plugin integrates with existing projects without requiring inheritance from EnemyControllerBase or EnemyCharacterBase.

Does this work with multiplayer?

Yes. The plugin supports both listen server and dedicated server configurations. AI logic runs on the server, and key state (health, action execution, combat roles, active ActionSet) replicates to clients. See the Multiplayer docs for details.

Can I use this without Gameplay Ability System?

The melee trace system works standalone, but action execution relies on GAS. A non-GAS path works with Behavior Tree execution only. GAS unlocks ability blocking, tagging, and cooldown integration, so it is worth exploring if you haven't already.

What Unreal Engine versions are supported?

UE 5.6+. StateTree APIs have breaking changes between versions, so older versions are not compatible.

Can I make bosses with this?

Yes. The system scales well. Use ActionSets with phase-specific actions, swap sets at health thresholds, and combine with custom Behavior Tree sequences for scripted attacks.

How do I make ranged enemies?

There is already an example for Supporter role. Study the Supporter role example and adapt the ranged ability to your needs.

Is source code included?

Yes. Full C++ source is included under MIT license.

How do I handle death (ragdoll, weapon drop, dissolve)?

Call HandleDeath() on the SECCombatControllerComponent when the AI should die. This shuts down all SEC combat systems in the correct order and broadcasts the OnDeath delegate.
Weapon drop is automatic: HandleDeath unequips the weapon with bSimulatePhysics = true in the unequip context. Override K2_OnUnequipped on your weapon Blueprint to enable physics on the mesh and apply an impulse. Set bDropWeaponOnDeath to false on the combat controller to handle the drop manually (e.g. from a death montage AnimNotify).
Ragdoll: enable it in the OnDeath delegate or the K2_OnDeath Blueprint event on your controller. By then all combat systems are shut down, so it's safe to call SetSimulatePhysics on the character mesh.
Dissolve/destroy: use SetLifeSpan or a timer in your K2_OnDeath handler to delay actor destruction, giving time for a material dissolve effect.

Support & Resources

Purchase: Fab Marketplace
Support: Contact through Discord, Fab Marketplace or via email
Updates: Plugin updates delivered through Fab Marketplace
Feature Requests: Contact via Discord, Fab Marketplace, or via email