Composites

Composites (multi-child) types for behaviour trees.

Composites are responsible for directing the path traced through the tree on a given tick (execution). They are the factories (Sequences and Parallels) and decision makers (Selectors) of a behaviour tree.

PyTree Composites

Composite behaviours typically manage children and apply some logic to the way they execute and return a result, but generally don’t do anything themselves. Perform the checks or actions you need to do in the non-composite behaviours.

Most any desired functionality can be authored with a combination of these three composites. In fact, it is precisely this feature that makes behaviour trees attractive - it breaks down complex decision making logic to just three primitive elements. It is possible and often desirable to extend this set with custom composites of your own, but think carefully before you do - in almost every case, a combination of the existing composites will serve and as a result, you will merely compound the complexity inherent in your tree logic. This this makes it confoundingly difficult to design, introspect and debug. As an example, design sessions often revolve around a sketched graph on a whiteboard. When these graphs are composed of just five elements (Selectors, Sequences, Parallels, Decorators and Behaviours), it is very easy to understand the logic at a glance. Double the number of fundamental elements and you may as well be back at the terminal parsing code.

Tip

You should never need to subclass or create new composites.

The basic operational modes of the three composites in this library are as follows:

• Selector: execute a child based on cascading priorities

• Sequence: execute children sequentially

• Parallel: execute children concurrently

This library does provide some flexibility in how each composite is implemented without breaking the fundamental nature of each (as described above). Selectors and Sequences can be configured with or without memory (resumes or resets if children are RUNNING) and the results of a parallel can be configured to wait upon all children completing, succeed on one, all or a subset thereof.

Tip

Follow the links in each composite’s documentation to the relevant demo programs.

Selector

class py_trees.composites.Selector(name: str, memory: bool, children: Optional[List[Behaviour]] = None)

Selectors are the decision makers.

A selector executes each of its child behaviours in turn until one of them succeeds (at which point it itself returns RUNNING or SUCCESS, or it runs out of children at which point it itself returns FAILURE. We usually refer to selecting children as a means of choosing between priorities. Each child and its subtree represent a decreasingly lower priority path.

Note

Switching from a low -> high priority branch causes a stop(INVALID) signal to be sent to the previously executing low priority branch. This signal will percolate down that child’s own subtree. Behaviours should make sure that they catch this and destruct appropriately.

Note

If configured with memory, higher priority checks will be skipped when a child returned with running on the previous tick. i.e. once a priority is locked in, it will run to completion and can only be interrupted if the selector is interrupted by higher priorities elsewhere in the tree.

See also

The py-trees-demo-selector program demos higher priority switching under a selector.

Parameters

• memory (bool) – if RUNNING on the previous tick, resume with the RUNNING child

• name (str) – the composite behaviour name

• children ([Behaviour]) – list of children to add

Sequence

class py_trees.composites.Sequence(name: str, memory: bool, children: Optional[List[Behaviour]] = None)

Sequences are the factory lines of behaviour trees.

A sequence will progressively tick over each of its children so long as each child returns SUCCESS. If any child returns FAILURE or RUNNING the sequence will halt and the parent will adopt the result of this child. If it reaches the last child, it returns with that result regardless.

Note

The sequence halts once it engages with a child is RUNNING, remaining behaviours are not ticked.

Note

If configured with memory and a child returned with running on the previous tick, it will proceed directly to the running behaviour, skipping any and all preceding behaviours. With memory is useful for moving through a long running series of tasks. Without memory is useful if you want conditional guards in place preceding the work that you always want checked off.

See also

The py-trees-demo-sequence program demos a simple sequence in action.

Parameters

• name (str) – the composite behaviour name

• memory (bool) – if RUNNING on the previous tick, resume with the RUNNING child

• children (Optional[List[Behaviour]]) – list of children to add

Parallel

class py_trees.composites.Parallel(name: str, policy: Base, children: Optional[List[Behaviour]] = None)

Parallels enable a kind of spooky at-a-distance concurrency.

A parallel ticks every child every time the parallel is itself ticked. The parallelism however, is merely conceptual. The children have actually been sequentially ticked, but from both the tree and the parallel’s purview, all children have been ticked at once.

The parallelism too, is not true in the sense that it kicks off multiple threads or processes to do work. Some behaviours may kick off threads or processes in the background, or connect to existing threads/processes. The behaviour itself however, merely monitors these and is itself encosced in a py_tree which only ever ticks in a single-threaded operation.

• Parallels will return FAILURE if any child returns FAILURE

• Parallels with policy SuccessOnAll only returns SUCCESS if all children return SUCCESS

• Parallels with policy SuccessOnOne return SUCCESS if at least one child returns SUCCESS and others are RUNNING

• Parallels with policy SuccessOnSelected only returns SUCCESS if a specified subset of children return SUCCESS

Policies SuccessOnAll and SuccessOnSelected may be configured to be synchronised in which case children that tick with SUCCESS will be skipped on subsequent ticks until the policy criteria is met, or one of the children returns status FAILURE.

Parallels with policy SuccessOnSelected will check in both the setup() and tick() methods to to verify the selected set of children is actually a subset of the children of this parallel.

See also

• Context Switching Demo

Parameters

• name (str) –

• policy (Base) –

• children (Optional[List[Behaviour]]) –