A system for creating choice-based HTML games & interactive fiction.

Version 1.1 (02 Jan 2024)

By Matt Mower <self@mattmower.com>

Introduction

Rez is an open source system for creating choice-based HTML games & interactive fiction. It uses HTML/CSS, Javascript, images, movies, and sounds to present an interface, where players make choices by interactive HTML elements like links & forms.

An obvious comparison for Rez is Twine. The ideal Rez user is likely creating a game that is over-ambitious for Twine and is not afraid to write a bit of Javascript code for, e.g., handling events.

Rez has excellent support for making good looking interfaces. It includes a sophisticated layout system with a simple, yet compreshensive, template language. It is built upon the Bulma CSS framework and includes Alpine.JS for simple dynamic layout.

Rez supports asset management, NPC actors & behaviours, item & inventory management, factions, relationships, plots, customisable systems, and much more.

Rez can get deep but you can be productive with a subset of the language and learn the rest as you need to make use of it. See the online documentation for tutorials, language reference, and runtime API documentation.

Getting Started

To write a game with Rez you write one or more .rez source files and then use the rez compiler to turn them into a complete game: all the HTML, javascript code, & assets bundled ready to play the game in the browser, or distribute it.

The Rez language is mostly declarative. You use attributes to specify what happens and Rez takes care of the details. Dynamic behaviours (for example procedural generation) are supported by through incorporating Javascript functions. It requires only a little Javascript knowledge to get productive.

Installation

Rez is written in the Elixir programming language and requires both Elixir and Erlang to be installed.

Rez targets Elixir v1.15/OTP-26 but should be compilable with previous versions back to 1.13/OTP-25.

macOS

Installation on macOS depends on git, Homebrew and ASDF. If you install ASDF directly the homebrew dependency is unnecessary.

# Install git
# Install homebrew
# Get Rez
git clone git@github.com:mmower/rez.git
cd rez
# We use ASDF for tool dependency management
brew install asdf
# Will bring in nodejs, erlang, and elixir
asdf install
# Will install BulmaCSS, and Alpine.JS
npm install
# Install Elixir deps
mix deps.get
# Creates the `rez` compiler binary
./build_escript
# Check the binary works
./rez --version # should report something like 1.0
# Copy to somewhere in your ${path}
cp rez ~/bin/

The Node.js dependency is not for Node at runtime but to bring in some Javascript dependencies that get compiled into the resulting Rez applications.

Windows

  1. Install Elixir and Erlang.

    Download the Elixir web installer from https://elixir-lang.org/install.html#windows[elixir-lang.org] and install v1.14.2 or newer (the installer will give you a choice of versions during install). Installing Elixir will also install the appropriate version of Erlang by default. If you have a prior install of Erlang, you may need to check that it's compatible with latest Elixir.
    Verify your install in Powershell with
    > elixir -v
Erlang/OTP 25 [erts-13.0.4] [source] [64-bit] [smp:16:16] [ds:16:16:10] [async-threads:1] [jit:ns]
Elixir 1.14.2 (compiled with Erlang/OTP 25)

  2. Install Node.

    Install https://nodejs.org/https://github.com/coreybutler/nvm-windows[NodeJS 19]. A optional version manager like [NVM for Windows] can make this easier.

  3. Clone the repo.

    > git clone git@github.com:mmower/rez.git
> cd rez

  4. Install dependencies.

    > npm install
> mix deps.get

  5. Build the rez compiler binary.

    From Powershell:
    > $env:BUILD_MODE = 'escript'; $env:MIX_ENV = 'prod'; mix escript.build
    Verify your build:
    > .\rez --version

  6. Put rez in your path.

    Edit your environment variables and add the repo to your PATH. Now you should be able to run `rez` from any directory in your shell, undecorated. Check that you can print the version from the root directory:
    > cd \; rez version

Other OS

If you are able to get Rez to run on a different platform please create a PR with the instructions.

Usage

Creating A New Game

To create a new game:

rez new <game-name>

This creates a new game directory with the same name as the game name and populates it with a template game and its dependencies. The dist folder is where the compiled game will be placed.

Optionally you can specify any of these additional command line arguments:

--author-name="My name"
--author-email="My email"
--game-title="What my game is called"
--game-homepage="URL for more info about my game"

Compiling

A Rez game is compiled into a set of HTML, Javascript, CSS, and asset files that represent the game.

From the game directory:

rez compile [--verbose 0-4] src/<file.rez>

This will build the complete game in the dist folder including all assets referenced in the game.

The resulting files can be zipped for easy distribtion or potentially turned into an Electron application.

Note that, at present, no attempt is made to minimise or optimise the resulting JS or CSS. This exercise is left to the author.

Acknowledgements

Front end libraries

Backend dependencies