Rez Elements & Directives Catalog

Elements describe in-game concepts.

Directives modify in-game concepts.

An actor represents an in-game character which could be the player avatar or a non-playable character that the player interacts with. Define an actor with the @actor element. In-game actors are represented by the RezActor object.

Actors are an optional concept and a simple game might not need them, choosing instead to represent any actors via attributes of the game or scene. But in more complex games it’s useful to be able to model actors separately.

An @asset element refers to a file on disk, typically an image, audio, or video file, that will be presented in game.

Rez automatically copies asset files into the game distribution folder when the game is compiled and manages pathing so that assets can be referred to in game without worrying about filenames and paths.

Assets can be collected into groups (using @group) dynamically choose from among related assets.

Behaviours are elements that describe components of a behaviour tree. There are four types of behaviour:

While the difference between conditions and actions are fairly intuitive, the difference between composites and decorators is more subtle. Composites are about coordinating between a series of other behaviours, while a decorator typically modifies the results of another behaviour.

For example the $sequence core behaviour executes its children in turn and succeeds or fails based on them, while the $invert core behaviour turns its childs succees into failure (or vice verca).

When a behaviour is executed it either succeeds or fails.

As we have seen from the examples above, a composite behaviour usually succeeds or fails based on the success or failure of its children. A decorator typically modifies the success or failure of another behaviour. Conditional behaviours succeed or fail based on a test and action behaviours succeed based on whether their implied action is successful.

From these four simple concepts some very powerful behaviours can be built.

Rez defines a number of 'core' behaviours. By convention these have $ prefix to their id to separate them from author written behaviours. The core behaviours are mostly composites and decorators that are intended to be building blocks for author written behaviours.

The core of a behaviour element is its execute: script attribute. This is intended to implement the functionality of the behaviour and return a value whether it succeeds or fails.

Each behaviour can, optionally, receive options and, again optionally, a list of child behaviours. Conditions and actions are not expected to have children while composites and decorators don’t make sense without at least one child.

When a behaviour tree is run it gets passed an empty object {} as "working memory" to allow different behaviours to communicate state required to run the tree. As a new working memory is used each time the tree is run, any persistent state changes should be in the world model.

Let’s look at an example. We want a condition that tests whether a given actor is in a certain location. Here’s how we could implement it.

A behaviour template is a composable element of behaviour. When writing behaviour trees you may find yourself wanting to use some behaviours over and over but not want to copy a whole tree. That’s where behaviour templates come in. With a template you can include just the parts of behaviour you need.

Cards are the basic unit of content & interaction in a Rez game. Cards are "played" into a scene to present what is happening to the user and offer them choices about what to do next. In this they serve a similar role to Twine passages.

The content attribute is key as it defines the template that is rendered each time the card is played. Optionally a card may also define flipped_content which is what is displayed in a scene using a stack layout after the card has been used (i.e. the player has followed a link from that card).

Cards can be part of the main interface but can also be used as blocks in other cards. For example a card could be defined to represent a sidebar and included into scene layout.

Internally the content and flipped_content attributes of the card are converted into template expressions (a kind of Javascript function) so that they render quickly.

A @component directive is used to specify an HTML component used in templates.

For example we may have specified a button like this:

There’s nothing wrong with this but the details are obscured by the attribute syntax, what if we could write:

The . prefix in <.event_button> indicates that this tag is implemented as a user component.

Let’s write this component:

Container components like <.event_button> have their contents available in the content argument, attribute values in assigns, and all bindings available at the component site in bindings. Self contained components have no content specified.

A @declare directive is a shorthand for defining an @object element without attributes. Typically you use this for declaring an object to be the target of relationships but which does not, itself, need to be defined in terms of a set of attributes.

A @defaults directive is a way to setup default attributes for a type of element or alias.

The syntax is simple:

The @derive directive is used to form keywords into hierarchies of types for items, effects, and so on.

Let’s take an example of where this might be useful: inventories.

