Warning: preg_replace(): Compilation failed: invalid range in character class at offset 4 in /home/customer/www/qualgame.com/public_html/wp-content/plugins/crayon-syntax-highlighter/crayon_langs.class.php on line 340
Behavior Tree | BtEngineSDK

Behavior Tree

Table of contents

1. Introduction
2. Terminology Definition
3. Behavior Tree Components
3.1 Tree Root Node
3.2 Composite Node
3.2.1 Selector Node
3.2.2 Sequence Node
3.2.3 Parallel Node
3.3 Decorator Node
3.4 Leaf Node
3.4.1 Condition Node
3.4.2 Action Node
4. Behavior Tree Operations
4.1 Play
4.2 Pause
4.3 Resume
4.4 Stop
4.5 Reset
4.6 Load
4.7 Destroy
5 Behavior Tree Properties
5.1 Tree Status
5.2 Basic Play Mode
5.3 Target Loop Count
5.4 Accumulated Loop Count
5.5 Tree Property Wrapper
6. References

1. Introduction

Behavior tree is a decision making system used in AI games to build the abilities of characters to decide what to do. Behavior tree has a lot in common with Hierarchy State Machine where the main building block is a state, and the change of states is triggered by events (event-driven), but instead of states, the main building block of a behavior tree is a task. Tasks are composed into sub-trees to represent complex actions. In turn, these complex actions can again be composed into higher level behaviors. Since all the tasks have a common interface and are largely self-contained, they can be easily built up into hierarchies, i.e., behavior trees, without having to worry about the details of how each sub-task in the hierarchy is implemented. We can consider that the root of the tree performs the top level task, i.e., the overall behavior. This top level task can be decomposed recursively into a hierarchy of sub-tasks (sub-trees) that accomplish simpler behaviors (tasks) that make up the whole. Since the whole tree is registered in a lookup table, the behavior logic can be accessed through out all the nodes in a data-driven way.

2. Terminology Definition

Based on the implementation of the behavior tree engine system, some terminologies were defined to explain the synchronization and how the system works.

Term Definition
Sub-tree Root Sub-tree The Tree Root Node and all the nodes below the Tree Root Node but no lower than any Parallel Nodes.
Parallel Node Child Sub-tree A child node of a Parallel Node and all the nodes below that child node but no lower than any Parallel Nodes.
Execute Execute refers to one of these tree operations: Play or Resume a tree.
When playing a tree, it starts execution from the sole child node of the Tree Root Node if it is a reset tree or a reported tree, otherwise, from the executing node(s) or the interrupted node(s). When resuming a tree, it starts execution from the interrupted node(s) as well as the executing node(s).
A parent node executes its sole child node if it is a Tree Root Node or a Decorator Node (top-down). A parent node executes the next child node if it is a Selector Node or a Sequence Node (top-down). A parent node executes the root nodes of all its reset child sub-trees, the executing nodes of all its notified executing child sub-trees, or the interrupted nodes of all its notified interrupt child sub-trees, concurrently if it is a Parallel Node (top-down). The execution traversal goes down to its child node(s).
Report A child node reports a node status of either Success or Failure to its parent node (bottom-up). The execution traversal goes up to its parent node. If the parent node is a Tree Root Node or a Decorator Node, it invokes its OnReport operation with a node status passed from its child node. If the parent node is a Selector Node or a Sequence Node, it either continues to execute the next child node or reports a node status to its parent node based on the reported node status. If the parent node is a Parallel Node, it waits until all of its executing child sub-trees either reports a node status from the root node of the child sub-tree or notifies termination from the current executing node of the child sub-tree and will report a node status to its parent node accordingly.
Notify Notify Executing When the OnExecute operation of a Decorator Node or the OnTest operation of a Condition Node returned a node status of Executing, the current executing node notifies executing to its lowest parent Parallel Node which, if non-terminated, will notify executing all the way up to the Tree Root Node, if it is in a Parallel Node child sub-tree, otherwise, to the Tree Root Node directly, to request one more execution (bottom-up). A sub-tree that notified executing will turn to a notified executing sub-tree, and the execution traversal of which will be suspended at the node that notified executing. The Tree Root Node that is notified executing will invoke its OnNotify operation.
Notify Interrupt When an executing sub-tree was interrupted, the current executing node notifies interrupt to its lowest parent Parallel Node which waits until the last executing child sub-tree notifies interrupt and will notify interrupt all the way up to the Tree Root Node, if it is in a Parallel Node child sub-tree, otherwise, to the Tree Root Node directly, to indicate that the executing sub-tree was no longer executing (bottom-up). A sub-tree that notified interrupt will turn to a notified interrupt sub-tree, and the execution traversal of which will be suspended at the node that notified interrupt. The Tree Root Node that is notified interrupt will invoke its OnNotify operation.
Notify Termination When an executing sub-tree was terminated, the current executing node notifies termination to its lowest parent Parallel Node to indicate that the executing sub-tree was no longer executing (bottom-up). A sub-tree that notified termination will turn to a notified termination sub-tree, and the execution traversal of which will be suspended at the node that notified termination.
 Interrupt Interrupt refers to one of these tree operations: Pause, Stop, Reset, or Destroy a tree.
