Oh, Behave (II) – Composites

Welcome to another entry in this series of articles talking about Crimild’s support for Behavior Trees. If you haven’t done so already, I recommend reading my previous article where the most important concepts were introduced.

As we discussed before, a behavior tree can be as simple as a single action, like printing a value in standard output. But what if we would like to do something more complex, like calculating the sum of two values stored in the behavior tree’s context?

In this article we’ll be describing Composite nodes and how they can be used to execute one or more actions for a given behavior.

What are composites?

A composite node is one that may contain one or more child nodes, executing them in serial, random or whatever fashion is required, returning a single result based on how the child nodes behave. Which reminds me…


(Yes, this image will appear in every article. Non negotiable. Keep reading)

At the time of this writing, Crimild implements three different composites: Sequence, Parallel and Selector. We’ll be describing each of them below, comparing both the way in which they execute their children and how the resulting state is calculated.


A Sequence node is a composite that executes its child nodes one by one in a serial way. We’ve seen a sequence in action in the previous article when we made the analogy between a behavior tree and adding two numbers in Assembly language:

Behavior Tree - Intro (1)

The nodes are executed as follow: Sequence -> Mov(x, 5) -> Mov(y, 10) -> Add(x, y) -> PrintContextValue

The resulting state (SUCCESS, FAILURE or RUNNING) depends only on the resulting states of the children. A Sequence itself will succeed only when all of its children succeed. In other words, if any children in the sequence returns a FAILURE, then the sequence itself will return FAILURE and the remaining nodes, if any, will not be executed at all.

A Sequence returning a RUNNING state indicates that there have been no FAILURE so far and that there is at least one running child node which execution has not been completed, so we need to keep updating the sequence in the next frame.

You can think about sequences as the AND operator in a programming language. In order to better understands this, let’s represent a sequence as a for loop:

void Sequence::execute( void ) {
    for ( int i = 0; i < getChildCount(); i++ ) {
        auto state = getChild( i )->execute();
        if ( state != SUCCESS ) {
            return state;
    return SUCCESS;


A Parallel composite executes all of its child nodes at the same time.

Please note that the term parallel here does not mean that the child nodes are executed concurrently. Child nodes are executed without the use of any additional thread or parallelism at all. Crimild does not support concurrency while traversing a behavior tree at the time of this writing.

What do we mean by executing nodes at the same time? It means that a Parallel composite will execute child nodes without waiting for them to succeed. In other words, it will execute the first node and then it will move to the next one and so on, regardless of wether the execution of the previous child was successfully completed or if it’s still running.

void Parallel::execute( void ) { 
    State result = SUCCESS;
    for ( int i = 0; i < getChildCount(); i++ ) { 
        auto state = getChild( i )->execute(); 
        if ( state == FAILURE ) { 
            return state; 
        else if ( state == RUNNING ) {
            result = RUNNING;
    return RESULT; 

(Please keep in mind the actual implementation is a bit different than the code above)

Just like a sequence, a parallel composite will succeed only when all of its children finish their executing with a SUCCESS state. Whenever a child fails, the parallel itself fails, leaving the rest of the nodes in an undefined state (they could’ve finished already or they might still be running).

A Parallel node is typically used to execute two or more things at the same time, like when we need to update a character animation at the same time he’s running towards a goal.


A selector will execute child nodes just as a sequence, one after the other in serial fashion. Unlike sequences, a selector will succeed whenever any of its children does. On the other hand, it will fail only if all of its children do so. The RUNNING state indicates that there have been no successes so far and there are more child nodes to be evaluated.

We can make an analogy between selectors an the OR operator in a programming language. They are used to branch the executing of a behavior tree based on wether or not nodes are executed successfully.

For example, take a look at the following behavior tree:

Behavior Tree - Selectors

Instead of just printing the result of the X + Y, now we want to output wether the result is good or bad. If the value of X after the addition is 15, then the first node in the selector will succeed, and the string “Good” will appear. The second action in the selector won’t be executed because we already have a good result.

On the other hand, if we modify the values of X and Y in order make the first node of the selector to fail (that is X != 15), the “Good” result will be skipped and the selector’s second child will be executed, producing the output “Bad”.

This is how a Selector is implemented in pseudocode

void Selector::execute( void ) {
    for ( int i = 0; i < N; i++ ) {
        auto state = getChild( i )->execute();
        if ( state != FAILURE ) {
            return state;
    return FAILURE;

If we compare the above pseudocode with the one show for Sequences earlier, we’ll noticed that the main difference is the condition for breaking the loop.

About Random Sequence/Selector Composites

At the time of this writing Crimild does not provide an implementation for randomized composites, although I believe that it will in the near future.

A randomized sequence, for instance, may help to add more variation to a behavior. Think about an NPC for a game, doing some chores in his/her house. By using a sequence, the chores will be done always in the way, which is pretty boring. Now, by using a randomize sequence, instead, the NPC will feel more alive doing different things at different points in time.


I hope that you can see the power of composite nodes by now, since they are probably the most used kind of nodes in behavior tree.

They can also be used to modularize our behaviors. By defining sub-trees for adding and multiplying numbers, for example, we can end up with behaviors for calculating complex math formulas by just reusing entire sequences of nodes.

And just imagine what could be accomplished by nesting composites…

In the next episode

In the next article we’ll deal with Decorator nodes and why they are useful to manipulate behavior results.

Stay tuned




Oh, Behave (I) – Introduction

Time to talk about Austin Powers.

No, wait…

Behavior Trees.

Time to talk about behavior trees.


This will be the first in a series of articles describing what behavior trees are and how Crimild implements them.

Throughout the next articles I’ll be talking about what are the different components in a Behavior Tree, how to create simple behaviors and how to combine them into more complex ones.

Before we begin…

Keep in mind that Behavior Trees were recently introduced to Crimild and, as any new feature, they might change during the course of the writing of this series (actually, that applies to pretty much the entire engine). Whenever that happens, I’ll try and update the already existing articles as much as possible so they don’t get too far behind.

What are Behavior Trees?

A Behavior Tree is a tree-like structure where each node is a self-contained action that executes and terminates independently of the other nodes. In contrast, a Finite State Machine requires that each state also provides the necessary transitions to other states, avoiding reusability of states and therefore limiting its scalability.

Due to their self-contained nature, behaviors can be easily grouped together to represent advanced logics in a modular way.

Since each behavior does not explicitly define a transition to the next one, it’s the parent behavior’s responsibility to execute its children. If we make the analogy with functions (for example, in C++), each function contains one or more instructions executed sequentially. A parent behavior may execute each one of its children in the same way (and the parent itself may be a child of another behavior). But the parent behavior might need to execute its children in a different way, say, only until one of them fails or succeeds. And thats were the true power of Behavior Trees is shown.

The next image shows the simplest Behavior Tree: one that contains only an action that prints the value of a variable:

Behavior Tree - Simple

A single-node behavior tree that prints a value from the context

In order to work, each Behavior Tree has an associated context that stores values which are accessible from every node in the tree. The context is used a way to communicate behaviors with one another, like registers in a low-level programming language. In the example above, the PrintContextValue action will look for the value of “x” (the argument) stored in the context and displays it on the screen.

A little bit more complex tree would look like this:

Behavior Tree - Intro (1)

A behavior tree to add two values

Making an analogy with the x86 Assembly programming language, the above graphic shows a parent node that will execute each of its children in sequence. Then, we have three operations for setting and adding the values of X and Y together and storing the result in X (that’s how ADD operates). Finally, we output the result stored in X.

Due to its modular nature, Behavior Trees can be as powerful as any programming language.

Implementing Behavior Trees in Crimild

The Behavior class represents a single node in the Behavior Tree. It’s an abstract class defining the basic interface for all behaviors and implementing the common code for all of them. Probably its most important method is the step() one, that is executed every frame for the active behavior in the tree. When a behavior is executed, the step() method will return one of three possible results:

  • Behavior::State::SUCCESS: The behavior has completed its execution and has a valid result
  • Behavior::State::FAILURE: There was a problem when executing the behavior and there is no result
  • Behavior::State::RUNNING: The behavior has not completed its execution yet, so it should be executed at least one more time.

Simple behaviors, like the ones in the diagram above, perform basic operations but they can still fail if the arguments do not match with context values. More complex behaviors, like a character walking towards a destination will require several updates before completing (either by succeeding or failing) and therefore will make use of the RUNNING state while they’re being processed.

The BehaviorContext class contains the data that is shared among all nodes in a behavior tree. The context is usually passed as an argument to the step() function in behaviors. It includes methods for getting and setting values directly and converting them to the correct data types.

The BehaviorContext also stores a reference an agent, which is a Node object that is linked to the behavior tree. In addition to the agent, the context also stores one or more Node objects that serve as targets for some behaviors. For example, if you implement an attack behavior for you game, the agent would be the character attacking while the target would be the victim.

Finally, the BehaviorController component is used to store the behavior tree and execute it each frame. This controller may contain more than one tree, switching them by using messages or other mechanisms based on your app’s logic.

In practice, you’ll end up seeing something like this:

auto node = crimild::alloc< Node >();
auto sequence = crimild::alloc< Sequence >();
sequence->attachBehavior( crimild::alloc< MOVBehavior >( "x", 5 ) );
sequence->attachBehavior( crimild::alloc< MOVBehavior >( "y", 10 ) );
sequence->attachBehavior( crimild::alloc< ADDBehavior >( "x", "y" ) );
sequence->attachBehavior( crimild::alloc<PrintMessage >( "x" ) );
auto controller = crimild::alloc< BehaviorController >();
controller->getBehaviorContext()->setValue( "x", 0 );
controller->getBehaviorContext()->setValue( "y", 0 );
controller->attachBehavior( BehaviorController:SCENE_STARTED_BEHAVIOR_NAME, sequence );
node->attachComponent( controller );

When attaching behaviors to a controller, you need to take into account when that behavior should be triggered. In the example above, we use SCENE_STARTED_BEHAVIOR_NAME to indicate that we want to execute our behavior only once at the very beginning of our program. In contrast, by using DEFAULT_BEHAVIOR_NAME we would end up trigger the behavior every frame, leading to the value of X being constantly incremented by 10 until de program stops.

We’ll talk more about behaviors and events in later posts. For now, let’s just say that, during an update process, the controller will traverse down the current behavior tree (set by an event) following the path described by those nodes that are still running. This will make more sense once we’ve seen sequences in the next article.

At the time of this writing there are several generic behaviors already available in Crimild.

Data driven design

Hopefully, by now you should have enough knowledge about the very basics of behavior trees to see that they can be easily setup in a data driven fashion. Crimild already includes a set of builders for Lua to define behavior trees like this:

local bt = {
    type = 'crimild::behaviors::composites::Sequence',
    behaviors = {
            type = 'crimild::behaviors::actions::PrintMessage',
            message = 'Hello World!',

This construct leads to a very expressive solution and now it’s possible to easily write logic for actors in a simulation using scripting without having to actually code it. In practice, I usually group behaviors together in small modules that are later reused by different actors.

It’s a really powerful tool.

In the next episode…

Now that we have a basic idea of Behavior Trees, in the next article we’ll continue talking about sequences and how they can be used to execute behaviors one after the other.


If you want to know more about behavior trees, I recommend the following websites:



Experimenting with Emscripten

Let’s start the year with a bang!

No, I was not planning on adding support for Emscripten so soon, but I woke up on Saturday morning with that idea in my mind. I was assuming that the process to take a Crimild demo and make it run on a web browser would take me several weekends, but it turned out to be a lot easier.

So, here’s a–

Wait. I see it in your face. You don’t believe me, right? Take a look at THIS WORKING DEMO then.

Screen Shot 2018-01-07 at 1.36.25 PM


Keep in mind that it might take a while to load. Also, try rotating the model by dragging the left mouse button. You can use the WASD keys too, but you need to click on the frame first in order to give it focus.

The source code for this demo is already available at Github. It’s using a branch of the latest Crimild version just to make sure I’m not breaking anything else. I intent to merge this code with the main one once I’m confident enough.

Now, where were we? Oh yes: “So, here’s a postmortem”

First things first

The first step was the obvious one: install Emscripten in my computer. The official website has a todo list that is very clear and easy to follow. And I already had NodeJS on my computer so the whole process was quite simple.

After the installation, I made sure the most basic examples, like the Hello World one, were all working. And with my environment correctly configured, I moved on to write the first demo

Dumping a scene

I wanted to start with something simple. Create a scene (a similar one as in the Triangle example), and dump it to the standard output. That’s it. No simulation, no rendering. Just to make sure Crimild’s core module would build and work correctly.

In order to setup the project, I used the official toolchain for CMake also provided by the same Emscripten installation. That was the key to make the process a lot simpler.

The project’s CMakeLists.txt only needed to specify the location of Crimild sources, making sure that only the core classes would be included in the final Makefile. I used the same macros for building apps as in the example projects.

Then, compiled the whole thing and ran it using node.

There was no need to change anything in the code.

At all.

Moving on.

The GLFW affair

I wanted to render something on the screen next, but it wouldn’t be that easy this time.

First, I had to enable the modules that I needed from Crimild. I knew that Emscripten has built-in support for OpenGL ES and GLFW, that was all I needed.

I had to make some changes in Crimild’s CMake files in order to detect wether or not we’re building for Emscripting. That way we’ll use one version of the libraries or the other. For example, although Crimild has a reference to the GLFW project sources, we need to use the one provided by Emscripten in the end. Therefore, I had to make sure I was using the appropriated ones at linking time (which was not the case for the first couple of hours until I figure it out).

Several “undefined symbols” later, I managed to organize Crimild’s CMake files in a way that can be reused for any platform.

I also had to add some extra flags in the code, specially for handling cases like where to locate the OpenGL header files. In addition, I implemented the required methods to declare the main loop function that will be called each frame.

At that point, I started running the demo using a simple index.html page that only contained the canvas and the loading code for the demo.

S**t got real

With a triangle spinning on the screen, the next step was to actually load an animated model.

I didn’t even try to build the Import module, because I knew that Assimp may became a problem, so I took the easy way out: loading a model already saved as a binary stream.

It took me a while to figure out how to work with Emscripten internal file system, and the fact that, as with any other web project, I eventually had to ran an instance of an HTTP server (the SimpleHTTPServer from python, if you’re curious) in order to publish not only the code, but also de data files.

The result was the working demo you have seen above.

Not only was the character walking on the screen, but all the keyboard and mouse interactions worked as well. I wasn’t expecting that.

Closing comments

Like I said, integrating Emscripten was a lot easier than I originally though. And it works like a charm!

At the time of this writing, I still need to enable other modules, like scripting, but I’m pretty confident that it will be just as easy (specially because Lua is already written in ANSI C/C++). Audio support is still to be added as well.

Based on the results so far, I’m considering making a web version of The P.U.R.G.E Protocol as soon as I have the chance.

Who knows. Maybe my next project would be a web based one 😉

See you next time!