Custom Task

Instruction to create custom user task

In the AI Tree you can easily create your own task by using scripting API. In this page we will show how you can do it.

Let's create task to move platforms between two point.

This is a very simple example, we have specially chosen a simple example to make it easier to learn this material.

First of all you need to create new script. The easiest way is to use templates. Open context menu in Project window (right mouse click) and go to following path.

Create -> Renowned Games -> AI Tree -> Script Templates -> Task

Menu item path to Task template

We'll call it MovePlatformTask, after creation open it script in you scripts editor tool.

MovePlatformTask script

Task script template already contains all required code blocks, you just need to add task logic.

using RenownedGames.AITree;

[NodeContent("MovePlatformTask", "Tasks/Custom/MovePlatformTask")]
public class MovePlatformTask : TaskNode
{
    /// <summary>
    /// Called on behaviour tree is awake.
    /// </summary>
    protected override void OnInitialize()
    {
        base.OnInitialize();
    }

    /// <summary>
    /// Called when behaviour tree enter in node.
    /// </summary>
    protected override void OnEntry()
    {
        base.OnEntry();
    }

    /// <summary>
    /// Called every tick during node execution.
    /// </summary>
    /// <returns>State.</returns>
    protected override State OnUpdate()
    {
        return State.Success;
    }

    /// <summary>
    /// Called when behaviour tree exit from node.
    /// </summary>
    protected override void OnExit()
    {
        base.OnExit();
    }
}

---

We want to create following logic: A task is considered successful if the platform reaches one of the points after which it go to another task.

We will remove methods that are not necessary for this task so as not to overload the code.

using RenownedGames.AITree;

[NodeContent("MovePlatformTask", "Tasks/Custom/MovePlatformTask")]
public class MovePlatformTask : TaskNode
{
    /// <summary>
    /// Called on behaviour tree is awake.
    /// </summary>
    protected override void OnInitialize()
    {
        base.OnInitialize();
    }
    
    /// <summary>
    /// Called when behaviour tree enter in node.
    /// </summary>
    protected override void OnEntry()
    {
        base.OnEntry();
    }

    /// <summary>
    /// Called every tick during node execution.
    /// </summary>
    /// <returns>State.</returns>
    protected override State OnUpdate()
    {
        return State.Success;
    }
}

---

Let's focus on each line to understand what they are for.

// Namespace to load all required AITree API. 
using RenownedGames.AITree;

// An attribute so that the tree can see this task.
// First param: Initialname of task.
// Second param: Path to task in search context menu of the tree.
[NodeContent("Move Platform", "Tasks/Custom/Move Platform")]

The label in node content attribute may differ from the name of the class, for example, you can add spaces, symbols, numbers, etc. there.

We renamed the automatically generated MovePlatformTask label to Move Platform, just for nice display in tree graph.

// TaskNode base class for all tasks, all the tasks must be implemented from TaskNode
public class MovePlatformTask : TaskNode

// Virtual method which called on behaviour tree is awake.
protected override void OnInitialize()

// Virtual method called when behaviour tree enter in node.
protected override void OnEntry()

// Virual method which called every tick during node execution.
protected override State OnUpdate()

These are not the only virtual methods available for overloading. Each method is overloaded in a similar way and has a detailed description.

In this example, we have described only those methods that are needed for this task, you can learn more about all the methods in this page.

---

For moving platform we will use Unity transform component. Every gameobject in the scene has this component, so let's store it to easy access in every tick update.

using RenownedGames.AITree;
using UnityEngine;

[NodeContent("Move Platform", "Tasks/Custom/Move Platform")]
public class MovePlatformTask : TaskNode
{
    private Transform transform;

    protected override void OnInitialize()
    {
        base.OnInitialize();
        
        // GetOwner() it's a reference to current AI entity in the scene.
        transform = GetOwner().transform;
    }
    
    protected override void OnEntry()
    {
        base.OnEntry();
    }

    protected override State OnUpdate()
    {
        return State.Success;
    }
}

Note that we used the OnInitialize() method to retrieve the Transform component, rather than OnEntry(). Although these methods may seem similar, in this case, it's preferable to use OnInitialize() because the Transform component remains unchanged throughout the game. There's no need to fetch it every time the node is entered through the OnEntry() method. Instead, we store the Transform reference once and use it throughout the entire lifecycle of the tree, improving efficiency.

---

In next step we need to define two point, speed and one vector for destination, for this time let's make them fixed.

using RenownedGames.AITree;
using UnityEngine;

[NodeContent("Move Platform", "Tasks/Custom/Move Platform")]
public class MovePlatformTask : TaskNode
{
    private Transform transform;

    private Vector3 pointA;
    private Vector3 pointB;
    private Vector3 destination;
    private float speed;

    protected override void OnInitialize()
    {
        base.OnInitialize();
        transform = GetOwner().transform;
    
        pointA = Vector3.zero;
        pointB = new Vector3(3, 0, 0);
        destination = pointB;
        speed = 0.5f;
    }

    protected override void OnEntry()
    {
        base.OnEntry();
        if(Vector3.Distance(transform.position, pointA) < 0.1f)
        {
            destination = pointB;
        }
        else
        {
            destination = pointA;
        }
    }

    protected override State OnUpdate()
    {
        return State.Success;
    }
}

Here we implemented OnEntry() to determine the next destination point for moving before each node running. Because trasform position will change and we need to swap destination point every time before running.

---

Now let's implement the logic of moving between points.

using RenownedGames.AITree;
using UnityEngine;

[NodeContent("Move Platform", "Tasks/Custom/MovePlatformTask")]
public class MovePlatformTask : TaskNode
{
    private Transform transform;

    private Vector3 pointA;
    private Vector3 pointB;
    private Vector3 destination;
    private float speed;

    protected override void OnInitialize()
    {
        base.OnInitialize();
        transform = GetOwner().transform;

        pointA = Vector3.zero;
        pointB = new Vector3(3, 0, 0);
        destination = pointB;
        speed = 0.5f;
    }

    protected override void OnEntry()
    {
        base.OnEntry();
        if(destination == pointA)
        {
            destination = pointB;
        }
        else
        {
            destination = pointA;
        }
    }

    protected override State OnUpdate()
    {
        if(Vector3.Distance(transform.position, destination) > 0.01f)
        {
            float speed = platformKey.GetValue().speed;
            transform.position = Vector3.MoveTowards(transform.position, destination, speed * Time.deltaTime);
            return State.Running;
        }
        transform.position = destination;
        return State.Success;
    }
}

Note that we return two different states Success and Running depending on the condition.

Success means that the node has successfully completed its task. This is the final state that tells the system that this operation has been completed successfully and need to proceed to the next node.

Running means that the node is in the process of completing its task. This status indicates that the action is ongoing and has not yet been completed. The node that returns Running will continue execution the next time the Behavior Tree is updated.

Until the platform reaches its destination, we tell the tree to update the position. After reaching the destination, we tell the tree that the next node can be started.

In this example, we have described only those states that are needed for this task, you can learn more about all the states in this page.

---

Done. Now we can add our task on behaviour tree window and setup simple tree.

What happed in this tree:

1. Sequencer running task from left to right (built-in node).

2. Move Platform task moving self to destination point.

3. Wait task waiting for a 1 second (built-in node).

4. Repeat.

First, we move the platform to point B (since it’s already at point A), then wait for one second. On the next entry to the MovePlatform task, we change the destination to point A (since the platform is now at point B) and repeat this process infinitely.

Tree sample

---

Result