Zorb

Zorb compiles Z-machine story files (versions 1-5, 7, and 8) into standalone WebAssembly binaries. Version 6 is not supported.

The output is a single .wasm module with the story data embedded, so a host only needs to instantiate it and provide the zio import namespace described in CAPSULE_HOST.md. Compilation takes roughly 1 ms per story.

Requirements

• Elixir 1.19+

Installation

def deps do
  [
    {:zorb, "~> 0.13.0"}
  ]
end

Usage

wasm = Zorb.compile("path/to/story.z5", cache: true)
File.write!("story.wasm", wasm)

Options:

• :cache (default false) - reuse a previously compiled capsule stored under Zorb.Config.cache_dir/0.
• :method (default :patcher) - :patcher patches a pre-compiled template with the story data. :traditional runs the full AST compilation pipeline and is intended for debugging.

How It Works

Zorb does not interpret story data at runtime. The interpreter logic and the story data are baked into one WASM module, specialized to that story's version:

• Template patching: the default :patcher method starts from a pre-compiled template for the story's version and patches in story-specific values (header fields, dictionary hash table, story memory).
• Tokenizer: dictionary lookups run inside WASM against baked-in hash tables.
• Host interface: the capsule imports I/O and system functions from the zio namespace. See CAPSULE_HOST.md for the full interface.

Documentation

• usage-rules.md: rules and conventions for library consumers.
• CAPSULE_HOST.md: specification of the WASM host interface.
• Z-Machine Specification: the official Z-machine specification.

Development

Run the test suite:

mix test

For additional Z-machine test files and stories, see the zifmia repository.