Documentation

Learn how to use NodeCanvas

Download PDF Version

BT Nodes Reference

Leafs

Leafs have no children at all and they reside by the end of a branch.

Action

action

The Action Node will execute an Action Task assigned. The Action node will return Running until the Action Task is finished at which point it will return Success or Failure based on the Action Task assigned. NC comes with a variaty of different Action Tasks to use.

  • Success: When assigned Action Task finish in Success
  • Failure: When assigned Action Task finish in Failure
  • Running: While assigned Action Task has not finished.
Condition

condition

The Condition Node will execute a Condition Task and return Success or Failure based on that Condition Task. NC comes with a variaty of different Condition Tasks to use.

  • Success: If assigned Condition Task is true
  • Failure: If assigned Condition Task is false
  • Running: Never

Composites

Composites work with multiple chid nodes and execute them in some order based on the composite functionality.

Sequencer

sequencer

The Sequencer executes it’s child nodes in order from highest to lowest priority (left to right). It will return Failure as soon as any child returns Failure. It will return Success if all children return Success.

A Dynamic Sequencer will revaluate higher priority children Status changes. So if a higher priority child status returns Failure, the Sequencer will Interrupt the currently Running child and return Failure as well. This is extremely useful to create dynamic and immediate responses to higher priority status changes like for example conditions.

A Random Sequencer will shuffle it’s children on each reset and then start executing them in the new order.

  • Success: When all children finish in Success
  • Failure: When any child returns Failure
  • Running: When current executing child is Running
Selector

selector

The Selector executes it’s child nodes in order from highest to lowest priority (left to right). It will return Success as soon as any child returns Success. It will return Failure if all children return in Failure.

A Dynamic Selector will revaluate higher priority children Status changes. So it a higher priority child status returns Success, the Selector will interrup the currently Running child and return Success as well. Like the sequencer, this is extremely usefull to respond immediatly on status changes of higher priority children like for example conditions.

A Random Sequencer will shuffle it’s children on each reset and then start executing them in the new order.

  • Success: When any child returns Success.
  • Failure: When all children return Failure.
  • Running: When current executing child is Running.
Probability Selector

probabilitySelector

The Probability Selector will select and execute a child node based on it’s chance to be selected. If that selected child returns Succes, the Probability Selector will also returns Success. If it returns Failure though, a new child will be picked. The Probability Selector will return Failure if no child returned Success, or may immediately return Failure if a ‘Failure Chance’ is introduced.

As soon as you connect a child node, a probability value will show up in the inspector for that child and the node information will read the final chances calculated based on all probability values and the direct failure chance.

  • Success: When the selected child node returns Success.
  • Failure: When the selected child node returns Failure, or no child is selected because of a ‘Failure Chance’.
  • Running: When the selected child node returns Running.

Note: The probability values can be taken from blackboard variables to dynamicaly alter the probabilities.

Priority Selector

Priority Selector

prioritySelector

The Priority Selector is similar to a normal Selector but will pick the order of child execution based on the priority each child has. As soon as you connect child nodes, Priority weights will show up which you can alter either directly or through Blackboard variables.

  • Success: When the first child returns Success.
  • Failure: When all children return Failure.
  • Running: When the current child is Running.
Parallel

parallel

The Parallel will execute all it’s children simultaneously. It can be set to have the policy of a Sequencer or a Selector like so:

If set to First Failure, then as soon as any child returns Failure, the parallel will reset all current Running children and return Failure as well. Else it will return Success when all children have returned Success.

If set to First Success, then as soon as any child returns Success, the parallel will reset all current Running children and return Success as well. Else it will return Failure when all children have returned Failure.

  • Success: If set to ‘First Success’, when any child returns Success. If set to ‘First Failure’, when all children finish in Success.
  • Failure: If set to ‘First Failure’, when any child returns Failure. If set to ‘First Success’, when all children finish in Failure.
  • Running: When any child is Running.
Flip Selector

flipsSelector

