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.

A behaviour instance can access the object that owns the tree via behaviour.owner. Any state that needs to persist between runs of the tree should be stored in the world model (e.g. attributes of the owner).

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.

A card has one or more faces. The content attribute defines the template that is rendered each time the card is played. Optionally a card may also define a back face which is what is displayed in a scene using a stack layout after the card has been used (i.e. the player has moved on 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 back attributes of the card are converted into template functions (stored as $content_template and $back_template) 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.

Note: In components you cannot use links like <a card="card_id"> or <a interlude="scene_id"> as these are only supported in template attributes. But they are anyway merely syntax sugar for <a data-event="card" data-target="card_id"> and <a data-event="interlude" data-target="scene_id">. In your components remember to use data-event and data-target attributes.

A @const directive declares a named value that is available both within the Rez sources and as a Javascript global.

Allow you to use PI as an attribute value:

Also in action and event handlers:

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.

Effects are applied and removed by @inventory when an item carrying the effect is placed into or removed from a slot. There is no support 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.

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 @generator creates a list of copies of an existing element, for example a group of similar monsters. At runtime a generator becomes a RezList with the same id whose values are the ids of the newly created copies.

A group specifies a collection of assets that can be selected from. Groups are dynamic: they are defined by a set of tags and collect together all assets carrying any of the include_tags (or, alternatively, all assets that do not carry any of the exclude_tags).

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

The @inventory element describes a container that can hold heterogenous items in slots.

For example, in an RPG it is common to have different slots to hold different types of items like armour, a shield, melee weapon, range weapon, rings, and amulets. In other games you might have slots describing wardrobe items. We can also think of memory (things we know about) as an inventory (where the items are topics we know about) or spell books (where items are individual spells). The @inventory element is designed to handle such cases.

An inventory is made up of positions, each declared by a nested @contains block. The @contains block has its own id, which becomes the name of that position in the inventory, and a slot_id naming the @slot that defines what the position accepts. This allows the same @slot to be re-used for several positions.

Slots are matched against items to determine whether it’s possible to put an item in a position: an item can be placed in a position if its type (including any @derived types) is what the slot accepts.

An actor owns an inventory by naming it as its container_id.

@item is an alias, defined using @elem, of the @object element. Items are ordinary objects with some extra attributes and defaults, and they do not have content so they aren’t rendered directly. They can, of course, be referred to by cards.

The @item element defines a conceptual item 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 have a type keyword-attribute (defaulting to :item) that connects them to compatible slots in inventories. That might include a shop, a wardobe, and a players backpack inventories.

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.

Some items can grant effects, which are applied when the item is put into a slot that has effects enabled (e.g. equipped) and removed when it is taken out.

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.

An element uses a mixin by listing it in its $mixins attribute:

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

The @pragma directive specifies an instruction to be run during the compilation process. For example this pragma runs the pragmas/source_explorer.lua file after the compiler has run a first pass processing the abstract syntax tree (AST).

A pragma is specified using a timing instruction:

a name e.g. source_explorer which corresponds either to one of the built-in pragmas (write_content, write_id_map, write_hierarchy, and write_obj_map) or to a Lua source file in the pragmas project folder, followed optionally by values that get passed to the pragma script.

A pragma receives the Rez internal %Compilation{} struct as a value compilation and any parameters as values and can use the plugin API to query & modify the compilation (for example adding new assets). It is expected to return either the original or a modified compilation.

Use with care.

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

A @patch adds a new function or method to a built-in Javascript class when the runtime is created. The Rez stdlib uses patches to extend classes such as Boolean and Object.

Patches have no id. Specify the class to patch with patch: and either function: (a static function added to the class) or method: (a method added to instances) but not both.

A @plot element represents a 'plot clock' or 'progress track' such as you might find in games like 'Blades in the Dark' and 'IronSworn: Starforged'. Each @plot has a number of stages and can be advanced.

As well as the plot itself firing events when advancing, it notifies it’s subcribers (which can be other plots).

In general the plot mechanism can be satisifed with a simple variable on any other object such as the game or an actor. However where plot requirements are more complex the @plot is available.

The @quest element represents a quest that the player character may become aware of, accept, and complete. It further supports becoming botched (incompletable) and unbotched.

Where the @plot elements represents a plot-clock, the @quest represents an overarching goal of the players.

A quest has a status which moves through the states :unknown, :mentioned, :accepted, :achieved, and :completed, or is :botched. The runtime provides methods to move between them: mention(), accept(), achieve(), complete(), botch(), and unbotch(). Each is ignored unless the quest is in a state from which the change is legal.

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 @scenes and @cards. Each @card represents some content that is presented to the player. By contrast the @scene represent the structure and intelligence about which @cards to represent and how to respond to player input.

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_id: #card_ref attribute that identifies the card that will be played when the scene begins. Optionally it has a layout: attribute that specifies the surrounding markup. The layout must contain a ${content} template expression which specifies where the scene’s cards are inserted. The default layout is just ${content}.

A @scene may have a layout_mode: attribute which must be either :single or :stack (default :single). In the :single layout mode only a single @card is ever displayed. While in :stack mode each new @card is laid out after the previous one, and finished cards that have a back face are flipped to display it.

Lastly a @scene may optionally have a blocks: [name_1: #card_id_1 name_2: #card_id_2 …​] attribute, a list of bindings from a name to a card. Each referenced @card will be rendered and its content can be inserted into the layout using ${name_1}, ${name_2}, etc.

The @schema directive is used to specify validation rules for element attributes. Schemas provide compile-time validation to ensure your game elements are properly configured and catch errors early in development.

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 @systems 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. @systems are run in highest-priority order (so priority 100 runs before priority 99).

Every @system must define at least one of before_event:, after_event:, before_lifecycle_event:, or after_lifecycle_event: but can potentially define several.

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.