Overview

The Behavior Selection Tree (BST) Editor is a tool for easy setup of AI Behavior Selection Trees in CryENGINE3.

Selection Trees

Each AI can have its own BST. The BST is used to select an AI Behavior depending on the state of Variables.

The Selection Tree is evaluated every time the AI receives signals. It starts at the root node and walks down the tree until it ends at a Leaf node. The assigned AI Behavior of this Leaf node is then selected.

Each Node can have a Condition that is evaluated. If the Condition is true, the Node is selected otherwise it evaluates the next node.

Tree Variables

Each tree has Variables. Those variables are used by the condition nodes. All Variables are Boolean values. Usually those Variables are set by Signals.

It is also possible to set those variables directly through an AI Behavior script, but this is not common.

Tree Signals

AI Signals are usually sent directly by the AI System (System Signals) or via AI behavior scripts (Custom Signals).

Each tree can define how AI signals are changing the tree variables. One signal can be used to set more than one variable.

References

A reference is a part of a BST that can be reused by different SelectionTrees. While a SelectionTree can be assigned directly to an AI, the References are only used within other SelectionTrees.

A Reference can be a Signals Reference, Variables Reference and a Reference Tree. Usually a Signals Reference, a Variables Reference and one (or more) Tree Reference(s) are grouped together.

The main advantage of reference groups are the re-usability of some parts of a SelectionTree. If a reference group is changed it will affect all SelectionTrees that are using this reference.

While a Leaf node in a Selection Tree usually directly points to an existing AI Behavior, a Leaf Node in a Reference can have a Name that is not pointing to an existing AI Behavior. If this Reference Tree is used in a SelectionTree, those Nodes are mapped to an existing Behavior via a "Leaf Mapping" within the SelectionTree. See -> Leaf Mappings

To use a Tree Reference within a SelectionTree simply add a Reference Node and choose your Reference.

Once you add a Reference Node the BST Editor will automatically add the Variables and Signals Reference of the Reference Group to the Tree as well, since each Reference usually has its own Variables and Signals that are needed by the referenced tree.

You can also add a Variables or Signals Reference directly into the Variables/Signals list.

Leaf Mappings

Each Leaf node can be mapped with a specific AI Behavior via a Leaf Mapping.

This is manly used to map a specific AI Behavior to a Leaf Node that is in a Reference Tree.

E.g. The Reference Tree "RefTree" has a Leaf Node "Goto". The "RefTree" is used in the SelectionTree "HumanGrunt" and "AlienGrunt".

Now the SelectionTree "HumanGrunt" has a Leaf Mapping that maps "Goto" to "HumanGoto" and the SelectionTree "AlienGrunt" maps this node to "AlienGoto".

Each SelectionTree uses the same Reference Tree but if the selection reaches the "Goto" Node, it will select the special Behavior for each SelectionTree.

Creating and editing a SelectionTree

To create a new Selection Tree simply click in the Tree List and choose "Add Selection Tree". The Name must be unique.

Variables

To add a new Variable just click "Add Variable" in the Variable List and define a name for it. You can also add a Variables Reference by choosing "Add Reference".

Note: The Name must be unique within the Tree (and References).

Signals

To add a new SignalVariable click "Add Signal Variable" in the Signal List. You can choose one of the System Signals from the dropdown list or type in the Name of a Custom Signal.

Then choose the Variable from the dropdown list that you want to modify if this Signal is sent. You can also choose if the Variable is set to true or false.

Each Signal can have more than one Variable that is set by this Signal.

You can also add a Signals Reference by choosing "Add Reference". Once you add a Signals Reference, it will automatically add the Variables Reference that is grouped with the chosen Signals Reference.

Nodes

To create your SelectionTree you have to add Nodes to the Tree. There are different kinds of Nodes: Priority Nodes, Leaf Nodes, Condition Nodes and Reference Nodes

To place a new Node simply right click in the Graph and select "Create Node". It is also possible to add a node directly as a child to another node. This can be done by right clicking on the Parent Node and choose "Add Child".

To connect two Nodes simply press shift and drag a connection from one node to another. The tree will automatically reorder itself.

Priority Node

This Node is an internal Node that is used to organize the Tree.

