Skip to content

Behavior Tree Basic Node Types

We have defined a number of basic node types. These are the building blocks of any behavior tree. They are defined in the vultron.bt.base module.

vultron.bt.base.node_status

This module defines a Behavior Tree Node Status object.

NodeStatus

Bases: Enum

NodeStatus is the return value of a node's tick() method. Nodes can only return one of these values.

Nodes return SUCCESS if they have completed their task successfully. Nodes return FAILURE if they have completed their task unsuccessfully. Nodes return RUNNING if they are still in the process of completing their task.

vultron.bt.base.bt_node

This module provides the base class for all nodes in the Behavior Tree.

It also provides a number of core node types that can be used to build a Behavior Tree.

ActionNode

Bases: LeafNode

ActionNode is the base class for all action nodes in the Behavior Tree. Action nodes are leaf nodes that perform an action. An action node's func() method returns True for success, False for failure, and None for running.

BtNode

BtNode is the base class for all nodes in the Behavior Tree.

add_child(child)

Adds a child to the node.

Parameters:

Name Type Description Default
child BtNode

the child node to add

required

Returns:

Type Description
BtNode

the child node

add_children()

Adds children to the node. Loops through the _children list and creates a new instance of each child class.

setup()

Sets up the node and its children.

Propagates the blackboard reference from parent to this node and recursively to all children. Skips setup if already completed to avoid redundant O(N²) traversals on every tick.

Returns:

Type Description
None

None

tick(depth=0)

Ticks the node. Performs the following actions:

  • calls _pre_tick()
  • calls _tick()
  • calls _post_tick()
  • sets the node's status based on the return value of _tick()

Parameters:

Name Type Description Default
depth int

the node's depth in the tree

0

Returns:

Type Description
NodeStatus

the node's status (as a NodeStatus enum)

to_mermaid(depth=0, topdown=True)

Returns a string representation of the tree rooted at this node in mermaid format.

to_str(depth=0)

Returns a string representation of the tree rooted at this node.

ConditionCheck

Bases: LeafNode

ConditionCheck is the base class for all condition check nodes in the Behavior Tree. Condition check nodes are leaf nodes that check a condition. A condition check node's func() method returns True for success, False for failure. Although it is possible to return None for running, this is not recommended.

CountTicks

Bases: BtNode

CountTicks is a decorator node that counts the number of times it is ticked.

LeafNode

Bases: BtNode

LeafNode is the base class for all leaf nodes in the Behavior Tree. Leaf nodes are nodes that do not have children.

__init__()

Raises a LeafNodeError if the node has children.

func()

Override this method in your subclass. Return True for success, False for failure, and None for running.

SnapshotState

Bases: BtNode

SnapshotState is a decorator node that takes a snapshot of the blackboard and appends it to the STATELOG list.

vultron.bt.base.composites

This module implements Composite Nodes for a Behavior Tree.

FallbackNode

Bases: BtNode

FallbackNode is a composite node that ticks its children in order.

  • If a child returns SUCCESS, the FallbackNode returns SUCCESS.
  • If a child returns RUNNING, the FallbackNode returns RUNNING.
  • If a child returns FAILURE, the FallbackNode ticks the next child.
  • If all children return FAILURE, the FallbackNode returns FAILURE.

ParallelNode

Bases: BtNode

ParallelNode is a composite node that ticks its children in parallel.

When subclassing, you must set the m attribute indicating the minimum number of successes. The maximum failures is then calculated as N - m, where N is the number of children.

  • When a child returns SUCCESS, the ParallelNode increments a success counter.
  • When a child returns FAILURE, the ParallelNode increments a failure counter.
  • If the success counter reaches the minimum number of successes, the ParallelNode returns SUCCESS.
  • If the failure counter reaches the maximum number of failures, the ParallelNode returns FAILURE.
  • If neither of the above conditions are met, the ParallelNode returns RUNNING.

Not Fully Implemented

In the current implementation, the ParallelNode does not actually tick its children in parallel. Instead, it ticks them in a random order and counts the results until either SUCCESS or FAILURE is indicated as above. This is good enough for demonstration purposes, but it should be replaced with a proper parallel implementation.