When pausing, stopping, resetting, or destroying a tree, all executing sub-trees will be interrupted. The current executing node in each executing sub-tree will notify interrupt to its lowest parent Parallel Node which waits until the last executing child sub-tree notifies interrupt and will notify interrupt all the way up to the Tree Root Node, if it is in a Parallel Node child sub-tree, otherwise, to the Tree Root Node directly.
 Terminate When the first executing child sub-tree of a Parallel Node with Sequence Policy reported a node status of Success, or the first executing child sub-tree of a Parallel Node with Selector Policy reported a node status of Failure, the executing Parallel Node terminates all its other remaining executing child sub-trees. The current executing node in each executing child sub-tree will notify termination to the executing Parallel Node, which waits until the last executing child sub-tree notifies termination and will either report a corresponding node status to its parent node or notify termination to its lowest parent Parallel Node if which terminated the current sub-tree.
 Executing Sub-tree An executing sub-tree refers to a sub-tree that was executed, but
1. hasn’t reported a result node status from its root node to, or
2. hasn’t notified executing from an executing node, or
3. hasn’t notified interrupt from an interrupted node, or
4. hasn’t notified termination from a terminated node
to its lowest parent Parallel Node if it is a Parallel Node child sub-tree, otherwise, to the Tree Root Node.
 Reported Sub-tree reported sub-tree refers to an executing sub-tree that completes an execution traversal back to the root node of the sub-tree and reported a node status to the lowest parent Parallel Node if it is a Parallel Node child sub-tree, otherwise, the Tree Root Node, from the root node of the sub-tree.
Notified Executing Sub-tree A notified executing sub-tree refers to an executing sub-tree that notified executing from the OnExecute operation a Decorator Node or the OnTest operation of a Condition Node that returned a node status of Executing, or from a non-terminated executing Parallel Node which was notified executing from one of its notified executing child sub-tree, to the lowest parent Parallel Node if it is a Parallel Node child sub-tree, otherwise, to the Tree Root Node.
Notified Interrupt Sub-tree A notified interrupt sub-tree refers to an executing sub-tree that was interrupted and notified interrupt from the interrupted node to the lowest parent Parallel Node if it is a Parallel Node child sub-tree, otherwise, to the Tree Root Node.
 Notified termination Sub-tree notified termination sub-tree refers to an executing child sub-tree of a Parallel Node that was terminated and notified termination from the terminated node to the lowest parent Parallel Node.
 Reset Sub-tree When loading or resetting a tree, all sub-trees turns to reset sub-trees. A reset sub-tree also refers to a reported Parallel Node child sub-tree whose parent Parallel Node also reported a node status to the parent node.

3. Behavior Tree Components

There are several kinds of nodes in the behavior tree engine system: Tree Root Node, Composite Node (Selector Node, Sequence Node, Parallel Node), Decorator Node, and Leaf Node (Condition Node, Action Node). The concrete node types that can be instantiated  in the behavior tree engine system are Tree Root Node, Selector Node, Sequence Node, Parallel Node, Decorator Node, Condition Node, and Action Node. The concrete node types whose behaviors can be customized in Unity engine through scripting, i.e., whose member functions can be overridden in customized node scripts, are Tree Root Node, Decorator Node, Condition Node, and Action Node. These node types are all classes inherited from the UnityEngine.MonoBehaviour class that can can be updated by the Unity engine, as well as being looked up and invoked on their node operations when executing the behavior trees.

Abstract Node Type Definition Concrete Node Type
Tree Root Node A tree root node has no parent node and exactly one child node. Tree Root Node
Composite Node A composite node has exactly one parent node and at least one child node. Selector Node, Sequence Node, Parallel Node
Decorator Node A decorator node has exactly one parent node and exactly one child node. Decorator Node
Leaf Node A leaf node has exactly one parent node and no child node. Condition Node, Action Node

3.1. Tree Root NodeTreeRootNode

The Tree Root Node represents the entire behavior tree and can be considered as the top level task that the whole tree accomplishes. The TreeRootNode class is the representation of a Tree Root Node instance that performs corresponding responses on the Unity engine side. A list of node operations are defined to perform these responses accordingly.

Member Function Definition
OnExecute A node operation that is invoked when executing the tree.
OnReport A node operation that is invoked when the tree completes an execution traversal with a result status, i.e., when the Tree Root Node was reported a node status of Success or Failure from its child node.
OnNotify A node operation that is invoked when the tree execution traversal was suspended due to re-execution request or interruption, i.e., when the Tree Root Node was notified executing by an arbitrary Decorator Node or Condition Node whose OnExecute or OnTest operation returned a node status of Executing, or was notified interrupt by an arbitrary interrupted node when pausing, stopping, resetting or destroying an executing tree.
OnConstruct A node operation that is invoked when loading the tree.
OnDestruct A node operation that is invoked when destroying the tree.
OnPause A node operation that is invoked when pausing the tree.
OnStop A node operation that is invoked when stopping the tree.
OnReset A node operation that is invoked when resetting the tree.

Executing a Tree Root Node

Each time when executing a tree, the OnExecute operation of the Tree Root Node always gets invoked accordingly. When the execution thread completes a tree traversal by reporting a node status of Success or Failure from the child node of the Tree Root Node, the OnReport operation of the Tree Root Node gets invoked and passed a result node status of Success or Failure from its child node as a parameter. When the OnExecute operation of a Decorator Node or the OnTest operation of a Condition Node in the tree returned a node status of Executing to notify executing, the OnNotify operation of the Tree Root Node gets invoked and passed an executing node that requested one more execution. When pausing, stopping, resetting or destroying an executing tree, the OnNotify operation of the Tree Root Node gets invoked and passed an interrupted node that notified interrupt.

3.2. Composite Node

A Composite Node has at least one child node and can also have multiple child nodes. There are three types of it: Selector Node, Sequence Node, and Parallel Node.

3.2.1. Selector NodeSelectorNode

Selectors are used to choose the first of a set of possible actions that is successful.
~ Artificial Intelligence For Games, 2nd Edition

Executing a Selector Node

When executing a Selector Node, it always executes its child nodes starting from the leftmost one. It reports a node status of Success to its parent node when a child node reported a node status of Success to it. It continues to execute the next right child node when a child node reported a node status of Failure to it. It reports a node status of Failure to its parent node when all its child nodes reported a node status of Failure to itself.

3.2.2. Sequence NodeSequenceNode

Sequences represent a series of tasks that need to be undertaken.
~ Artificial Intelligence For Games, 2nd Edition

Executing a Sequence Node

When executing a Sequence Node, it always executes its child nodes starting from the leftmost one. It reports a node status of Failure to its parent node when a child node reported a node status of Failure to it. It continues to execute the next right child node when a child node reported a node status of Success to it. It reports a node status of Success to its parent node when all its child nodes reported a node status of Success to itself.

3.2.3. Parallel NodeParallelNode

The Parallel task acts in a similar way to the Sequence task. It has a set of child tasks, and it runs them until one of them fails. At that point, the Parallel task as a whole fails. If all of the child tasks complete successfully, the Parallel task returns with success. In this way, it is identical to the Sequence task and its non-deterministic variations.
The difference is the way it runs those tasks. Rather than running them one at a time, it runs them all simultaneously. We can think of it as creating a bunch of new threads, one per child, and setting the child tasks off together.
When one of the child tasks ends in failure, Parallel will terminate all of the other child threads that are still running. Just unilaterally terminating the threads could cause problems, leaving the game inconsistent or failing to free resources (such as acquired semaphores). The termination procedure is usually implemented as a request rather than a direct termination of the thread. In order for this to work, all the tasks in the behavior tree also need to be able to receive a termination request and clean up after themselves accordingly.
~ Artificial Intelligence For Games, 2nd Edition

