Behavior Tree Engine
Table of contents
1. Introduction
2. Engine Operations
2.1 Start
2.2 Update
2.3 Shut down
3. Engine Properties
3.1 Forest XML File
3.2 Parallel Operation
3.3 Engine Property Wrapper
4. Tree/Forest Execution Operations
5. Tree/Forest Interruption Operations
6. Tree/Forest Property Querying Operations
The behavior tree engine, Bt Engine, is the top level of the entire behavior tree engine system. Externally, Bt Engine provides a scripting API for users to manage, control, and access all of the engine, forest, tree, and node instances and their properties that are running behind the Unity Engine. Internally, Bt Engine manages multiple threads to perform synchronized tree execution and interruption tasks. The behavior tree execution and interruption operations in Bt Engine are all asynchronous, that is, the calling thread from Unity Engine, e.g., the Update function, is always non-blocking and won’t actually do the execution or interruption work but just send a task to an operation queue. An operation thread in Bt Engine always checks the operation queue and all tree instances’ statuses, and then dispatch operations to corresponding trees accordingly in a first-in-first-out order. When performing tree execution operations from the operation queue, since there is always a tree specific execution thread for each tree instance, these operations are always non-blocking. However, when performing tree interruption operations from the operation queue, they might cause delay of invocation on later operations from the operation queue for other trees since an interruption has to wait until all nodes under the target behavior tree to return. Therefore, a parallel operation option in Bt Engine is provided to enable tree specific operation queues to perform tree specific blocking operations. In this way with trading more resources, there won’t be any delay of invocation on operations for different trees.
In order to implement Parallel Node and asynchronous tree executions and interruptions, Bt Engine was implemented fully multi-threaded. As a result, there must be some performance overhead as expected. Users should take care on their own to evaluate this cost when employing Bt Engine as their AI framework.
Start Bt Engine. All of the trees and forests can only be loaded and executed after Bt Engine was started. The behavior forest file and parallel operation can only be set before Bt Engine was started. Refer to Bt Engine API of engine operations – BtEngine.Start.
Update Bt Egnine. Refer to Bt Engine API of engine operations – BtEngine.Update.
Shut down Bt Engine. Shutting down Bt Engine will automatically destroy all of the tree and forest instances if any of them haven’t been destroyed yet. Bt Engine should be shut down before quitting Unity Engine application. Refer to Bt Engine API of engine operations – BtEngine.Shutdown.
Bt Engine maintains a fixed forest XML file name which cannot be changed after Bt Engine was started. When loading a group of trees in a forest or a single tree, Bt Engine will look up both the forest name(s) and the tree name(s) from the fixed forest XML file, and then it will load the corresponding trees from the specified tree XML files. If the forest XML file or the tree XML file(s) cannot be found, the loading operation will fail. Refer to Bt Engine API of engine properties – BtEngine.SetForestFile.
Bt Engine provides an option to invoke tree operations with parallel tree specific operation queues. Without parallel operation, a queued sequence of tree operations such as Load, Destroy, Play, Pause, Resume, Stop, Reset can only be invoked sequentially by parallel running trees. However, interrupt operations (Destroy, Pause, Stop, Reset) can block the operation queue until all the nodes in the invoked tree return, which will delay the invocation of other operations on other trees. Enabling parallel operation will ensure operations getting invoked immediately per tree without waiting for other trees. Refer to Bt Engine API of engine properties – BtEngine.EnableParallelOp.
The engine property wrapper is a wrapper that contains the properties from the engine level down to the node level depending on the depth level. The depth level of the engine property wrapper can also be specified when acquiring the property wrapper from the engine property operation of Bt Engine API. The engine property wrapper enable users to iterate through all properties of those forest, tree, and node instances. Refer to Bt Engine API of engine properties – BtEngine.GetEnginePropWrap.
4. Tree/Forest Execution Operations
Asynchronous (non-blocking) operations.
Include tree playing, tree resuming, forest playing, and forest resuming operations.
5. Tree/Forest Interruption Operations
Asynchronous (non-blocking) operations.
Include tree pausing, tree stopping, tree resetting, tree destroying, forest pausing, forest stopping, forest resetting, and forest destroying operations.
6. Tree/Forest Property Querying Operations
Include tree status, basic play mode, target loop count, accumulated loop count, tree property wrapper, and forest property wrapper operations.