{
public static implicit operator SharedCustomClass(CustomClass value) { return new SharedCustomClass { Value = value }; }
}
```
---
# Accessing Variables from non-Task Objects
[View this page online](https://opsive.com/support/documentation/behavior-designer/variables/accessing-variables-from-non-task-objects/)
Variables are normally referenced by [assigning](https://opsive.com/support/documentation/behavior-designer/variables/) the variable name to the task field within the Behavior Designer inspector panel. Local variables can also be accessed by non-Task derived classes (such as MonoBehaviour) by calling the method:
```csharp
behaviorTree.GetVariable("MyVariable");
behaviorTree.SetVariable("MyVariable", value);
behaviorTree.SetVariableValue("MyVariableName", value);
```
When setting a variable, if you want the tasks to automatically reference that variable then make sure a variable is created with that name ahead of time. The following code snippet shows an example of modifying a variable from a MonoBehaviour class:
```csharp
using UnityEngine;
using BehaviorDesigner.Runtime;
public class AccessVariable : MonoBehaviour
{
public BehaviorTree behaviorTree;
public void Start()
{
var myIntVariable = (SharedInt)behaviorTree.GetVariable("MyVariable");
myIntVariable.Value = 42;
}
}
```
In the above example we are getting a reference to the variable named "MyVariable" within the Behavior Designer Variables pane. Also, as shown in the example, you can get and set the value of the variable with the SharedVariable.Value property. Similarly, global variables can be accessed by getting a reference to the GlobalVariable instance:
```csharp
GlobalVariables.Instance.GetVariable("MyVariable");
GlobalVariables.Instance.SetVariable("MyVariable", value);
```
All variables can be retrieved with:
```csharp
var variables = BehaviorTree.GetAllVariables();
```
---
# Conditional Aborts
[View this page online](https://opsive.com/support/documentation/behavior-designer/conditional-aborts/)
https://www.youtube.com/watch?v=GFsK5x6ZW7k Conditional aborts allow your behavior tree to dynamically respond to changes without having to clutter your behavior tree with many Interrupt/Perform Interrupt tasks. This feature is similar to the Observer Aborts in Unreal Engine 4. Most behavior tree implementations reevaluate the entire tree every tick. Conditional aborts are an optimization to prevent having to rerun the entire tree. As a basic example, consider the following tree:
When this tree runs the Conditional task will return success and the Sequence task will start running the next child, the Wait task. The Wait task has a wait duration of 10 seconds. While the wait task is running, lets say that the conditional task changes changes state and now returns failure. If Conditional aborts are enabled, the Conditional task will issue an abort and stop the Wait task from running. The Conditional task will be reevaluated and the next task will run according to the standard behavior tree rules. Conditional aborts can be accessed from any Composite task:
There are four different abort types: None, Self, Lower Priority, and Both.
| None | Self |
| --- | --- |
|
**Lower Priority** Behavior trees can be organized from more important tasks to least important. If a more important Conditional task changes status then can issue an abort that will stop the lower priority tasks from running.
| **Both** This abort type combines both self and lower priority. |
Conditional aborts can also be thought of the following way: **Lower Priority:** will reevaluate when any task to the right of the current branch is active. **Self:** will reevaluate when any task within the current branch is active. **Both:** will reevaluate when any task to the right or within the current branch is active. The following example will use the lower priority abort type:
In this example the parent Sequence task of the left branch has an abort type of lower priority. Lets say that the left branch fails and moves the tree onto the right branch due to the Selector parent task. While the right branch is running, the very first Conditional task changes status to success. Because the task status changed and the abort type was lower priority the Action task that is currently running gets aborted and the original Conditional task is rerun. The conditional task's execution status will have a repeater icon around the success or failure status to indicate that it is being reevaluated by a conditional abort:
Conditional aborts can be nested beneath one another as well. For example, you may want to run a branch when one of two conditions succeed, but they both don't have to. In this example we will be using the Can See Object and Can Hear Object tasks. You want to run the action task when the object is either seen or heard. To do this, these two conditional tasks should be parented by a Selector with the lower priority abort type. The action task is then a sibling of the Selector task. A Sequence task is then parented to these two tasks because the action task should only run when either of the conditional tasks succeed. The Sequence task is set to a Lower Priority abort type so the two conditional tasks will continue to be reevaluated even when the tree is running a completely different branch.
The important thing to note with this tree is that the Selector task must have an abort type set to Lower Priority (or Both). If it does not have an abort type set then the two conditional tasks would not be reevaluated.
---
# Events
[View this page online](https://opsive.com/support/documentation/behavior-designer/events/)
The event system within Behavior Designer allows your behavior trees to easily react to changes. This event system can trigger an event via code or through behavior tree tasks. Events can be signaled through the behavior tree with the Send Event and the Has Received Event tasks. When an event should be signaled, the Send Event task should be used. The Has Received Event task is a conditional task and will return success as soon as the event has been received. An event name can be specified for both of these tasks. In order to properly receive the events the Has Received Event task should be reevaluated with conditional aborts. As an example, consider the following tree:
During the first tick the Has Received Event task will fail because the event has not been received yet. The Selector will then move to the right branch and the Wait task will start. After a second the Send Event Task will send the event and then Idle is started to keep the tree active. During the next tick the Has Received Event task returns a status of success because of the previous event that was sent. It then outputs the value of the MyInt variable which was sent with the Send Event task.
The Target GameObject variable on the Send Event task must contain a behavior tree. The task will return failure if the Target GameObject does not have a behavior tree.
In addition to being able to send events via the behavior tree, events can be sent through code. The BehaviorTree.SendEvent method will allow you to send an event to the specified behavior tree. For example:
```csharp
var behaviorTree = GetComponent();
behaviorTree.SendEvent("MyEvent", 5);
```
In this example the "MyEvent" event will be sent to the behavior tree component with a parameter value of 5. If the behavior tree contains the Has Received Event task then it will react accordingly. You are also able to receive events from outside the behavior tree. To continue with the "MyEvent" example, you can receive this event by using the BehaviorTree.RegisterEvent method. BehaviorTree.UnregisterEvent will stop listening for that event.
```csharp
public void OnEnable()
{
var behaviorTree = GetComponent();
behaviorTree.RegisterEvent("MyEvent", ReceivedEvent);
}
public void ReceivedEvent(object arg1)
{
}
public void OnDisable()
{
var behaviorTree = GetComponent();
behaviorTree.UnregisterEvent("MyEvent", ReceivedEvent);
}
```
---
# External Behavior Trees
[View this page online](https://opsive.com/support/documentation/behavior-designer/external-behavior-trees/)
In some cases you may have a behavior tree that you want to run from multiple objects. For example, you could have a behavior tree that patrols a room. Instead of creating a separate behavior tree for each unit you can instead use an external behavior tree. An external behavior tree is referenced using the Behavior Tree Reference task. When the original behavior tree starts running it will load all of the tasks within the external behavior tree and act like they are its own. Any SharedVariable within the external tree of the same name and type of its parent tree will automatically be overridden. For example, if the parent tree has a SharedInt named "MyInt" with a value of 7, and the External Tree has a SharedInt named "MyInt" with a value of 0, when the tree runs MyInt will have a value of 7 within the External Tree.
### Behavior Tree Reference
The Behavior Tree Reference task allows you to run another behavior tree within the current behavior tree. You can create this behavior tree by saving the tree as an external behavior tree. One use for this is that if you have an unit that plays a series of tasks to attack. You may want the unit to attack at different points within the behavior tree, and you want that attack to always be the same. Instead of copying and pasting the same tasks over and over you can just use an external behavior and then the tasks are always guaranteed to be the same. This example is demonstrated in the RTS sample project located on the [samples page](/integrations/?pid=803). The GetExternalBehaviors method allows you to override it so you can provide an external behavior tree array that is determined at runtime. The Behavior Tree Reference task allows you to specify variables per-reference task. For most cases this is not needed because variables will automatically be transferring from the parent tree to the External Tree. However, if you have multiple Behavior Tree Reference tasks in the same tree all pointing to the same External Tree, you may want to be able to specify different variable values per tree. In this situation you can specify the variable value on the Behavior Tree Reference task and that variable value will be transferred to the External Tree.
### Pooling
External behavior trees can be pooled for better performance when switching between many external trees. When the external behavior tree is instantiated the Init method should be called to deserialize the external behavior tree. Pooled external behavior trees can then be assigned to the behavior tree component just like non pooled external behavior trees. For example:
```csharp
using UnityEngine;
using BehaviorDesigner.Runtime;
public class ExternalPoolExample : MonoBehaviour {
public BehaviorTree behaviorTree;
public ExternalBehavior externalBehaviorTree;
private ExternalBehavior[] externalPool;
private int index;
public void Awake()
{
// Instantiate five External Behavior Tree which will be reused. The Init method will deserialize the External Behavior Tree.
externalPool = new ExternalBehavior[5];
for (int i = 0; i < externalPool.Length; ++i) {
externalPool[i] = Object.Instantiate(externalBehaviorTree);
externalPool[i].Init();
}
}
public void OnGUI()
{
// Assign the next External Behavior Tree within the simplified pool.
if (GUILayout.Button("Assign")) {
behaviorTree.DisableBehavior();
behaviorTree.ExternalBehavior = externalPool[index];
behaviorTree.EnableBehavior();
index = (index + 1) % externalPool.Length;
}
}
}
```
---
# Networking
[View this page online](https://opsive.com/support/documentation/behavior-designer/networking/)
Behavior Designer supports Unity's networking system UNET introduced with Unity 5.1. Networking is a complex topic so it is highly recommended that you first go through Unity's [networking documentation](http://docs.unity3d.com/Manual/UNetOverview.html) before continuing. Note: UNET has been deprecated in current versions of Unity. This guide is for those using older Unity versions. Shared Variables can automatically be synchronized over the network from the server to the client. This can be enabled by opening the details of the variable and selecting "Network Sync":
The ENABLE\_MULTIPLAYER [compiler definition](http://docs.unity3d.com/Manual/PlatformDependentCompilation.html) must be added for the variables to sync correctly. Due to a current networking limitation, ClientRPC calls cannot be overloaded so the type has to be known ahead of time. This means that only the following types of variables can be synchronized:
- bool
- Color
- float
- GameObject
- int
- Quaternion
- Rect
- string
- Transform
- Vector2
- Vector3
- Vector4
The Behavior component from the [runtime source code](https://opsive.com/support/documentation/behavior-designer/installation/) must be used in order to allow the variables to be synchronized. This is a result of a current Unity networking bug. ClientRPC calls cannot be called on the parent class from a subclass. A bug report has been submitted and are waiting for a fix. This bug manifests itself by displaying the following warning in the console: _Failed to invoke RPC \[RpcPath\](\[ObjectID\]) on netID \[NetID\]_ Where \[RpcPath\] is the method path, \[ObjectID\] is the ID of the object, and \[NetID\] is the network ID.
---
# Referencing Tasks
[View this page online](https://opsive.com/support/documentation/behavior-designer/referencing-tasks/)
When writing a new task, in some cases it is necessary to access another task within that task. For example, TaskA may want to get the value of TaskB.SomeFloat. To accomplish this, TaskB needs to be referenced from TaskA. In this example TaskA looks like:
```csharp
using UnityEngine;
using BehaviorDesigner.Runtime.Tasks;
public class TaskA : Action
{
public TaskB referencedTask;
public void OnAwake()
{
Debug.Log(referencedTask.SomeFloat);
}
}
```
TaskB then looks like:
```csharp
using UnityEngine;
using BehaviorDesigner.Runtime.Tasks;
public class TaskB : Action
{
public float SomeFloat;
}
```
Add both of these tasks to your behavior tree within Behavior Tree and select TaskA.
Click the select button. You'll enter a link mode where you can select other tasks within the behavior tree. After you select Task B you'll see that Task B is linked as a referenced task:
That is it. Now when you run the behavior tree TaskA will be able to output the value of TaskB's SomeFloat value. You can clear the reference by clicking on the "x" to the right of the referenced task name. If you click on the "i" then the linked task will highlight in orange:
Tasks can also be referenced using an array:
```csharp
public class TaskA : Action
{
public TaskB[] referencedTasks;
}
```
---
# Object Drawers
[View this page online](https://opsive.com/support/documentation/behavior-designer/object-drawers/)
Object Drawers are very similar to the Unity feature [Property Drawers](http://docs.unity3d.com/Manual/editor-PropertyDrawers.html). Object drawers allow you to customize the look of different objects within the inspector. As an example, we will modify the Shared Custom Object example found in the [Creating Your Own Shared Variable](https://opsive.com/support/documentation/behavior-designer/variables/creating-shared-variables/) topic. With the default inspector, the SharedCustomClass variable looks like the following in the inspector:
For this example, we will limit the range of the integer between 0 and 10 using object drawers:
The following object drawer was used to accomplish this (this script goes in an Editor folder):
```csharp
using UnityEngine;
using UnityEditor;
using BehaviorDesigner.Editor;
[CustomObjectDrawer(typeof(CustomClass))]
public class CustomClassDrawer : ObjectDrawer
{
public override void OnGUI(GUIContent label)
{
var customClass = value as CustomClass;
EditorGUILayout.BeginVertical();
if (FieldInspector.DrawFoldout(customClass.GetHashCode(), label)) {
EditorGUI.indentLevel++;
customClass.myInt = EditorGUILayout.IntSlider("Integer", customClass.myInt, 0, 10);
customClass.myObject = EditorGUILayout.ObjectField("Object", customClass.myObject, typeof(UnityEngine.Object), true);
EditorGUI.indentLevel--;
}
EditorGUILayout.EndVertical();
}
}
```
The only method that you need to override for object drawers to work is the OnGUI(GUIContent label) method. The label field is the name of the field that is being drawn. Just like property drawers, you can specify a object drawer by the class type or by attributes. The example above is using the class type method. As another example, we will convert the Ranged Attribute used in Unity's example to a Object Drawer. First we need to create the attribute:
```csharp
using UnityEngine;
using BehaviorDesigner.Runtime.Tasks;
using BehaviorDesigner.Runtime.ObjectDrawers;
public class RangeAttribute : ObjectDrawerAttribute
{
public float min;
public float max;
public RangeAttribute(float min, float max)
{
this.min = min;
this.max = max;
}
}
```
Now that the attribute is created, we need to create the actual object drawer (this script goes in an Editor folder):
```csharp
using UnityEngine;
using UnityEditor;
using BehaviorDesigner.Editor;
[CustomObjectDrawer(typeof(RangeAttribute))]
public class RangeDrawer : ObjectDrawer
{
public override void OnGUI(GUIContent label)
{
var rangeAttribute = (RangeAttribute)attribute;
value = EditorGUILayout.Slider(label, (float)value, rangeAttribute.min, rangeAttribute.max);
}
}
```
Once both of these have been created, we can use it within a task:
```csharp
using UnityEngine;
using BehaviorDesigner.Runtime;
using BehaviorDesigner.Runtime.Tasks;
using BehaviorDesigner.Runtime.ObjectDrawers;
public class NewAction : Action
{
[Range(5, 10)]
public float rangedFloat;
public override TaskStatus OnUpdate()
{
Debug.Log(rangedFloat);
return TaskStatus.Success;
}
}
```
This will show up in the task inspector as:
---
# Variable Synchronizer
[View this page online](https://opsive.com/support/documentation/behavior-designer/variable-synchronizer/)
[Shared Variables](https://opsive.com/support/documentation/behavior-designer/variables/) are great for sharing data across tasks and behavior trees. However, in some cases you want to share to same variables with non-behavior tree components. As an example, you may have a GUI Controller component which manages the GUI. This GUI Controller displays a GUI element indicating whether or not the agent being controlled by the behavior tree is alive. It does this by having a boolean which says whether or not the agent is alive:
```csharp
public bool isAlive { get; set; }
```
With the Variable Synchronizer component, you can automatically keep this boolean and the corresponding Shared Variable synchronized with each other. To setup the Variable Synchronizer, first make sure you have created the Shared Variables that you want to synchronize. For this example we created three Shared Variables:
Following that, add the Behavior Designer/Variable Synchronizer component to a GameObject.
Next, start adding the Shared Variable that you want to keep synchronized. For this example we are going to add the Is Alive variable that was previously mentioned.
1. Specify the GameObject which contains the behavior tree that has the Shared Variable that you want to synchronize.
2. Select from the popup box which Shared Variable you want to use.
3. Specify a direction. If the arrow is pointing to the left then you are setting the Shared Variable value. If the arrow is pointing to the right then you are getting the Shared Variable value.
4. Specify the type of synchronization. Currently the following types are supported: Behavior Designer, Property, Animator, and PlayMaker.
5. The remaining steps will depend on the type of synchronization selected. In this example Property was selected so you'll need to select the component which contains the property that you want to synchronize with the Shared Variable.
6. Click Add.
Once added the Is Alive Shared Variable will set the isAlive property at an interval specified by Update interval. The following screenshot contains a few more synchronized variables:
- The Is Alive Shared Variable is setting the isAlive property.
- The Speed Share Variable is setting the Speed Animator parameter.
- The Target Shared Variable is being set by the Target PlayMaker variable.
---
# Syncing Animations
[View this page online](https://opsive.com/support/documentation/behavior-designer/syncing-animations/)
Behavior Designer includes a set of Animator tasks which allow you to play animations within the tree. Consider the tree below:
This is an extremely simple Animator Controller that uses a blend tree to blend between the Idle and Run state based on the Speed parameter. If you'd like to then sync this blend tree with the Seek task your behavior tree would then look similar to:
Before the Seek task starts the Speed parameter is set to 1 so the blend tree can play the run animation. After the Seek task completes the Speed parameter is then set to 0 to play the Idle animation again. With a small behavior tree and Animator Controller this process works well. However, as the amount of animations grow for your agent this method starts to become extremely cumbersome. In addition, your behavior tree also starts to become extremely verbose with all of the Animator tasks and if you change a transition within your Animator Controller you'd have to rework the behavior tree to work with that Animator Controller change. There is a better way. The recommended approach to syncing animations within your behavior tree is to not sync the animations at all within the behavior tree. Instead your agent's character controller should do it for you. Using Unity's NavMeshAgent as an example, when the behavior tree sets the NavMeshAgent destination (such as with the Seek task) the NavMeshAgent's velocity will change to move towards the destination. The character controller should then use the velocity and translate the movements into parameters that the Animator Controller can understand. MecWarriors had an excellent tutorial on how to accomplish this. The MecWarriors site is no longer operational but a cached version of the tutorial can be found [here](https://web.archive.org/web/20160317180801/http://mecwarriors.com/2014/12/09/navmesh-and-mecanim/). Unity also has a similar tutorial within [their documentation](https://docs.unity3d.com/Packages/com.unity.ai.navigation@1.1/manual/CouplingAnimationAndNavigation.html). A similar implementation can be done with A\* Pathfinding Project. The advantage of this approach is that your behavior tree is then not aware of the animations at all and it can even work with [root motion](https://docs.unity3d.com/Manual/RootMotion.html). You also don't over-complicate your tree with Animator tasks and makes your tree a lot cleaner. The [Ultimate Character Controller](https://assetstore.unity.com/packages/slug/233710?aid=1100lGdc) uses this approach and for that asset we created a pretty large behavior tree. You can see the behavior tree on [this page](https://opsive.com/support/documentation/behavior-designer/integrations/opsive-character-controllers/) and you'll notice that there are no Animator tasks within the tree. A bridge component is linking the NavMeshAgent's velocity to the character controller's inputs which then allow the Ultimate Character Controller to take care of the animations.
---
# Referencing Scene Objects
[View this page online](https://opsive.com/support/documentation/behavior-designer/referencing-scene-objects/)
As you are creating your tree it is common practice to reference objects within the scene from a Shared Variable or task. For example, in this tree Can See Object is determining if the Enemy object can be seen:
As you are testing you find that everything is working well and now you'd like to make a prefab out of it so you can have multiple agents in your scene. As soon as you make the agent a prefab and remove it from the scene you'll find that the Target Object reference has gone missing. The reason this occurs is because as a project level asset (the prefab, or global variables file) cannot reference objects in the scene. This is a Unity restriction and the way to overcome it is to populate the variable at runtime after you have spawned the prefab. The scene reference object can be populated at runtime in many different ways. One way is to use the Find task and search for the object by name:
When the Find task runs it'll search for a GameObject named "Enemy" and then place it in a SharedVariable. When Can See Object runs it'll then use that SharedVarible to search for the target object. Another way to populate the value at runtime is to have a component already in the scene which has a reference to the object. After the prefab has been spawned this component can then set the value of a SharedVariable that the Can See Object uses.
```csharp
using UnityEngine;
using BehaviorDesigner.Runtime;
public class Spawner : MonoBehaviour
{
public GameObject m_Enemy;
public void Start()
{
var behaviorTree = GetComponent();
behaviorTree.SetVariableValue("Enemy", m_Enemy);
}
}
```
---
# Task Attributes
[View this page online](https://opsive.com/support/documentation/behavior-designer/task-attributes/)
Behavior Designer exposes the following task attributes: HelpURL, TaskIcon, TaskCategory, TaskDescription and LinkedTask.
### Help URL
If you open the task inspector panel you will see on the doc icon on the top right. This doc icon allows you to associate a help webpage with a task. You make this association with the HelpURL attribute. The HelpURL attribute takes one parameter which is the link to the webpage.
```csharp
[HelpURL("http://www.example.com")]
public class MyTask : Action
{
```
### Task Icon
Task icons are shown within the behavior tree using the TaskIcon attribute and are used to help visualize what a task does. Paths are relative to the root project folder. The keyword {SkinColor} will be replaced by the current Unity skin color, "Light" or "Dark".
```csharp
[TaskIcon("Assets/Path/To/{SkinColor}Icon.png")]
public class MyTask : Action
{
```
### Task Name
The default task name can be changed with the TaskName attribute. This will change the displayed name when the task is added and also within the task list.
```csharp
[TaskName("MyCoolTask")]
public class MyTask : Action
{
```
### Task Category
Organization starts to become an issue as you create more and more tasks. For that you can use TaskCategory attribute:
```csharp
[TaskCategory("Common")]
public class Seek : Action
{
```
This task will now be categorized under the common category:
Categories can be nested by separating the category name with a slash:
```csharp
[TaskCategory("RTS/Harvester")]
public class HarvestGold : Action
{
```
### Task Description
The TaskDescription attribute allows you to show your class-level comment within the graph view. For example, the sequence description starts out with:
```csharp
[TaskDescription("The sequence task is similar to an \"and\" operation. ..."]
public class Sequence : Composite
{
```
This description will then be shown in the bottom left area of the graph:
###  Linked Task
[Variables](https://opsive.com/support/documentation/behavior-designer/variables/) are great when you want to share information between tasks. However, you'll notice that there is no such thing as a "SharedTask". When you want a group of tasks to share the same tasks use the LinkedTask attribute. As an example, take a look at the task guard task. When you reference one task with the task guard, that same task will reference the original task guard task back. Linking tasks is not necessary, it is more of a convince attribute to make sure the fields have values that are synchronized. Add the following attribute to your field to enable task linking:
```csharp
[LinkedTask]
public TaskGuard[] linkedTaskGuards = null;
```
To perform a link within the editor perform the same steps as [referencing another task](https://opsive.com/support/documentation/behavior-designer/referencing-tasks/).
---
# Integrations
[View this page online](https://opsive.com/support/documentation/behavior-designer/integrations/)
Behavior Designer includes many tasks which integrate with third party assets. For most of those integrations, no extra steps are required and they can be added to a behavior tree and then have their values assigned. However, the integrations below have a more detailed explanation for how they work. [Dialogue System for Unity](https://opsive.com/support/documentation/behavior-designer/integrations/dialogue-system-for-unity/) [Playmaker](https://opsive.com/support/documentation/behavior-designer/integrations/playmaker/) [Ultimate Character Controller](https://opsive.com/support/documentation/behavior-designer/integrations/opsive-character-controllers/) [uScript](https://opsive.com/support/documentation/behavior-designer/integrations/uscript/)
---
# Dialogue System
[View this page online](https://opsive.com/support/documentation/behavior-designer/integrations/dialogue-system-for-unity/)
The [Dialogue System](https://assetstore.unity.com/packages/tools/ai/dialogue-system-for-unity-11672?aid=1100lGdc) is a complete dialogue system for Unity. Behavior Designer is integrated with the Dialogue System by allowing you to manage conversations, barks, sequences, and quests within your behavior tree. Also, Dialogue System is integrated with Behavior Designer so it can synchronize variables with Lua and start/stop behavior trees with sequence commands. More information on this side of the integration can be found [here](http://www.pixelcrushers.com/dialogue_system/manual/html/behavior_designer.html). All of the Dialogue System integration files are located on the [downloads page](/downloads/). To get started, first make sure you have Dialogue System for Unity installed and have imported the integration package. Once those files are imported you are ready to start creating behavior trees with the Dialogue System. Let's create a very basic tree with a sequence task which has a Wait task and a Start Conversation task:
When the Dialogue System finishes with a conversation or sequence it will callback to Behavior Designer to let Behavior Designer know that it is done. In order for this to occur the Dialogue System Callback component must be added to the same GameObject that your behavior tree is on:
Now we are ready to start creating the actual conversion. Create a new Dialogue System Database and create a basic conversation:
Make note of the conversation name because that will be needed later. Assign that database to the Dialogue System Controller:
The last step is to simply assign the values within the Start Conversation task. The only two values that are required are the conversation name and the actor GameObject:
Once those values have been assigned, hit play and you'll see the text "Hello World" appear at the top of the game screen:
This topic hardly scratches the surface for what is possible with Behavior Designer / Dialogue System integration. For a more complex example, take a look at the Dialogue System sample project.
---
# Opsive Character Controllers
[View this page online](https://opsive.com/support/documentation/behavior-designer/integrations/opsive-character-controllers/)
https://www.youtube.com/watch?v=W5Of1lC-L68 **This integration package can be downloaded on the [downloads page](/downloads/).** The Opsive Character Controllers are integrated with Behavior Designer allowing your AI to perform any function that a player-controlled character can perform. When you are creating a new character that should be used with Behavior Designer ensure you have enabled AI Agent within the Character Manager. If you are using Unity's Navigation Mesh you should also enabled the NavMeshAgent toggle.
After the character has been created the Behavior Tree Agent Setup should be run on the character. This can be found within the Opsive Character Controller [integration package](/downloads/).
The Agent Setup editor will add the Behavior Tree and Behavior Tree Agent components. In the demo scene you'll notice that there is also a Demo Agent component added which adds the character's health and ammo as property's for Behavior Designer's [Property Mapping](https://opsive.com/support/documentation/behavior-designer/variables/) feature. After the character has been setup it's time to create your own behavior tree. The included behavior tree provides a great overview of the behavior tree flow so the rest of this document will describe how that behavior tree works. In order to get the most out of Behavior Designer it is highly recommended that you create your own behavior tree. The included behavior tree will perform the following functions:
- Attack if the player is within sight.
- Attack if the player attacks the agent.
- Move towards the audio source location if a sound from the player is heard.
- Search for the player if the player is lost.
- Get health if needed.
- Get ammo if needed.
- Patrol if no other actions are necessary.
The entire behavior tree looks like:
Behavior trees evaluate from top to bottom, left to right. This means that the very first task that runs is the Sequence task directly beneath the Entry task:
The Sequence task is a Composite task that will evaluate all of its children until a child returns a status of failure. The Sequence task can be thought of an AND between the child tasks. The first three tasks that this Sequence task will execute relate to resetting the behavior tree to get it ready for the next run. The variables that these tasks are resetting will be described later. A Parallel task is then used to execute multiple children at the same time. There are two branches that this Parallel task will execute:
- Left branch which will perform the actual actions such as the movement or attack.
- Right branch which will keep the player's location up to date when the Update Position variable is true.
The main functionality of the tree is contained within the left branch:
This branch is parented with a Repeater task which is set to Repeat Forever. The Repeater task is a Decorator which will keep executing the child branch for as long as requested. Since Repeat Forever is enabled the Repeater will keep the branch active until the bheavior tree ends. A Selector is parented to the Repeater. The Selector task will execute its children until a child returns success. The Selector can be thought of as as OR between the child tasks. Because behavior trees evaluate from left to right the branches on the left have a higher priority than those on the right. This means that the very first branch that will execute is the branch that checks to determine if the agent is out of ammo:
The Sequence task of the ammo branch has a Lower Priority [Conditional Abort](https://opsive.com/support/documentation/behavior-designer/conditional-aborts/) set. Conditional Aborts allow the behavior tree to reevaluate child Conditional tasks when other branches are active. If the character is out of ammo then the character can't do anything so this branch has the highest priority. If a lower priority branch (any branch to the right of the ammo branch) is active and the agent runs low on ammo then the conditional abort will abort the lower priority branch and start executing the ammo branch. The ammo branch is a relatively simple branch that first checks to determine how much ammo the character has with the Int Comparison Conditional task. This Int Comparison task will compare the agent's ammo to a constant number. The amount of ammo is retrieved through the Ammo property mapping setup through the Demo Agent component. If this amount is less than the constant then the Int Comparison task will return success and the branch will execute. If the agent is low on ammo then it will stop aiming through the Start Stop Ability task. This is a task created for the Ultimate Character Controller and it will start or stop an ability based on the values specified. In this case the task will stop the Aim ability because the character shouldn't aim when retrieving ammo. Another Start Stop Ability task is run and this task will start the Speed Change task so the character will start running towards the ammo location. The Seek task (from the [Movement Pack](/assets/behavior-designer-movement-pack/)) will use Unity's navigation mesh to move the character to the specified position. After the character has arrived at the position the Start Stop Ability task is executed again only this time it will stop the Speed Change ability so the character will stop running.
> Image unavailable in the source documentation: `UltimateCharacterControllerTreeCanSeeBranch-1024x736.png`
If the agent doesn't need ammo then the next highest priority branch is the Can See branch. This branch contains the main action in that it will actually attack the player when the player is within sight. Similar to the Ammo branch, the can see branch uses a Lower Priority Conditional Abort so it will abort any lower priority branch. The Can See branch will be able to abort any branches to the right of it, which means that it will not be able to abort the Ammo branch because the Ammo branch is to the left of the Can See branch. The first task within the Can See branch is the Can See Object task from the Movement Pack. Can See Object will use a layer mask to search for any objects within sight. The player is on the Character layer so the task will only search for objects that are on that layer. Once the task finds the player the Is Alive task executes which will determine if the player is alive. There's no need to attack a dead character. The Set Shared GameObject task is then a helper task that will transfer the found Can See Object value to the Target variable. This is done so when other tasks operate on the found player variable the original object isn't lost. Two Set Bool tasks are then executed which indicates that the agent should wander if the player is lost and that the target's position should be updated. The right branch under the original Parallel task will then set the target's position to the Last Position variable.
A Selector task is then run which will first evaluate the left branch. The goal of the left branch is to attack the target for as long as the target is in sight. To accomplish this a Sequence task is used with the Self Conditional Abort. The Self Conditional Abort is a new abort type and this abort type will reevaluate the Conditional task for as long as the current branch is active. In this case the current branch contains the Is Alive task along with a Selector so it will reevaluate Is Alive for as long as the agent can see the target. The Is Alive task will return failure when the target is no longer alive.
The first branch that the Selector task will evaluate has a Parallel task as the parent. This Parallel task runs two branches:
- The left branch attacks if the target is within sight
- The right branch will keep the agent near the target
The left Attack branch uses another Can See Object task to determine if the agent is near the target. This Can See Object task is different from the first Can See Object task as it has a smaller distance magnitude so the agent will only attack when near the target. If the target is near the Start Stop Ability task will execute to keep the character aiming. After the agent is aiming the Start Stop Use task will execute which will actually use the item, which will either fire the assault rifle or swing the sword. A Wait task is then used to prevent the agent from trying to attack every frame.
While the Attack branch is running the Move Towards branch will also run. This branch contains two parts:
- Move into position after first acquiring the target.
- Stay in position after arriving in position.
To move into position the Within Distance task is used to determine if the agent is within distance of the target. A Self Conditional Abort is used so the Within Distance task will reevaluate for as long as any tasks within the current branch are active, in this case it will be the Seek task. As soon as Seek moves the agent close to the target the Within Distance task will return success and the Inverter will change that success to a failure so the branch will then stop executing. While the Seek task is active the Speed Change ability will be activated so the agent will run towards the target.
After the agent has move to be within distance of the target the right branch will keep the agent near the target. There are three main differences between this branch and the previous Move Towards branch:
- The current branch will have the character walk instead of run while seeking the target.
- A Can See Object task is used in addition to Within Distance so the agent will always be in sight of the target while attacking. As an example the target may move inside a structure which would cause prevent the agent from seeing the target even though the target may still be near the agent.
- An Idle task is used if the agent doesn't need to seek into any position. If the target is standing still and is within sight then the agent can keep attacking without having to change positions.
The agent will now attack and move towards the target while within distance. If the target gets away from the agent and moves too far away then the right Move Towards branch will return failure and execute the Reset branch. This Reset branch runs two Actions which will ensure the agent is no longer attacking and is no longer aiming.
When the target was first acquired the Wander and Update Position variables were set so the agent will search for the target if the target is lost. If the target is killed by the agent then there is no need for the agent to wander so the Target Death branch will reset all of the attacking related variables back to the default.
If the agent doesn't need to get ammo and the player is not within sight then the next highest priority branch will run. This branch uses the Ultimate Character Controller's event system to determine if the agent has taken damage. If the agent has taken damage then the Has Taken Damage task will return success and the branch will execute. When the agent has taken damage the branch will first get the position of the object that it took damage from and set Wander to true. Before the agent moves towards the target it will first determine if their health is critically low. If the health is critically low then the agent will seek towards a health pack. After the agent has either retrieved a health pack or determines that more health is not needed the branch will end. Remember that the Wander variable was set to true so the Wander branch will start executing if there are no more higher priority branches.
The next highest priority branch is the Can Hear branch. This branch uses the Can Hear Object task from the Movement Pack to determine if any audio sources are emitted a sound. If any audio is heard then the agent will run towards the audio source position by starting the Speed Change task and using the Seek task to move into position. The Wander variable is also set to true so the agent will wander if the target can't be seen by the time the agent arrives at the Seek location.
Throughout the execution of the tree there have been multiple cases where the Wander task was set to true. The Bool Comparison task will compare this Wander task variable to true to determine if the agent should wander. Before the agent can wander they first have to Seek to the Last Position. This variable will be set whenever the Update Position variable is true and it will indicate the last position that the target was located. When the agent arrives at the Last Position the Wander task will then execute which allows the agent to search for the target. Remember that during this time the higher priority branches are being reevaluted so if the player comes within sight of the agent at any time then the Can See branch will abort the current branch so the character can start to attack. The Wander task is parented to the Parallel Selector task which will execute all children until a child returns success. To the right of the Wander task is the Wait task which will return success after a predetermined duration. This will prevent the agent from wandering forever and put a cap to the amount of time that the agent wanders.
If no other branches need to execute then the tree will fall back to the Patrol branch. This branch will move the character between patrol points and keep the character moving until a higher priority branch aborts it.
As the Ammo, Can See, Taken Damage, Can Hear, Wander, and Patrol branches are executed near the top of the tree the Update Position branch will also execute. This branch will update the position of the target when the Update Position is true. This branch is separated out from the rest of the tree because not just a single branch can set Update Position to true so to prevent having to add the same tasks multiple times this branch has been added near the top under a Parallel task. Now that you've completed this overview you should have enough knowledge to get started to create you own tree with the Ultimate Character Controller. Make sure you go through the demo tree a few times to get familiar with Behavior Designer's visual editor.
---
# Playmaker
[View this page online](https://opsive.com/support/documentation/behavior-designer/integrations/playmaker/)
[Playmaker](https://assetstore.unity.com/packages/tools/visual-scripting/playmaker-368?aid=1100lGdc) is a popular visual scripting tool which allows you to easily create finite state machines. Behavior Designer integrates directly with PlayMaker by allowing PlayMaker to carry out the action or conditional tasks and then resume the behavior tree from where it left off. PlayMaker integration files are located on the [downloads page](/downloads) because Playmaker is not required for Behavior Designer to work. To get started, first make sure you have Playmaker installed and have imported the integration package. Once those files are imported you are ready to start creating behavior trees with Playmaker. To get started, create a very basic tree with a sequence task who has two Start FSM child tasks:
Next add two Playmaker FSM components to the same game object that you added the behavior tree to.
Open Playmaker and start creating a new FSM. This FSM is going to be a simple FSM to show how Behavior Designer interacts with Playmaker. For a more complicated FSM take a look at the Playmaker sample project. Behavior Designer starts the Playmaker FSM by sending it an event. Create this event by adding a new state called "Behavior Tree Listener" and adding a new global event called "StartFSM". The event must be global otherwise Behavior Designer will never be able to start the FSM.
Add a transition from that event along with a wait state, a set bool state, and a resume behavior tree state. Make sure you transition from the Resume Behavior Tree state to the Behavior Tree Listener state so the FSM can be started again from Behavior Designer.
Create a new variable within the Set Bool state and set that value to true.
Then within the Resume Behavior Tree state we want to return success based off of that bool value:
That's it for this FSM. Create the same states and variables for the second FSM that we created earlier. Do not set the bool variable to true for this FSM.
We are now done working in Playmaker. Open your behavior tree back up within Behavior Designer. Select the left Playmaker task and start assigning the values to the variables. Playmaker Game Object is assigned to the game object that we added the Playmaker FSM components to. FSM Name is the name of the Playmaker FSM. Event name is the name of the global event that we created within Playmaker.
Now we need to assign the values for the right Playmaker task. The values should be the same as the left Playmaker task except a different FSM Name.
That's it! When you hit play you'll see the first Playmaker task run for a second and then the second Playmaker task will start running.
If you were to swap the tasks so the second Playmaker task runs before the first Playmaker FSM, the behavior tree will never get to the first Playmaker FSM because the second Playmaker FSM returned failure and the sequence task stopped executing its children.
---
# uScript
[View this page online](https://opsive.com/support/documentation/behavior-designer/integrations/uscript/)
[uScript](https://assetstore.unity.com/packages/tools/visual-scripting/uscript-professional-1808?aid=1100lGdc) is a visual scripting tool which allows you to create complicated setups without needing to write a single line of code. Behavior Designer integrates directly with uScript by allowing uScript to carry out the action or conditional tasks and then resume the behavior tree from where it left off. uScript integration files are located on the [downloads page](/downloads) because uScript is not required for Behavior Designer to work. To get started, first make sure you have uScript installed and have imported the integration package. Once those files are imported you are ready to start creating behavior trees with uScript . To get started, create a very basic tree with a sequence task who has two Start Graph child tasks:
Now we need to create two GameObjects which will hold the compiled uScript graph:
Open uScript and start creating a new graph. Add the Behavior Tree Signal node, located under Events/Signals. When Behavior Designer wants to start executing a uScript graph it will start from this node. This node contains four events: Start Signal, Pause Signal, Resume Signal, and End Signal. Start Signal is used when the behavior tree task starts running. Pause Signal gets called when the behavior tree is paused, and the Resume Signal gets called when the behavior tree resumes from being paused. Finally, End Signal gets called when the uScript task ends. For our graph we are only going to create a few nodes, the uScript sample project shows a more complicated uScript graph. Create a node which has a delay of 3 seconds, sets a bool, then resumes the behavior tree. The Resume Behavior Tree node is located under Actions/Behavior Designer:
Now we need to create a Owner GameObject and bool variable.
Save the uScript graph and assign the component to your first uScript graph GameObject. Answer no if uScript asks if you want to assign the component to the master GameObject.
Create one more uScript graph. Make it the same as the last graph except set the bool to false:
Finally save that graph and assign the component to the second uScript GameObject:
We're almost done. The only thing left to do is to assign the correct uScript GameObject to the tasks within Behavior Designer. Open your behavior tree within Behavior Designer again. Click on the left uScript task and assign the uScript GameObject to your first uScript graph GameObject.
Do the same for the right uScript task, only assign the uScript GameObject to your second uScript graph GameObject. That's it! When you hit play you'll see the first uScript task run for three seconds, followed by the second uScript task.
If you were to swap the tasks so the second uScript graph runs before the first uScript graph, the behavior tree will never get to the first uScript graph because the second uScript graph returned failure and the sequence task stopped executing its children.
---
# Visual Scripting
[View this page online](https://opsive.com/support/documentation/behavior-designer/integrations/visual-scripting/)
Behavior Designer integrates directly with Unity's [Visual Scripting package](https://learn.unity.com/project/introduction-to-visual-scripting) by allowing Visual Scripting to carry out the action tasks and then resume the behavior tree from where it left off. The Visual Scripting integration files are located on the [downloads page](https://opsive.com/downloads). To get started ensure you have first added the BehaviorDesignerExtensions type to the Visual Scripting Type Options. This menu option can be found within the Unity Project Settings dialogue. Be sure to select Regenerate Nodes after you have added the type.
After the type has been added your Script Graph can communicate with your behavior tree. Your behavior tree should contain the Start Script Graph task with the name of the event that you want to start with your Script Graph. This event name should be the same as the string within a new Custom Event node from your Script Graph.
After your Custom Event has executed you can perform any operations within your Script Graph. In the sample Script Graph the Add node is used to add a constant to the synchronized variable. After all of your operations have been performed you can sync with the behavior tree by using the Resume Behavior Tree node from Behavior Designer Extensions object.
If within the Start Script Graph task you are not waiting on the Behavior Tree to complete then you do not need to add the Resume Behavior Tree node.
---
# Videos
[View this page online](https://opsive.com/support/documentation/behavior-designer/videos/)
The following videos will describe how to use Behavior Designer: https://www.youtube.com/watch?v=PuLuwzgYB4g&list=PLCPL5IYZm1NLVVxJx3-CFTLuHvLbCgmzk