Debugging

Export

Use this guide when a behavior tree does not start, chooses the wrong branch, remains Running, or uses an unexpected value. Start with the Error Window, then diagnose execution status and data in Play Mode.

Start with the Error Window

Open Tools > Opsive > Behavior Designer > Error Window, select the status-bar error count, or press Ctrl/Cmd+E. Select an error to identify its Task in the graph.

Resolve structural errors before entering Play Mode:

  1. Confirm that Start connects to the intended root Task.
  2. Connect required children to every Composite and Decorator.
  3. Assign required fields and object references.
  4. Confirm that referenced Subtrees and Shared Variables exist.
  5. Clear Console compile errors, because an incomplete script can remove a Task type or field from the graph.

A clean Error Window means the editor found no known structural or serialized-field problem. It does not prove that the gameplay conditions or values are correct.

Watch the tree in Play Mode

Keep the editor open while entering Play Mode. Task borders and status show which branch is active and whether a Task is Running, Success, or Failure.

Can See Enemy has succeeded and Chase Enemy is running while Patrol is inactive.

Read from the root toward the expected Task:

  • If no Task activates, inspect the owner, component, and Start connection.
  • If traversal stops early, inspect the first Task that reports Failure.
  • If a later branch never runs, inspect the earlier Selector child that is succeeding or remaining Running.
  • If a Sequence stops, inspect the child that failed.
  • If a Task never finishes, inspect its completion condition and cancellation path.

Pause Play Mode when the relevant state is visible. Use the available step controls when the selected runtime supports them.

Inspect values

Select the active Task and inspect its fields. Use a field’s watch icon to show a supported live value on the node. Then inspect the Shared Variables panel and confirm:

  • the expected variable name and type;
  • the intended Graph, GameObject, Scene, or Project scope;
  • whether the field is using a Shared Variable or a direct value;
  • whether the variable is Internal, read-only, or dynamically resolved; and
  • whether another Task, property binding, or script changes it before the decision.

Do not repair a value problem by duplicating similarly named variables. Follow Variables and Variable Scope to identify the owner.

Diagnose common symptoms

Symptom Check Fix
The graph never starts. Selected GameObject, enabled Behavior Tree component, active GameObject, Start connection, and Console errors. Select or enable the correct owner, connect Start, and resolve compilation errors.
The tree starts on the wrong object. GameObject and Behavior Tree selections in the operations toolbar. Choose the intended GameObject and component; use the lock control while inspecting other objects.
A Task is skipped. Disabled state, parent Composite rules, and an earlier sibling’s result. Enable it and correct the parent flow or sibling order.
A Selector never reaches its fallback. An earlier child remains Running or succeeds every tick. Inspect that child’s completion/result and reorder only when priority should change.
A Sequence stops before the final Action. The first failed child. Correct the failing condition or wrap optional work in the intended fallback structure.
A Conditional Abort does not react. Abort type, reevaluation range, Shared Variable value, and whether the branch is eligible. Follow Conditional Aborts and watch the Conditional’s live inputs.
A Subtree uses the wrong target. Override mappings, source variable name/type, and runtime replacement. Correct the mapping on the Subtree Reference and reopen the referenced asset.
A value differs between editor and runtime. Scope, property binding, scene reload, and the script that writes the value. Inspect the owning scope and binding before changing the Task.
The tree works in editor but not a build. Scene/build inclusion, stripped types, baking, and referenced assets. Reproduce in a development build and preserve the referenced Task, Subtree, and data assets.

Reduce the graph safely

When the source is still unclear, duplicate the owner or work in a test scene. Disable one branch at a time, replace a project Action with Log, and use fixed values instead of live variables. Stop when the smallest graph reproduces the issue.

Restore one dependency at a time. This distinguishes graph flow from component, input, animation, navigation, or networking behavior without destroying the original tree.