#include <CUBehaviorNode.h>

Inheritance diagram for cugl::ai::BehaviorNode:

Public Types
enum	State : unsigned int { State::INACTIVE = 0, State::RUNNING = 1, State::PAUSED = 2, State::FINISHED = 3 }

Public Member Functions
	BehaviorNode ()

	~BehaviorNode ()

bool	init (const std::string &name)

virtual void	dispose ()

const std::string &	getName () const

float	getPriority () const

BehaviorNode::State	getState () const

virtual void	setState (BehaviorNode::State state)

std::function< float()>	getPrioritizer () const

void	setPrioritizer (const std::function< float()> &func)

virtual std::string	toString (bool verbose=false) const

	operator std::string () const

const BehaviorNode *	getParent () const

void	setParent (BehaviorNode *parent)

void	removeFromParent ()

int	getParentalOffset () const

size_t	getChildCount () const

std::vector< const BehaviorNode * >	getChildren () const

const BehaviorNode *	getChild (Uint32 pos) const

template<typename T >
const T *	getChild (Uint32 pos) const

const BehaviorNode *	getNodeByName (const std::string &name) const

const BehaviorNode *	getNodeByName (const char *name) const

template<typename T >
const T *	getNodeByName (const std::string &name) const

template<typename T >
const T *	getNodeByName (const char *name) const

virtual void	reset ()

virtual void	pause ()

virtual void	resume ()

virtual void	preempt ()

virtual void	start ()

virtual void	query (float dt)=0

virtual BehaviorNode::State	update (float dt)=0

void	setPriority (float priority)

std::shared_ptr< BehaviorNode >	removeChild (Uint32 pos)

void	addChild (const std::shared_ptr< BehaviorNode > child)

Static Public Member Functions
static bool	compareSiblings (const std::shared_ptr< BehaviorNode > &a, const std::shared_ptr< BehaviorNode > &b)

Protected Attributes
std::string	_name

std::string	_classname

BehaviorNode *	_parent

BehaviorNode::State	_state

float	_priority

std::function< float()>	_prioritizer

std::vector< std::shared_ptr< BehaviorNode > >	_children

int	_activeChild

int	_childOffset

Detailed Description

An abstract class for a behavior tree node.

This class is a base class for the individual nodes of the behavior tree. Behavior tree nodes are either composite, decorator, or leaf nodes. A leaf node has no children, a decorator has only one, and a composite has one or more. Only leaf nodes have actions attached.

A behavior tree is a construction of behavior nodes. The top node without a parent is the the root of the tree. The tree chooses the action to run based on the priority value of each of the root's descendents. The tree must use an update function to run on each tick, updating the state of each node. The root node of a behavior tree returns the state of the selected leaf node to run.

This class has abstract methods for calculating the priority and updating, which are implemented by the subclasses.

Behavior trees should be managed by a BehaviorManager, which creates each BehaviorNode from a BehaviorNodeDef and runs and updates the behavior trees. While in the BehaviorManager, a behavior tree cannot be modified by any outside methods and any references to the nodes of the behavior tree will be constant.

Member Enumeration Documentation

◆ State

enum cugl::ai::BehaviorNode::State : unsigned int

strong

An enumeration indicating the current state of the tree node.

Behaviors are long running, across multiple animation frames. Therefore, we need to track them in the same way that we would track an audio asset.

Enumerator
INACTIVE	The node is neither running nor has already finished with an action.
RUNNING	The node is active and currently running.
PAUSED	The node is active but currently paused.
FINISHED	The node is finished with an action.

Constructor & Destructor Documentation

◆ BehaviorNode()

cugl::ai::BehaviorNode::BehaviorNode ( )

Creates an uninitialized behavior tree node.

You should never call this constructor directly. Instead, you should allocate a node with the BehaviorManager instance.

◆ ~BehaviorNode()

cugl::ai::BehaviorNode::~BehaviorNode ( )

inline

Deletes this node, disposing all resources.

Member Function Documentation

◆ addChild()

void cugl::ai::BehaviorNode::addChild ( const std::shared_ptr< BehaviorNode > child )

Adds the child at the end of the child list of this node.

Parameters

child The child to add.

◆ compareSiblings()

static bool cugl::ai::BehaviorNode::compareSiblings	(	const std::shared_ptr< BehaviorNode > &	a,
		const std::shared_ptr< BehaviorNode > &	b
	)

static

Returns true if sibling a has a larger priority than sibling b.

