CUGL 1.2
Cornell University Game Library
Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
cugl::ai::BehaviorNode Class Referenceabstract

#include <CUBehaviorNode.h>

Inheritance diagram for cugl::ai::BehaviorNode:
cugl::ai::CompositeNode cugl::ai::DecoratorNode cugl::ai::LeafNode cugl::ai::PriorityNode cugl::ai::RandomNode cugl::ai::SelectorNode cugl::ai::InverterNode cugl::ai::TimerNode

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 BehaviorNodegetParent () const
 
void setParent (BehaviorNode *parent)
 
void removeFromParent ()
 
int getParentalOffset () const
 
size_t getChildCount () const
 
std::vector< const BehaviorNode * > getChildren () const
 
const BehaviorNodegetChild (Uint32 pos) const
 
template<typename T >
const T * getChild (Uint32 pos) const
 
const BehaviorNodegetNodeByName (const std::string &name) const
 
const BehaviorNodegetNodeByName (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< BehaviorNoderemoveChild (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

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

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.

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

Deletes this node, disposing all resources.

Member Function Documentation

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
childThe child to add.
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
aThe first child
bThe second child
Returns
true if sibling a is has a larger priority than sibling b.
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.

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
posThe child position
Returns
a (weak) pointer to the child node at the given position.
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
posThe child position
Returns
a (weak) pointer to the child node at the given position.
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.
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.
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.
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
nameAn identifier to find the node.
Returns
the (first) node with the given name.
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
nameAn identifier to find the node.
Returns
the (first) node with the given name.
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
nameAn identifier to find the node.
Returns
the (first) node with the given name.
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
nameAn identifier to find the node.
Returns
the (first) node with the given name.
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.
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.
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.
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.
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.
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
nameThe name of the behavior node
Returns
true if initialization was successful.
cugl::ai::BehaviorNode::operator std::string ( ) const
inline

Cast from a BehaviorNode to a string.

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.

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.

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

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

Removes the child at the given position from this node.

Parameters
posThe position of the child node that will be removed.
Returns
the child removed at the given position
void cugl::ai::BehaviorNode::removeFromParent ( )
inline

Removes this node from its parent.

If this node has no parent, nothing happens.

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.

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.

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
parentThe parent of this node.
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
funcThe priority function for this node.
void cugl::ai::BehaviorNode::setPriority ( float  priority)

Sets the priority of this node.

Parameters
priorityThe priority of this node.
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
stateThe state of this node.

Reimplemented in cugl::ai::TimerNode.

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.

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

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
dtThe 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

int cugl::ai::BehaviorNode::_activeChild
protected

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

int cugl::ai::BehaviorNode::_childOffset
protected

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

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

The array of children for this composite node.

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

The name of this class (for debugging polymorphism).

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

The descriptive, identifying name of the node.

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

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

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

The current priority function for this behavior node.

float cugl::ai::BehaviorNode::_priority
protected

The current priority, or relevance of this node.

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

The current state of this node.


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