# BT Debugging

Level: Intermediate

## Goal

Diagnose why a Behavior Tree branch does not tick, selects the wrong child, never finishes, or returns a result that does not match the authored tree.

## Symptoms

| Symptom                                | First place to look                                        |
| -------------------------------------- | ---------------------------------------------------------- |
| BTRoot never ticks.                    | Flow path into BTRoot Active, Guard, or Debug Context.     |
| BTRoot ends immediately.               | Missing children, Guard rejection, or root result mapping. |
| Selector chooses the wrong child.      | Child order, conditions, or Reactive vs Memory mode.       |
| Sequence never completes.              | A child stays Running, waits forever, or is shielded.      |
| A subtree is interrupted unexpectedly. | Reactive composite preemption or missing BT Shield.        |
| BtSubGraph returns the wrong result.   | Selected BTRoot and Return Mode mapping.                   |

## Likely Causes

* The Flow chain never reaches the BTRoot Active input.
* BTRoot has no child outputs connected.
* Child ports are connected in the wrong order.
* A Guard rejects before the BT node can evaluate.
* A Selector or Sequence is using a composite mode that does not match the intended behavior.
* A BTAction runs work that never completes or waits on missing data.
* A BT Shield is missing around a child that must finish uninterrupted.
* BtSubGraph points at a graph but no BTRoot is selected.

## Checks

1. Confirm the BTRoot is entered.
   * Start from the Flow node that should activate the tree.
   * Follow the branch into BTRoot Active.
   * Use Visual Debugging to confirm the chain reaches the root.
2. Check root validity.
   * Confirm the BTRoot Guard does not reject unexpectedly.
   * Confirm child outputs exist.
   * Confirm each child output is connected to a BT-compatible child.
3. Read child order as priority.
   * Children are evaluated left to right.
   * In a Selector, earlier valid children can prevent later children from running.
   * In a Sequence, earlier failed or running children can prevent later children from running.
4. Confirm composite mode.
   * Reactive composites re-evaluate from high priority children and can preempt lower priority running work.
   * Memory composites continue from the running child until it finishes.
   * Use BT Shield when a child must not be interrupted by reactive priority changes.
5. Inspect leaf behavior.
   * BTCondition is a check.
   * BTAction runs work and returns Success unless aborted or mapped otherwise by the surrounding node behavior.
   * A leaf that waits on missing Blackboard data can keep the branch Running.
6. Check BtSubGraph.
   * Confirm the referenced graph is assigned.
   * Confirm a BTRoot is selected inside the referenced graph.
   * Confirm Return Mode maps subgraph results to the parent tree as intended.

## Fixes

* Connect the Flow branch into BTRoot Active.
* Add child outputs and connect them in intended priority order.
* Move a high-priority child left or a fallback child right.
* Switch Reactive to Memory when a running child should continue.
* Add BT Shield around non-interruptible work.
* Fix missing Blackboard keys or wrong scopes used by BTConditions.
* Select the intended BTRoot in BtSubGraph and verify Return Mode.

## Visual Debugging Notes

* Child order is priority. Read BT debugging from left to right.
* Chain dots show evaluation movement even when priority-only checks reduce highlight noise.
* Pulsing highlights usually mean a leaf is still Running.
* A repeatedly restarting child often points to Reactive preemption.
* A silent subtree often means it is not connected as a child of the active root.

## Related

* [Graph Debugging](/flow-core-docs/documentation/troubleshooting/graph-debugging.md)
* [Behavior Tree Authoring](/flow-core-docs/documentation/gameplay-modules/behavior-tree-authoring.md)
* [BT Cookbook](/flow-core-docs/documentation/gameplay-modules/bt-cookbook.md)
* [BTRoot](https://github.com/HaikunHuang/FlowCore/blob/main/reference/nodes/node-bt-root.md)
* [Invoke and Reject Modes](/flow-core-docs/documentation/reference/invoke-and-reject-modes.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://flow-core.gitbook.io/flow-core-docs/documentation/troubleshooting/bt-debugging.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.