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.

../_images/many-hats.png

An example:

 1#!/usr/bin/env python3
 2# -*- coding: utf-8 -*-
 3"""Example demonstrating the use of some simple decorator nodes."""
 4
 5import py_trees.decorators
 6import py_trees.display
 7
 8if __name__ == "__main__":
 9    root = py_trees.composites.Sequence(name="Life", memory=False)
10    timeout = py_trees.decorators.Timeout(
11        name="Timeout", child=py_trees.behaviours.Success(name="Have a Beer!")
12    )
13    failure_is_success = py_trees.decorators.Inverter(
14        name="Inverter", child=py_trees.behaviours.Success(name="Busy?")
15    )
16    root.add_children([failure_is_success, timeout])
17    py_trees.display.render_dot_tree(root)

Decorators (Hats)

Decorators with specific functionality:

And the X is Y family:

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.