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

#include <bt_factory.h>

Classes
struct	PImpl

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

Public Member Functions
void	addMetadataToManifest (const std::string &node_id, const KeyValueVector &metadata)

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 diferent node type (already registered) instead. If the rule is a TestNodeConfig, a test node with that configuration will be created instead. More...

	BehaviorTreeFactory ()

	BehaviorTreeFactory (BehaviorTreeFactory &&other) noexcept=default

	BehaviorTreeFactory (const BehaviorTreeFactory &other)=delete

const std::unordered_map< std::string, NodeBuilder > &	builders () const
	All the builders. Made available mostly for debug purposes. More...

const std::set< std::string > &	builtinNodes () const
	List of builtin IDs. More...

void	clearRegisteredBehaviorTrees ()
	Clear previously-registered behavior trees. More...

void	clearSubstitutionRules ()

Tree	createTree (const std::string &tree_name, Blackboard::Ptr blackboard=Blackboard::create())

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]. More...

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]. More...

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. More...

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. More...

const std::unordered_map< std::string, TreeNodeManifest > &	manifests () const
	Manifests of all the registered TreeNodes. More...

BehaviorTreeFactory &	operator= (BehaviorTreeFactory &&other) noexcept=default

BehaviorTreeFactory &	operator= (const BehaviorTreeFactory &other)=delete

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: More...

void	registerBehaviorTreeFromText (const std::string &xml_text)

template<typename T >
void	registerBuilder (const std::string &ID, const NodeBuilder &builder)

void	registerBuilder (const TreeNodeManifest &manifest, const NodeBuilder &builder)

std::vector< std::string >	registeredBehaviorTrees () const

void	registerFromPlugin (const std::string &file_path)
	registerFromPlugin load a shared library and execute the function BT_REGISTER_NODES (see macro). More...

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

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)

void	registerScriptingEnum (StringView name, int value)
	Add an Enum to the scripting language. For instance if you do: More...

template<typename EnumType >
void	registerScriptingEnums ()
	registerScriptingEnums is syntactic sugar to automatically register multiple enums. We use https://github.com/Neargye/magic_enum. More...

void	registerSimpleAction (const std::string &ID, const SimpleActionNode::TickFunctor &tick_functor, PortsList ports={})
	registerSimpleAction help you register nodes of type SimpleActionNode. More...

void	registerSimpleCondition (const std::string &ID, const SimpleConditionNode::TickFunctor &tick_functor, PortsList ports={})
	registerSimpleCondition help you register nodes of type SimpleConditionNode. More...

void	registerSimpleDecorator (const std::string &ID, const SimpleDecoratorNode::TickFunctor &tick_functor, PortsList ports={})
	registerSimpleDecorator help you register nodes of type SimpleDecoratorNode. More...

const std::unordered_map< std::string, SubstitutionRule > &	substitutionRules () const
	substitutionRules return the current substitution rules. More...

bool	unregisterBuilder (const std::string &ID)
	Remove a registered ID. More...

	~BehaviorTreeFactory ()

Private Attributes
std::unique_ptr< PImpl >	_p

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.

Definition at line 209 of file bt_factory.h.

Member Typedef Documentation

◆ SubstitutionRule

using BT::BehaviorTreeFactory::SubstitutionRule = std::variant<std::string, TestNodeConfig>

Definition at line 473 of file bt_factory.h.

Constructor & Destructor Documentation

◆ BehaviorTreeFactory() [1/3]

BT::BehaviorTreeFactory::BehaviorTreeFactory ( )

Definition at line 43 of file bt_factory.cpp.

◆ ~BehaviorTreeFactory()

BT::BehaviorTreeFactory::~BehaviorTreeFactory ( )

Definition at line 110 of file bt_factory.cpp.

◆ BehaviorTreeFactory() [2/3]

BT::BehaviorTreeFactory::BehaviorTreeFactory ( const BehaviorTreeFactory & other )

delete

◆ BehaviorTreeFactory() [3/3]

BT::BehaviorTreeFactory::BehaviorTreeFactory ( BehaviorTreeFactory && other )

defaultnoexcept

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()

Definition at line 429 of file bt_factory.cpp.

◆ 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 diferent 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

Definition at line 464 of file bt_factory.cpp.

◆ builders()

const std::unordered_map< std::string, NodeBuilder > & BT::BehaviorTreeFactory::builders ( ) const

All the builders. Made available mostly for debug purposes.

Definition at line 368 of file bt_factory.cpp.

◆ builtinNodes()

const std::set< std::string > & BT::BehaviorTreeFactory::builtinNodes ( ) const

List of builtin IDs.

Definition at line 379 of file bt_factory.cpp.

◆ clearRegisteredBehaviorTrees()

void BT::BehaviorTreeFactory::clearRegisteredBehaviorTrees ( )

