Skip to content

Gameplay Debugger and AI Debugger for Blueprint Beginners

The apostrophe AI overlay is not just "more debug text." It is a live view of the selected pawn/controller, NavMesh, Behavior Tree, Blackboard, EQS, and AI Perception data, so use it before rewriting working logic by guesswork.

At a glance

Use this for: live AI, Behavior Tree, Blackboard, perception, NavMesh, and EQS inspection during PIE - Main key: apostrophe (') opens the debugger; Numpad 0-4 toggle default categories - Beginner rule: select the actor you are debugging and read pawn/controller/tree/key data before changing logic - Official docs: Using the Gameplay Debugger and AI Debugging

The one-minute version

  • In beginner AI work, the "AI Debugger" is the Gameplay Debugger's AI-focused overlay and categories.
  • Press apostrophe (') during play to open it. Use the Numpad keys to toggle the default categories.
  • You must debug the right actor. Point at or select the AI pawn you care about, then verify the overlay is showing that pawn and controller.
  • Numpad 0 shows NavMesh. Use it when Move To fails or an AI is off the walkable area.
  • Numpad 1 shows general AI data: controller, pawn, path following, movement mode, running behavior, active task, and related live facts.
  • Numpad 2 shows Behavior Tree and Blackboard data. Use it before editing decorators, services, or task flow.
  • Numpad 3 shows EQS data when an Environment Query is running.
  • Numpad 4 shows AI Perception data such as active senses, stimuli, and last known locations.
  • Blueprint-only projects usually use the built-in categories as-is. Custom Gameplay Debugger categories are a C++ extension topic.

What tool this is

The Gameplay Debugger is a runtime overlay. It shows live data in the game viewport while Play In Editor, Simulate In Editor, or a standalone session is running.

For AI beginners, it answers questions like:

Which pawn am I looking at?
Which AIController owns it?
Is a Behavior Tree running?
Which task is active?
What does the Blackboard say TargetActor is?
Is there NavMesh under this pawn?
Did AI Perception remember the player?
Is an EQS query currently running?

Those are the questions that usually decide whether a patrol/chase/attack bug is possession, navigation, perception, blackboard data, tree logic, or the attack function itself.

Opening and selecting

Basic flow:

1. Start PIE with the enemy visible.
2. Press apostrophe (`'`) to open the debugger.
3. Aim at or select the AI actor you want to inspect.
4. Confirm the overlay names the expected pawn and controller.
5. Toggle categories with Numpad keys.

If the overlay is empty or confusing, do not edit the Behavior Tree yet. First prove the selected actor is the one that is actually broken.

Useful selection checks:

  • the pawn name matches the enemy in the level;
  • the controller name is your AIController class;
  • the Behavior Tree name is the asset you expected;
  • the Blackboard keys belong to this specific AI instance;
  • the PIE window is the server/client you meant to inspect.

When several enemies use the same Blueprint, wrong selection can look exactly like wrong logic.

Default AI categories

The default AI-focused categories are enough for most first-project debugging:

Key Category Use when
Numpad 0 NavMesh AI cannot move, path fails, or the pawn/goal might be off the navigation area.
Numpad 1 AI / Basic You need controller, pawn, movement/path-following, active task, montage, or behavior summary.
Numpad 2 Behavior Tree / Blackboard A branch, decorator, service, task, or key value is suspicious.
Numpad 3 EQS A running query is choosing a bad location or no location.
Numpad 4 Perception Sight/hearing/stimuli data does not match what the enemy appears to know.

Turn on only the categories you need. The overlay can become unreadable if every category is visible at once.

Use NavMesh first when movement is the symptom:

AI Move To failed
Behavior Tree Move To stuck
enemy stands still
patrol point looks valid but task fails

Read it this way:

Is there green navigation under the pawn?
Is there navigation under or near the target location?
Is a wall, gap, ramp, nav modifier, or missing volume blocking the path?
Is the pawn trying to reach a point outside the generated area?

If there is no navigation, the Behavior Tree is not the first bug. Fix the NavMesh, pawn movement setup, or destination before changing decorators.

AI / Basic category

Use the Basic/AI category to prove the brain/body relationship:

Pawn:
    correct enemy class?

Controller:
    correct AIController class?

Path following:
    idle, moving, failed, or blocked?

Movement mode:
    walking, falling, nav walking, or disabled?

Behavior:
    correct Behavior Tree running?

Active task:
    Move To, Wait, Attack, or a custom task?

This catches simple setup failures:

AI pawn exists but controller is None
wrong AIController class assigned
behavior tree never started
movement mode is disabled/falling
path following has no active request
custom attack montage is active when movement should resume

Do not skip this category because it looks less interesting than the Behavior Tree display. It often proves the first broken link.

Behavior Tree and Blackboard category

This category is the main reason beginners should learn the debugger.

It shows:

  • which Behavior Tree asset is running;
  • which branch and task are currently active;
  • Blackboard key names and current values;
  • whether the tree sees the facts your Blueprint thinks it set.

Use it like this:

Symptom:
    enemy sees player but keeps patrolling

Check:
    Is TargetActor set in the Blackboard?
    Is Chase branch higher priority than Patrol?
    Is the chase decorator reading TargetActor, or a different key?
    Is Observer Aborts configured so patrol can be interrupted?

If the Blackboard key is wrong, fix the controller/perception/service that writes the key. If the key is right but the branch is wrong, inspect branch priority, decorators, aborts, and task state.

Perception category

Use Perception when sight/hearing facts do not match behavior.

Read it before adding more traces:

Which senses are configured?
Is the player a valid stimulus for sight/hearing?
Is the stimulus currently sensed or only remembered?
What is the last known location?
Is the debug color/radius/cone showing what you expected?

Common outcomes:

Perception sees the player, Blackboard stays empty
-> controller event did not write the key, wrote the wrong key, or filtered the actor out.

Perception never sees the player
-> sight config, stimuli source, affiliation, line of sight, radius, cone, or enabled state.

Perception remembers too long
-> Max Age / forgetting settings or your own TargetActor never clears.

EQS category

Use EQS only if the AI is actually running an Environment Query.

The category can show generated items, failed items, scores, and the chosen result for the current query. That helps answer:

Did the query run?
Which generator produced candidates?
Which tests filtered out candidates?
Which item won?
Did the winning location make sense for this pawn and context?

For a first patrol/chase enemy, do not add EQS just to make debugging feel professional. Use EQS when the AI needs to choose a tactical or environmental position, such as cover, line-of-sight attack spot, flee location, or pickup choice.

Networked debugger display

The Gameplay Debugger can show data in networked play, and enabled categories can replicate debug data for display. That is debugging data, not gameplay state.

For multiplayer AI:

Server:
    usually owns AI decisions, perception, movement, and damage

Client:
    may display replicated actor state and debugger overlay

If the overlay differs between windows, label the PIE window and actor:

Server window:
    AIController, Behavior Tree, Blackboard are authoritative

Client window:
    may show replicated/debug display for what the client can receive

Do not use "the client overlay did not show it" as the only proof that the server AI did not run. Pair it with server-window debugging or labeled prints.

Custom categories

Custom Gameplay Debugger categories are useful for larger projects:

  • threat score;
  • team/faction attitude;
  • combat cooldowns;
  • cover-slot ownership;
  • current weapon state;
  • ability system summaries;
  • project-specific objective state.

But they are C++ extension work. A Blueprint-first beginner should usually use the built-in categories, Print String, breakpoints, Visual Logger, and small debug widgets before creating a custom category.

If the only missing debug value is one Blueprint variable, the quicker and better path is often a labeled print, watch value, or temporary world widget.

When it fails, and what failure looks like

Symptom Likely cause
Apostrophe does nothing Key binding, focus, debugger availability, console/PIE mode, or project settings differ.
Overlay opens but data is empty No valid selected actor, wrong actor selected, or the selected pawn has no relevant controller/tree/perception data.
Behavior Tree category shows wrong keys Wrong Blackboard asset, wrong AI instance, or wrong debug selection.
NavMesh display is absent No NavMeshBoundsVolume, nav data not generated, category off, or wrong actor/area selected.
Perception category shows no stimuli Sense config, stimuli source, affiliation, line of sight, or perception component setup is wrong.
EQS category shows nothing No query is currently running, query finished too quickly, or the AI does not use EQS.
Client window disagrees with server window You are looking at debug/replicated display from different network worlds.
Overlay is unreadable Too many categories enabled; toggle down to one question at a time.

When the debugger output surprises you, first confirm selection and PIE world. Then trust the ownership chain: pawn, controller, Blackboard, tree, movement, perception.

What the Gameplay Debugger does not do

  • It does not create a NavMesh, AIController, Behavior Tree, Blackboard, or Perception component.
  • It does not select the correct actor if you never point at or choose it.
  • It does not prove a Blueprint graph is correct just because a key is set.
  • It does not store a timeline for later review; use Visual Logger when you need to scrub history.
  • It does not turn Blueprint-only projects into custom debugger-category projects without C++.
  • It does not replace breakpoints when you need to pause a task/service.
  • It does not make client debug display authoritative server truth.

Lookalikes - which one do I want?

Tool Use when Not for
Gameplay / AI Debugger You need live AI, NavMesh, Behavior Tree, Blackboard, EQS, or Perception data. Recording a rare bug for later scrubbing.
Print String / Output Log You need quick proof a Blueprint path ran and what value it saw. Reading the whole AI stack at once.
Blueprint breakpoints You need to pause one task, service, controller event, or pawn function. Seeing broad runtime NavMesh/perception context.
Behavior Tree asset debugger You are inspecting a running tree from the asset editor. Debugging NavMesh or perception cones.
Visual Logger You need recorded snapshots, messages, paths, and shapes over time. Immediate key-by-key overlay while tuning.
EQS Testing Pawn You need to preview an EQS query in the editor. Debugging a full live AI decision chain.
showdebug / console overlays A built-in system has a DisplayDebug category you want on the current view. Actor selection plus AI categories in one overlay.

The quick path is to add more Print Strings everywhere. The concrete cost is that you still might not know which pawn/controller/tree/key you were looking at. Use the debugger to inspect the owner chain, then add targeted prints only where the chain breaks.

Going deeper