Language Guide

A Rez game is written in the form of one or more .rez source files that get compiled into an HTML index page & a Javascript application, plus any associated assets like images, movies, and sounds.

A Rez source file contains elements and directives that describe the various components of a game and how it connects together.

At the top level is the @game element that contains the game metadata and all the other elements that make up the game.

The command:

For example specifying <game name> as "mygame" will create a mygame folder containing a number of subfolders. In the src subfolder will be mygame.rez that will contain some example source. In the lib folder will be the stdlib.rez containing Rez standard library. It’s good to familiarize yourself with the contents of stdlib.rez but do not modify it as the game will overwrite it when you compile.

The command:

Compiles the sources into a game in the dist sub-folder. It creates an index.html as well as copying all of the Javascript & other asset files that constitute the game.

To distribute your game you distribute the contents of the dist folder. For example by compressing it into a .zip file or wrapping it in an Electron app.

Rez includes two default frameworks:

The files for these are included within the Rez compiler and will be automatically copied into your assets folder when you create or update the game. However whether you choose to use them or not is down to you. The new game template includes them as follows:

If you remove these lines from your game file those assets will not be included in the compiled game and you can replace them with other assets of your own. Rez does not, by itself, make use of any of their features so replacing them is intended to have no side effects.

The $pre_runtime attribute controls whether an asset is loaded before the compiled runtime.js (that includes the Rez standard library and your own elements and event handlers) or after. The $js_defer attribute controls whether JS attributes should be included using the <script> tag defer attribute that ensures it will only be run after the page has loaded.

The $built_in attribute is purely to help differentiate between things defined by Rez itself and things defined by the author. It has no in-game purpose.

Rez games are written in plain UTF-8 files with a .rez extension.

The % character is special in Rez and indicates a macro of which the most common is %% for comments.

Rez comments begin with %% and continue to the end of the line.

Once source file may include another by using the include macro %(…), for example:

An included file may include other files but beware of creating a cyclic dependency. For example this code will hang the compiler:

In the first place is the element itself:

There is a common pattern for writing elements:

Directives, by contrast, may look a little bit different, e.g. they don’t have a unique id.

Elements are used to describe in-game concepts. The Element Catalog describes each element in detail.

The id of an element must be unique and follow the rules for Javascript identifiers. In JavaScript, identifiers are case-sensitive and can contain Unicode letters, $, _, and digits (0-9), but may not start with a digit.

In some situations you may want to use similar ids for different kinds of elements, in this case a helpful protocol is to prefix the id with the type, e.g. instead of #emergency_exit you might use #s_emergency_exit for a scene or #c_emergency_exit for a card.

The most important thing when you are writing an element is its attributes. These describe the element and how it behaves in the game. In our @item example there are 7 attributes that demonstrate many of the built-in types:

There are seven attributes defined here:

The pattern for any attribute is <name>: <value>. The space after the colon is required and note that there is no , or ; at the end as you may be familiar with from other programming languages.

Legal

Not-legal

Attribute names follow the rule for Javascript identifiers:

Note that attribute names with a leading underscore (_) are considered to be 'internal' to the Rez compiler. These attributes are not converted into runtime attributes and are, therefore, not available.

Attribute names with a leading dollar ($) are considered to be 'special' and it is not advised to use them yourself unless you know what you are doing. Rez itself makes use of attributes with the $ prefix for housekeeping and you could, inadvertently, trample these.

Rez defines many attribute types, some simple and some more complicated. The more complicated types are generally related to creating dynamic behaviour and may require additional Javascript knowledge:

A boolean value is either true or false (alternatively we can use yes and no) and is often used for flags.

The underlying data representation is a Javascript boolean.

A number value can represent either integers or floating point values.

The underlying data representation is a Javascript number.