Clear previously-registered behavior trees.

Definition at line 276 of file bt_factory.cpp.

◆ clearSubstitutionRules()

void BT::BehaviorTreeFactory::clearSubstitutionRules ( )

Definition at line 459 of file bt_factory.cpp.

◆ createTree()

Tree BT::BehaviorTreeFactory::createTree	(	const std::string &	tree_name,
		Blackboard::Ptr	blackboard = `Blackboard::create()`
	)

Definition at line 421 of file bt_factory.cpp.

◆ 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

Definition at line 402 of file bt_factory.cpp.

◆ 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

Definition at line 384 of file bt_factory.cpp.

◆ 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.

Definition at line 281 of file bt_factory.cpp.

◆ 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)

Definition at line 469 of file bt_factory.cpp.

◆ manifests()

const std::unordered_map< std::string, TreeNodeManifest > & BT::BehaviorTreeFactory::manifests ( ) const

Manifests of all the registered TreeNodes.

Definition at line 374 of file bt_factory.cpp.

◆ operator=() [1/2]

BehaviorTreeFactory& BT::BehaviorTreeFactory::operator= ( BehaviorTreeFactory && other )

defaultnoexcept

◆ operator=() [2/2]

BehaviorTreeFactory& BT::BehaviorTreeFactory::operator= ( const BehaviorTreeFactory & other )

delete

◆ 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">

Definition at line 260 of file bt_factory.cpp.

◆ registerBehaviorTreeFromText()

void BT::BehaviorTreeFactory::registerBehaviorTreeFromText ( const std::string & xml_text )

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

Definition at line 266 of file bt_factory.cpp.

◆ registerBuilder() [1/2]

template<typename T >

void BT::BehaviorTreeFactory::registerBuilder	(	const std::string &	ID,
		const NodeBuilder &	builder
	)

inline

Definition at line 232 of file bt_factory.h.

◆ registerBuilder() [2/2]

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.

Definition at line 129 of file bt_factory.cpp.

◆ registeredBehaviorTrees()

std::vector< std::string > BT::BehaviorTreeFactory::registeredBehaviorTrees ( ) const

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

Definition at line 271 of file bt_factory.cpp.

◆ 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

Definition at line 181 of file bt_factory.cpp.

◆ 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

Definition at line 252 of file bt_factory.cpp.

◆ 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()

Definition at line 326 of file bt_factory.h.

◆ 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.

Definition at line 362 of file bt_factory.h.

◆ 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:

Parameters

name	string representation of the enum
value	its value.

Definition at line 440 of file bt_factory.cpp.

◆ 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.

Definition at line 462 of file bt_factory.h.

◆ 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.

Definition at line 155 of file bt_factory.cpp.

◆ 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.

Definition at line 142 of file bt_factory.cpp.

◆ 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.

Definition at line 168 of file bt_factory.cpp.

◆ substitutionRules()

const std::unordered_map< std::string, BehaviorTreeFactory::SubstitutionRule > & BT::BehaviorTreeFactory::substitutionRules ( ) const

substitutionRules return the current substitution rules.

Definition at line 518 of file bt_factory.cpp.

◆ unregisterBuilder()

bool BT::BehaviorTreeFactory::unregisterBuilder ( const std::string & ID )

Remove a registered ID.

Definition at line 113 of file bt_factory.cpp.

Member Data Documentation

◆ _p

std::unique_ptr<PImpl> BT::BehaviorTreeFactory::_p

private

Definition at line 504 of file bt_factory.h.

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

Classes

Public Types

Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ SubstitutionRule

Constructor & Destructor Documentation

◆ BehaviorTreeFactory() [1/3]

◆ ~BehaviorTreeFactory()

◆ BehaviorTreeFactory() [2/3]

◆ BehaviorTreeFactory() [3/3]

Member Function Documentation

◆ addMetadataToManifest()

◆ addSubstitutionRule()

◆ builders()

◆ builtinNodes()

◆ clearRegisteredBehaviorTrees()

◆ clearSubstitutionRules()

◆ createTree()

◆ createTreeFromFile()

◆ createTreeFromText()

◆ instantiateTreeNode()

◆ loadSubstitutionRuleFromJSON()

◆ manifests()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ registerBehaviorTreeFromFile()

◆ registerBehaviorTreeFromText()

◆ registerBuilder() [1/2]

◆ registerBuilder() [2/2]

◆ registeredBehaviorTrees()

◆ registerFromPlugin()

◆ registerFromROSPlugins()

◆ registerNodeType() [1/2]

◆ registerNodeType() [2/2]

◆ registerScriptingEnum()

◆ registerScriptingEnums()

◆ registerSimpleAction()

◆ registerSimpleCondition()

◆ registerSimpleDecorator()

◆ substitutionRules()

◆ unregisterBuilder()

Member Data Documentation

◆ _p