We setup a hierarchy as follows:

The result is that an item with type: :sword, type: :mace, or type: :potion can be placed into a slot that accepts: :item. It’s not required to list all the different types of items that are legal in that slot. Equally our sword can be placed into a slot that accepts: :sword but an item type: :mace cannot, nor can an item type: :potion.

An item hierarchy can be as simple of complex as you need. At run-time all of the item type information is converted into tags. For example an item with type: :sword would have tags as if we had written tags: #{:sword :weapon :item}.

Effects are modifiers to aspects of the game that can be applied and removed dynamically as the game progresses.

For example an item, when worn, might convey a bonus to the actor wearing it. In this case the effect, attached to the item, is applied when the item is worn and removed when the item is removed.

Effect support is limited in v0.8. Effect scripts will be called and its up to the caller to ensure these work. In particular there is no support yet for effects that, for example, wear off over time.

The @elem directive allows the author to create a specialised alias for a particular kind of element, using a convenient and meaningful name.

For example, it may be desirable to be able use @sword and @watch instead of @item and customise those items using @defaults. We can apply @defaults to custom elements.

Factions represent in-game groups with their own agenda, reputation, and views of others. Define a faction using a @faction element.

An @enum directive defines a set of legal values for an attribute. The syntax is:

Here’s an example:

This would cause a compilation error because the color attribute does not use one of the legally defined values.

Notes:

A @filter directive defines a filter function that can be used in a subsitution Template Expression. A filter has a name which is how you refer to it in a template expression, e.g. capitalize and an impl function that takes a variable number of parameters (but at least one).

The game element is the top-level specification of the game and its metadata. It also defines the scene entry point of the game.

The @game element has an implicit ID of game.

A group specifies a collection of assets that can be selected from. Groups can be static by defining the id of member assets, or dynamic by specifying a set of tags. In the latter case the group will collect together all assets with any of the specified tags.

A group can be used to select an image at random, or cycle through the collection one-by-one.

The @inventory element creates a container that can hold `@item`s through the use of `@slot`s. Rez inventories are deliberately flexible to handle a range of use cases for example working memory (where items are thoughts) or spell books (where items are spells).

Rez has a fairly flexible inventory system that is based around 'slots' that define how items can be held. This allows an inventory to hold different kinds of items: you could have an inventory for items as well as an inventory for spells (spell book).

Inventory slots are matched against items to determine whether it’s possible to put an item in a slot.

Inventories are defined using the @inventory tag.

Inventories have a category which determines the kind of items that can be added to their slots. For example "spell" could represent a spell book, while "equipment" could represent the players inventory.

The @item element defines a conceptual item the player the player (or potentially an NPC) can acquire and add to an inventory. Items don’t have to represent physical objects but anything a player has for example a spell could be an item or even a memory.

Items are required to have a type keyword-attribute that connects them to compatible slots in inventories. That might include a shop, a wardobe, and a players backpack inventories.

However the Item/Inventory system is quite flexible so we can also think about spells as Items with the Inventory being a spell-book, or knowledge as Items with an Inventory being memory.

Items may be usable in which case they may have a limit to the number of times they can be used.

Some items can grant effects, either when the item is acquired, put into a specific slot (e.g. equipped), or when it is used.

The can_equip/on_equip scripts are used to decide whether the player can put an item in a given inventory & slot, and to process what happens when doing so.

For example equipping a magic ring might confer an effect on the player. But first it may be necessary to check that the player doesn’t already have a magic ring equipped.

A potion on the other hand confers no effect until it is used and might have only one use after which is presumed to be consumed.

Use the @keybinding directive to generate custom events from the user pressing a specific key, optionally with modifiers.

The syntax is:

(modifiers)? + keyName

A list is a named collection of values that can be used by other in-game elements, for example lists of names, locations, actors, and so on. Lists are defined using the @list element.

The run-time API supports selecting randomly from lists including with & without replacement.