The Flip Selector works like a normal Selector, but once a child node returns Success, it is moved to the end (right). As a result previously Failed children will always be checked first and recently Successfull children last.

  • Success: When a child returns Success.
  • Failure: When all children return Failure.
  • Running: When the current child is Running.
Switch

switch

The Switch node can switch either an Enum or an Integer value. Depending on what the current Enum or integer value is, it will execute the respective child node. If another child node was previously Running, it will be interrupted. Once you connect child nodes, you the connections will read the enum or integer values.

  • Success: When the current child node returns Success.
  • Failure: When the current child node returns Failure, or if the enum or integer value is out of range in respects to the number of child nodes connected.
  • Running: When the current child node returns Running.
Step Iterator

stepIterator

he Step Iterator is similar to a Selector. It returns Success if a child node returns success and it returns Failure if all children return Failure. The only difference is that it remembers which child returns success and start the next execution from the next child in order the next time the Step Iterator is executed again.

  • Success: When a child node returns Success.
  • Failure: When all children return Failure.
  • Running: When the current child is Running.

Decorators

Decorators always have one child node. They usualy give extra functionality to that child, filter it or modify it in some way.

Interruptor

interuptor

Interuptor gets assigned a Condition Task. If the condition is or becomes true, the child node will be interrupted if Running and the Interruptor will return Failure. Otherwise the Interruptor will return whatever the child node returns.

  • Success: When the child node returns Success.
  • Failure: When child node returns Failure, or the condition assigned is or becomes true even while the child node is Running. (Interruption made).
  • Running: When child node returns Running.

Note: The fact that the Interruptor can be assigned any condition, makes possible for interruptions to happen due to any reason.

Conditional

conditional

Conditional will execute it’s child node only if the condition assigned is true and then it will return whatever the child node returns. It will return Failure if the condition is false but the child node is not already Running. So in other words, if the condition succeeds even for one frame, the child node will execute and not be interrupted even if the condition no longer holds true.

This node is extermely useful for creating state-like behaviours and switching between them.

  • Success: When the child node returns Success.
  • Failure: When the child node returns Failure, or the condition is false and the child node is not already Running.
  • Running: When the child node returns Running.
Inverter

inveter

Inverter will remap it’s child node’s Success and Failure return status, to the opposite. Success: When the child node is remaped to Success.

  • Success: When the child node return Failure.
  • Failure: When the child node returns Success.
  • Running: When the child node is Running.
Repeater

repeater

Repeater will repeat it’s child either a Number of Times, or Until it returns the specified status, or Forever.

  • Success: If ‘Repeat Times’, when the child node returns Success on it’s last repeat. If ‘Repeat Until’, when the child node returns Success and the required status is Success.
  • Failure: If ‘Repeat Times’, when the child node returns Failure on it’s last repeat. If ‘Repeat Until’, when the child node returns Failure and the required status is Failure.
  • Running: For as long as it’s repeating.

Note: The times to reapeat can be assigned from a blackboard variable to make this more dynamic.

Filter

filter

Filters the access of it’s child node either a specific Number of Times, or every specific amount of time (like a Cooldown). By default this node will be treated as Inactive in regards to it’s parent node if it is filtered. Uncecking this option will instead return Failure.

  • Success: When the child node is accessed and returns Success.
  • Failure: When the child node is accessed and returns Failure, or ‘Inactive when limited’ is turned off.
  • Running: When the child node is accessed and returns Running.

Note: The number of times and the cool down time values can be set to be taken from the Blackboard to make this node more dynamic.

Iterator

iterator

Iterator will iterate a List taken from the Blackboard. On each iteration the current iterated element will be saved on that same blackboard with the name provided and the child node will be executed.

The Iterator can optionaly be set to terminate iteration as soon as the decorated node returns either Success or Failure. If no termination condition is set (NONE) or if the list is iterated and the termination condition is not met, then the Iterator will return whatever the last iteration child execution returned.

