Zorb (Z-machine in Orb)

Zorb is a modern Z-machine implementation that compiles Z-machine story files into highly optimized, standalone WASM "Game Capsules".

Putting Zorb to Work

Zorb transforms classic interactive fiction into modern WebAssembly artifacts.

Prerequisites

• Elixir 1.15+
• Wasmex (for execution)
• Orb (for WASM generation)

Installation

Add zorb to your list of dependencies in mix.exs:

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

Running a Story

You can run a Z-machine story file (V1-V5, V7-V8) directly from the CLI. First, build the standalone executable:

mix escript.build

Then run a story:

./zorb_interpreter path/to/your/story.z5 --cache

Programmatic Usage

To run a story within your own Elixir application:

Using Zorb.run/2 (Recommended)

Zorb.run/2 starts a Zorb.Session (a GenServer) that provides a non-blocking, asynchronous interface. It is ideal for use in Phoenix channels or anywhere you need a long-lived, supervised process.

# Start the session from a story file with caching enabled
{:ok, session_pid} = Zorb.run("path/to/story.z5", cache: true)

# Listen for messages in your process
receive do
  {:zorb_output, char} when is_integer(char) -> 
    IO.write([char])
  {:zorb_output, {:cursor, line, col}} -> 
    # Handle screen model commands
    :ok
  {:zorb_halt, reason, pc, _opcode} ->
    IO.puts("Game halted.")
end

# Send input to the game
Zorb.Session.send_input(session_pid, "look\n")

Core Architecture: Game Capsules

Unlike traditional Z-machine interpreters that load and interpret story data at runtime, Zorb uses a Baking Factory approach. Stories are transformed into bespoke WASM binaries where the story data is baked in, and the interpreter logic is optimized for that specific story's version.

• Bespoke Generation: Optimized capsules eliminate runtime JIT overhead.
• WASM Tokenizer: High-performance tokenization with O(1) dictionary lookups via baked-in hash tables.
• Host Interface: Standardized zio namespace for I/O and system calls.

Documentation

• usage-rules.md: Essential rules and conventions for library consumers, including the WASM host interface.
• Z-Machine Specification: The official Z-machine specification.

Development

Running Tests

All integration tests use the bespoke capsule system:

mix test

The first run for a new story file may take several seconds as it "bakes" the optimized capsule. Compilation is currently handled on the consumer side; if intermediate artifacts emerge that benefit from shared persistence, a global cache may be reintroduced.

Test Resources

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