Executing a Parallel Node

When executing a Parallel Node, it executes all its corresponding child sub-trees concurrently within individual threads, blocks the execution of the current sub-tree and waits for all its child sub-trees to complete their executions for synchronization. The execution order of each child sub-tree is arbitrary.

Parallel Node Status To Execute Situation Result
Reset Parallel Node The execution of a sub-tree reaches a Parallel Node from its parent node. Since all child sub-trees of a reset Parallel Node are reset child sub-trees, all child sub-trees get executed starting from their root nodes.
Notified Executing Parallel Node The execution of a sub-tree is currently blocked by a Parallel Node that notified executing. All notified executing child sub-trees get executed from their executing nodes.
Notified Interrupt Parallel Node The execution of a sub-tree is currently blocked by a Parallel Node that notified interrupt. All notified executing child sub-trees and all notified interrupt child sub-trees get executed from their executing nodes or interrupted nodes.

After executing a Parallel Node, it turns to an executing Parallel Node, and all those child sub-trees that were executed by their parent Parallel Node turn to executing child sub-trees.

Term Definition
Executing Parallel Node A Parallel Node that was executed, and at least one of its child sub-trees is an executing child sub-tree.

Notifying executing from a Parallel Node

When an executing child sub-tree notified executing to an executing Parallel Node without a determined node status based on the Parallel Node Policy, the Parallel Node notifies executing to its lowest parent Parallel Node and all the way up to the Tree Root Node if it is in a Parallel Node child sub-tree, otherwise, to to the Tree Root Node directly, to request one more execution.

Term Definition
Notified Executing Parallel Node An executing Parallel Node that was notified executing by one or multiple executing child sub-tree(s).

The sub-tree of the notified executing Parallel Node will turn to a notified executing sub-tree after all executing child sub-trees turn to notified executing sub-trees, reported sub-trees or notified termination sub-trees, as well as notifying executing to its lowest parent Parallel Node and all the way up to the Tree Root Node if it is a Parallel Node child sub-tree, otherwise, to the Tree Root Node directly.

Notifying interrupt from a Parallel Node

When an executing Parallel Node was interrupted, it interrupts all of its executing child sub-trees, waits until all of them notified interrupt to it and notifies interrupt to its lowest parent Parallel Node and all the way up to the Tree Root Node if it is in a Parallel Node child sub-tree, otherwise, to the Tree Root Node directly.

Term Definition
Notified Interrupt Parallel Node An executing Parallel Node that was interrupted, and whose executing child sub-trees turned to notified interrupt sub-trees.

The sub-tree of the notified interrupt Parallel Node will turn to a notified interrupt sub-tree after notifying interrupt to its lowest parent Parallel Node and all the way up to the Tree Root Node if it is a Parallel Node child sub-tree, otherwise, to the Tree Root Node directly.

Notifying termination from a Parallel Node

When an executing Parallel Node was terminated, it terminates all of its executing child sub-trees, waits until all of them notified termination to it and notifies termination to its lowest parent Parallel Node.

Term Definition
Notified Termination Parallel Node An executing Parallel Node that was terminated, and whose executing child sub-trees turned to notified termination sub-trees.

The sub-tree of the notified termination Parallel Node will turn to a notified termination sub-tree after notifying termination to its lowest parent Parallel Node.

Reporting from a Parallel Node

When at least one executing child sub-trees of an executing Parallel Node reported a node status and all the others either reported a node status or notified termination to it, the Parallel Node reports a corresponding node status to its parent node, based on the Parallel Node Policy.

Parallel Node Policy Definition
Sequence The Parallel Node reports a node status of Success to its parent node only when all its executing child sub-trees reported a node status of Success to it. As long as there is at least one executing child sub-tree that reported a node status of Failure to it, the Parallel Node’s status will be determined as Failure. Once a Parallel Node’s status was determined as Failure, it terminates all the remaining executing child sub-trees. After all the executing child sub-trees have either reported a node status or notified termination to it, the Parallel Node will report a node status of Failure to its parent node.
Selector The Parallel Node reports a node status of Failure to its parent node only when all its executing child sub-trees reported a node status of Failure to it. As long as there is at least one executing child sub-tree that reported a node status of Success to it, the Parallel Node’s status will be determined as Success. Once a Parallel Node’s status was determined as Success, it terminates all the remaining executing child sub-trees. After all the executing child sub-trees have either reported a node status or notified termination to it, the Parallel Node will report a node status of Success to its parent node.