If a Priority Node is selected it will evaluate its children from left to right. The first Node that is reached will be executed.

In case of a condition node, the condition will be evaluated. If it is true the child of the condition is executed otherwise the next node is evaluated.

Leaf Nodes

If a Leaf node is reached, the AI Behavior of this node is executed.

Condition Nodes

If a condition node is reached, the condition will be evaluated, if the condition is true, the child is executed, otherwise the next node will be evaluated.

Reference Node

A reference node is simply a placeholder for a reference tree; it will be replaced by the Reference Tree. You can double click on a reference node to see the content of the reference.

Reordering of Nodes

To change the order of the children of a node, simply drag the child to its new position. To change the parent of a node simply shift click on the new parent and drag a connection to the child you want to add.

Leaf Mappings

To create a Leaf Mapping, right click on a leaf and choose "Create Leaf Mapping". First you have to choose an AI Behavior that should be mapped to this leaf. After that the whole tree will be grayed out you have to define the "path".

Since a mapping can be "Goto" -> "HumanGoto", all Leafs with the name "Goto" will be mapped with "HumanGoto".

The current Node that is edited is marked red. All Nodes that are affected by this mapping are marked blue.

Sometimes it is needed to create a Mapping that only affects a specific node. To archive this you can define an "end" node for the mapping (See picture). The "path" to the end node is marked yellow.

Picture A:

Picture B:

Example:

• In picture A the mapping "LogicControl:AvoidImmediateThreat" -> "AlienGruntAvoidImmediateThreat" will affect the other (blue) leaf node as well since the path is the same.
• In picture B the mapping only affects one node since the path only fits to this node.

"Root:LogicControl:AvoidImmediateThreat" -> "AlienGruntAvoidImmediateThreat"

To define the "path" you have to click on an end node for the path (must not be a condition or reference node). Once you clicked on the "end" node you will instantly see what other nodes are affected. To confirm you have to click the same "end" node again.

It is also possible to click directly on the edited leaf node. In this case you create a simple mapping "LeafFoo"->"MappedFoo".

Creating and editing Reference Groups

To create a new Reference group just right click in the Tree List and choose "Add new Reference Group".

If you don't use the advanced dialog the Reference will automatically create a Variables Reference, Signals Reference and a Reference Tree.

In the advanced dialog you can define which elements you want to have in this reference.

Note: If your Reference Group has a Variables and/or Signals Reference, both must have at least one element. Otherwise the Reference Group can't be saved!

Multiple Reference Trees

While a SelectionTree always have one Tree, a Reference group can have 0-N trees. All trees in a reference group share the variables and signals for this group.

To add a new Tree to a group simply right click on the Group in the Tree List and choose "Add new Tree".

How to see changes InGame

Once you want to test your changes you have to save them first. If you choose "Save All" from the Menu it will first save all modified XML files and then force the AI System to reload the Behavior Selection Tree scripts.

Debug SelectionTrees

Once you jump into Game it is possible to debug the SelectionTrees using the CVar:

bst_debug_ai = <Name of AI Actor>

The current SelectionTree of the chosen AI is automatically displayed.

The Variables View will display the current values of each variable. If a value changed since last evaluation the variable is highlighted.

You can also see the path to the current Leaf node and each Condition node will display the result of the evaluation.

• Blue: This node was evaluated.
• Yellow: A condition node was evaluated with result FALSE.
• Green: A condition node was evaluated with result TRUE.
• Red: This Node is the current active node of the tree.

If you want the TreeGraph to center the current selected node you can use:

bst_debug_centernode = 1

Tree Validation

The Selection Tree Editor automatically validates all trees in real-time. All found errors or warnings are displayed in the Error Report. If Errors or warnings are present the dialog will automatically pop up on save. You can also open the Error Report via the Main Menu of the Selection Tree Editor.

There is also a CVar to control the level of warnings that are displayed in the dialog

bst_validator_warnlevel = 0 //Dispay all Errors and Warnings
bst_validator_warnlevel = 1 //Hide all Warnings from References
bst_validator_warnlevel = 2 //Hide all Warnings and Errors from References
bst_validator_warnlevel = 3 //Show only Errors
bst_validator_warnlevel = 4 //Show only Errors from SelectionTrees