Class BehaviorGraphAgent

Manages a behavior graph's lifecycle on a GameObject and handles data through blackboard variables.

The BehaviorGraphAgent maintains the following lifecycle states:

- Uninitialized - The graph has been assigned but not instantiated yet

- Initialized - The graph has been instantiated with a unique copy for this agent

- Started - The graph has started running

- Running - The graph is being updated each frame via Tick()

- Ended - The graph has been stopped and is no longer running

Initialization Sequence:

- When a graph is assigned in the Inspector, it's automatically initialized during Awake()

- When assigning a graph via the Graph property at runtime, it's automatically initialized during the next Update()

- You can also explicitly control initialization by calling Init() manually

Blackboard Variable Handling:

- Before initialization: SetVariableValue() sets agent-level overrides (visible in the Inspector)

- After initialization: SetVariableValue() sets values in the instanced graph's blackboard

Inheritance
object
Object
Component
Behaviour
MonoBehaviour
BehaviorGraphAgent
Implements
Inherited Members
Object.InstantiateAsync<T>(T)
Object.InstantiateAsync<T>(T, Transform)
Object.InstantiateAsync<T>(T, Vector3, Quaternion)
Object.InstantiateAsync<T>(T, Transform, Vector3, Quaternion)
Object.Instantiate<T>(T, InstantiateParameters)
Object.Instantiate<T>(T, Vector3, Quaternion, InstantiateParameters)
Object.FindObjectsByType<T>(FindObjectsSortMode)
Object.FindObjectsByType<T>(FindObjectsInactive, FindObjectsSortMode)
Object.FindFirstObjectByType<T>()
Object.FindAnyObjectByType<T>()
Object.FindFirstObjectByType<T>(FindObjectsInactive)
Object.FindAnyObjectByType<T>(FindObjectsInactive)
Namespace: Unity.Behavior
Assembly: Unity.Behavior.dll
Syntax
[AddComponentMenu("AI/Behavior Agent")]
public class BehaviorGraphAgent : MonoBehaviour, ISerializationCallbackReceiver
Examples

Common Usage Patterns:

// Basic usage - assign graph and configure at runtime
agent.Graph = myBehaviorGraph;  // Graph will auto-initialize next Update
agent.SetVariableValue("Destination", targetPosition);

// Template pattern - configure, then instantiate multiple agents
templateAgent.Graph = sharedGraph;
templateAgent.SetVariableValue("Speed", defaultSpeed);  // Sets override


var newAgent = Instantiate(templateAgent);
newAgent.Init();  // Explicitly initialize
newAgent.SetVariableValue("PatrolPoints", uniquePatrolPoints);  // Per-instance value

Properties

BlackboardReference

The blackboard associated with the agent's graph.

Declaration
public BlackboardReference BlackboardReference { get; }
Property Value
Type Description
BlackboardReference

Graph

The graph of behaviours to be executed by the agent.

When assigning a new graph to this property:

- The agent will be marked as uninitialized and will automatically initialize during the next Update cycle (if agent is enabled)

- You don't have to manually call Init() or Start() when setting this property

About blackboard variable:

- Calling SetVariableValue() before the agent is initialized (after setting Graph but before the next Update) will set blackboard overrides at the agent level, visible in the inspector

- Calling SetVariableValue() after the agent is initialized will modify the individual instance variables

- This makes it possible to set default values that apply to all instances, or customize individual agent behaviors

Declaration
public BehaviorGraph Graph { get; set; }
Property Value
Type Description
BehaviorGraph
Examples
// Assign graph and set default value before initialization
agent.Graph = myGraph;
agent.SetVariableValue("Destination", new Vector3(10, 0, 10)); // Sets agent-level override

// After automatic initialization in Update, or manual Init():
agent.SetVariableValue("PatrolPoints", customPatrolPoints); // Sets instance-specific value

Methods

Deserialize<TSerializedFormat>(TSerializedFormat, IBehaviorSerializer<TSerializedFormat>, IUnityObjectResolver<string>)

Deserializes data on to the associated BehaviorGraph.

Declaration
public void Deserialize<TSerializedFormat>(TSerializedFormat serialized, RuntimeSerializationUtility.IBehaviorSerializer<TSerializedFormat> serializer, RuntimeSerializationUtility.IUnityObjectResolver<string> resolver)
Parameters
Type Name Description
TSerializedFormat serialized

Serialized data.
RuntimeSerializationUtility.IBehaviorSerializer<TSerializedFormat> serializer

Serializer to use.
RuntimeSerializationUtility.IUnityObjectResolver<string> resolver

Object resolver to use.
Type Parameters
Name Description
TSerializedFormat

Type of serialized data.

End()

Ends the execution of the agent's behavior graph.

Declaration
public void End()

GetVariable(string, out BlackboardVariable)

Gets the variable associated with the specified name. As blackboard variables are instantiated per agent instance on initialization, this function will return false in edit mode.

Declaration
public bool GetVariable(string variableName, out BlackboardVariable variable)
Parameters
Type Name Description
string variableName

The name of the variable
BlackboardVariable variable

Contains the value associated with the specified name, if the named variable is found; otherwise, the default value is assigned.
Returns
Type Description
bool

Returns true if a variable matching the name and type is found. Returns false otherwise (or if in edit mode).

GetVariable(SerializableGUID, out BlackboardVariable)

Gets a variable associated with the specified GUID. As blackboard variables are instantiated per agent instance on initialization, this function will return false in edit mode.