When a Parallel Node reports a node status to its parent node, the execution of the current sub-tree continues to its parent node.

Term Definition
Reported Parallel Node A Parallel Node whose node status was determined based on Parallel Node Policy, and whose child sub-trees are at least one reported sub-tree and rest all reported sub-trees or notified termination sub-trees.
Reset Parallel Node A Parallel Node whose child sub-trees are all reset sub-trees, as well as a Parallel Node that reported a node status to its parent node.

3.3. Decorator NodeDecoratorNode

Decorator is a type of task that has one single child task and modifies its behavior in some way. We could think of it like a composite task with a single child. One simple and very common category of Decorator makes a decision whether to allow their child behavior to run or not (they are sometimes called “filters”). If they allow the child behavior to run, then whatever status code it returns is used as the result of the filter. If they don’t allow the child behavior to run, then they normally return in Failure, so a Selector can choose an alternative action.
~ Artificial Intelligence For Games, 2nd Edition

The DecoratorNode class is the representation of a Decorator Node instance that performs corresponding responses on the Unity engine side. A list of node operations are defined to perform these responses accordingly.

Member Function Definition
OnExecute A node operation that is invoked when executing the Decorator Node, or when the OnReport operation returned a node status of Executing.
OnReport A node operation that is invoked when the Decorator Node was reported a node status of Success or Failure from its child node, or was reported a node status of Executing from the OnExecute operation that had returned a node status of Failure.
OnConstruct A node operation that is invoked when loading the tree.
OnDestruct A node operation that is invoked when destroying the tree.
OnReset A node operation that is invoked when resetting the tree.
OnPause A node operation that is invoked when pausing the tree.
OnStop A node operation that is invoked when stopping the tree.

Executing a Decorator Node

When executing a Decorator Node, the OnExecute operation of the Decorator Node gets invoked. When the child node of a Decorator Node reported a node status to it, the OnReport operation of the Decorator Node gets invoked with a result node status from its child node. In order to enable the capability of a Decorator Node to modify the behavior of its child task, the behaviors of OnExecute and OnReport operations can be changed based on the returned node status.

Operation Behaviors Based On The Returned Node Status
OnExecute If a node status of Success was returned, the Decorator Node continues to execute its child node; if a node status of Failure was returned, the Decorator Node reports a node status of Executing to itself by invoking the Decorator Node’s OnReport operation with a node status of Executing; if a node status of Executing was returned, the Decorator Node notifies executing to the lowest parent Parallel Node if it is in a Parallel Node child sub-tree and all the way up to the Tree Root Node, otherwise, to the Tree Root Node directly, to request one more execution and get invoked again.
OnReport If a node status of Success or Failure was returned, the Decorator Node reports the result node status to its parent node; if a node status of Executing was returned, the Decorator Node continues to execute itself by invoking the OnExecute operation.

In this way, the child task behavior can be completely customized by the Decorator Node. There are several standard filters that are useful which can be realized with a Decorator Node. For example, we can use a Decorator Node to limit the number of times a task can be run, and we can also keep running a task in a loop until it fails.

3.4. Leaf Node

A Leaf Node has no child node under it. There are two types of a Leaf Node: Condition Node and Action Node. A Condition Node is used to check some conditions for decision making and branching in the behavior tree execution traversal. As a consequence, a Condition Node is able to report a node status of either Success or Failure to its parent node to indicate the result of performing the node task. On the other hand, an Action Node is used to perform some certain task where the result is not important so that the reported node status won’t affect branching in the behavior tree execution traversal.

3.4.1. Condition NodeConditionNode

Conditions test some property of the game.
~ Artificial Intelligence For Games, 2nd Edition

The ConditionNode class is the representation of a Condition Node instance that performs corresponding responses on the Unity engine side. A list of node operations are defined to perform these responses accordingly.