This method is used by std::sort to sort the children. Ties are broken from the offset of the children.

Parameters

a	The first child
b	The second child

Returns: true if sibling a is has a larger priority than sibling b.

◆ dispose()

virtual void cugl::ai::BehaviorNode::dispose ( )

virtual

Disposes all of the resources used by this node, including any descendants.

A disposed node can be safely reinitialized. Any children owned by this node will be released. They will be deleted if no other object owns them. This method should only be called by BehaviorManager.

Reimplemented in cugl::ai::RandomNode, cugl::ai::CompositeNode, cugl::ai::TimerNode, and cugl::ai::LeafNode.

◆ getChild() [1/2]

const BehaviorNode* cugl::ai::BehaviorNode::getChild ( Uint32 pos ) const

Returns a (weak) pointer to the child node at the given position.

The purpose of this pointer is to allow access to the subtree of a behavior tree. It does not grant ownership, as ownership is confined to BehaviorManager.

Parameters

pos	The child position

Returns: a (weak) pointer to the child node at the given position.

◆ getChild() [2/2]

template<typename T >

const T* cugl::ai::BehaviorNode::getChild ( Uint32 pos ) const

inline

Returns a (weak) pointer to the child node at the given position.

The purpose of this pointer is to allow access to the subtree of a behavior tree. It does not grant ownership, as ownership is confined to BehaviorManager.

This version of the method performs a dynamic typecast to the correct type.

Parameters

pos	The child position

Returns: a (weak) pointer to the child node at the given position.

◆ getChildCount()

size_t cugl::ai::BehaviorNode::getChildCount ( ) const

inline

Returns the number of children of this composite node.

Returns: The number of children of this composite node.

◆ getChildren()

std::vector<const BehaviorNode*> cugl::ai::BehaviorNode::getChildren ( ) const

Returns the list of (weak) references to the node's children.

The purpose of this collection is to allow access to the subtree of a behavior tree. It does not grant ownership, as ownership is confined to BehaviorManager.

Returns: the list of (weak) references the node's children.

◆ getName()

const std::string& cugl::ai::BehaviorNode::getName ( ) const

inline

Returns a string that is used to identify the node.

This name is used to identify nodes in a behavior tree. It is used by the BehaviorManager to access this node.

Returns: a string that is used to identify the node.

◆ getNodeByName() [1/4]

const BehaviorNode* cugl::ai::BehaviorNode::getNodeByName ( const char * name ) const

inline

Returns the (first) node with the given name.

This method performs a recursive search down the behavior tree. If there is more than one node with the given name, it returns the first one that is found in an unspecified search order. As a result, names should be unique for best results.

The purpose of this pointer is to allow access to the subtree of a behavior tree. It does not grant ownership, as ownership is confined to BehaviorManager.

Parameters

name	An identifier to find the node.

Returns: the (first) node with the given name.

◆ getNodeByName() [2/4]

template<typename T >

const T* cugl::ai::BehaviorNode::getNodeByName ( const char * name ) const

inline

Returns the (first) node with the given name.

This method performs a recursive search down the behavior tree. If there is more than one node with the given name, it returns the first one that is found in an unspecified search order. As a result, names should be unique for best results.

The purpose of this pointer is to allow access to the subtree of a behavior tree. It does not grant ownership, as ownership is confined to BehaviorManager.

This version of the method performs a dynamic typecast to the correct type.

Parameters

name	An identifier to find the node.

Returns: the (first) node with the given name.

◆ getNodeByName() [3/4]

const BehaviorNode* cugl::ai::BehaviorNode::getNodeByName ( const std::string & name ) const

Returns the (first) node with the given name.

This method performs a recursive search down the behavior tree. If there is more than one node with the given name, it returns the first one that is found in an unspecified search order. As a result, names should be unique for best results.

The purpose of this pointer is to allow access to the subtree of a behavior tree. It does not grant ownership, as ownership is confined to BehaviorManager.

Parameters

name	An identifier to find the node.

Returns: the (first) node with the given name.

◆ getNodeByName() [4/4]

template<typename T >

const T* cugl::ai::BehaviorNode::getNodeByName ( const std::string & name ) const

inline

Returns the (first) node with the given name.

This method performs a recursive search down the behavior tree. If there is more than one node with the given name, it returns the first one that is found in an unspecified search order. As a result, names should be unique for best results.

The purpose of this pointer is to allow access to the subtree of a behavior tree. It does not grant ownership, as ownership is confined to BehaviorManager.

