Skip to main content
Version: 3.8

Main Concepts

BehaviorTree.CPP is a C++ library that can be easily integrated into your favourite distributed middleware, such as ROS or SmartSoft.

You can statically link it into your application (for example a game).

These are the main concepts which you need to understand first.

Nodes vs Trees

The user must create his/her own ActionNodes and ConditionNodes (LeafNodes); this library helps you to compose them easily into trees.

Think about the LeafNodes as the building blocks which you need to compose a complex system. It Nodes were lego bricks, your trees would be lego sets.

By definition, your custom Nodes are (or should be) highly reusable.

Instantiate trees at run-time using the XML format

Despite the fact that the library is written in C++, trees themselves can be created and composed at run-time, more specifically, at deployment-time, using an XML base scripting language.

An XML format is described in details here, but the best way to learn the syntax is following the tutorials.

The tick() callbacks

Any TreeNode can be seen as a mechanism to invoke a callback, i.e. to run a piece of code. What this callback does is up to you.

In most of the following tutorials, our Actions will simply print messages on console or sleep for a certain amount of time to simulate a long calculation.

In production code, especially in Model Driven Development and Component Based Software Engineering, an Action/Condition would probably communicate to other components or services of the system.

// The simplest callback you can wrap into a BT Action
NodeStatus HelloTick()
std::cout << "Hello World\n";
return NodeStatus::SUCCESS;

// Allow the library to create Actions that invoke HelloTick()
// (explained in the tutorials)
factory.registerSimpleAction("Hello", std::bind(HelloTick));

The factory may create multiple instances of the node Hello.

Create custom nodes with inheritance

In the example above, a specific type of TreeNodes which invoke HelloTick was created using a function pointer (dependency injection).

Generally, to define a custom TreeNode, you should inherit from the class TreeNode or, more specifically, its derived classes:

  • ActionNodeBase
  • ConditionNode
  • DecoratorNode

As a reference please look at the first tutorial.

Dataflow, Ports and Blackboard

Ports are explained in detail in the second and third tutorials.

For the time being, it is important to know that:

  • A Blackboard is a key/value storage shared by all the Nodes of a Tree.

  • Ports are a mechanism that Nodes can use to exchange information between each other.

  • Ports are "connected" using the same key of the blackboard.

  • The number, name and kind of ports of a Node must be known at compilation-time (C++); connections between ports are done at deployment-time (XML).

  • You can store as value any C++ type (we use a _type erasure technique similar to std::any).