Member Function Definition
OnTest A node operation that is invoked when executing the Condition Node.
OnConstruct A node operation that is invoked when loading the tree.
OnDestruct A node operation that is invoked when destroying the tree.
OnReset A node operation that is invoked when resetting the tree.
OnPause A node operation that is invoked when pausing the tree.
OnStop A node operation that is invoked when stopping the tree.

Executing a Condition Node

When executing a Condition Node, the OnTest operation of the Condition Node gets invoked. It returns a node status of Success of Failure to its parent node to indicate the test result of some property of the game. If the property cannot be determined at this time, it returns a node status of Executing to request one more execution and get invoked again.

Operation Behaviors Based On The Returned Node Status
OnTest If a node status of Success or a Failure was returned, the Condition Node reports the result node status to its parent node. If a node status of Executing was returned, the Condition Node notifies executing to the lowest parent Parallel Node if it is in a Parallel Node child sub-tree and all the way up to the Tree Root Node, otherwise, to the Tree Root Node directly, to request one more execution and get invoked again.

In this way, some property of the game can be queried and the decision path can be branched in the behavior tree based on the result node status.

3.4.2. Action NodeActionNode

Actions alter the state of the game.
~ Artificial Intelligence For Games, 2nd Edition

The ActionNode class is the representation of an Action Node instance that performs corresponding responses on the Unity engine side. A list of node operations are defined to perform these responses accordingly.

Member Function Definition
OnStep A node operation that is invoked when executing the Action Node.
OnConstruct A node operation that is invoked when loading the tree.
OnDestruct A node operation that is invoked when destroying the tree.
OnReset A node operation that is invoked when resetting the tree.
OnPause A node operation that is invoked when pausing the tree.
OnStop A node operation that is invoked when stopping the tree.

Executing an Action Node

When executing an Action Node, the OnStep operation of the ActionNode class gets invoked.

Action Node Policy

The only difference between Action Node and Condition Node is that Action Node only performs some task without making decisions based on the task it performs. Therefore, the Action Node always reports a fixed node status to its parent node regardless of the result of the task it performs. The Action Node Policy defines the fixed node status it reports to its parent node.

Action Node Policy Definition
Success The Action Node always reports a node status of Success to its parent node after the OnStep operation returns.
Failure The Action Node always reports a node status of Failure to its parent node after the OnStep operation returns.

4. Behavior Tree Operations

Behavior tree operations can be invoked through the group tree operations at engine level or forest level, or the single tree operations, of Bt Engine scripting API.

Based on the implementation, some terminologies were defined to explain the synchronization and how the system works.

Term Definition
Executing Tree An executing tree refers to a tree whose root sub-tree is an executing sub-tree.
Notified Executing Tree A notified executing tree refers to a tree whose root sub-tree is a notified executing sub-tree.
Notified Interrupt Tree A notified interrupt tree refers to a tree whose root sub-tree is a notified interrupt sub-tree.
Reported Tree A reported tree refers to a tree whose root sub-tree is a reported sub-tree.
Reset Tree A reset tree refers to a tree whose root sub-tree is a reset sub-tree.

4.1 Play

Start to execute the tree in a loop with the accumulated loop count reset to 0. The execution traversal starts from the sole child node of the Tree Root Node when executing a reset tree or a reported tree. It starts from the executing node(s) when executing a notified executing tree. It starts from the interrupted node(s) as well as the executing node(s) when executing a notified interrupt tree. Refer to the Bt Engine API of tree operations – BtEngine.Play.

4.2 Pause

Pause the tree. Pausing an executing tree interrupts all the remaining executing sub-tree(s). The Tree Root Node will be notified interrupt from an interrupted node by invoking its OnNotify operation, and the executing tree will turn to a notified interrupt tree. Pausing a notified executing tree, notified interrupt treereported tree or reset tree won’t interrupt anything. All node’s OnPause operations will then be invoked in the depth-first traversal order. Refer to the Bt Engine API of tree operations – BtEngine.Pause.

4.3 Resume

Resume to execute the tree if it was paused with its remaining loop count. The execution traversal starts from the interrupted node(s) as well as the executing node(s). Refer to the Bt Engine API of tree operations – BtEngine.Resume.

4.4 Stop