This version of the method performs a dynamic typecast to the correct type.

Parameters

name	An identifier to find the node.

Returns: the (first) node with the given name.

◆ getParent()

const BehaviorNode* cugl::ai::BehaviorNode::getParent ( ) const

inline

Returns a (weak) pointer to the parent node.

The purpose of this pointer is to climb back up the behavior tree. No child asserts ownership of its parent.

Returns: a (weak) pointer to the parent node.

◆ getParentalOffset()

int cugl::ai::BehaviorNode::getParentalOffset ( ) const

inline

Returns the offset of this behavior tree node within its parent node.

If this node is a root node, it will return -1.

Returns: The child offset of this behavior node.

◆ getPrioritizer()

std::function<float()> cugl::ai::BehaviorNode::getPrioritizer ( ) const

inline

Returns the priority function for this node.

This function should return a value between 0 and 1 representing the priority. When this function is defined, it overrides the rules that this node uses for defining its priority in query.

Returns: the priority function for this node.

◆ getPriority()

float cugl::ai::BehaviorNode::getPriority ( ) const

inline

Returns the current priority of this node.

This priority value is used to determine the relevance of a node in comparison to other nodes. This value is between 0 and 1. Higher priority nodes are more likely to be selected. It will be updated each time query is called.

Returns: a float that signifies the priority of this behavior tree node.

◆ getState()

BehaviorNode::State cugl::ai::BehaviorNode::getState ( ) const

inline

Returns the state of this node.

If this node has no parent, then this is the state of the behavior tree.

Returns: the state of this node.

◆ init()

bool cugl::ai::BehaviorNode::init ( const std::string & name )

Initializes a behavior tree node with the given name.

You should never call this method directly. Instead, you should initialize a node with the BehaviorManager instance.

Parameters

name	The name of the behavior node

Returns: true if initialization was successful.

◆ operator std::string()

cugl::ai::BehaviorNode::operator std::string ( ) const

inline

Cast from a BehaviorNode to a string.

◆ pause()

virtual void cugl::ai::BehaviorNode::pause ( )

virtual

Pauses this running node and all running nodes below it in the tree.

A paused node can be resumed later. This method has no effect on values stored within nodes, and values (such as priority or timer delay) will not be updated while nodes are paused.

Reimplemented in cugl::ai::LeafNode.

◆ preempt()

virtual void cugl::ai::BehaviorNode::preempt ( )

virtual

Stops this node from running.

This method also stops any running nodes under this one if they exist.

Reimplemented in cugl::ai::TimerNode, and cugl::ai::LeafNode.

◆ query()

virtual void cugl::ai::BehaviorNode::query ( float dt )

pure virtual

Updates the priority value(s) for this node.

This method recursively determines the priority of this node and all of its children. The priority may be determined by a user-provided priority function or by the default priority function of the class.

When this method is complete, it will chose a child node to run, but will not run it. Unlike update, this method is guaranteed to run every time step in BehaviorManager, provided that the root node is running.

Parameters

dt	The elapsed time since the last frame.

Implemented in cugl::ai::TimerNode, cugl::ai::CompositeNode, cugl::ai::RandomNode, cugl::ai::LeafNode, cugl::ai::DecoratorNode, and cugl::ai::InverterNode.

◆ removeChild()

std::shared_ptr<BehaviorNode> cugl::ai::BehaviorNode::removeChild ( Uint32 pos )

Removes the child at the given position from this node.

Parameters

pos	The position of the child node that will be removed.

Returns: the child removed at the given position

◆ removeFromParent()

void cugl::ai::BehaviorNode::removeFromParent ( )

inline

Removes this node from its parent.

If this node has no parent, nothing happens.

◆ reset()

virtual void cugl::ai::BehaviorNode::reset ( )

virtual

Resets this node and all nodes below it to an uninitialized state.

This method also resets any class values to those set at the start of the tree. This method allows the node to be started again, as if it had not been run before.

Reimplemented in cugl::ai::TimerNode, and cugl::ai::LeafNode.

◆ resume()

virtual void cugl::ai::BehaviorNode::resume ( )

virtual

Resumes a paused node and all paused nodes below it in the tree.

Values such as priority or timer delay will not have been updated while the node was paused.

Reimplemented in cugl::ai::LeafNode.

◆ setParent()

void cugl::ai::BehaviorNode::setParent ( BehaviorNode * parent )

inline

Sets the parent of this node.

The purpose of this pointer is to climb back up the behavior tree. No child asserts ownership of its parent.