If Reset Index is checked, then the Iterator will reset the current iterated index to zero whenever it resets, else the index will remain unless it’s the last index of the list. Think of it as a ‘for each’.

  • Success: When the list is iterated and the child node returns Success, or if set to ‘First Success’, the first time that the child node returns Success.
  • Failure: When the list is iterated and the child node returns Failure, or if set to ‘First Failure’, the first time that the child node returns Failure.
  • Running: For as long as it’s iterating.
Timeout

Aborts the child node after a specified amount of time.

The Timeout decorator will interrupt the child node Running if it is Running for more time than the one specified in seconds. Otherwise it will return whatever the child node returns.

  • Success: When the child returns Success.
  • Failure: When the child returns Failure or has Timed Out.
  • Running: When the child returns Running.
Wait Until

Waits until a modular condition becomes true and only then executes the child node.

Wait Until will return Running until the assigned Condition Task becomes true. If the condition becomes false after the child has been ticked, it will not interrupt it. The condition is check only when the child is not already Running.

  • Success: When the child returns Success.
  • Failure: When the child returns Failure.
  • Running: When the child returns Running OR the condition is false.
Optional

optional

The Optional Decorator executes the decorated child without taking into acount its Success or Failure return status, thus making it optional to the parent node in regards to status expected.

  • Success: Never.
  • Failure: Never.
  • Running: When the child node is Running.
Guard

guard

Protectes the decorated child from Running if another Guard with the same specified token is already guarding (Running) that token. Guarding is global for all of the Behaviour Trees running for the same agent.

When protected, it can be set to either return Failure or Running.

  • Success: When the child returns Success.
  • Failure: When the child returns Failure or protection is active and is set to return Failure when protected.
  • Running: When the child returns Running or protected is active and is set to return Running when protected.
Override Agent

overrideAgent

Override Agent will set another Agent for the rest of the Behaviour Tree from it’s point and on from the game object directly selected or taken from a Blackboard variable. What this means is that every node underneath the this decorator will now be Ticked for that new agent. This Decorator is one of the ways that NodeCanvas allows you to control more than one agents from a single “master” Behaviour Tree, or to dynamicaly change the agent.

  • Success: When the child node returns Success.
  • Failure: When the child node returns Failure.
  • Running: When the child node returns Running.

Sub-Behaviours

Sub-Behaviours are references to other whole graphs, usualy Behaviour Trees and are used for organization and behaviour modularity.

SubTree

subTree

A SubTree is an entire other Behaviour Tree. The SubTree node, will return whatever the assigned Behaviour Tree’s root node (“Start”) returns. The agent and the blackboard of the root Behaviour Tree will be passed down to the SubTree, thus all available blackboard variables will be the same and available to the SubTree as well.

  • Success: When SubTree’s root node return Success.
  • Failure: When SubTree’s root node return Failure.
  • Running: When SubTree’s root node returns Running.

Note: You can create a new SubTree out of a whole branch! To do this, right click a composite node and select “Convert To SubTree”. This will create a new Behaviour Tree and a new SubTree Node. The selected node as well as all of it’s children concurently will be moved to that new Behaviour Tree! This is extremely useful to organize the behaviours without knowing before hand how that organization should be.

NestedFSM

BTnestedFSM

Nested FSM can be assigned an entire FSM. When executed, the FSM will Start. The NestedFSM node will return Running for as long as the FSM is running. You can specify one state of the FSM for Success and another for Failure. As soon as the nested FSM enters any of those states, the FSM will stop and this node will return Success or Failure acordingly. Otherwise it will return Success when the nested FSM is finished somehow. The Agent and the Blackboard of this Behaviour Tree will be passed to the Nested FSM, thus all available variables of the root Behaviour Tree will also be the same and available to the Nested FSM.

  • Success: When the Nested FSM enters the selected Success State, or the Nested FSM is finished.
  • Failure: When the Nested FSM enters the selected Failure State.
  • Running: For as long as the Nested FSM is running.
Yes No Suggest edit
7 of 7 users found this section helpful
Suggest Edit