Declaration
public bool GetVariable(SerializableGUID guid, out BlackboardVariable variable)
Parameters
Type Name Description
SerializableGUID guid

The GUID of the variable to get
BlackboardVariable variable

The variable associated with the specified GUID.
Returns
Type Description
bool

Returns true if a variable with a matching GUID was found and false otherwise (or if in edit mode).

GetVariableID(string, out SerializableGUID)

Gets the ID of the variable associated with the specified name.

Declaration
public bool GetVariableID(string variableName, out SerializableGUID id)
Parameters
Type Name Description
string variableName
SerializableGUID id

Contains the ID associated with the specified name, if the named variable is found; otherwise, the default value is assigned.
Returns
Type Description
bool

Returns true if a variable matching the name and type is found. Returns false otherwise.

GetVariable<TValue>(string, out BlackboardVariable<TValue>)

Gets a variable associated with the specified name and value type. For values of type subclassed from UnityEngine.Object, use the non-generic method. As blackboard variables are instantiated per agent instance on initialization, this function will return false in edit mode.

Declaration
public bool GetVariable<TValue>(string variableName, out BlackboardVariable<TValue> variable)
Parameters
Type Name Description
string variableName

The name of the variable
BlackboardVariable<TValue> variable

The blackboard variable matching the name and value type
Returns
Type Description
bool

Returns true if a variable matching the name and type is found. Returns false otherwise (or if in edit mode).
Type Parameters
Name Description
TValue

The type of value stored by the variable

GetVariable<TValue>(SerializableGUID, out BlackboardVariable<TValue>)

Gets a variable associated with the specified GUID and value type. As blackboard variables are instantiated per agent instance on initialization, this function will return false in edit mode.

Declaration
public bool GetVariable<TValue>(SerializableGUID guid, out BlackboardVariable<TValue> variable)
Parameters
Type Name Description
SerializableGUID guid

The GUID of the variable to get
BlackboardVariable<TValue> variable

The variable associated with the specified GUID.
Returns
Type Description
bool

Returns true if a variable with a matching GUID and type was found and false otherwise (or if in edit mode).
Type Parameters
Name Description
TValue

The value type of the variable

Init()

Initializes a new instance of the agent's behavior graph.

When called, this method:

- Creates a unique instance of the assigned behavior graph

- Applies any blackboard variable overrides that were set prior to initialization

- Prepares the graph instance to run on this specific agent

Initialization sequence:

- Called automatically in Awake() if a graph is assigned in the Inspector

- Called automatically in the next Update() after setting the Graph property

- Can be called manually to explicitly control the initialization timing

- If the agent is already initialized, this method only reassigns the GameObject to graph modules

About blackboard variable:

- SetVariableValue() calls made before Init() set agent-level overrides

- SetVariableValue() calls made after Init() set variables on the instanced graph

- This allows for setting up default values before instantiation and instance-specific values after

Declaration
public void Init()
Examples
// Pattern for pre-configuring agents before instantiation:
templateAgent.Graph = sharedGraph;
templateAgent.SetVariableValue("BaseSpeed", 5f);  // Sets default override

// After spawning from template (or calling Init explicitly):
agent.Init();
agent.SetVariableValue("TargetPosition", GetRandomPosition());  // Sets instance variable

OnAfterDeserialize()

Declaration
public void OnAfterDeserialize()

OnBeforeSerialize()

Declaration
public void OnBeforeSerialize()

Restart()

Restarts the execution of the agent's behavior graph.

Declaration
public void Restart()

Serialize<TSerializedFormat>(IBehaviorSerializer<TSerializedFormat>, IUnityObjectResolver<string>)

Serializes the associated BehaviorGraph to data of TSerializedFormat type.

Declaration
public TSerializedFormat Serialize<TSerializedFormat>(RuntimeSerializationUtility.IBehaviorSerializer<TSerializedFormat> serializer, RuntimeSerializationUtility.IUnityObjectResolver<string> resolver)
Parameters
Type Name Description
RuntimeSerializationUtility.IBehaviorSerializer<TSerializedFormat> serializer

Serializer to use.
RuntimeSerializationUtility.IUnityObjectResolver<string> resolver

Object resolver to use.
Returns
Type Description
TSerializedFormat

Serialized data.
Type Parameters
Name Description
TSerializedFormat

Type of serialized output.

SetVariableValue<TValue>(string, TValue)

Sets the value of a blackboard variable matching the specified name and value type.

Declaration
public bool SetVariableValue<TValue>(string variableName, TValue value)
Parameters
Type Name Description
string variableName

The name of the variable
TValue value

The value to assign to the variable
Returns
Type Description
bool

Returns true if a variable matching the name and type is found and set. Returns false otherwise.
Type Parameters
Name Description
TValue

The type of value stored by the variable

SetVariableValue<TValue>(SerializableGUID, TValue)

Sets the value of the variable associated with the specified GUID.

Declaration
public bool SetVariableValue<TValue>(SerializableGUID guid, TValue value)
Parameters
Type Name Description
SerializableGUID guid

The guid associated with the variable
TValue value

The value to assign to the variable
Returns
Type Description
bool

Returns true if the value was set successfully and false otherwise.
Type Parameters
Name Description
TValue

The value type of the variable

Start()

Begins execution of the agent's behavior graph.

Declaration
public void Start()

Update()

Ticks the agent's behavior graph and initializes and starts the graph if necessary.

Declaration
public void Update()

Implements