Documentation 📖

Your guide to using NodeCanvas in Unity

Runtime Instantiation Tips

There is often the need to procedurally instantiate a number of different agents using the same Behaviour Tree or FSM at runtime. Due to the way NodeCanvas decouples the Behaviour Tree data from the agent, this is very easy to do with a number of different options.

Option 1

You just have a BehaviourTree asset created. You can use it directly without a BehaviourTreeOwner at all.

The StartGraph method has the following parameters:

  • Component agent: is the target agent the graph will use. In the above example the script component itself is passed.
  • IBlackboard parentBlackboard: an optional parent blackboard for the graph. If null like in the example above, only the graph local blackboard will be used.
  • UpdateMode updateMode: Determines when the graph will update. It can also be UpdateMode.Manual, in which case you will need to update the graph manually by calling .UpdateGraph().

Option 2

You have a game object prefab with a BehaviourTreeOwner. You also have created a BehaviourTree asset.

At runtime you can instantiate the BehaviourTreeOwner game object prefab and call StartBehaviour(Graph newGraph) on it, providing the BehaviourTree like this:

Option 3

You only have a BehaviourTree created and no BehaviourTreeOwner at all. You can add the BehaviourTreeOwner component at runtime and similarily to above, Start a new graph for them:

Of course in most cases you will also want to assign a blackboard for the BehaviourTreeOwner to use.

 Going Further

Using the StartBehaviour(Graph) or SwitchBehaviour(Graph) you can go further and even switch BehaviourTrees at runtime. Here is an example:

While this is quite possible, it is best design-wise, to have only one BehaviourTree and switch behaviours within using Sub Behaviour Trees.

All the above examples are also true for State Machines as well.

Manual Tick (BehaviourTrees only)

Sometimes you may want to Tick a BehaviourTree manually instead of relying on StartBehaviour, PauseBehaviour and StopBehaviour. Here is how you could do this:

Remember that the Tick method also returns the root node status in case you care about it. Alternatively, you can get the root node status with the rootStatus property on the BehaviourTreeOwner, which in essence returns the currently assigned Behaviour Tree’s root node status.

Yes No
Last updated on May 10, 2025
Suggest Edit

© Paradox Notion 2014-2025. All rights reserved.