Documentation

Learn how to use NodeCanvas

Download PDF Version

Framework Concepts

In this section, the core concepts of the NodeCanvas framework will be explained in as much detail as needed to get help you understand how things work behind the scenes. This information holds true for all systems created on the NC framework. The following text can become a bit technical so if you don’t feel like it, feel free to skip this.

Agents

Agent is a core term used to describe the ‘object’ that something is executed for, like for example ‘who’ an Action will execute for, or ‘who’ a Condition will be checked against. In NodeCanvas, Agent is a Component type reference rather than a GameObject reference which allows for some flexibility. An Agent reference is propagated to the Graph when it executes.

Blackboards

Blackboard is a object in which variables can be stored or be retrieved from. It is used to communicate data within different Nodes or Tasks that have no knowledge of one another what so ever. A Blackboard reference is propagated to the Graph when it executes. You will use Blackboard variables to parametrize the Graph assigned to a GraphOwner.

GraphOwners

The GraphOwner is a simple component that wraps the execution of a graph that is assigned to it. It acts as a front-end “interface” through which the assigned graph gets executed and can be controlled, or information about it’s state can be retrieved. Using GraphOwners is the easiest way to make an object behave based on a NodeCanvas graph system, but it’s not mandatory.

Gameobjects with at least one GraphOwner attached to them will show a ♟ icon in the scene hierarchy within unity.

Graphs

Graphs hold the actual functionality of a system like BehaviourTree, FSM or DialogueTree, what it does and how it does it, as well as all the nodes within it. When a graph executes, it always does so for an Agent and using a specific Blackboard. A graph is able to run only for one Agent at a time, thus a separate instance for each agent required is created. This is of course automatically handled when you are using a GraphOwner.

Graphs can be Bound to an Agent or be an Asset reference. Bound Graphs are local and saved along with the gameobject that the GraphOwner is attached to, while Asset graphs are saved as a .asset file in your assets folder and as such they can be assigned to any number of different GraphOwners. The benefit of using Bound graphs though, is that because they are saved with the gameobject, if that game object is also in the scene, you can have scene object references assigned to that graph.

Nodes

Nodes live within a Graph and depending on the type of the Graph, different Nodes types can live within different Graph types. In NodeCanvas the ‘what’ and ‘if’ happens in most cases is not contained within a Node’s functionality though, but rather a Node wraps the functionality of Tasks which are assigned on nodes.

So in other words, a Node doesn’t contain the Action. It is rather assigned an Action to use if needed. This allows for non-destructive design by decoupling the tree design from the task implementation.

Tasks

Tasks are the Actions and Conditions. They are assigned on Nodes that require them and are the final destination of the execution tick. When a Task is executed or checked, it is done so for an Agent and a Blackboard. By default, this Agent and Blackboard are the ones that the Graph is using, although an Agent can be overridden if you want for example an Action to be performed by another Agent other than the default one that the Graph has assigned. Creating custom Tasks is what you most probably going to do for your game if you want so.

Yes No Suggest edit
27 of 29 users found this section helpful
Suggest Edit