Oh, Behave (III) – Decorators

As we’ve seen before, composites let us build complex behavior trees by combining smaller ones and executing them in several different ways. Still, we’re in need of a way to add new features to existing behaviors, like inverting its result or execute it multiple times or until a given condition is met.

Modularity and reusability are key when working with behavior trees (actually, that applies to pretty much all in software engineer). Therefore, we should avoid reimplementing a behavior whenever possible. So the question is: how can we add these new features and maximize reusability at the same time?

That’s when decorators are added to the mix.



In contrast to composites, decorator behaviors have one and only one child behavior. Although technically doable, there is no gain in adding a decorator as leaf node to our tree, since their strength lies in modifying existing behaviors.

Decorator behaviors add new functionalities to their child behavior without necessarily knowing its internal execution. A decorator behavior may transform the result provided by their child behavior and/or change the way it’s executed in some other way.

For example, a common use for decorators is to repeat the execution of its child behavior until a given condition is satisfied, independently of what the child behavior actually does.

Available Decorators

At the time of this writing, the following decorators are already available in Crimild:


A Repeat behavior will execute its child behavior multiple times. There are several variations of the Repeat behavior, implementing different looping conditions. For example, we might need to loop only a limited number of times or do so until the child behavior fails or succeeds.

If, for example, you need a character that should run from one location to another, you’ll probably be using a Repeat behavior along with a Sequence or Selector that moves the character and check if the destination has been reached in every loop. Such a behavior tree should like this:

  |-> Sequence
        |-> AwayFromTarget
        |-> Move

The behavior tree above will move a character (or any Node) until AwayFromTarget fails. When that happens, the Sequence behavior will fail too and RepeatUntilFail itself will terminate (you might be surprised to know that RepeatUntilFail will return a SUCCESS result even when the inner behaviors failed. That’s because the loop itself did succeeded).

Another use of a Repeat behavior is to just execute the same behavior over and over again, like and idle behavior.


As the name suggests, an Inverter behavior will change the result of its child behavior once it has been executed. Then, if the child returns SUCCESS, the Inverter will return FAILURE, and vice versa.

Inverter behaviors are commonly used to check conditions inside a loop. The behavior tree shown earlier could be rewritten as follows:

  |-> Sequence
      |-> Inverter
            |-> ArrivedAtTarget
      |-> Move

Basically, move the character as long as we’re not at the target location. In this case, the Inverter behavior allows to reuse other behaviors. Otherwise, we might need to implement behaviors for all cases.


A Succeeder behavior always returns SUCCESS, disregarding of whether its child behavior returned SUCCESS or FAILURE. This behavior is useful when we need to branch the executing of a tree.

Please not that there is not “Failer” behavior since that can be accomplished by using an Inverter behavior on a Succeeder.

Other uses

Decorators are quite powerful and could radically change the execution of a branch in order behavior tree. Here are some other uses for Decorators:

  • Avoid executing the child node based on a predefined condition
  • Avoid executing a branch in our tree based on a timer
  • Deal with error status
  • Pause execution of a tree (like a breakpoint)

By combining Sequence and Decorator behaviors in our tree we can create really complex logics for virtually any logic we would like to achieve.

It’s show time!

Enough theory. The time has come for us to see behavior trees in action.

So, in the next episode, we’re going to create at a live demo to better understand how behavior trees work in practice, their strengths and limitations.

Stay tuned.