SequenceNode

Bases: BtNode

SequenceNode is a composite node that ticks its children in order.

  • If a child returns SUCCESS, the SequenceNode ticks the next child.
  • If a child returns RUNNING, the SequenceNode returns RUNNING.
  • If a child returns FAILURE, the SequenceNode returns FAILURE.
  • If all children return SUCCESS, the SequenceNode returns SUCCESS.

vultron.bt.base.decorators

This module defines a number of Behavior Tree Decorator Nodes.

BtDecorator

Bases: BtNode

BtDecorator is the base class for all decorators in the Behavior Tree.

ForceFailure

Bases: BtDecorator

ForceFailure decorator returns FAILURE no matter what the child node returns.

ForceRunning

Bases: BtDecorator

ForceRunning decorator returns RUNNING no matter what the child node returns.

ForceSuccess

Bases: BtDecorator

ForceSuccess decorator returns SUCCESS no matter what the child node returns.

Invert

Bases: BtDecorator

Inverts the result of the child node.

  • If the child node returns SUCCESS, the Invert decorator will return FAILURE.
  • If the child node returns FAILURE, the Invert decorator will return SUCCESS.
  • If the child node returns RUNNING, the Invert decorator will return RUNNING.

LoopDecorator

Bases: BtDecorator

LoopDecorator is the base class for all decorators that loop.

RepeatN

Bases: LoopDecorator

Repeat up to n times until the child returns failure or running. When subclassing RepeatN, set the n class variable to the number of repeats.

RepeatUntilFail

Bases: LoopDecorator

Repeat until the child returns FAILURE, then return SUCCESS.

RetryN

Bases: LoopDecorator

Retry up to n times until the child returns success or running. When subclassing RetryN, set the n class variable to the number of retries.

RunningIsFailure

Bases: BtDecorator

RunningIsFailure decorator returns FAILURE if the child node returns RUNNING. Otherwise, it returns the result of the child node.

RunningIsSuccess

Bases: BtDecorator

RunningIsSuccess decorator returns SUCCESS if the child node returns RUNNING. Otherwise, it returns the result of the child node.

vultron.bt.base.fuzzer

This module provides fuzzer node classes for a Behavior Tree. It is intended to be used for testing, simulation, and debugging.

Many of the classes provided are subclasses of the WeightedSuccess class. Their names are based in part on the Words of Estimative Probability from Wikipedia and the Probability Survey (github) by Mauboussin and Mauboussin.

AlmostAlwaysFail

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.10.

AlmostAlwaysSucceed

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.90.

AlmostCertainlyFail

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.07.

AlmostCertainlySucceed

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.93.

AlwaysFail

Bases: FuzzerNode

Always returns NodeStatus.FAILURE

AlwaysRunning

Bases: FuzzerNode

Always returns NodeStatus.RUNNING

AlwaysSucceed

Bases: FuzzerNode

Always returns NodeStatus.SUCCESS

FortyNineInFifty

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.98.

NineteenInTwenty

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.95.

NinetyNineInOneHundred

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.99.

OftenFail

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.30.

OftenSucceed

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.70.

OneInFifty

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.02.

OneInOneHundred

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.01.

OneInThirty

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.033333.

OneInTwenty

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.05.

OneInTwoHundred

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.005.

OneNinetyNineInTwoHundred

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.995.

ProbablyFail

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.3333.

ProbablySucceed

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.6667.

RandomActionNodeWithRunning

Bases: FuzzerNode

Returns a random NodeStatus, including NodeStatus.RUNNING, with equal probability.

SuccessOrRunning

Bases: FuzzerNode

Returns NodeStatus.SUCCESS or NodeStatus.RUNNING with equal probability.

TwentyNineInThirty

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.96667.

UniformSucceedFail

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.50.

UsuallyFail

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.25.

UsuallySucceed

Bases: WeightedSuccess

Returns NodeStatus.SUCCESS with a probability of 0.75.

WeightedSuccess

Bases: FuzzerNode

Returns NodeStatus.SUCCESS with a probability of success_rate. Otherwise, returns NodeStatus.FAILURE.

When subclassing, set the success_rate class attribute to the desired probability of success.