Stop the tree. Stopping an executing tree interrupts all the remaining executing sub-tree(s). The Tree Root Node will be notified interrupt from an interrupted node by invoking its OnNotify operation, and the executing tree will turn to a notified interrupt tree. Stopping a notified executing tree, notified interrupt treereported tree or reset tree won’t interrupt anything. All node’s OnStop operations will then be invoked in the depth-first traversal order. Refer to the Bt Engine API of tree operations – BtEngine.Stop.

4.5 Reset

Reset the tree. Resetting an executing tree interrupts all the remaining executing sub-tree(s). The Tree Root Node will be notified interrupt from an interrupted node by invoking its OnNotify operation, the executing tree will turn to a reset tree. Resetting a notified executing tree, notified interrupt treereported tree or reset tree won’t interrupt anything. All node’s OnReset operations will then be invoked in the depth-first traversal order. Refer to the Bt Engine API of tree operations – BtEngine.Reset.

4.6 Load

Instantiate the tree(s) whose instance(s) don’t exist from the corresponding forest xml and tree xml files. All node’s OnConstruct operations will then be invoked in the depth-first traversal order. Refer to the Bt Engine API of tree operations – BtEngine.Load.

4.7 Destroy

Destroy the tree instance(s). All node’s OnDestruct operations will then be invoked in the depth-first traversal order. Refer to the Bt Engine API of tree operations – BtEngine.Destroy.

5. Behavior Tree Properties

5.1 Tree Status

Based on the tree operations, the behavior tree can have these statuses: Destructed, Played, Resumed, Executing, Paused, Stopped, Reset.

Tree Status Definition
Destructed The tree instance was destroyed.
Played The tree instance was started to execute.
Resumed The tree instance was resumed to execute.
Executing The tree instance is executing without completing the target loop count.
Paused The tree instance was paused.
Stopped The tree instance was stopped or completed the target loop count.
Reset The tree instance was loaded or reset.

Refer to the Bt Engine API of tree properties – BtEngine.GetTreeStatus.

5.2 Basic Play Mode

Basic play mode specifies the way to count loop number and stop execution. Seven basic play modes are provided to execute a tree in a loop with an associated target loop count: StopByExecuteLoopCount, StopByReportLoopCount, StopByReportSuccessLoopCount, StopByReportFailureLoopCount, StopByNotifyLoopCount, StopByNotifyExecutingLoopCount, StopByNotifyInterruptLoopCount.

Basic Play Mode Definition
StopByExecuteLoopCount Stop executing a tree when it has executed for certain number of loops as specified by the target loop count.
StopByReportLoopCount Stop executing a tree when it has reported either success or failure for certain number of loops as specified by the target loop count.
StopByReportSuccessLoopCount Stop executing a tree when it has reported success for certain number of loops as specified by the target loop count.
StopByReportFailureLoopCount Stop executing a tree when it has reported failure for certain number of loops as specified by the target loop count.
StopByNotifyLoopCount Stop executing a tree when it has notified either executing or interrupt for certain number of loops as specified by the target loop count.
StopByNotifyExecutingLoopCount Stop executing a tree when it has notified executing for certain number of loops as specified by the target loop count.
StopByNotifyInterruptLoopCount Stop executing a tree when it has notified interrupt for certain number of loops as specified by the target loop count.

Refer to Bt Engine API of tree properties – BtEngine.GetBasicPlayMode.

5.3 Target Loop Count

A target loop count can be specified when playing a tree with an associated basic play mode. Refer to Bt Engine API of tree properties – BtEngine.GetTgtLoopCount.

5.4 Accumulated Loop Count

The accumulated loop count of a tree as specified by the basic play mode. Refer to Bt Engine API of tree properties – BtEngine.GetAccuLoopCount.

5.5 Tree Property Wrapper

The properties of a tree instance can be queried from a tree property wrapper. The tree property wrapper is a wrapper that contains the properties from the tree level down to the node level. The depth level of the tree property wrapper can also be specified when acquiring the property wrapper from the tree property wrapper operation of the Bt Engine API. The tree property wrapper enables users to iterate through all properties of those node instances under a particular tree instance. Refer to Bt Engine API of tree properties – BtEngine.GetTreePropWrap.

6. References

1. Ian Millington and John Funge. Artificial Intelligence for Games, 2nd Edition. Morgan Kaufmann, 2009.