Skip to main content
Version: 4.6

Decorators

A decorator is a node that must have a single child.

It is up to the Decorator to decide if, when and how many times the child should be ticked.

Inverter

Tick the child once and return SUCCESS if the child failed or FAILURE if the child succeeded.

If the child returns RUNNING, this node returns RUNNING too.

ForceSuccess

If the child returns RUNNING, this node returns RUNNING too.

Otherwise, it returns always SUCCESS.

ForceFailure

If the child returns RUNNING, this node returns RUNNING too.

Otherwise, it returns always FAILURE.

Repeat

Tick the child up to N times (within one of its tick), where N is passed as Input Port num_cycles, as long as the child returns SUCCESS. Return SUCCESS after the N repetitions in the case that the child always returned SUCCESS.

Interrupt the loop if the child returns FAILURE and, in that case, return FAILURE too.

If the child returns RUNNING, this node returns RUNNING too and the repetitions will continue without incrementing on the next tick of the Repeat node.

RetryUntilSuccessful

Tick the child up to N times, where N is passed as Input Port num_attempts, as long as the child returns FAILURE. Return FAILURE after the N attempts in the case that the child always returned FAILURE.

Interrupt the loop if the child returns SUCCESS and, in that case, return SUCCESS too.

If the child returns RUNNING, this node returns RUNNING too and the attempts will continue without incrementing on the next tick of the RetryUntilSuccessful node.

KeepRunningUntilFailure

The KeepRunningUntilFailure node returns always FAILURE (FAILURE in child) or RUNNING (SUCCESS or RUNNING in child).

Delay

Tick the child after a specified time has passed. The delay is specified as Input Port delay_msec. If the child returns RUNNING, this node returns RUNNING too and will tick the child on next tick of the Delay node. Otherwise, return the status of the child node.

RunOnce

The RunOnce node is used when you want to execute the child only once. If the child is asynchronous, it will tick until either SUCCESS or FAILURE is returned.

After that first execution, you can set value of the Input Port then_skip to:

  • TRUE (default), the node will be skipped in the future.
  • FALSE, return synchronously the same status returned by the child, forever.

PreCondition

Cf. Introduction to the Scripting language

SubTree

Cf. Compose behaviors using Subtrees.

Other decorators requiring registration in C++

ConsumeQueue

Execute the child node as long as the queue is not empty. At each iteration, an item of type T is popped from the "queue" and inserted in "popped_item".

An empty queue will return SUCCESS

Register for example with factory.registerNodeType<ConsumeQueue<Pose2D>>("ConsumeQueue"); Cf. ex04_waypoints.cpp.

SimpleDecoratorNode

Register a simple decorator node with void BehaviorTreeFactory::registerSimpleDecorator("MyDecorator", tick_function, ports), which uses SimpleDecoratorNode internally and where tick_function is a function with signature std::function<NodeStatus(NodeStatus, TreeNode&)> and ports is a variable of type PortsList.