Behavior Tree Editor User Manual

Overview

Behavior Tree is one of the most commonly used game AI interaction methods and can be called the Processing Unit of an AI Agent. It is a behavioral expression that describes complex AI logic strategies through a tree structure.

The Behavior Tree is equivalent to the brain of the AI, and the Blackboard is sort of the "memory" of the brain. The operating rule of the Behavior Tree is to continuously read data from the Blackboard to make decisions and execute different branches of behavior.

The Behavior Tree Editor includes:

• Editing Section of the Behavior Tree
• Editing Section of the Blackboard Key

User Guide

This chapter mainly describes how to create behavior tree resources in the Editor.

Creating Behavior Tree Resources

There are two types of Behavior Tree resource files: Behavior Tree with the suffix .bt and Blackboard with the suffix .bb.

Creating Behavior Trees

The Behavior Tree is essentially the processor of AI, making decisions and executing various branches of behavior from the data obtained in the Blackboard.

A Behavior Tree can be created in the Resource Preview window in the following way:

Right-click in the blank space of the Resource Preview window, then click Create Res -> AI -> Behavior Tree in the pop-up menu to create a Behavior Tree and set a name for it.

Creating Blackboards

Consider the Blackboard resource as the "brain" of the AI Agent. It stores some data objects called Blackboard Keys. These keys are similar to "memories" in the brain, and they are updated, read, and written in specific ways to help the Behavior Tree make decisions continuously.

A Blackboard resource can be created in the following way:

Right-click in the blank space of the Resource Preview window, then click Create Res -> AI -> Blackboard in the pop-up menu to create a Blackboard and set a name for it.

Editing Blackboards

Since Behavior Trees will associate with Blackboard resources during execution and make decisions repeatedly through the data in the Blackboards, it is usually necessary to create a Blackboard before creating a Behavior Tree.

Double-click the Blackboard resource file in the Resource Preview window to open the Behavior Tree Editor and enter Blackboard editing mode.

Click the New Key button in the Blackboard panel to add a new Blackboard Key.

If the Behavior Tree under editing has already been associated with a Blackboard, then click Blackboard in the upper right corner of the Behavior Tree Editor to switch from Behavior Tree editing mode to Blackboard editing mode.

Currently supported Blackboard Key types:

After a Blackboard Key is created, the related properties can be edited in the Details panel.

The Name, Description, Instance Synced and Type properties are supported for modification.

The associated property types can be changed in the Type property.

To delete a created Blackboard Key, either right-click it and select Delete, or select the target and press the Delete key.

Editing Behavior Trees

Double-click the Behavior Tree file in the Resource Preview window to open the Behavior Tree Editor and enter the editing mode.

If you are in the Blackboard editing mode of the Behavior Tree, click the Behavior Tree button in the upper right corner of the Behavior Tree Editor to switch to the Behavior Tree editing mode (Note: The Behavior Tree needs to be associated with a Blackboard resource to switch editing mode).

Specifying Blackboards

To read the content of the Blackboard, the Behavior Tree needs to be specified with an associated Blackboard resource first.

Select the Entry Node in the Behavior Tree (This is the entry node for all Behavior Trees), and then set the Blackboard resource to be associated with in the Details panel.

After the Blackboard resource is specified successfully, the Entry Node will display the associated Blackboard resource and update the associated Blackboard Keys.

Node-related Operations

Different nodes can be added to the Behavior Tree by right-clicking in the blank space of the Behavior Tree and selecting the node to be created.

Or drag off the node pin and select the node to be created from the menu.

To delete a node from the graph, select the target node and press the Delete key, or right-click the node and select Delete.

Drag off a node pin to the input pin of another node to link the two nodes together.

To break a node link, right-click the node and select Break Link.

Edit the node. Select the node to be edited and modify its properties in the Details panel.

Decorator Nodes and Service Nodes

Decorator Nodes and Service Nodes can be added to nodes in the Behavior Tree graph at the node context menu.

Right-click the target node and select Add New Service and Add New Decorator.

To remove a Decorator or Service Node from the node, select the target node and press the Delete key, or right-click the node and select Delete.

Agents Development Process

Right-click in the blank space of the Resource Preview window, and click Create Res -> AI -> Behavior Tree in the pop-up menu to create a Behavior Tree and name it bt_agent.

Then create a Blackboard resource similarly and name it bb_agent.

Double-click bb_agent to open it, add three different types of Blackboard Keys including Object, Vector and Int, then change their names and save them respectively.

Double-click bt_agent to open it and set bb_agent as its associated Blackboard resource.

Click on the Entry Node pin and drag it off to a blank space. In the pop-up menu, select Selector in the Composites directory to add a Selector Node.

Select the newly created Selector Node and set its name as Root in the Details panel.

Click the Root Node, and drag off the node pin to add a Sequence Node named State Is Idle. The Sequence Node is to tell the target Agent the series of actions it needs to perform next.

Click the Root Node and drag off the node pin to add a Sequence Node named State Is Combat. This node is used to control the Agent to adjust its movement speed and move to the specified position. After moving to the specified position, it will play an animation and perform a custom task, and then repeat this process all over again.