Parameters

parent The parent of this node.

◆ setPrioritizer()

void cugl::ai::BehaviorNode::setPrioritizer ( const std::function< float()> & func )

inline

Sets the priority function for this node.

This function should return a value between 0 and 1 representing the priority. When this function is defined, it overrides the rules that this node uses for defining its priority in query.

Parameters

func	The priority function for this node.

◆ setPriority()

void cugl::ai::BehaviorNode::setPriority ( float priority )

Sets the priority of this node.

Parameters

priority The priority of this node.

◆ setState()

virtual void cugl::ai::BehaviorNode::setState ( BehaviorNode::State state )

virtual

Sets the state of this node.

If this node has no parent, then this is the state of the behavior tree.

Parameters

state The state of this node.

Reimplemented in cugl::ai::TimerNode.

◆ start()

virtual void cugl::ai::BehaviorNode::start ( )

virtual

Initializes this node for execution.

When called this node moves from an uninitialized state to one where the update() function is safe to be called.

◆ toString()

virtual std::string cugl::ai::BehaviorNode::toString ( bool verbose = false ) const

virtual

Returns a string representation of this node for debugging purposes.

If verbose is true, the string will include class information. This allows us to unambiguously identify the class.

Parameters

verbose Whether to include class information.

Returns: a string representation of this node for debugging purposes.

Reimplemented in cugl::ai::RandomNode, cugl::ai::TimerNode, and cugl::ai::LeafNode.

◆ update()

virtual BehaviorNode::State cugl::ai::BehaviorNode::update ( float dt )

pure virtual

Updates this node and any active children.

This method runs the update function, which executes to active child (if not a leaf) or the associated action (if a leaf). This method is not guaranteed to execute every time step; only if the node is the root of the tree or is selected as part of the active path.

If a node is not a leaf node and it has no active children, then the method will return INACTIVE.

Parameters

dt	The elapsed time since the last frame.

Returns: the state of this node after updating.

Implemented in cugl::ai::TimerNode, cugl::ai::CompositeNode, cugl::ai::LeafNode, and cugl::ai::DecoratorNode.

Member Data Documentation

◆ _activeChild

int cugl::ai::BehaviorNode::_activeChild

protected

The index of the child running (-1 if no child is currently running).

◆ _childOffset

int cugl::ai::BehaviorNode::_childOffset

protected

The (current) child offset of this node (-1 if root)

◆ _children

std::vector<std::shared_ptr<BehaviorNode> > cugl::ai::BehaviorNode::_children

protected

The array of children for this composite node.

◆ _classname

std::string cugl::ai::BehaviorNode::_classname

protected

The name of this class (for debugging polymorphism).

◆ _name

std::string cugl::ai::BehaviorNode::_name

protected

The descriptive, identifying name of the node.

◆ _parent

BehaviorNode* cugl::ai::BehaviorNode::_parent

protected

A weaker pointer to the parent (or null if root).

◆ _prioritizer

std::function<float()> cugl::ai::BehaviorNode::_prioritizer

protected

The current priority function for this behavior node.

◆ _priority

float cugl::ai::BehaviorNode::_priority

protected

The current priority, or relevance of this node.

◆ _state

BehaviorNode::State cugl::ai::BehaviorNode::_state

protected

The current state of this node.

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

include/cugl/ai/behavior/CUBehaviorNode.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ State

Constructor & Destructor Documentation

◆ BehaviorNode()

◆ ~BehaviorNode()

Member Function Documentation

◆ addChild()

◆ compareSiblings()

◆ dispose()

◆ getChild() [1/2]

◆ getChild() [2/2]

◆ getChildCount()

◆ getChildren()

◆ getName()

◆ getNodeByName() [1/4]

◆ getNodeByName() [2/4]

◆ getNodeByName() [3/4]

◆ getNodeByName() [4/4]

◆ getParent()

◆ getParentalOffset()

◆ getPrioritizer()

◆ getPriority()

◆ getState()

◆ init()

◆ operator std::string()

◆ pause()

◆ preempt()

◆ query()

◆ removeChild()

◆ removeFromParent()

◆ reset()

◆ resume()

◆ setParent()

◆ setPrioritizer()

◆ setPriority()

◆ setState()

◆ start()

◆ toString()

◆ update()

Member Data Documentation

◆ _activeChild

◆ _childOffset

◆ _children

◆ _classname

◆ _name

◆ _parent

◆ _prioritizer

◆ _priority

◆ _state