BehaviorTree.CPP Plugins

This package provides a set of tools that allows users to easily export plugins for behaviortree_cpp, such as new types of BT Nodes.

Under the hood, it uses ROS’ pluginlib to allow for discovery of plugins without hardcoding of library names and classes - which the patterns provided by behaviortree_cpp and navigation2 currently require.

Usage

There are two usage patterns - the plugin provider and the plugin consumer.

Registering Plugins

Simple as 1, 2, 3: depend on this package, register your library as a plugin provider, call registration macro on plugin classes.

1. package.xml - you need only a build dependency on this package

    ...
    <build_depend>behaviortree_cpp_pluginlib</build_depend>
    ...
    

1. CMakeLists.txt - find the package, link against its library target, and call custom macro to register your target as containing plugins

    find_package(behaviortree_cpp_pluginlib REQUIRED)

    ...
    add_library(my_plugin_library
      src/source1.cpp
      ...
    )
    target_link_libraries(my_plugin_library
      behaviortree_cpp_pluginlib::plugin
      ...
    )
    register_behaviortree_cpp_plugin(my_plugin_library)
    ...
    

1. C++ sources (note: registration needs to happen in compilation unit, not in exposed header!)

    #include "behaviortree_cpp_pluginlib/register_macro.hpp

    ...

    namespace my_namespace
    {
    class MyActionNodeClass : public BT::SyncActionNode
    {
      ...
    };
    }  // namespace my_namespace

    ...

    BT_REGISTER_PLUGIN_NODE(MyActionNodeName, my_namespace::MyActionNodeClass)
    

1. Also note a more generic exposure mode. BT_REGISTER_PLUGIN_NODE is provided for simple use in the average case, but if you have other exposures to do, you can use:

    BT_PLUGIN_REGISTER(factory)
    {
      // factory will be a BT::BehaviorTreeFactory &
      factory.ArbitraryMethodCalls();
    }
    

Registering Subtrees

You can also ship reusable subtrees as .xml files. They are discovered and registered by BT::PluginAwareFactory automatically, so any loaded tree can reference them via <SubTree ID="..."/> without loading files by hand.

1. Write a subtree XML with a single <BehaviorTree ID="..."> (the ID is the name you reference as a <SubTree>):

    <root BTCPP_format="4">
      <BehaviorTree ID="GoAndBeep">
        ...
      </BehaviorTree>
    </root>
    

1. CMakeLists.txt - register the file(s). Use the SUBTREES keyword to ship them alongside a plugin library (e.g. one that provides the nodes the subtree uses):

    register_behaviortree_cpp_plugin(my_plugin_library
      SUBTREES trees/go_and_beep.xml
    )
    

Or, for a package that ships subtrees but builds no plugin library, use the standalone function:

    register_behaviortree_cpp_subtrees(FILES trees/go_and_beep.xml)
    # Pass a distinct NAME when calling more than once in a single package:
    # register_behaviortree_cpp_subtrees(NAME navigation FILES trees/go_and_beep.xml)
    

File truncated at 100 lines see the full file

Changelog for package behaviortree_cpp_pluginlib

0.2.0 (2026-09-24)

• Add subtree registration system (#4)
• Contributors: Zeerek Ahmad

0.1.0 (2025-11-13)

• Initial implementation (#1)
  • Initial implementation pulled out of Polymath core
  • Apply pre-commit configurations
  • Migrate to gtest
  • Add GitHub action CI
• Contributors: Emerson Knapp