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.
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.
-
🎮 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.pyreplays 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)
- Agentic solver (
-
🧪 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
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]"# 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.z5python3 scripts/replay_solve.py games/zcode/zork1.z3 walkthroughs/zork1_verified_350.txt --seeds 4More examples (Python API, test generation, use cases) are in docs/USAGE.md.
→ View Full Documentation & Game Index
- Verified Solves & AI Walkthroughs
- 100+ Game Sources with Download URLs
- Test Suite Results
- VERIFIED_SOLVES.md - table of the 50 verified solves and replay commands
- USAGE.md - Python API, walkthrough generation, use cases
- ARCHITECTURE.md - source tree and key scripts
- PROJECT_STATUS.md - what works, limitations, contributing
- CHANGELOG.md - Z-machine bug fixes
- ZORKIE_TESTING.md - using the verified solves to test the zorkie ZIL compiler, and why released
.z≠ compiled historicalsource ZIL - TEST_GENERATION.md - z2js test pipeline
- ADVANCED_SOLVER.md - strategic solver design (Dec 2025)
- PROJECT_NOTES.md - project overview and approach
- docs/archive/ - historical status and progress reports
GPL v3 License - see LICENSE file.
- 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
- Source: https://github.com/avwohl/zwalker
- Issues: https://github.com/avwohl/zwalker/issues
- z2js Compiler: https://github.com/avwohl/z2js
- IF Archive: https://www.ifarchive.org/
- IFDB: https://ifdb.org/
Note: This is alpha software under active development. Use for testing and exploration. Bug reports and contributions welcome!