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 above hybrid movement range
  • 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

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 if you want to handle the drop manually (e.g. from a death montage AnimNotify).
Ragdoll can be enabled in the OnDeath delegate or K2_OnDeath Blueprint event on your controller — all combat systems are already shut down at that point, 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