BT::BehaviorTreeFactory Class Reference

The BehaviorTreeFactory is used to create instances of a TreeNode at run-time. More...

#include <bt_factory.h>

Public Types
using	SubstitutionRule = std::variant< std::string, TestNodeConfig, std::shared_ptr< TestNodeConfig > >

Public Member Functions
	BehaviorTreeFactory (const BehaviorTreeFactory &other)=delete
BehaviorTreeFactory &	operator= (const BehaviorTreeFactory &other)=delete
	BehaviorTreeFactory (BehaviorTreeFactory &&other) noexcept
BehaviorTreeFactory &	operator= (BehaviorTreeFactory &&other) noexcept
bool	unregisterBuilder (const std::string &ID)
	Remove a registered ID.
void	registerBuilder (const TreeNodeManifest &manifest, const NodeBuilder &builder)
template<typename T >
void	registerBuilder (const std::string &ID, const NodeBuilder &builder)
void	registerSimpleAction (const std::string &ID, const SimpleActionNode::TickFunctor &tick_functor, PortsList ports={})
	registerSimpleAction help you register nodes of type SimpleActionNode.
void	registerSimpleCondition (const std::string &ID, const SimpleConditionNode::TickFunctor &tick_functor, PortsList ports={})
	registerSimpleCondition help you register nodes of type SimpleConditionNode.
void	registerSimpleDecorator (const std::string &ID, const SimpleDecoratorNode::TickFunctor &tick_functor, PortsList ports={})
	registerSimpleDecorator help you register nodes of type SimpleDecoratorNode.
void	registerFromPlugin (const std::string &file_path)
	registerFromPlugin load a shared library and execute the function BT_REGISTER_NODES (see macro).
void	registerFromROSPlugins ()
	registerFromROSPlugins finds all shared libraries that export ROS plugins for behaviortree_cpp, and calls registerFromPlugin for each library.
void	registerBehaviorTreeFromFile (const std::filesystem::path &filename)
	registerBehaviorTreeFromFile. Load the definition of an entire behavior tree, but don't instantiate it. You can instantiate it later with:
void	registerBehaviorTreeFromText (const std::string &xml_text)
std::vector< std::string >	registeredBehaviorTrees () const
void	clearRegisteredBehaviorTrees ()
	Clear previously-registered behavior trees.
std::unique_ptr< TreeNode >	instantiateTreeNode (const std::string &name, const std::string &ID, const NodeConfig &config) const
	instantiateTreeNode creates an instance of a previously registered TreeNode.
template<typename T , typename... ExtraArgs>
void	registerNodeType (const std::string &ID, const PortsList &ports, ExtraArgs... args)
template<typename T , typename... ExtraArgs>
void	registerNodeType (const std::string &ID, ExtraArgs... args)
const std::unordered_map< std::string, NodeBuilder > &	builders () const
	All the builders. Made available mostly for debug purposes.
const std::unordered_map< std::string, TreeNodeManifest > &	manifests () const
	Manifests of all the registered TreeNodes.
const std::set< std::string > &	builtinNodes () const
	List of builtin IDs.
Tree	createTreeFromText (const std::string &text, Blackboard::Ptr blackboard=Blackboard::create())
	createTreeFromText will parse the XML directly from string. The XML needs to contain either a single <BehaviorTree> or specify the attribute [main_tree_to_execute].
Tree	createTreeFromFile (const std::filesystem::path &file_path, Blackboard::Ptr blackboard=Blackboard::create())
	createTreeFromFile will parse the XML from a given file. The XML needs to contain either a single <BehaviorTree> or specify the attribute [main_tree_to_execute].
Tree	createTree (const std::string &tree_name, Blackboard::Ptr blackboard=Blackboard::create())
void	addMetadataToManifest (const std::string &node_id, const KeyValueVector &metadata)
void	registerScriptingEnum (StringView name, int value)
	Add an Enum to the scripting language. For instance if you do:
template<typename EnumType >
void	registerScriptingEnums ()
	registerScriptingEnums is syntactic sugar to automatically register multiple enums. We use https://github.com/Neargye/magic_enum.
void	clearSubstitutionRules ()
void	addSubstitutionRule (StringView filter, SubstitutionRule rule)
	addSubstitutionRule replace a node with another one when the tree is created. If the rule ia a string, we will use a different node type (already registered) instead. If the rule is a TestNodeConfig, a test node with that configuration will be created instead.
void	loadSubstitutionRuleFromJSON (const std::string &json_text)
	loadSubstitutionRuleFromJSON will parse a JSON file to create a set of substitution rules. See Tutorial 11 for an example of the syntax.
const std::unordered_map< std::string, SubstitutionRule > &	substitutionRules () const
	substitutionRules return the current substitution rules.
template<typename Derived , typename Base >
void	registerPolymorphicCast ()
	Register a polymorphic cast relationship between Derived and Base types.
PolymorphicCastRegistry &	polymorphicCastRegistry ()
	Access the polymorphic cast registry.
const PolymorphicCastRegistry &	polymorphicCastRegistry () const
std::shared_ptr< PolymorphicCastRegistry >	polymorphicCastRegistryPtr () const
	Get a shared pointer to the polymorphic cast registry.

Detailed Description

The BehaviorTreeFactory is used to create instances of a TreeNode at run-time.

Some node types are "builtin", whilst other are used defined and need to be registered using a unique ID.

Member Function Documentation

addMetadataToManifest()

void BT::BehaviorTreeFactory::addMetadataToManifest	(	const std::string &	node_id,
		const KeyValueVector &	metadata
	)

Add metadata to a specific manifest. This metadata will be added to <TreeNodesModel> with the function writeTreeNodesModelXML()

addSubstitutionRule()

void BT::BehaviorTreeFactory::addSubstitutionRule	(	StringView	filter,
		SubstitutionRule	rule
	)

addSubstitutionRule replace a node with another one when the tree is created. If the rule ia a string, we will use a different node type (already registered) instead. If the rule is a TestNodeConfig, a test node with that configuration will be created instead.

Parameters

filter	filter used to select the node to sobstitute. The node path is used. You may use wildcard matching.
rule	pass either a string or a TestNodeConfig

createTreeFromFile()

Tree BT::BehaviorTreeFactory::createTreeFromFile	(	const std::filesystem::path &	file_path,
		Blackboard::Ptr	blackboard = Blackboard::create()
	)

createTreeFromFile will parse the XML from a given file. The XML needs to contain either a single <BehaviorTree> or specify the attribute [main_tree_to_execute].

Consider using instead registerBehaviorTreeFromFile() and createTree().

Parameters

file_path	location of the file to load
blackboard	blackboard of the root tree

Returns

the newly created tree

createTreeFromText()

Tree BT::BehaviorTreeFactory::createTreeFromText	(	const std::string &	text,
		Blackboard::Ptr	blackboard = Blackboard::create()
	)

createTreeFromText will parse the XML directly from string. The XML needs to contain either a single <BehaviorTree> or specify the attribute [main_tree_to_execute].

Consider using instead registerBehaviorTreeFromText() and createTree().

Parameters

text	string containing the XML
blackboard	blackboard of the root tree

Returns

the newly created tree

instantiateTreeNode()

std::unique_ptr< TreeNode > BT::BehaviorTreeFactory::instantiateTreeNode	(	const std::string &	name,
		const std::string &	ID,
		const NodeConfig &	config
	)		const

instantiateTreeNode creates an instance of a previously registered TreeNode.

Parameters

name	name of this particular instance
ID	ID used when it was registered
config	configuration that is passed to the constructor of the TreeNode.

Returns

new node.

loadSubstitutionRuleFromJSON()

void BT::BehaviorTreeFactory::loadSubstitutionRuleFromJSON

(

const std::string &

json_text

)

loadSubstitutionRuleFromJSON will parse a JSON file to create a set of substitution rules. See Tutorial 11 for an example of the syntax.

Parameters

json_text

the JSON file as text (BOT the path of the file)

polymorphicCastRegistry()

PolymorphicCastRegistry & BT::BehaviorTreeFactory::polymorphicCastRegistry

(

)

Access the polymorphic cast registry.

The registry is shared with all trees created from this factory, allowing trees to outlive the factory while maintaining access to polymorphic cast relationships.

polymorphicCastRegistryPtr()

std::shared_ptr< PolymorphicCastRegistry > BT::BehaviorTreeFactory::polymorphicCastRegistryPtr

(

)

const

Get a shared pointer to the polymorphic cast registry.

This allows trees and blackboards to hold a reference to the registry that outlives the factory.

registerBehaviorTreeFromFile()

void BT::BehaviorTreeFactory::registerBehaviorTreeFromFile

(

const std::filesystem::path &

filename

)

registerBehaviorTreeFromFile. Load the definition of an entire behavior tree, but don't instantiate it. You can instantiate it later with:

BehaviorTreeFactory::createTree(tree_id)

where "tree_id" come from the XML attribute <BehaviorTree ID="tree_id">

registerBehaviorTreeFromText()

void BT::BehaviorTreeFactory::registerBehaviorTreeFromText

(

const std::string &

xml_text

)

Same of registerBehaviorTreeFromFile, but passing the XML text, instead of the filename.

registerBuilder()

void BT::BehaviorTreeFactory::registerBuilder	(	const TreeNodeManifest &	manifest,
		const NodeBuilder &	builder
	)

The most generic way to register a NodeBuilder.

Throws if you try to register twice a builder with the same registration_ID.

registeredBehaviorTrees()

std::vector< std::string > BT::BehaviorTreeFactory::registeredBehaviorTrees

(

)

const

Returns the ID of the trees registered either with registerBehaviorTreeFromFile or registerBehaviorTreeFromText.

registerFromPlugin()

void BT::BehaviorTreeFactory::registerFromPlugin

(

const std::string &

file_path

)

registerFromPlugin load a shared library and execute the function BT_REGISTER_NODES (see macro).

Parameters

file_path

path of the file

registerFromROSPlugins()

void BT::BehaviorTreeFactory::registerFromROSPlugins

(

)

registerFromROSPlugins finds all shared libraries that export ROS plugins for behaviortree_cpp, and calls registerFromPlugin for each library.

Exceptions

If	not compiled with ROS support or if the library cannot load for any reason

registerNodeType() [1/2]

template<typename T , typename... ExtraArgs>

void BT::BehaviorTreeFactory::registerNodeType ( const std::string &  ID, const PortsList &  ports, ExtraArgs...  args  )

inline

registerNodeType where you explicitly pass the list of ports. Doesn't require the implementation of static method providedPorts()

registerNodeType() [2/2]

template<typename T , typename... ExtraArgs>

void BT::BehaviorTreeFactory::registerNodeType ( const std::string &  ID, ExtraArgs...  args  )

inline

registerNodeType is the method to use to register your custom TreeNode.

It accepts only classed derived from either ActionNodeBase, DecoratorNode, ControlNode or ConditionNode.

registerPolymorphicCast()

template<typename Derived , typename Base >

void BT::BehaviorTreeFactory::registerPolymorphicCast ( )

inline

Register a polymorphic cast relationship between Derived and Base types.

This enables passing shared_ptr<Derived> to ports expecting shared_ptr<Base> without type mismatch errors. The relationship is automatically applied to all trees created from this factory.

Example: factory.registerPolymorphicCast<Cat, Animal>(); factory.registerPolymorphicCast<Sphynx, Cat>();

Template Parameters

Derived	The derived class (must inherit from Base)
Base	The base class (must be polymorphic)

registerScriptingEnum()

void BT::BehaviorTreeFactory::registerScriptingEnum	(	StringView	name,
		int	value
	)

Add an Enum to the scripting language. For instance if you do:

registerScriptingEnum("THE_ANSWER", 42),

You may type this in your scripts:

<Script code="myport:=THE_ANSWER" >

Parameters

name	string representation of the enum
value	its value.

registerScriptingEnums()

template<typename EnumType >

void BT::BehaviorTreeFactory::registerScriptingEnums ( )

inline

registerScriptingEnums is syntactic sugar to automatically register multiple enums. We use https://github.com/Neargye/magic_enum.

Please refer to https://github.com/Neargye/magic_enum/blob/master/doc/limitations.md for limitations.

registerSimpleAction()

void BT::BehaviorTreeFactory::registerSimpleAction	(	const std::string &	ID,
		const SimpleActionNode::TickFunctor &	tick_functor,
		PortsList	ports = {}
	)

registerSimpleAction help you register nodes of type SimpleActionNode.

Parameters

ID	registration ID
tick_functor	the callback to be invoked in the tick() method.
ports	if your SimpleNode requires ports, provide the list here.

registerSimpleCondition()

void BT::BehaviorTreeFactory::registerSimpleCondition	(	const std::string &	ID,
		const SimpleConditionNode::TickFunctor &	tick_functor,
		PortsList	ports = {}
	)

registerSimpleCondition help you register nodes of type SimpleConditionNode.

Parameters

ID	registration ID
tick_functor	the callback to be invoked in the tick() method.
ports	if your SimpleNode requires ports, provide the list here.

registerSimpleDecorator()

void BT::BehaviorTreeFactory::registerSimpleDecorator	(	const std::string &	ID,
		const SimpleDecoratorNode::TickFunctor &	tick_functor,
		PortsList	ports = {}
	)

registerSimpleDecorator help you register nodes of type SimpleDecoratorNode.

Parameters

ID	registration ID
tick_functor	the callback to be invoked in the tick() method.
ports	if your SimpleNode requires ports, provide the list here.

---

The documentation for this class was generated from the following file:

• include/behaviortree_cpp/bt_factory.h