How to use the behaviour tree visualizer
- Paste or open your XML. Use a file from your package, a Groot export, or one of Nav2's trees. The drawing updates as you type.
- Read the tree top to bottom, left to right. That is the order BehaviorTree.CPP ticks children. Colours show what each node is: blue controls decide the order, purple decorators change one child's result, green actions do work and amber conditions check something.
- Fix the problems listed under the drawing. Errors stop BehaviorTree.CPP from loading the file, or make it throw as soon as the node runs; warnings load fine but are probably not what you meant. Nodes with errors get a red dashed border.
- Explore subtrees and export. Pick another tree from the list, tick Expand subtrees to draw them inline, and download the drawing as SVG for documentation or a pull request.
What the checker looks for
| Check | Why it matters |
|---|---|
Well-formed XML with a <root> element | A typo such as an unclosed tag stops the whole file from loading. |
BTCPP_format="4" on the root | BehaviorTree.CPP 4 warns when it is missing, and a file written for version 3 may use node names that version 4 renamed. |
One top-level node per <BehaviorTree> | A tree has exactly one root node; wrap several in a Sequence or Fallback. |
| A main tree can be found | main_tree_to_execute must name an existing tree when the file has several. |
Every SubTree ID exists, and subtrees don't call each other in a loop | A missing subtree fails at load time; a loop would recurse forever. |
| Decorators have exactly one child; leaves have none | BehaviorTree.CPP rejects both at load time. |
| Child counts for IfThenElse, WhileDoElse, SwitchN and Nav2's RecoveryNode | These nodes give each child a fixed role, so the count must match. |
| Actions before the last child of a ReactiveSequence or ReactiveFallback | Reactive nodes re-tick earlier children on every tick, so such an action restarts while a later child runs. BehaviorTree.CPP loads the tree without a warning. |
| Unknown node names | Your own nodes must be registered in code; a TreeNodesModel section documents them for tools like this one. |
The node list covers every built-in node of BehaviorTree.CPP 4.10 and the Nav2 nodes shipped with ROS 2 Jazzy, so a stock Nav2 tree shows no warnings. We test the checker by loading the same files with BehaviorTree.CPP 4.10 itself. Version 3 names such as SequenceStar are flagged with their version 4 replacement: as an error in a version 4 file, which BehaviorTree.CPP 4 refuses to load, and as a warning in a file without BTCPP_format, which may be meant for version 3 (ROS 2 Humble).
Reading a tree in thirty seconds
- Sequence: run children in order; stop at the first failure. Think "and then".
- Fallback: try children in order; stop at the first success. Think "or else".
- Reactive versions re-check earlier children on every tick, so a condition can interrupt a running action.
- Decorators wrap one child: Inverter flips its result, RetryUntilSuccessful retries it, Timeout cancels it after a time limit.
The visualizer reads trees; it does not run them. To design trees with your team and run them on real robots, use the behaviour tree editor in the XPARO fleet dashboard.
