Documentation

Features

Specs:

• Available for unity indie as well as pro licensees
• Can run in webplayers as well as stand-alone
• Requires no additional installations at runtime

Features:

• Implements behaviour trees
• Re-use common behaviour by reference
• Drag and drop editor interface inside the unity editor
• Simple connection to character actions via C# interface
• Designed trees are built to .net assembly code for maximum performance
• Runtime debugging features

New version, old documentation

Behave 1.0 just hit and with that, a lot of things have been improved, changed and removed. This page will be updated with up to date information as fast as possible, but for now I will keep this page in place as many parts of the product remain the same or very similar.

One of the areas which have undergone a lot of changes is the Behave runtime, so without further ado, here follows the new API:

Syntax: user defined, [ optional ].

namespace BehaveLibrary
{
    public enum BehaveResult{ Running, Success, Failure };

    public delegate BehaveResult TickForward( bool init, Tree sender, string stringParameter, float floatParameter, IAgent agent, object data );
    public delegate void ResetForward( Tree sender, string stringParameter, float floatParameter, IAgent agent, object data );
    public delegate BehaveResult TickForwardShort( bool init, Tree sender );
    public delegate void ResetForwardShort( Tree sender );

    public class Tree
    {
        public BehaveResult Tick( IAgent agent, object data );
        public void Reset( IAgent agent, object data );

        public int ActiveID{ get; }
        public int LastTicked{ get; }
        public int LastTickedAction{ get; }
        public int LastTickedDecorator{ get; }

        public float Frequency{ get; }
        public float LastTickTime{ get; }

        public void SetTickForward( int id, TickForward tick );
        public void SetResetForward( int id, ResetForward reset );
        public void SetForward( int id, TickForward tick, ResetForward reset );
        public void SetTickForward( int id, TickForwardShort tick );
        public void SetResetForward( int id, ResetForwardShort reset );
        public void SetForward( int id, TickForwardShort tick, ResetForwardShort reset );

        public bool DebugAvailable{ get; }
        // Available in debug builds:
        public int ActiveComponent{ get; }
        public void OnGUI();
    }
}

using BehaveLibrary;

public class YourClass : [ MonoBehaviour, ] IAgent
{
    [
        void BehaveResult YourActionNameAction{ get; set; }
        void BehaveResult YourDecoratorNameDecorator{ get; set; }

        BehaveResult TickYourActionNameAction( bool init, Tree sender
            [, string stringParameter, float floatParameter, IAgent agent, object data ] );

        void ResetYourActionNameAction( Tree sender
            [, string stringParameter, float floatParameter, IAgent agent, object data ] );

        BehaveResult TickYourDecoratorNameDecorator( bool init, Tree sender
            [, string stringParameter, float floatParameter, IAgent agent, object data ] );

        void ResetYourDecoratorNameDecorator( Tree sender
            [, string stringParameter, float floatParameter, IAgent agent, object data ] );

        /* ... */
    ]

    BehaveResult Tick( bool init, Tree sender );
    void Reset( Tree sender );
}

public class BLYourLibraryName
{
    public BLYourLibraryName Instance{ get; }
    public enum Trees{ YourCollectionName_YourTreeName, /* ... ,*/ Unknown };
    public enum Actions{ YourActionName, /* ... ,*/ Unknown };
    public enum Decorators{ YourDecoratorName, /* ... ,*/ Unknown };

    public Tree Tree( int treeID, IAgent agent );
    public int TreeID( Tree tree );
    public bool IsAction( int id );
    public bool IsDecorator( int id );
}

Tutorials

I’ve had some requests to add a tutorials section, so here we go. If you have gone through these and you’re looking for more, I’d recommend you download the demo project available from the Downloads section and pick that apart.

This section will *not* contain tutorials on behaviour tree design. On that subject I would recommend the awesome resources at aigamedev.com.

Tutorial 1: Getting started

This tutorial describes, step by step, the process of going from a brand new unity project to using the Behave editors to design a behaviour tree, compiling it and using it in your code. New to Behave? Go for it!

Tutorial 2: Taking advantage of OOP in agents

In this tutorial I describe how the script action interface of Behave enables developers to take advantage of OOP in their designs. Sounds like fun, eh?

Designing and compiling your trees

The Behave project consists of three parts: an editor, a compiler and a runtime. While this section briefly describes the editor and compiler parts, the runtime is covered in the next section.