A @mixin defines attributes that can be included into an object at runtime. This differs from @defaults which are applied to an element at compile time and become attributes of that object. Essentially each object gets a copy of their defaults. By contrast using a mixin there is only one copy which is shared by all instances using it.

Now that @elem supports arbitrary nesting it is possible that @mixin is not required.

An @object element describes an author-driven concept. Isn’t everything in Rez an object of some kind? Yes, but elements like @author, @item, and @plot have built-in meaning and functionality. By contrast @object is a blank canvas that an author can use for anything they think of.

The @rel directive describes the relationship between two game elements called the source (the element which has the relationship) and the target (the element the source has relationship with).

A relationship is unidirectional from source to target. Where applicable use a second @rel to describe the relationship in the opposite direction.

A relationship can be specified between any two elements with an id. The most obvious example being between one actor and another, but you could equally define relationships between actors and factions, factions and factions, or — if it makes sense in your game — factions and items (the holy grail anyone?).

A Game in Rez is authored in terms of @scene`s and `@card`s. Each `@card represents some content that is presented to the player. By contrast the @scene represent the structure and intelligence about which `@card`s to represent and how to respond to player input.

If you are familiar with Twine then a @card is roughly equivalent to a Twine passage. A Twine game is one long stream of passages woven together. Rez differs from Twine in that it uses the @scene to organise how the player interacts with the game and which/how the content is presented.

For example you might use different scenes for moving around the map, examining items, interacting with NPCs, buying from shops, and so on. You don’t have to, you could implement the game in a single scene, but the different layout and event handling possibilities make it easier.

A @scene requires an initial_card: #card_ref attribute that identifies the card that will be rendered when the scene begins. Additionally it requires a layout: attribute that specifies the surrounding markup.

Within the layout using the ${content} template expression to specify where scene content is inserted.

A @scene requires a layout_mode: attribute which must be either :single or :stack. In the :single layout mode only a single @card is ever displayed. While in :stack mode each new @card is layed out after the previous one.

Lastly a @scene may optionally have a blocks: [#card_id_1 #card_id_2 …​] attribute. Each referenced @card will be rendered and it’s content can be inserted into the layout using ${card_id_1}, ${card_id_2}, etc.

A script is used to include arbitrary Javascript code into the compiled game. Specify a script using the @script directive.

The @script directive consists of a string containing the code to include between { and } markers.

The code defined in the game’s @script directives will be automatically included as <script> tags before the end of the <body> element of the generated HTML template.

A @slot describes a component of an @inventory so that an inventory can hold different types of things.

For example an inventory representing what a player is wearing might have slots for coats, trousers, and so forth while an inventory representing a spell book might have slots for different levels of spell.

See also: [Type Hierarchy]

The @styles directive is used to include arbitrary CSS into the compiled game.

The styles defined within a @styles directives will be automatically included as <style> tags before the end of the <head> element of the generated HTML template.

The @system element describes an author defined system that can respond to events generated in the game and modify the game world.

Systems are orthogonal to event handlers that are specific to a given event. For example, when a user clicks a link this has a specific outcome that will be meaningful to the player. However any number of systems might also respond to this event.

For example we might want to model weather in our game world and have the weather change, automatically, over time. This change is not necessarily related to any specific player activity (e.g. clicking a link to move between locations) but any event might trigger such a change.

Whenever the player generates an event all @system`s whose `enabled: attribute is true get the opportunity to process, and potentially modify, the event before normal processing and to change the result afterward.

Every @system must have a priority: attribute that is a number greater than 0. @system`s are run in highest-priority order (so priority `100 runs before priority 99).

Every @system must define at least one of before-event: or after-event: but can potentially define both.

The @timer element describes a game component that generates events after specific time interval has passed, either once or repeatedly.

Use a timer element when you want something to happen irrespective of player input.

For example a timer could be used to create a proper "wandering monster" scenario, where every minute the player is at risk of a monster wandering into their location.