The number in the upper right corner of each node represents the execution operation sequence of the current node in the whole Behavior Tree.

The Behavior Tree follows a left-to-right, top-down execution sequence, so the order of the nodes is important. Actions that are relatively important to the Agent in terms of decision-making are usually placed on the left, while less important actions are placed on the right.

Drag off State Is Idle Node and add a Play Animation Node.

Drag off State Is Idle Node, add a Wait Node and set the Wait Time as 5.0 seconds.

Drag off State Is Combat Node and add a Set Integer Value Node. Set the node Name as Walk Speed, the associated Blackboard Key as TargetWalkSpeed, and the Current Value as 5.

Drag off State Is Combat Node and add a Move To Node. Set the associated Blackboard Key as TargetLocation.

Drag off State Is Combat Node and add a Play Animation Node. Set Animation Name as the name of the animation to be executed (Depending on the actual situation and the animation supported by the associated Agent).

Drag off State Is Combat Node and add a Custom Task Node. Set the Task Name and Task Data properties as required. After the Custom Task Node is executed, a message containing the Task Name and Task Data will be received.

Add a Service Node to the previously created Root Selector Node to update the associated Blackboard Key, and set the associated Blackboard Key to TargetObject.

Add a new Decorator Node of Blackboard type to each of the two previously created Sequence Nodes.

Set the associated Blackboard Key of each Decorator Node as TargetObject, and set the Key Operation property of the two nodes to Is Set separately, so that different branches of logic can be executed while the Blackboard Key value changes.

A simple Agent Behavior Tree instance is now completed.

Behavior Tree Node Types

The main works performed by the Behavior Tree Node include tasks, logical flow control, and data updates.

Composite Nodes

The Composite Node defines the root of the branch and the basic rules for executing that branch.

Sequence

The Sequence Composite Node executes its children in left-to-right order. When one of the child nodes fails to execute, the Sequence Node will also stop executing.

Properties:

Property	Description
Name	The name of the node displayed in the behavior tree.

Selector

The Selector Composite Node executes its children in left-to-right order. When one of the child nodes executes successfully, the Selector Node will stop executing.

Properties:

Property	Description
Name	The name of the node displayed in the behavior tree.

Task Nodes

Task Nodes are the leaves of the Behavior Tree. They are executable operation nodes with no output connections (Nodes are shown in purple).

Wait

The Wait Task Node keeps the Behavior Tree waiting at this node until the specified wait time ends.

Properties:

Property	Description
Name	The name of the node displayed in the behavior tree.
Wait Time	The duration of the wait in seconds.
Random Deviation	A random time length (positive or negative) added to the Wait Time property, which is the range of time deviations allowed to occur.

Move To

The Move To Task Node notifies the target to move to a specified location.

Properties:

Property	Description
Name	The name of the node displayed in the behavior tree.
Acceptable Radius	The required distance between the Pawn and the target when the task node runs successfully.
Time Out	By default, 0 = no timeout. If the time exceeds the set time (non-0 value), the task is considered to be timed out and the return fails.
Blackboard Key	A key that can be used for time reference. Works best for data types that return None (e.g. Object), since other types of data may return to their initial values (such as 0, false, {0,0,0}).

Play Animation

The Play Animation Task Node notifies the target to play set animation.

Properties:

Property	Description
Name	The name of the node displayed in the behavior tree.
Looping	When checked, the animation will be played in a loop.
Animation	Animation assets to play.

Rotate To

The Rotate To Task Node will rotate the associated Pawn towards the specified Blackboard Key.

Properties:

Property	Description
Precision	The number of degrees that can be successfully executed.
Name	The name of the node displayed in the behavior tree.
Blackboard Key	The blackboard key that the target rotation is oriented to. It can be either a Vector or an Object.

Set Vector Value

The Set Vector Value Node sets the Vector Blackboard Key variable value.

Properties:

Property	Description
Value X	X-axis direction variable value.
Value Y	Y-axis direction variable value.
Value Z	Z-axis direction variable value.
Name	The name of the node displayed in the behavior tree.
Blackboard Key	The currently set target blackboard key variable object.

Set String Value

The Set String Value Node sets the string Blackboard Key variable value.

Properties:

Property	Description
Current Value	The variable value set by the current blackboard key object.
Name	The name of the node displayed in the behavior tree.
Blackboard Key	The currently set target blackboard key variable object.

Set Integer Value

The Set Integer Value Node sets the Integer type blackboard Object variable value.

Properties:

Property	Description
Current Value	The default variable value set by the current blackboard key object.
Deviation	Whether the current variable value is allowed to deviate within a certain range.
Min Deviation	The minimum range of deviation allowed.
Max Deviation	The maximum range of deviation allowed.
Name	The name of the node displayed in the behavior tree.
Blackboard Key	The currently set target blackboard key variable object.

Set Float Value

The Set Float Value Node sets the Float type blackboard Object variable value.

Properties:

Property	Description
Current Value	The default variable value set by the current blackboard key object.
Name	The name of the node displayed in the behavior tree.
Blackboard Key	The currently set target blackboard key variable object.

