StateTree Debug Overlay

StateTree Debug Overlay draws short text above an Actor while a StateTree state is active. Use it in PIE to confirm that a state entered, bound text changed, and exit cleanup occurred. It is local read-only HUD diagnostics, not replicated state or Shipping UI.

For StateTree setup, see Integrate StateTree and Blackboard; for settings, see Project Settings and Blackboard; for runtime panels, see GameplayDebugger.

Prerequisites

Draw code is compiled only in Editor plus debug-drawing build conditions. At runtime, enable both CVars:

plaintext

1gais.DebugOverlay.Enable 1
2gais.DebugOverlay.StateTree 1

Turning either off stops drawing. The overlay is neither replicated nor saved as game UI state; in multiplayer each local client sees only its own HUD drawing.

StateTree Task

Add Task: Debug Overlay Text to a StateTree.

Field	Meaning
`Text`	Static state/diagnostic text such as `Charge` or `Holding Cover`.
`BindableText`	Runtime-bound text appended after static text, for a target name, count, or reason.
`ReferenceActor`	World-space anchor; when null, uses the StateTree execution owner.

When ReferenceActor is a Controller, drawing resolves its current Pawn. A Pawn or ordinary Actor is used directly. Entering the state registers text and exiting unregisters it. The Task returns Running and has bConsideredForCompletion disabled, so it does not affect StateTree completion.

Project settings

These UGAIS_DeveloperSettings Debug Overlay fields exist only in Editor data.

Setting	Purpose
`DebugOverlayOffset`	World-space text offset from the Actor.
`DebugOverlayFontScale`	HUD text scale.
`DebugOverlayColor`	Text color.
`DebugOverlayPawnClassFilters`	Optional Pawn-class filters; empty draws any Actor, otherwise only matching Pawns.

Filtering applies to the final draw Actor. A Controller resolves to Pawn before the Pawn-class filter is applied.

Verification and troubleshooting

Symptom	Check
No text at all	Editor/debug-drawing build condition and both CVars are 1.
State enters but nothing appears	`Text` and `BindableText` are not both empty; ReferenceActor or StateTree owner is valid.
Bound Controller does not display	It has a current Pawn and the Pawn is not excluded by the class filter.
Wrong text position	Adjust `DebugOverlayOffset`; verify the anchor is Pawn rather than Controller.
Text remains after exit	StateTree really called ExitState, or another state text is still active.

Use GameplayDebugger for system snapshots and Visual Logger for per-Tactical-Source production detail. Debug Overlay only draws local StateTree state text.

Table of contents