The editor

All Behave trees are stored in collections inside Behave libraries. These are stored in Behave assets which can be created via the “Assets -> Create -> Behave library” menu in unity or the mini menu located above your assets browser. Once you have created such an asset, you can edit it via the “Assets -> Behave -> Edit library” menu.

Selecting “Edit library” launches the Behave library editor. In here you are able to manage your collections and the trees stored within them. Pressing the “Edit” button below the tree list launches the Behave tree editor on the selected tree.

The Behave tree editor consists of three parts: the components list, the inspector and the tree view. The component list enables you to add the basic components and references to other trees to your current tree. These appear in the tree view which is the core of the tree editor.

In the tree editor you can move your components around and drag-drop connections from component input connectors to the output connectors of other components. At the top, centre of the tree view, the entry point output connector is located, connect this to the component to be executed first in your tree.

The inspector view enables you to remove outgoing connections from the selected sequence or selector component and re-arrange the order of them. In here you can also specify component comments and action names.

Once you are done editing a tree, simply close the Behave tree editor and you will get a “save changes” prompt.

The compiler

Once you have finished designing your behaviour trees, you need to compile the data to a .net assembly in order to access their functionality in the Behave runtime. This is simply done by selecting your Behave library asset and clicking the compile menu item in the “Assets -> Behave” menu in unity. When compilation completes, your Behave library is available in the Behave runtime.

If you decide to compile the library including debug information, the library data will be included in the resulting assembly which enables debug functionality in the Behave runtime (see the Runtime section for more information). Furthermore, a debug compile will generate a text file in your assets folder. This file contains the name of the library class and a list of the values included in the Trees, Actions and Decorators enums.

Runtime script interface

Once your Behave library is compiled, your next step is to implement its functionality in your game code. This is done via the Behave runtime script interface.

Agent

In order to have a character receive action information from a Behave tree, it needs to implement the BehaveLibrary.Agent interface. This interface defines two methods: TickAction and Reset action.

TickAction is called by a Behave tree once it reaches an action node. The method receives an int identifying which action is requested (this value is mapped to the BLYourLibraryName.Actions enum), a reference to the tree calling this action, and finally the user data Object reference set when the tree was ticked.

Once your code has executed the requested action, TickAction should return one of the BehaveLibary.BehaveResult enum values: Running (the requested action is a time-consuming one which will need to be called again next AI frame) / Success (the action has been executed with success) or Failure (the action has been executed and the result is a failure).

ResetAction is called by a Behave tree when that tree is reset. Its parameters are set like those of TickAction.

The TickDecorator and ResetDecorator works in exact same way, only for decorators.

BLYourLibraryName

To access your library, you need to create an instance of your library class. The name of this class is BL<The name of the behave asset at compile time> (for this very reason, it is important that you name your behave asset in a fashion which translates into a legal class name – for instance no spaces in the name).

Call the Tree method with a BLYourLibraryName.Trees enum value to get an instance of the desired tree.

The TreeID method returns the integer mapped to the BLYourLibraryName.Trees enum corresponding to the Tree given as parameter.

DebugAvailable returns a boolean value indicating whether the library has been compiled with debug data available. If this is not the case then the functionality of the GetActiveComponent and OnGUI methods will be unavailable.

When a Behave library is compiled with debugging enabled, the Behave runtime will keep track of the currently active component. The GetActiveComponent method will return a string describing the currently active component of the given Tree.

Also when a Behave library is compiled with debugging enabled, the OnGUI method will render the given Tree to the unity GUI. Note that this method must be called from within an MonoBehaviour.OnGUI method.

Tree

The tree class is the compiled version of the behaviour tree which you designed via the editor. In order to execute one traversal of the tree, you need to call its Tick method and supply an instance of a class implementing the Agent interface as parameter.

This will cause the tree to run through the branches you previously defined and ask the supplied Agent to execute all action nodes encountered in that run. When the run is completed, the result of the entry-point node is returned as a BehaveLibrary.BehaveResult enum value.

Calling the Reset method of the tree will cause it to reset all internal representations of progress (specifically the markers representing the progress of sequences and selectors) including all actions used by the tree and implemented by the supplied Actor.

The Tick and Reset methods allow for user data to be passed on via the data Object reference parameter.