Set Bool Value

The Set Bool Value Node sets the Bool type blackboard Object variable value.

Properties:

Property	Description
Name	The name of the node displayed in the behavior tree.
Current Value	The default variable value set by the current blackboard key object.
Blackboard Key	The currently set target blackboard key variable object.

Custom Task

The Custom Task Node can be used to customize tasks.

Properties:

Property	Description
Name	The name of the node displayed in the behavior tree.
Task Name	Customize the task function name.
Task Data	Customize task function additional parameters.

Decorator Nodes

The Decorator Node needs to be attached to Composite Node or Task Node, determining whether a branch or even a single node in the tree can be executed (The node is shown in blue).

Compare Blackboard Entries

The Compare BB Entries Decorator Node can compare the values of two blackboard keys and allow or block the node execution based on the result.

Properties:

Property	Description
Name	The name of the node displayed in the behavior tree.
Operator	Is Equal: Whether the values of the two blackboard keys are equal. Is Not Equal: Whether the values of the two blackboard keys are not equal.
Blackboard Key A	The first key in this comparison.
Blackboard Key B	The second key in this comparison.
Observer Aborts	None: Do not abort the execution. Lower Priority: Abort all nodes to the right of the node. Self: Abort the node itself and all subtrees running under it. Both: Abort the node itself and all subtrees running under it, along with all nodes to the right of the node.

Is At Location

The Is At Location Decorator Node can check if the AI-controlled Pawn is at the given location.

Properties:

Property	Description
Name	The name of the node displayed in the behavior tree.
Radius	Test range radius variable value.
Blackboard Key	Blackboard key values to be tested.

Loop

The Loop Decorator Node can loop the node or branch a specified or infinite number of times.

Properties:

Property	Description
Name	The name of the node displayed in the behavior tree.
Num Loops	Loop running times.

Blackboard

The Blackboard Decorator Node can check whether the given blackboard key is set to a value.

Properties:

Property	Description
Name	The name of the node displayed in the behavior tree.
Blackboard Key	The blackboard key that the decorator will run.
Key Operation	Is Set: Whether the value is set. Is Not Set: Whether the value is not set.
Observer Aborts	None: Do not abort the execution. Lower Priority: Abort all nodes to the right of the node. Self: Abort the node itself and all subtrees running under it. Both: Abort the node itself and all subtrees running under it, along with all nodes to the right of the node.
Notify Observer	On Result Change: Recalculate only when the condition changes. On Value Change: Recalculate only when the observed blackboard key changes.

Conditional Loop

When the blackboard condition is satisfied, the Conditional Loop Decorator Node will make its connected node execute a loop.

Properties:

Property	Description
Name	The name of the node displayed in the behavior tree.
Blackboard Key	The blackboard key that the decorator will run.
Key Operation	Is Set: Whether the value is set. Is Not Set: Whether the value is not set.
Observer Aborts	None: Do not abort the execution. Lower Priority: Abort all nodes to the right of the node. Self: Abort the node itself and all subtrees running under it. Both: Abort the node itself and all subtrees running under it, along with all nodes to the right of the node.
Notify Observer	On Result Change: Recalculate only when the condition changes. On Value Change: Recalculate only when the observed blackboard key changes.

Server Nodes

The Service Node needs to be attached to Composite Node or Task Node, which is typically used to check and update the blackboard at a set frequency (The node is shown in green).

Default Service

The Default Service Node is generally used to update the blackboard at a set frequency.

Properties:

Property	Description
Name	The name of the node displayed in the behavior tree.
Blackboard Key	The variable value set by the current blackboard key object.
Interval	Define the time interval between subsequent Ticks of the Service Node.
Random Deviation	Add a random range value to the Interval property.
Call Tick	Whether to activate the Tick function.

Customizing Service

Currently there are two types of Service callback methods for extending and implementing customized Service features.

C++ registration

Function header file:

i_ai_command_processor.h

Function declaration:

// Service
typedef void (*on_service)(IAICommandProcessor* from, PERSISTID object, 
    onst char* bt_file, const char* bb_key);

Callback registration method:

AICommandProcessor:: virtual bool RegisterOnService(on_service f);

Callback registration query:

AICommandProcessor::IsRegisterCallback(EAICommandCallback:: OnService)

Parameter types:

• ·IAICommandProcessor* from: AIcommandProcessor object
• PERSISTID object: Current AIObject ID
• const char* bt_file: Current bound behavior tree asset file
• const char* bb_key: Blackboard key set by the current ServiceNode

Script registration

Select LSceneSettings in the Hierarchy panel of the Component Editor and configure the default callback script file in the AI Script of its Property panel.

Function example code for registering a callback:

--AI
function on_init(self)

    --Service: Update the blackboard
    nx_callback(self, "on_service", "ai_service")

    return 1
end

Function example code:

function ai_service(self,  target,  behavior_tree, blackboard_key)

    // File judgment
    if "" == behavior_tree then
        // TODO Something
    end

    // Blackboard key judgment
    if "" == blackboard_key then
        // TODO Something
    end
end