
Behavior Trees Library in C++. Batteries included.
Repo BehaviorTree/BehaviorTree.CPP, read from GitHub 1 d ago. BehaviorTree has not joined Take My Repo.
77 merged PRs: two new XML features for writing trees (the Finally node and the _onlyIf / _onStart preconditions), XML schema validation, input port subscriptions, and a large batch of robustness fixes, many of them found by fuzzing.
ABI: 4.11.0 is binary compatible with 4.10.0. We checked the class layouts against 4.10.0, and restored the timer nodes' layout that an earlier fix had changed (#1283). A few fixes change behavior, though; see Behavior changes below.
New Finally control node: guaranteed cleanup. It ticks its first child ("main") and then its second child ("cleanup"), like try/finally. Cleanup runs whether main succeeds, fails, throws, or is halted. The node returns main's status, or FAILURE if cleanup fails. By default, a halt gives cleanup a single tick. Set halt_timeout_msec to let an asynchronous cleanup finish. This blocks the halting parent for up to that long, so keep it short. Issue #1228, PR #1229.
<Finally halt_timeout_msec="500"> <MoveArm/> <EnableCollisions/> </Finally>
New preconditions _onlyIf and _onStart. _onlyIf="<script>" skips the node unless the condition is true (the readable opposite of _skipIf). _onStart="<script>" runs a script right before the node's first tick, which is handy to initialize or reset blackboard entries. Issues #820, #895, PR #1261.
<MoveBase _onlyIf="battery > 20" _onStart="attempts := 0" goal="{target}"/>
XML validation with XSD and Schematron. writeTreeXSD(factory, generic) can emit a lax schema that accepts unknown custom nodes. The new writeTreeSchematron() checks what XSD can't: every custom node used in a tree has a TreeNodesModel entry, every <SubTree ID> resolves, and main_tree_to_execute exists. Ready-made schemas for the built-in nodes are in tools/generated/, and tools/validate_xml.py validates a file against both. Thanks @vivoeiva. PR #1146.
Input port update subscriptions. TreeNode::subscribeToInputPort("port", callback) calls back when the blackboard entry behind an input port is written, so a node can react before its next tick instead of polling. It follows SubTree remapping, and it is notified by set(), setOutput(), scripts, JSON import and snapshot restore. PR #1247.
BTCPP_version in generated XML. WriteTreeToXML() and writeTreeNodesModelXML() write the library version in <root>, so tools such as Groot2 know which built-in nodes and attributes the file targets. PR #1264.
Groot2Publisher bind address. The new constructor Groot2Publisher(tree, port, bind_address) lets you listen on "127.0.0.1" only. The Groot2 protocol has no authentication, and a reachable port allows inserting hooks that replace node results. The existing constructor keeps binding to all interfaces. PR #1251.
Use the system nlohmann_json. With -DUSE_VENDORED_JSON=OFF, the library builds and exports against find_package(nlohmann_json), so it no longer clashes with another copy of the header in your project. The default stays ON. Issue #959, PR #1235.
Smaller API additions:
Many of these were found by fuzzing and code review.
haltTree() from another thread now stops tickWhileRunning(). Before, the loop restarted the tree that had just been halted. Issue #686, PR #1201._onlyIf, _onStart and Finally are now reserved names. A node registered as Finally gets a duplicate-registration error."1" + "2" is "12" (issue #1246, PR #1254)._autoremap="true", SubTree model defaults are now applied when the parent has no such entry at tree creation (#1272).The full list is in CHANGELOG.rst.
Thanks to Arthur Chan, Aysha Afrah Ziya, Azer Ben Ali, David Vadovszki, Golitsin Vyacheslav, Igor Stadnyk, Jonas Otto, KImanalieva, Lim Jooyoung, Nikola Kachmaryk, Varun Kumar, Victor Voronin, ktyang and simobenziane.
New node TryCatch: similar to a Sequence, but with a "cleanup" node that is execute only if the Sequence failed or was halted. A feature requested by many users!
Polymorphic shared_ptr port support. Nodes producing shared_ptr<Derived> can now connect to ports expecting shared_ptr<Base>. Register inheritance relationships with factory.registerPolymorphicCast<Derived, Base>() and the library handles upcasting/downcasting transparently, including transitive chains (e.g. Sphynx -> Cat -> Animal). Issue #943, PR #1107.
Exception tracking in nodes. When an exception is thrown during tick(), it is now wrapped in a NodeExecutionError that includes the failing node's name, path, and registration name. Issue #990, PR #1106.
Replaced lexy scripting dependency with a hand-written Pratt parser. The lexy third-party dependency has been removed and replaced with a custom tokenizer and recursive-descent Pratt parser. This reduces compilation time, binary size, and eliminates a non-trivial dependency. PR #1099.
EntryUpdatedDecorator::halt() not halting its child. The decorator was missing the call to DecoratorNode::halt(), leaving the child node running when the decorator was halted. Issue #1111, PR #1112.
Use-after-free when factory destroyed before tree. After createTree(), node manifest pointers pointed into the factory's internal map. If the factory was destroyed before ticking, these became dangling pointers. Tree::remapManifestPointers() now re-points each node's manifest to the tree's own copy. Issue #1046, PR #1081.
createTreeFromText could not find previously registered subtrees. createTreeFromText() and createTreeFromFile() used a temporary parser that couldn't see subtrees registered via registerBehaviorTreeFromText()/registerBehaviorTreeFromFile(). They now use the factory's shared parser. Issue #880, PR #1105.
Groot2Publisher destructor infinite loop. The destructor could hang indefinitely when the ZMQ server thread was waiting on recv(). Fixed by calling zmq_context.shutdown() to interrupt blocking receives. Issue #1057, PRs #1100, #1058.
Recursive subtree cycles now detected at parse time. Previously, mutually-recursive subtrees caused a stack overflow at tree instantiation. The parser now tracks an ancestor set and throws a clear RuntimeError when a cycle is detected. Issue #979, PR #1085.
Deeply-nested XML no longer causes stack overflow. A depth limit (256) is now enforced during XML parsing and tree instantiation. Issue #672, PR #1091.
Script parser left-associativity for arithmetic operators. Expressions like A - B + C were evaluated as A - (B + C) instead of (A - B) + C. Issue #1029, PR #1069.
Mock substitution hangs when TestNodeConfigs is absent. An empty TestNodeConfigs object was always created, causing mock nodes to be registered even when no test configuration was intended, which led to infinite loops. Issue #930, PR #1086.
Segfault when substituting a SubTree node. When a substitution rule replaced a SubTree with a TestNode, setSubtreeID was called on a null pointer. Issue #934, PR #1083.
BehaviorTreeFactory could not be returned by value. Move constructor and move assignment were defaulted in the header where PImpl is an incomplete type, preventing compilation. Issue #937, PR #1082.
getLockedPortContent creates entry for default-remapped ports. Issue #942, PR #1078.
getInput() failed for plugin custom types. When a node is loaded as a plugin, the convertFromString<T> specialization defined in the plugin is not visible to the main application. getInput<T>() now uses the StringConverter stored in PortInfo instead of calling convertFromString<T>() directly. Issue #953, PR #1104.
parseString now supports enums with convertFromString specializations. Issue #948, PR #1075.
LoopNode now accepts std::vector<T> in addition to SharedQueue<T>. Issue #969, PR #1074.
json: prefix handled in vector convertFromString specializations. When a port of type std::vector<T> had a default empty value {}, toStr() would produce "json:[]" which was not parsed correctly by the explicit specializations. Issue #982, PR #1073.
JsonExporter use-after-move in vector converter registration. The addConverter method moved converter before vector_converter captured it, causing std::bad_function_call. Issue #989, PR #1090.
debugMessage now shows type info for remapped subtree entries. Issue #408, PR #1079.
DelayNode ignoring delay_msec when created from XML. PR #1097.
DelayNode missing read_parameter_from_ports_ initialization. PR #1103.
Misleading static_assert when extra constructor args have wrong type. The compiler now reports that the extra arguments don't match instead of the misleading "you MUST add a constructor" message. Issue #837, PR #1098.
Windows build issues. Removed redundant TINYXML2_DEBUG definition that caused Debug mode crashes on VS 2022 and added MSVC runtime propagation in conanfile.py. Issues #762, #869, #836, PR #1089.
std::from_chars compilation failure on older g++ versions. PR #1110.
Removed deprecated std::aligned_storage usage. The type was deprecated in C++23 and could cause warnings in client code. PR #1061.
Improved PreCondition documentation. Added clarifying comments about _failureIf, _successIf, _skipIf, and _while evaluation semantics. Issue #917.
Generate .clangd in PROJECT_SOURCE_DIR. This allows BT.CPP to be used as a submodule or via FetchContent/CPM without rewriting the parent project's .clangd file. PR #1059.
Added vcpkg installation instructions. PR #421.
Improved test suite quality and coverage. Added 50+ new tests covering basic types, IfThenElseNode, WhileDoElseNode, loggers, decorators, LoopNode, and reactive nodes. Tests now run faster with reduced sleep durations. PR #1102.
Added Doxygen welcome page with organized navigation, quick links to core classes, and complete lists of built-in nodes.
The most notable change, that will also affect future PRs, is the introduction of static analysis through clang-tidy.
This allowed me to improve the consistency and readability of the code and to find some subtle potential bugs.
From now on, contributors will need run clang-tidy locally on their machine using the script run_clang-tidy.sh, before submitting their PR.
Full Changelog: 4.8.2...4.8.3
#1016 <https://github.com/BehaviorTree/BehaviorTree.CPP/issues/1016>_)#1012 <https://github.com/BehaviorTree/BehaviorTree.CPP/issues/1012>_)#1013 <https://github.com/BehaviorTree/BehaviorTree.CPP/issues/1013>_)