Behave documentation

Deprecated

Since the launch of Behave 2, documentation has been available through the AngryAnt community – accessible via the Unity help menu, when Behave 2 is installed.

This page contains documentation for Behave 1.4 and is no longer valid for the latest version of Behave – and will only be available so long as Behave 1.4 remains supported.

Behave 1.4 documentation

By default available for Unity, Behave runs on all Unity target platforms and does not require Unity pro. Once the package has been imported, you are all set.

Use the on-page navigation for documentation on various areas of Behave and don’t forget to check out the videos and external material section for additional documentation on Behave and behaviour trees.

Runtime types

Access

Behave.Runtime

Description

These are the types used by the Behave runtime classes. Specifically the Tree class and the IAgent interface and therefore you will be using them as well.

Enums

enum BehaveResult { Running, Success, Failure };

Delegates

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

The library class

Access

BL{YourLibraryName}

Description

As you compile your Behave library, the resulting .NET assembly will be set to contain a single point of entry – the library class. This is where you will be able to retrieve tree instances from, enums of the actions and delegates and so forth. If you do a debug build, you will also get an info text file generated, containing the name of the class, all enums, their integer values and so forth.

Static functions

Tree InstantiateTree (TreeType treeType, IAgent agent);
TreeType Type (Tree tree);
bool IsAction (int id);
bool IsDecorator (int id);

Enums

TreeType { CollectionName_TreeName, …, Unknown };
ActionType { ActionName, …, Unknown };
DecoratorType { DecoratorName, …, Unknown };
PriorityType { PriorityName, …, Unknown };
ContextType { ContextName, …, Unknown };

Tree

Access

Behave.Runtime.Tree

Description

The Tree class is an abstract class from which each compiled Behave tree in your library inherits. It is the interface you will use to communicate with the tree instances you receive from your library class.

Methods

BehaveResult Tick ([IAgent agent, object data]);
void Reset ([IAgent agent, object data]);
void SetInitForward (int id, TickForward init);
void SetInitForward (int id, TickForwardShort init);
void SetTickForward (int id, TickForward tick);
void SetTickForward (int id, TickForwardShort tick);
void SetResetForward (int id, ResetForward reset);
void SetResetForward (int id, ResetForwardShort reset);

Properties

int ActiveContext { get; }
// A context can be set by a component at any time and remains in place until another context is set or the tree tick ends. Subtrees inherit contexts.
float Frequency { get; }
// The frequency is set in the tree designer, but has no impact on the runtime apart from the return value of this property
int ActiveID { get; }
// In a tick or init call on an agent, this will be the ID of the action or decorator
// These are set after execution of a tick method on an agent:
int LastTicked { get; }
int LastTickedAction { get; set; }
int LastTickedDecorator { get; set; }
float LastTickTime { get; }
// This is grabbed from UnityEngine.Time.time
bool DebugAvailable { get; }
// If the above returns true, then debug is available and these get updated:
string Name { get; }
int ActiveComponent { get; }

IAgent

Access

Behave.Runtime.IAgent

Description

This is the interface you will be implementing on scripts responsible for handling action and decorator invokes. The interface itself is quite short and simple, but I will add in here the documentation on the action and decorator handlers which are automatically reflected and hooked up to your tree instances on creation.

What this basically means is that any method following a specific pattern of naming and declaration will be recognised as the handler for an action or decorator during the instantiation process of a tree. This is very similar to how Start, Awake and other events are automatically detected and invoked on Unity MonoBehaviours without being part of the MonoBehaviour class definition.

Your absolute bare minimum implementation of an agent is to just implement the Tick and Reset methods of the interface which means whenever an action or decorator is ticked or reset, those methods will be invoked. If you set up forwards/handlers for actions and decorators, those will be used in stead.

Remember that in stead of relying on automatic registration of handlers, you can always use the SetForward methods of the Tree class to manually specify which method should handle a given action or decorator. This also has the advantage of being able to cluster handling of related actions/decorators in a single method.

Methods

BehaveResult Tick (Tree sender, bool init);
void Reset (Tree sender);
int SelectTopPriority (Tree sender, params int[] IDs);

Recognised handlers (must be public)

BehaveResult Init{Name}{Action|Decorator} (Tree sender, string stringParameter, float floatParameter, IAgent agent, object data);
BehaveResult Tick{Name}{Action|Decorator} (Tree sender, string stringParameter, float floatParameter, IAgent agent, object data);
void Reset{Name}{Action|Decorator} (Tree sender, string stringParameter, float floatParameter, IAgent agent, object data);
BehaveResult Init{Name}{Action|Decorator} (Tree sender);
BehaveResult Tick{Name}{Action|Decorator} (Tree sender);
void Reset{Name}{Action|Decorator} (Tree sender);
BehaveResult {Name}{Action|Decorator} {get; set;}
// For properties, get is recognised as the tick handler and set as the reset handler. You are not required to implement both for one to be recognised.

Videos and external material

The following brief videos provide an overview of Behave:

These external resources are great for understanding both Behave and behaviour trees:

  • “Behavior trees for next-gen game AI” article and video presentation by Alex J. Champandard of aiGameDev.com. An account is required to view the video, but subscription is free.
  • “Introduction to Behaviour Trees” by Bjoern Knafla for #AltDevBlogADay. A nice introduction to how behaviour trees work – including examples. Choice and naming of component differs a bit from Behaves component set, but everything in the article is achievable with the Behave components.
  • “Oh, Behave! AI with behaviour trees in Unity and C#”" video masterclass by me for AIgameDev.com. This video goes through some of the inner workings of Behave – including its compiler and code generation structure. An AIgameDev Premium account is required to access this video.