Fernz

Fernz is a clean-room, pure Python reimplementation of Jericho and its underlying Frotz Z-machine engine, with a familiar Python API for playing and exploring interactive fiction. Here, clean-room means implementing the engine using only open specifications and documented public APIs, then testing its behavior against the original interpreters without inspecting their code (i.e., black-box behavioral comparisons).

It is also an experiment in agentic coding to see how far Astra could get with a public specification and a black-box reference implementation.

It was built to enable cross-platform play and redistribution in Cabin Fever x86 and to make Z-machine games easy to embed, test, and experiment with from Python. Fernz is MIT licensed and runs on Linux, macOS, and Windows.

It currently plays V3, V4, V5, and V8 stories and inspects V1–V8 files. The API covers gameplay, checkpoints, score/move queries, and object inspection; some Jericho methods and Z-machine features remain unimplemented.

Install

Requires Python 3.11+. Include the optional Textual terminal interface:

python -m pip install "fernz[textual]"

Use pip install fernz for the dependency-free library and simple terminal player.

Get a game and play

Download the BYU-PCCL game collection and play Zork I:

fernz --download-games
fernz zork1.z5

The download extracts only the contents of the archive's jericho-game-suite directly into ./games/, matching the test fixture. Games are distributed separately and retain their own copyrights and licenses. This Zork I file contains a V3 story despite its .z5 extension.

To choose a destination, use fernz --download-games /path/to/collection, then fernz /path/to/collection/zork1.z5. Existing destinations containing zork1.z5 are reused without downloading or overwriting files; an existing destination without that file reports an error.

You can also bring your own raw Z-machine story. Fernz first tries the exact supplied path, then, only if it is missing and relative, the same path under ./games. For example, zork1.z5 falls back to ./games/zork1.z5. There is no extension guessing or other search. Errors reading an existing path are reported without falling back. This lookup also applies to --inspect; the Python API uses explicit paths.

Try look, open mailbox, and read leaflet. Press Ctrl+Q to exit. Textual is selected automatically when installed; --simple selects plain text. The game's save and restore commands open file dialogs.

Use the API

from fernz import FernzEnv

env = FernzEnv("games/zork1.z5", seed=42)
try:
    observation, info = env.reset()
    print(observation.text, end="")
    for command in ("open mailbox", "take leaflet", "read leaflet"):
        observation, reward, done, info = env.step(command)
        print(observation.text, end="")
        if done:
            break
    checkpoint = env.get_state()
    env.step("look")
    env.set_state(checkpoint)
finally:
    env.close()

Observations provide plain .text and an ordered .stream with display tags. reward is the score change, info includes score and moves for supported games, and done means the interpreter has quit. Checkpoints include RNG state for reproducible replay; env.copy() forks an environment for independent exploration.

Further reading

Detailed guide · Terminal controls · API and project overview · Testing

Specifications: Z-machine Standard 1.1, annotated edition, Quetzal save format, and Jericho's public API.

Maintainers: see the publishing setup and release guide for GitHub/PyPI configuration, tag releases, local packaging checks and recovery.