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)
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
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
ForceFailure
ForceRunning
ForceSuccess
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
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
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
AlmostAlwaysSucceed
AlmostCertainlyFail
AlmostCertainlySucceed
AlwaysFail
Bases: FuzzerNode
Always returns NodeStatus.FAILURE
AlwaysRunning
Bases: FuzzerNode
Always returns NodeStatus.RUNNING
AlwaysSucceed
Bases: FuzzerNode
Always returns NodeStatus.SUCCESS
FortyNineInFifty
NineteenInTwenty
NinetyNineInOneHundred
OftenFail
OftenSucceed
OneInFifty
OneInOneHundred
OneInThirty
OneInTwenty
OneInTwoHundred
OneNinetyNineInTwoHundred
ProbablyFail
ProbablySucceed
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
UniformSucceedFail
UsuallyFail
UsuallySucceed
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.