====== Behavior Trees ======

You can find an example of behavior tree and behavior tree node creation in the following mods:
  * ''Example 01'' (file ''wooden_keep_guard_locator.lua'')
  * ''Example 02'' (file ''scripts/behavior_tree.lua'').

===== Register new behavior trees =====

You can now create custom behavior tree assets with ''[[:mod-management-functions#registerBehaviorTree|mod:registerBehaviorTree]]''.

A behavior tree is defined as a table containing an ID (''Id''), a list of variable (''VariableList'') and an execution tree (''Root'').

==== VariableList ====

Each variable in the list must contain at list a unique ''Name'', and a ''DataType''. The ''DataType'' must be a type inheriting ''[[api:behavior_tree_data|BEHAVIOR_TREE_DATA]]''.

You can also specify if a variable is public (''IsPublic''), thus specifying if this variable must be filled by the outer tree when this tree is used as a sub-tree node.

Finally, you can specify the variable's default value if none is specified (''DefaultValue'').

==== Node tree ====

A behavior tree is composed of multiple nodes, organized in tree. The first node to be executed is the root, defined in the ''Root'' field. There are two main types of nodes: branches and leaves.

Branch nodes (''NODE_BRANCH'') are all defined by the core game, and exist in two sub-types:
  * decorators (''NODE_DECORATOR''), which can have only one child, generally used for logic or repeat operations
  * composite nodes (''NODE_COMPOSITE''), which can have multiple childs, generally used for sequencing the execution of child nodes

Leaf nodes (''NODE_LEAF'') cannot have children. Some are defined in the core game, but you can also [[behavior-trees#custom_behavior_tree_nodes|define your own]].

When defining a node in a new behavior tree, you have to specify at least its unique name (''Name''), and its type (''Type'') inheriting from ''[[api:node|NODE]]''. If the node has public variables, you have to link by name each of the node's variables to the tree variables.

Finally, if the node is a branch node, you have to add the list of children (''Children'').

===== Custom behavior tree nodes =====

You can also create custom behavior tree nodes with ''foundation.registerBehaviorTreeNode''.

A node contains a unique name (''Name''), a list of variables (''VariableList''), and functions.

==== VariableList ====

The list of variables is a simple key-value pair list with the variables name as key, and its type (inheriting from ''[[api:behavior_tree_data|BEHAVIOR_TREE_DATA]]'') as value. Each of those variables are input by the tree using the node.

==== Functions ====

A leaf node has three basic functions: ''Init'', ''Update'', and ''Finish''. The implementation of ''Init'' and ''Finish'' are optional.

=== Init ===

''void **Init**(//instance//)''

^ Name ^ Type ^
| //''instance''// | ''BEHAVIOR_TREE_INSTANCE'' |

=== Update ===

''BEHAVIOR_TREE_NODE_RESULT **Update**(//level//, //instance//)''

^ Name ^ Type ^
| //''level''// | ''LEVEL'' |
| //''instance''// | ''BEHAVIOR_TREE_INSTANCE'' |

=== Finish ===

''void **Finish**(//instance//)''

^ Name ^ Type ^
| //''instance''// | ''BEHAVIOR_TREE_INSTANCE'' |

When a node is executed, the ''Init'' function is called first. Then, the ''Update'' function is called until it doesn't return ''[[api:behavior_tree_node_result|BEHAVIOR_TREE_NODE_RESULT.PROCESSING]]''. Finally, the ''Finish'' function is called.

You can access all of the node's variables in those functions with ''self''.