zorb

# 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](./CAPSULE_HOST.md). Compilation takes roughly 1 ms per story.

## Requirements

- Elixir 1.19+

## Installation

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

## Usage

```elixir
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](./CAPSULE_HOST.md) for the full interface.

## Documentation

- [usage-rules.md](./usage-rules.md): rules and conventions for library consumers.
- [CAPSULE_HOST.md](./CAPSULE_HOST.md): specification of the WASM host interface.
- [Z-Machine Specification](https://zspec.jaredreisinger.com/): the official Z-machine specification.

## Development

Run the test suite:

```bash
mix test
```

For additional Z-machine test files and stories, see the [zifmia](https://github.com/jeffnyman/zifmia) repository.