Skip to content
avwohlPublic

About

A walkthrough generator for Z-machine interactive fiction, with a CZECH-compliant interpreter, an AI solver, and a replay harness. It holds 50 verified complete solves across versions 1 through 8.

Topics

Resources

Stars

3 stars

Watchers

1 watching

Forks

Repository files navigation

ZWalker - Automated Z-Machine Walkthrough Generator

Python 3.8+ License: GPL v3

ZWalker is an automated walkthrough generator for Z-machine interactive fiction games. It combines a CZECH-compliant Z-machine interpreter, AI-assisted solvers, and a deterministic replay harness to produce and verify game walkthroughs, primarily as regression tests for the z2js compiler.

Verified Results

The headline result is a corpus of 50 verified complete solves spanning Z-machine versions V1 through V8. It covers a large slice of the Infocom catalogue — both Zork-era trilogies and Mini-Zork, the Planetfall series, Trinity, A Mind Forever Voyaging, The Hitchhiker's Guide to the Galaxy, Starcross, the three mysteries (Deadline, Suspect, Witness), Suspended, Ballyhoo, Hollywood Hijinx, Cutthroats, Infidel, Plundered Hearts, Moonmist, Leather Goddesses of Phobos, The Lurking Horror — alongside modern classics (Photopia, Shade, Lost Pig, The Dreamhold) and IF-Comp games. Every game is played start to finish and reproducibly won, verified by deterministic replay against a fixed RNG seed. The full table, notes on the odd columns, and the replay command for every game are in docs/VERIFIED_SOLVES.md.

Features

  • 🎮 Z-Machine Interpreter: 100% CZECH compliance — 1,604/1,604 tests passing across versions 3, 4, 5, and 8 (v3: 368, v4: 386, v5: 425, v8: 425)

    • Plays Z-machine versions 1–5 and 8 (v6/v7 screen model not supported); CZECH-verified on 3, 4, 5, 8
    • Accurate opcode implementation, full state save/restore
  • ✅ Deterministic Replay Verification: scripts/replay_solve.py replays a walkthrough with a pinned RNG seed and searches seeds until random events (combat, thief, wizard) line up — making "did we really win?" a reproducible yes/no

  • 🤖 AI-Assisted Solving: multiple solver generations

    • Agentic solver (zwalker/agentic_solver.py): perceive→decide→act→verify loop with BFS navigation, world model, and checkpoint backtracking; runs free with a local decider or with Claude via API
    • Strategic LLM solver (zwalker/advanced_solver.py) and assist layer (zwalker/ai_assist.py)
    • Persistent cross-run knowledge base (zwalker/knowledge.py)
  • 🧪 Compiler Testing: validate z2js and other compilers

    • Convert solutions into Node.js replay test scripts (155 tracked, including 73 "smart" tests that tolerate random events)
    • Compare outputs between interpreters, detect regressions automatically
  • 📊 Game Exploration: automated mapping and analysis

    • Room discovery and mapping, object detection and tracking
    • Command success/failure analysis

Installation

Not yet published to PyPI — install from source:

git clone https://github.com/avwohl/zwalker.git
cd zwalker
pip install -e .

# with AI backends (anthropic, openai)
pip install -e ".[ai]"

Quick Start

Basic Game Exploration

# Explore a game and generate a map
zwalker explore game.z5 --max-rooms 50 --json walkthrough.json

# Use AI assistance (requires ANTHROPIC_API_KEY)
zwalker explore game.z5 --ai --ai-backend anthropic --max-rooms 100

# Interactive play mode
zwalker play game.z5

Verify a Walkthrough

python3 scripts/replay_solve.py games/zcode/zork1.z3 walkthroughs/zork1_verified_350.txt --seeds 4

More examples (Python API, test generation, use cases) are in docs/USAGE.md.

Documentation

→ View Full Documentation & Game Index

License

GPL v3 License - see LICENSE file.

Credits

  • Z-Machine Spec: Based on the Z-Machine Standards Document
  • CZECH Test Suite: Compliance testing by Amir Karger
  • AI Assistance: Powered by Anthropic Claude and OpenAI

Links

Note: This is alpha software under active development. Use for testing and exploration. Bug reports and contributions welcome!

About

A walkthrough generator for Z-machine interactive fiction, with a CZECH-compliant interpreter, an AI solver, and a replay harness. It holds 50 verified complete solves across versions 1 through 8.

Topics

Resources

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages