Decorators

Decorate your children. They make great furniture pieces.

Decorators are behaviours that manage a single child and provide common modifications to their underlying child behaviour (e.g. inverting the result). That is, they provide a means for behaviours to wear different ‘hats’ and this combinatorially expands the capabilities of your behaviour library.

An example:

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import py_trees.decorators
import py_trees.display

if __name__ == '__main__':

    root = py_trees.composites.Sequence(name="Life")
    timeout = py_trees.decorators.Timeout(
        name="Timeout",
        child=py_trees.behaviours.Success(name="Have a Beer!")
    )
    failure_is_success = py_trees.decorators.Inverter(
        name="Inverter",
        child=py_trees.behaviours.Success(name="Busy?")
        )
    root.add_children([failure_is_success, timeout])
    py_trees.display.render_dot_tree(root)

Decorators (Hats)

Decorators with specific functionality:

• py_trees.decorators.Condition

• py_trees.decorators.Count

• py_trees.decorators.EternalGuard

• py_trees.decorators.Inverter

• py_trees.decorators.OneShot

• py_trees.decorators.Repeat

• py_trees.decorators.Retry

• py_trees.decorators.StatusToBlackboard

• py_trees.decorators.Timeout

And the X is Y family:

• py_trees.decorators.FailureIsRunning

• py_trees.decorators.FailureIsSuccess

• py_trees.decorators.RunningIsFailure

• py_trees.decorators.RunningIsSuccess

• py_trees.decorators.SuccessIsFailure

• py_trees.decorators.SuccessIsRunning

Decorators for Blocking Behaviours

It is worth making a note of the effect of decorators on blocking behaviours, i.e. those that return RUNNING before eventually returning SUCCESS or FAILURE.

A decorator, such as py_trees.decorators.RunningIsSuccess() on a blocking behaviour will immediately terminate the underlying child and re-intialise on it’s next tick. This is often surprising (to the user) but is necessary to ensure the underlying child isn’t left in a dangling state (i.e. RUNNING) as subsequent ticks move on to other parts of the tree.

A better approach in this case is to build a non-blocking variant or a combination of non-blocking behaviors that handle construction, monitoring and destruction of the activity represented by the original blocking behaviour.