Behaviour Trees are an amazing way of creating AIs, letting you write complex behaviours in a modular, easy and intuitive way. This project tries to deliver a simple yet complete Behaviour Tree tool for Unity with Editor and Runtime features.
This README assumes that you have some idea of what a BehaviorTree is; If you don't, I suggest you Google it first.
[!NOTE] The minimum version currently supported is Unity 2022.2
[!WARNING] This project is in an early phase of development and although it is quite stable, you may encounter bugs and is NOT recommended for use in production.
[!NOTE] At the moment, you can install this package ONLY through the Package Manager using Git.
First of all, we need to install a dependency called METools.
Open your Unity project, go to Window > Package Manager
and click the +
dropdown on the top-left corner, then select Add package from git URL...
and paste the following URL:
https://github.com/MoshitinEncoded/METools.git
[!NOTE] If you receive the error
No 'git' executable was found
you're likely missing a git installation. You can install git from here: https://git-scm.com/download/win
Once installed, do the same with this package:
https://github.com/MoshitinEncoded/AI-Behaviour-Tree.git
AI Behavior Tree is mainly composed of a ScriptableObject called BehaviourTree
and a MonoBehaviour called BehaviourTreeRunner
.
Like Unity's Animator
, the ScriptableObject contains the behavior while the MonoBehaviour is responsible for running it. Let's start by creating a BehaviourTree
in our project.
+
button in the top left corner.Create > Moshitin Encoded > Behaviour Tree
and choose a name.You will see that a new window has appeared, arrange it to your liking and let's see what it has:
A blank BehaviourTree graph.
As you can see it is super simple, on one hand we have the Graph and on the other the Blackboard.
The Graph contains the tree of nodes and their connections. At first you will only have one default node called Root
, which cannot be copied or deleted.
In each frame the tree begins its execution through the Root
and then continues towards its child. When the child returns its state to the Root
, it terminates the execution of the tree in that frame.
There are only 3 states that a node can return: Success
, Running
or Failure
.
[!IMPORTANT] Note that if the
Root
receives the statusSuccess
orFailure
, it will stop the tree from running completely and you will need to restart it manually.
Action | Control |
---|---|
Pan | Middle-Click + Drag |
Zoom | Mouse wheel scroll |
Select | Left-Click |
Rect Select | Left-Click + Drag |
Drag Selection | Left-Click + Drag (over node) |
Add/Remove Selection | Ctrl + Left-Click |
Open Contextual Menu | Right-Click |
Action | Shortcut |
---|---|
Delete | Del |
Copy | Ctrl + C |
Paste | Ctrl + V |
Duplicate | Ctrl + D |
Focus Selection | F |
Focus All | A |
Create Node | Spacebar |
Right click on the Graph and select Create Node
or press the Space
key on your keyboard to open the search window. Here you can search for any type of node that comes by default or that you have created yourself. Selecting any of these will add it to the graph of your BehaviourTree.
Creating your own node is very simple, you just have to create a script that inherits from a node class and add the CreateNodeMenu
attribute on top of it.
At the moment there are 3 node classes you can inherit from:
Node Class | Description |
---|---|
CompositeNode |
Has multiple childs. It is meant for flow control. |
DecoratorNode |
Has only one child. It is meant for child/flow control. |
TaskNode |
Does not have children. It is meant for logic. |
[!NOTE] If the compiler doesn't find the node classes, make sure you import these
namespaces
at the start of your script:using MoshitinEncoded.AI; using MoshitinEncoded.AI.BehaviourTreeLib;
Once you have created your class, you may notice that the CreateNodeMenu
attribute requires a path
. This parameter represents the submenu in the search window where your node will appear (e.g. "Task/Follow Target").
There are multiple functions that you can override to implement your node logic:
Function | Description |
---|---|
Run |
Called every time your node runs. You have to return the new state of your node. |
OnInitialize |
Called the first time your node starts running. |
OnStart |
Called when your node starts running. |
OnStop |
Callled when your node returns Success or Failure . |
The Blackboard contains parameters that provide useful information to the nodes, allowing them to communicate with each other and with the components of the scene.
In the editor do the following:
+
button in the upper right corner of the Blackboard.Right-Click > Rename
on the parameter to give it an appropriate name.You can manage your parameters in your code through the BehaviourTreeRunner functions. There are several ways to get to the value of a parameter.
You can Get or Set the parameter values directly with the GetParameterValue<>
and SetParameterValue<>
methods.
public string ParameterName;
protected override NodeState Run(BehaviourTreeRunner runner)
{
var parameterValue = runner.GetParameterValue<int>(ParameterName);
runner.SetParameterValue(ParameterName, 5);
}
[!WARNING] This method has an impact on the CPU since your
BehaviorTree
looks for the parameter every time you call any of the above methods. If you find yourself frequently reading and/or writing to a parameter value, it is recommended to use the following method.
You can get a reference to the parameter that you want to use with the GetParameter<>
function in your BehaviourTreeRunner
and then, Get or Set his value with the Value property.
public string ParameterName;
private BehaviourTreeParameter _Parameter;
protected override void OnInitialize(BehaviourTreeRunner runner)
{
_Parameter = runner.GetParameter<int>(ParameterName);
}
protected override NodeState Run(BehaviourTreeRunner runner)
{
var value = _Parameter.Value;
_Parameter.Value = 5;
}
[!TIP] There is a class called
BehaviourTreeParameterRef
that does the same thing eliminating the need for a string.public BehaviourTreeParameterRef Parameter; protected override void OnInitialize(BehaviourTreeRunner runner) { Parameter.Bind(runner); } protected override NodeState Run(BehaviourTreeRunner runner) { var value = Parameter.Value; Parameter.Value = 5; }
To create your own parameters, you have to:
BehaviourTreeParameter
.AddParameterMenu
attribute on top of your class.This attribute requires two parameters:
This MonoBehaviour is responsible for running your BehaviourTree
and works as an interface to interact with it.
Here you can assign the BehaviourTree
you want to run, decide how or when you want to run it and override parameters of the Blackboard.
Function | Description |
---|---|
GetParameter<> |
Returns the value of a parameter in the Blackboard. |
GetParameterByRef |
Returns a reference to the parameter in the Blackboard. |
GetParameterByRef<> |
Returns a generic reference to the parameter in the Blackboard. If the passed generic type is not correct, it returns null. |
SetParameter<> |
Sets the value of a parameter in the Blackboard. |
The Behaviour Tree tool in this repository was expanded from the one created by TheKiwiCoder in this video, whose repository you can find here.