A string value is text enclosed with double-quote (") characters used for descriptive properties. Typically single lines, where multiple lines need to be used the suggestion is to use the Heredoc string instead.

The underlying data representation is a Javascript string.

A keyword value is a special kind of string primarily used for identifier values. It is prefixed with a colon (:) and must obey Javascript identifier rules.

The underlying data representation is a Javascript string.

An element reference is used to refer to the id of a game element. It is prefixed with a hash (#) and must obey Javascript identifier rules. Although it acts like a string part of the value of element references is that the compiler will attempt to verify that they refer to an existing object.

The underlying data representation is a Javascript string.

An attribute alias is used to refer to an attribute of a specific element. It is prefixed with an ampersand (&) and consists of elem_id.attr_name where elem_id is an element id and attr_name is the name of an attribute of that element.

The underlying representation is a Javascript object {elem_id: <elem_id> attr_name: <attr_name>}.

A file string is a string value whose content is stored and read in from an external file.

A template is a kind of string value that supports dynamic content that is interpolated at run-time. This is controlled by the use of expressions such as ${…​}, $if() {% …​ %}, and $foreach(x: xs) {% %}. See template expressions for more.

A list of whitespace separated values that can include any of the other attribute types. It is separate from a @list element.

A set of whitespace separated values that can include any of the other attribute types.

A series of key: value pairs where the key should be a Javascript id and the value can be any of the other attribute types including another table.

However it is worth noting that using deeply nested tables is not advised. It does work, but the entire set of tables is the attribute making working with nested values more complicated.

An event script is written as a Javascript arrow function (args) ⇒ {…​} and therefore this will be null when it runs. Typically the object the event has been triggered for will be the first argument.

An action script is written as a regular Javascript function function (args) {…​} and this will refer to the object the script has been defined on.

Esp. useful for procedural generation a probability table is a list of pairs where the first element is the key and the second is the frequency. Let’s take eye color for example, we want characters we generate to have different coloured eyes. In reality brown eyes are most common at about 48% of the population, then blue at 29, green at 14%, and grey at about 9%. How could we generate a realistic distribution of eye colour (very important in games):

A different example might be a loot table, how could we generate one of those:

Our frequencies don’t have to % based and add up to 100, in this example we’ve given relative frequencies.

We can also use `#id’s as the key:

At the moment, due to a lack of JSON support, it is not possible to use attribute refs or functions as entries. A work around looks like this:

It’s not elegant but it’s feasible. This will likely get cleaned up in a future version.

A dynamic initializer is a value in the form ^i{js_expr} that is used to set the attribute value when the object is created using a dynamic Javascript expression. This is useful for setting a generated value (e.g. a random value) after which the attribute behaves normally using getters/setters.

Initializer are run in increasing order of priority from 1 to 10. This allows one initializer value to depend upon a previously initialized value. To specify a priority use the form ^i:<prio>{…​} for example ^i:5{…​}. Initializers that do not specify a priority get the default value of 10 and run last.

An ^i initializer expects its Javascript expression to explicitly return the value that is used to initialize the attribute.

In the following example we name an actor using a randomly generated given & family name.

A dynamic property is a value in the form ^p{js_expr} that is used to create an attribute that doesn’t have a stored value but is evaluated by evaluating the Javascript expression each time it is accessed.

For example:

Declaring an element as a global, Rez will create a global variable with the same name as the object id.

Declaring an element a template means it is intended to be used as a template for objects created with Rez copyAssigningId() and copyWithAutoId() methods. A template does not the usual init system.

Using the $js_ctor attribute allows overriding of the JS prototype for a given element.

All of the functionality of the game is converted into Javascript objects and functions which end up in a file called runtime.js. You can see this in the dist/assets folder of your game. It’s worth looking through runtime.js because you can see all of the library classes and functionality. Note that you should never modify runtime.js as it will be overwritten the next time you compile your game. However, in practice, there should be no reason to modify this file as its contents are produced from your game.

In the runtime environment, your @game element is translated into a JS object with RezGame as its prototype, the scenes into JS objects with RezScene as its prototype, and cards into JS objects having RezCard as their prototype. For most elements there is a 1:1 correspondence between it and an equivalent JS object defined in runtime.js.

[Advanced Note]: If you want to use different objects you can use the $js_ctor attribute to define which constructor function gets called. When replacing built in objects its advisable to have the built-in object as a prototype of your custom object.

The Game starts with a called to the game object start method which handles initialization and presenting the first scene & card.

The HTML that is presented in the browser is generated as follows:

At the top level the @game element requires a layout: template attribute. It further requires that this template contains a ${content} template expression. Internally the game uses a RezSingleLayout object to render the current scene, which it adds to the layout bindings as content. So the scene content is inserted into the game layout as ${content}.

At the next level down the @scene also requires a layout: template attribute and, it too, requires a ${content} template expression to be present. The scene either uses a RezSingleLayout (layout_mode: :single) or a RezStackLayout (layout_mode: :stack) depending on whether the scene is based on one @card or many @cards. The layout renders the card content and places it in the layout binding content. So the card content is inserted into the scene layout as ${content}.

At the next level down the @card provides a content_template: and, optionally, flipped_template: attribute. The flipped template is used in the stack layout which we’ll discuss shortly.

So in the simplest case the structure is:

The actual picture can be a little more complicated because the scene layout and card can also include content from other cards by specifying the id of the cards in their blocks: attribute. But what is a block?

Using the blocks: attribute we can specify the attribute of cards that we want to include beyond the main content card. For example, to include a sidebar that is common across cards in a scene:

When the explore scene gets rendered it will render its current card and bind the rendered content to content and also render the card #sidebar and bind that content to sidebar. So using the ${sidebar} template expression from the layout includes the sidebar content.

Note that when a card is used from a block: attribute it is automatically given a $parent_block binding (that points to the card using it as a block) so that it can refer to the attributes of its parent card.

This is useful when you want to create a "parameterized" block. For example, we could dynamically render a list of available exits in a card representing a location, this way:

In this example #room_with_exits and #another_room_with_exits both define an exits: attribute and render the card #list_exits as a block.

However, #list_exits doesn’t have to know which card is rendering it, only that it defines an exits: attribute.

We use a code-block binding location: from the #list_exits card to reach up to its 'parent' card (the one that included it as a block) to find its exits: attribute and use that for rendering the list of exits.

This means we can use #list_exits from any card that defines an exits: attribute.

Bindings are how we make data from our game elements available to the code and templates that are rendering our view. You’ve already seen an example of a binding in the section above:

But what does this mean? And why do we need it?

Let’s go back to basics with a very simple content template, e.g.:

This will present the text "Hello from the first chapter" in the browser.

But how does this happen?

The next section is quite technical and will likely require a good understanding of Javascript, far more than is required to use bindings & expressions. Feel free to skip ahead if you don’t feel comfortable digging this deep.

Rez converts this simple markup into a Javascript function that renders it. For the content above you’d end up with something like

Now you might be thinking "OMG! Why do we need such a complex function to render a simple line of text?"

If every template was as simple as this, we wouldn’t. But a simpler approach wouldn’t allow us to build more complex, dynamic, templates. Before we get to that, let’s break down this function.

The outer level is a function that accepts an argument bindings and then returns the result of a reduce() call on an array. In this case an array containing a single function also taking bindings as its argument.

This 'inner' function doesn’t use its argument, it just returns the static string that is our output.

The reducer function takes some text (initially an empty string) and a function (taking a bindings argument), and returns of appending the function result to the text.

The result is that we "thread" the outer bindings variable through the inner function and concatenate the results.

So essentially this boils down to:

And, hence, to our output.

To see why it works this way, let’s look at a dynamic template using a template expression:

This template breaks down into three chunks:

The first and last chunk are simple strings, like our previous example. But the middle chunk is a template expression that must be generated, using some Javascript, when the card is being rendered. At that time the value of card.chapter is "second" so the template is equivalent to an expression like:

Let’s look at the rendering function generated for this template:

It’s more complicated but follows the same exact pattern, running reduce() over an array, that now contains three inner functions. These functions return the following content respectively:

That is concatenated to present the user with "Hello from the second chapter."

But how is "second" getting from the chapter: attribute of the card into the second inner function. It happens through the bindings argument that we are threading through the outer rendering function to those inner functions. Let’s look at the second inner function:

If we strip away the mechanism here the core part is:

This is what the template expression ${card.chapter} boils down to.

This inner function is using it’s bindings argument to look up card.chapter. card is an example of a default binding that Rez makes. Whenever a @card is rendering it binds card to the RezCard object representing that card. In this case the object that defines the chapter property, containing the string "second". Rez also automatically binds scene to the current RezScene and game to the RezGame instance. So you can always use expressions involving card, scene, or game bindings without needing to bind anything yourself.

But, by itself, the rendering system knows nothing about your game world and the elements you have populated it with. For example, you may have an @actor element with id #player that has a name: attribute, but the renderer doesn’t know about that. In order to use an expression like:

We have to teach Rez how to point player at the right object. That’s where bindings and the bindings: attribute come in. They bind a variable name that you can use in a template to the Javascript object containing the values you want to refer to. To make the expression above work we’d use:

This is an example of an 'element binding'.

By default a @scene specifies a layout_mode: of :single which means that the scene renders a single 'main' @card as its content. When a new card is played into the scene it replaces the previous card and the view gets re-rendered.

However, there are times when when you might want to render more than one card into a scene. For example a dialogue scene might represent a number of interactions back and forth between characters with the player able to specify a response. In these, and similar examples, you don’t want the "history" of the scene to disappear.

To achieve this a @scene can specify layout_mode: :stack to use the RezStackLayout. When using the stack layout, playing new cards into the scene do not replace the exist card but are appended or pre-pended to the list of previous cards (based on the layout_reverse: attribute).

When the RezStackLayout renders, it renders the list of cards played into the scene (separated by any content in the layout_separator: attribute).

However, in fact, an author probably doesn’t actually want to re-render previous cards. A card that presented a set of dialogue choices doesn’t make sense when the player has already made their choice. It would make more sense to render a version of the card representing the choice the player has made.

This is why cards support a flipped_content: attribute. When a new card is played into a scene with a stack layout the previous card gets 'flipped' and renders the flipped_content: template rather than the content: template.

But what happens if we play the same card multiple times? How does it know which is flipped and which is 'face up'. What happens if an event wants to store data in the card? To answer these questions we need to go a little deeper.

The rendering process doesn’t directly render @card`s, `@scene`s, or `@game’s. Rendering is done via an object whose prototype is `RezBlock. RezSingleLayout and RezStackLayout both have RezBlock as their prototype. For each @card that is being rendered there is an instance of RezBlock.

A RezBlock handles generating HTML to output to the view by calling executing it’s template with appropriate bindings. Where appropriate a block also has a parent_block reference that allows walking back up the content tree. (See the example above related to bindings).

So when a RezCard is added to a RezStackLayout it’s actually the card wrapped in an instance of RezBlock. The same card can get added to the layout many times, it’s always the same card, but different block instances.

What this means is that when a card is being flipped it’s actually the block that tracks flipped status and decided whether to render its cards content: or flipped_content: template.

Further it means that when an event wants to track how this changes the cards content it can store those changes in the block.

The first time the next_move card is added to a scene it displays the options to shoot or flee. There are two event cards which set the choosen route into the block and in the case of shooting what the result was.

When the card is re-rendered the flipped_content: template is rendered which uses the block properties action and hit to decide what should get rendered.

When the game layout gets rendered its content is embedded inside a built-in template:

You can target the whole game content using the game CSS class.

The game layout is a good place to put fixed parts of the interface, for example titles, score, current time or location, and so on. The game layout is expected to contain the template expression ${content} which will include the contents of the current scene.

When the current scene gets rendered its content is embedded into a different template:

In the same was as the game, the scene layout is expected to contain the template expression ${content} which will include the contents of the current card or (in stack mode) cards. You can style scenes by targetting the scene CSS class or customise styles for particular scenes by targetting the DOM id. In our example game that would be scene_play_the_game.

When a card gets rendered its content template is embedded within the following template:

One thing to note is that the scene_id may not be what you expect. If the current scene was set to #explore_office you might expect that the rendered HTML would contain this id. However Rez treats your @scene and @card elements as a template and uses a copy when rendering a scene.

Block content comes from cards that are being rendered inside another card. For example you might have a card #sidebar that we want to use to render sidebar content that should always be visible.

In this case we would add it to (for example) the scenes blocks: attribute. To include it within the scene layout you would use the template expression ${sidebar}.

A @scene has a required attribute layout_mode: which can, as of v0.11, have two values:

In :single mode the ${content} substitution embeds the content of the current card in the scene. When the card changes the content will change to match it. The effect is that the scene will jump from card to card.

In :stack mode the ${content} substitution embeds the content of every card that has been played into the scene so far. Rather than jumping from card to card the cards will accumulate.

However, as a new card is played the previous card gets "flipped". What that means is that instead of rendering the content attribute it renders the flipped_content attribute.

For example a card might present the player with two options. If the card didn’t get flipped it would continue to present two options even though an option had been selected. But the flipped version can, instead, display the chosen option.

When we play a card into the current scene we are either replacing (scene layout_mode: :single) or adding (scene layout_mode: :stack) to the content in the scene.

This will create a link titled "Play Again" that plays the card with id #play_game.

A scene switch is when we end one scene and begin another, automatically playing its initial card.

This will create a link titled "Draw your gun" that will end the current scene and begin the scene #fight.

An interlude is when we interrupt one scene to play out another, and when that scene ends returning to the original scene.

This will create a link "Shop at the store" that interrupts the current scene and starts the scene #store. This should be followed by a resume to return to the original scene.

An example of where this kind of link is useful is for presenting a player inventory. Looking at the inventory steps out of normal gameplay. When the player is done with the inventory they expect to be back where they were before they triggered it.

It is possible to have an interlude within an interlude but may get confusing if taken too far.

From an interlude we can resume the previous scene using a resume link.

This will end the interluded scene and resume the previous scene where it left off.

There may be situations where you only want links to appear under specific circumstances. You could do this a template expression but Rez has a built-in facility for dynamic links. Using the syntax:

A link can trigger a custom event.

This will create a link titled "Reload gat" that when clicked will run an event on_reload on the game, scene, or card (in that order).

Once the event handler has done its work it should return a response object.

Any of the previous types of link can be amended to pass arbitrary data values. For example we might have a dialogue scene and want to control which actor the player is going to have a dialog with:

When either link is clicked it will start the new scene #conversation and that scene will have it’s actor_id attribute set to either #gutman or #wilmer based on which of the links is clicked. This offers a great deal of ability to customise the behaviour of cards and scenes.

Return an object from an event handler to determine what happens next. Some object types can be combined (e.g. the flash message combines with most of the other choices)

To start a new scene.

To play a new card into the current scene.

To set a flash message.

To have the current view re-rendered.

To log an error message to the console.

An alternative to using a link is to use a <button> with a data-event attribute. For example a button to play a new card would look like:

By specifying data-event="card" we tell the button it’s loading a new card and the data-target attribute specifies which card to load. We can use a similar approach to load new scene:

Here data-target specifies the id of the scene to switch to. Use data-event="interlude" for an interluded scene, rather than a scene switch.

Where you want to run a custom event handler, on_something_interesting, use specify the event name directly in the data-event attribute:

You would pair this with an event handler as follows

In this example the handler is in a card but you can also put in the scene or game as appropriate.

Sometimes you want a link to be disabled based on dynamic criteria (the bar doesn’t open until 8am) or maybe not even to appear at all (the portal entrance isn’t visible if you’re not wearing your x-ray specs).

To make a dynamic link use the dyn_link template expression filter. Here’s an example:

In this case, if the player is already rested they are shown a disabled option. In some cases it might be preferable to use dyn_link.hide() so that no choice is offered at all.

The event handler is passed a RezDynamicLink object that it can use to customise link presentation.

For data capture the simplest approach is to bind an HTML form input element to an attribute value using the rez-bind attribute.

For more complex interactions use the rez-live attribute to generate events.

When the user changes the value of the field this will generate an on_input event on the corresponding RezCard object, passing the generated event as a parameter.

Will generate an on_submit event to the form. The handlers in either case should return as any other event handler. In the case of submit it is probably to load a new card or scene.

A substitution is where we replace a token like ${player.name} in a template with the value of the expression. For example:

If the player objects name attribute is "matt" this will return:

Note that the an expression is only a lookup. You cannot use arbitrary JS expressions, so:

Will not work. If you want to modify the value you must use a filter expression (see below) to do so. In this case it would be:

Where does this player reference come from? Good question, this is an example of a binding. You’ve already seen bindings at work with ${content} and ${sidebar}. content is an example of a binding that Rez automatically makes available but you can add your own to refer to any objects you like.

Here we are binding the Javascript variable player to an element with id player (which we might assume is an @actor element defining the player character). For example:

is an equivalent way of creating the same binding. If we didn’t know the object we wanted to bind to in advance we can use a dynamic binding with a function.

But you don’t have to make bindings only to elements, you can bind to any Javascript value:

In the context of a template there are usually default bindings:

The third type of template expression is the conditional template. This allows content to be dynamically included based on an expression. The format of a conditional template is:

or

In the game example above we used:

To determine whether to show the won/lost percentage template content. You can nest conditional templates inside other conditional templates.

The fourth type of template expression is an iterator template. This allows content to be created from a list of values (In Javascript terms, anything that could be an treated as an array). The format of an iterator template is:

This will iterate over the binding list and run the template expression once for each element of list binding x to that element.

This alternate form accepts an optional second template expression. This expression will be rendered between each rendering of the content expression.

Note that the list binding should either be an object in the bindings or a property of an object in bindings. You cannot use arbitrary expressions. If you need to use an arbitrary expression use a function binding, so instead of:

you would write:

A fairly common requirement when building dynamic interfaces is to want to render one card within another. For simple cases you can use the blocks: attribtue on @game, @scene, or @card to render a named card as a block.

However there are two areas where this approach does not work:

The latter is the $foreach case.

Solving these two problems are what the $partial expression is for.

To setup attributes for rendering you can run code in an event handler. For example a @card can have an on_start hander:

However in many cases it might be easier to use a "do block" inline in the template:

Sometimes it is advantageous to be able to be able to create new tags that hide some of the complexity of your HTML/CSS. That is what user components are for.

Here is a very simple example. Bulma CSS provides the block class that you may wish to apply to your paragraphs:

There’s nothing particularly complex about this but if you are using this everywhere it can get tedious to write every time and noisy to read. Here is a component that simplifies this situation:

User components are always written in markup with a . in front of their name. So the component p becomes the tag <.p>.

A user component is implemented by a Javascript function that receives three parameters:

The return value of the component is expected to be the markup the component emits.

Let’s look at another example. Let’s say we are writing a lot of event buttons like this:

The boilerplate to make a button can be a bit tiresome and it obscures the most important thing about this button, that pressing it triggers the reload event. Let’s make a component:

Now we can write:

Because evt_btn is a container tag the value of the content argument is the string "Reload". For self-closing tags the value of content will be null.

The event attribute above is an example of a static assign but we can also pass dynamic expressions:

In this case the expression event_name is going to be evaluated and that value will be passed to the assigns map under the event key. Any Javascript expression is permitted here and all in-scope bindings are available so:

Is legal.

Let’s start with an example of the syntax and main concepts:

At a high-level this behaviour tree defines some behaviour for our NPC Sam Spade. When Sam’s in his office he will attempt to have a drink. If he finds himself with Kasper Gutman he will attempt a wisecrack. While this is a contrived example it will serve to highlight the main concepts at work.

Behaviour trees are attribute values. In the example above the behaviours: attribute contains a behaviour tree. They are written in the form of a list but have a special ^ prefix to distinguish them from regular lists.

A behaviour tree is composed of behaviours, which may contain other behaviours as children, and where each behaviour is written as a list in the form:

So we have the name of the behaviour, followed by zero or more options, followed by zero or more children. In the example the first behaviour is a $select with no options ($select doesn’t take any) and two children:

The first child is a $sequence behaviour that again has no options ($sequence doesn’t take any either) and three children:

and its first child is an actor_in:

This behaviour has two options actor and location and no children. The other two children of the $sequence have a similar structure.

The name of the behaviour corresponds to the id of a @behaviour element in the game. The $ prefix tells us that $select and $sequence are a core behaviours that is @behaviour elements defined in the Rez stdlib and always available to any game.

Options are written as <option name>=<value> where the option name follows the Javascript variable naming pattern the same as attribute names, and the value can be any legal Rez value type.

The behaviours actor_in, item_in, and actor_drinks are not core behaviours but examples of author defined behaviours. As an author your job is to create behaviours that are meaningful in your games context.

Now let’s talk about what all of this means.

Although behaviour trees are syntactically written as a list, they form a branching tree structure as each behaviour can nest other behaviours in its child list, to an arbitrary depth. The first behaviour is the root behaviour of the tree.

When we "execute the tree" it means excuting the root behaviour which in turn may execute some or all of its children until execution reaches the leaves of the tree. But, before we can understand all that, there are some other concepts we need to be aware of.

When we talk about executing a behaviour tree what we are really saying is: when we execute the root behaviour of the tree does it succeed or fail?

At the level of the tree itself, if the root behaviour succeeds it means that some action was successfully taken in response to whatever event caused us to execute the tree in the first place.

In the context of a behaviour itself success or failure has different meaning. For example, a $select will succeed if any of its children succeed, while a $sequence will only succeed if all of its children succeed (the observant may notice a relation to boolean logic here).

To put this in context, $select can be used to choose among a range of behaviours (given as its children). If one child fails, the next is tried, and so on. If the $select succeeds we know that one of its children succeeded. Conversely the $select failing tells us that none of its children succeeded. By contrast the $sequence is a step-by-step procedure where if any step fails, the $sequence fails.

You will see this pattern of $select/$sequence for selecting among options that are described as a procedure (that may themselves contain other such patterns) often.

$sequence and $select are examples of composite behaviours. We’ll talk about behavior types in a moment.

The 'leaf' behaviours in a tree don’t have children and their success or failure it more directly tied to the state of the game world. In our example above the behaviour:

Will, we supppose, succeed if Sam is in his office and fail otherwise. The actor_drinks example is a little more subtle.

In our example we have already tested that the whisky item is in Sam’s location we can assume that actor_drinks is going to succeed. But this doesn’t always have to be the case. Whether or not a behaviour succeed automatically if its prior conditions succeed is down to you.

There are four different types of behaviour:

Our first example of a simple behaviour tree uses one composite behaviour ($sequence), two conditions (actor_in, item_in), and one action (actor_drinks).

Let’s make a more complex example:

In this example we’re using $select to choose between 2 high level behaviours (respond to threat, respond to thirst) with each of those behaviours being composed of further $sequence and $select based behaviours.

For example if the player senses danger, do they have a gun? Is there a weapon in their environment? Can they escape?

We’ve made up a bunch of condition and action behaviours like actor_is_armed and actor_says and hand waved over the detail of their implementation.

As an author most of your work will be creating meaningful conditions and actions that represent the state and actions available in your game world.

You’ll note in this example we have a number of actor_xxx behaviours but haven’t specified an actor=xxx option. In this context we’d probably put the actor into working memory.

When a behaviour tree gets executed (using RezBehaviour.executeBehaviour(wmem)) it is passed an object to represent the "working memory" of the tree. This object is passed from behaviour to behaviour and can be used to communicate information between behaviours.

In our example above we might initialize working memory with something like:

Now any behaviour that needs it can refer to self in the working memory to find out who is performing these behaviours. Working memory can be a useful way to pass information around that is either dynamic (and therefore difficult to refer to as an option) or repetitive.

The Rez stdlib defines a range of core behaviours whose id have a $ prefix to distinguish them from author written behaviours. The implementation of the core behaviours is in stdlib.rez.

The core behaviours are intended to provide an overall structure for creating different kinds of behaviour. In particular look at behaviours like $either, $random_choice and $random_each which can introduce variability into behaviour patterns.

The @behaviour element allows you to write your own behaviours, typically these will be conditions and actions that query & modify, respectively, your game world. Let’s take a look at a query first:

First note that the only thing we are required to define is the execute: attribute, which must be a regular function (an arrow function will not do). All execute: handler functions are required to return an object with two keys: success and wmem. The value for success should a boolean. In this case we return true if the players weapon slot has something in it, false if not. The value for wmem should be the working memory we were passed in.

In this example we’ve assumed the actor is the #player. But we could make it more flexible using an option.

Now we’d specify the behaviour as

An as long as Sam’s @actor definition contained a main_inventory all would be well.

Now let’s examine how we would define an action:

We can see that this is even simpler. Most actions will return a successful result since you have, likely, already queried whether they be executed or not. But if an action can be executed and fail you can return a different results as per the query above.

Working memory is assumed to be an object that is passed between the different behaviours in the tree. For example one behaviour could store a value that a later behaviour will use. We can see how actor_sees_item could return success and store the id of the item in the working memory for actor_equips_item to put into their inventory.

Lastly the owner is the object that owns the behaviour tree. This allows you to make use of the owner’s attributes within the behaviour. Here’s an example of doing this. Let’s create a generic query behaviour that lets us test a property of any object and compare it with an attribute of the owning element:

Might take you a while to see what is going on here but we are making use of bind to make this into the owner object within the context of the code block being passed to the query via its if option.

Having defined a behaviour tree, how do you use it?

Remember that a behaviour tree is defined as an attribute on an element:

At a basic level we can run this behaviour tree using:

The executeBehaviour() method returns an object:

The authors are still experimenting but a broad approach suggests itself:

Behaviours are likely to fall into broad categories that form a response to an event. An example might be "new day" or "player enters location".

You could then define, e.g., a new_day_behaviours: attribute any element that should respond to the :new_day event. Then use a @system to reponds to the event, running the behaviours for all relevant elements.

Another approach is to define a behaviour tree to cover all events and use $select to decide which branch to follow. For example:

Now you could define a system for running all behaviours in response to any event:

The behaviour system is quite flexible and can be made to work in a number of different ways to suit the needs of your game and ease of authorship.

Much of the writing on behaviour trees comes from a real-time video game perspective where the trees are used to power enemy-AI. This introduces a number of constraints for example that the behaviour AI must run within one frame (i.e. <0.04s). The "running" status can be used to "break up" a behaviour.

In the Rez context this is less relevant so we do not support the "running" status. However it may be implemented later if it proves useful.

From a terminology perspective we use "executing" instead of the more common "ticking" language. We think it’s more natural to say you are executing a behaviour than ticking one.

We use the term "behaviour" to refer to our behaviour types while you may see them referred to as "nodes" elsewhere. Node is a more mathematical term, we think behaviour is more natural.

Also where you see fallback as a type of behaviour we call it $select. The behaviour is ultimately the same.

What is a Behaviour Tree

Designing AI Agent’s Behaviours with Behavior Trees

The Behaviour Tree Start Kit by Alex J. Champandard and Philip Dunstan

Unreal 4 Behaviour Tree Overview

Chris Simpson’s Behaviour trees for AI: How they work

Video lectures on behaviour trees

especially:

5 minute Behaviour Tree tutorial

The @script and @style directives allow embedding arbitrary Javascript or CSS classes into your game.

The contents of these directives is automatically inserted into an appropriate spot in the game files.

Another way to include your own Javascript is through the use of the @patch directive which allows you to add new methods to existing JS classes. Here is an example from the stdlib.

This adds a new method fy_shuffle to Javascript Array instances. So you can now write:

To add a method to instances use the method: attribute and specify the method name. To add a function to a constructor use the function: attribute instead.

A third way to include custom Javascript is by implementing a template expression filter. Here is an example from the stdlib: