STR Behavior Tree

Behavior trees are a formal, graphical modelling language used primarily in systems and software engineering.

This documentation explains implementation details of behavior tree system implemented in DBB by str_behavior_tree script.

Tree is configured by creating entities and giving them correct names and occasionally attaching scripts.

Most of the behavior tree node configuration is done in the name, that has a certain syntax.

Here is the quick example of how entities describing the behavior tree could look like:

Zombie
    <sel> // Select between combat and roaming
        <seq> // combat sequence - walk and then attacka
            <s:btZombieWalking entity=Enemy> @if:isWalking==true // Walking
            <s:btZombieAttack entity=Enemy> @if:isAttacking==true // Attacking
        <seq> // idle sequence - stay idle and then roaming
            <s:btZombieIdle> @if:isIdle==true // Idle
            <s:btZombieRoaming> @if:isRoaming==true // Roaming

Zombie entity should have str_behavior_tree script on it, that would point to entity <sel> // Select between combat and roaming as the root of the tree.

Control Entity

When tree is running, it would always have exactly one entity that it controls. This entity is called control entity and it can be either set in the tree script, or it would be simply the entity that has the script on it.

Node Name Syntax

Example entity name defining a behavior tree node:

<set WalkTo=Door> @if:Closest==Door @if:Entering==Building // Enter building

When you are naming entities that define a behavior tree node, you should give them a name that can have following parts:

• Node type (required) - written in the begging of the name in angled brackets
  • in example above: <set> is a Setter node type
• One or more decorators (optional) - write them after symbol @, then follow with decorator type and value (e.g. @if:condition ) - in here if is a decorator type and condition is a value that decorator would use when node is checked
  • in example above both @if:Closest==Door and @if:Entering==Building are Conditional decorators
• Comment (optional) - written in the end of name after two slashes //
  • in the example above: // If closest door is closest, prepare to walk to it is a comment

If entity is not named according to the syntax, tree collection would fail and throw an error, that you would see in the console and the editor would highlight failed script in purple color.

Some examples of valid names are:

• <sel> - just node without any decorators or comments
• <seq> // This is a comment - node with a comment
• <seq> @if:SomeThing==SomeOtherThing - node with a decorator
• <seq> @if:SomeThing==SomeOtherThing // My Sequence - node with a decorator and a comment
• <s:btNpcWalk entity=Door> @if:SomeThing==SomeOtherThing - node with attribute and a decorator
• <s:btNpcWalk entity=Door>@if:SomeThing==SomeOtherThing@if:Entering==Building//another comment - node with attribute, two decorators and a comment, spaces are not required

Node types

Nodes are divided into composite and leaf nodes. Composite nodes usually do not do much themselves without children nodes, while leaf nodes are the ones that actually do interesting things in the game world, such as moving our entities around, triggering animations, decrementing health, etc.

This implementation uses special script nodes which would refer to adapter scripts that should be attached to the control entity. These nodes could be composite or leaf, depending on the script, but they are most often leaf nodes.

• Sequence <seq> - Composite node that would check children nodes in order and would return 'failure' status as soon as one of the children nodes returns 'failure' status.
• Selector <sel> - Composite node that would check children nodes in order and would return 'success' status as soon as one of the children nodes returns 'success' status.
• Leaf Node Blackboard Setter <set> - Leaf node that would set the value of the blackboard key to the provided value. It would always return 'success' status.
• Scripted Nodes <s:...> - This is the whole class of leaf nodes that are implemented as scripts. Prefix s: is followed by the name of the script that should be attached to control entity.

Decorators

Decorators are used to modify the behavior of the node. They are written after the @ symbol and you can have multiple decorators for one node, like f.e. @forceSuccess @if:condition @if:anotherCondition.

All decorators would be checked in order they are written in the name. Decorator would decide whether it would continue checking further decorators (or node) or it would stop and return the status as was decided by the decorator. For example if (aka conditional) decorator would stop checking further decorators if the condition is not met and would return 'failure' status.

• Conditional decorator is used to check some condition before the node (or further decorator) is checked.
• Force Success decorator is used to force the node to return 'success' status, no matter what the actual status is.
• Force Failure decorator is used to force the node to return 'failure' status, no matter what the actual status is.