ZWalker - Z-Machine Interpreter & Game Solver

Overview

ZWalker is a complete Python implementation of the Z-machine virtual machine with AI-assisted game solving capabilities. It achieves 100% CZECH test-suite compliance, generates walkthroughs for Interactive Fiction games, and verifies complete solves with a deterministic replay harness.

100% CZECH Compliance

1,604 Tests Passing

50 Verified Complete Solves

55 Exploration Walkthroughs

Features

Complete Z-machine interpreter (plays versions 1–5 and 8; CZECH-verified on 3, 4, 5, 8)
Deterministic walkthrough replay & verification with RNG seed search (scripts/replay_solve.py)
Agentic AI solver: perceive→act→verify loop with navigation and backtracking
AI-powered game solving with Claude/OpenAI
Game exploration and mapping
100% CZECH compliance; GNTests passing; TerpEtude critical tests verified
z2js compiler validation

Verified Complete Solves

These games are played start to finish for a perfect score — or, for unscored story games, to their true ending, asserted by a #% WIN_TEXT: check in the walkthrough header — and the win is reproduced deterministically by replaying the command list against a fixed RNG seed with scripts/replay_solve.py. The corpus spans Z-machine versions V1, V3, V4, V5 and V8.

Game	Z-ver	Score	Won	Turns	Commands	RNG Seed	Download
9:05	V5	Win (unscored)	Yes	0	20	1	JSON \| Text
A Mind Forever Voyaging	V4	Win (unscored)	Yes	0	623	1	JSON \| Text
Adventure (Colossal Cave)	V3	350/350	Yes	290	289	3	JSON \| Text
Adventureland	V5	100/100	Yes	146	146	3	JSON \| Text
All Quiet on the Library Front	V5	Win (unscored)	Yes	1	37	1	JSON \| Text
All Roads	V5	Win (unscored)	Yes	0	185	1	JSON \| Text
Balances	V5	51/51	Yes	123	124	1	JSON \| Text
Ballyhoo	V3	200/200	Yes	413	415	1	JSON \| Text
Castle Adventure!	V8	Win (unscored)	Yes	67	277	1	JSON \| Text
Cloak of Darkness	V3	Win (unscored)	Yes	4	5	1	JSON \| Text
Cold Iron	V8	Win (unscored)	Yes	89	30	1	JSON \| Text
Cutthroats	V3	250/250	Yes	416 (clock)	264	1	JSON \| Text
Deadline	V3	Win (unscored)	Yes	10 (clock)	129	1	JSON \| Text
Deephome	V5	Win (unscored)	Yes	11	315	1	JSON \| Text
Detective	V5	360/360	Yes	45	45	1	JSON \| Text
Enchanter	V3	400/400	Yes	300	206	1	JSON \| Text
Hollywood Hijinx	V3	150/150	Yes	395	394	1	JSON \| Text
Infidel	V3	400/400	Yes	305	306	1	JSON \| Text
Leather Goddesses of Phobos	V3	Win (unscored)	Yes	395	373	1	JSON \| Text
Lost Pig	V8	7/7	Yes	173	173	1	JSON \| Text
Mini-Zork I	V3	350/350	Yes	440	405	1	JSON \| Text
Moonmist	V3	Win (unscored)	Yes	26	86	1	JSON \| Text
Pentari	V5	70/70	Yes	35	35	3	JSON \| Text
Photopia	V5	Win (unscored)	Yes	80	110	1	JSON \| Text
Planetfall	V3	80/80	Yes	5165 (GST)	444	1	JSON \| Text
Plundered Hearts	V3	25/25	Yes	192	186	1	JSON \| Text
Reverberations	V5	Win (unscored)	Yes	4	72	1	JSON \| Text
Shade	V5	Win (unscored)	Yes	124	126	1	JSON \| Text
Sorcerer	V3	400/400	Yes	390	234	2	JSON \| Text
Spellbreaker	V3	600/600	Yes	531	422	1	JSON \| Text
Starcross	V3	400/400	Yes	265	240	1	JSON \| Text
Stationfall	V3	80/80	Yes	5700 (GST)	375	1	JSON \| Text
Suspect	V3	Win (unscored)	Yes	29 (clock)	110	1	JSON \| Text
Suspended	V3	Win (unscored)	Yes	71	72	1	JSON \| Text
Suveh Nux	V5	Win (unscored)	Yes	0	102	1	JSON \| Text
The Acorn Court	V5	30/30	Yes	18	18	1	JSON \| Text
The Dreamhold	V8	Win (unscored)	Yes	0	438	1	JSON \| Text
The Edifice	V5	Win (unscored)	Yes	136	142	1	JSON \| Text
The Hitchhiker's Guide to the Galaxy	V3	400/400	Yes	521	466	1	JSON \| Text
The Jewel of Knowledge	V5	90/90	Yes	246	248	1	JSON \| Text
The Lurking Horror	V3	100/100	Yes	310	306	1	JSON \| Text
The Witness	V3	Win (unscored)	Yes	42	56	1	JSON \| Text
Theatre	V5	50/50	Yes	295	357	1	JSON \| Text
Trinity	V4	100/100	Yes	485	473	1	JSON \| Text
Wearing the Claw	V5	Win (unscored)	Yes	159	160	1	JSON \| Text
Wishbringer	V3	100/100	Yes	162	179	1	JSON \| Text
Zork I	V3	350/350	Yes	499	431	3	JSON \| Text
Zork I (Release 5)	V1	350/350	Yes	416	418	4	JSON \| Text
Zork II	V3	400/400	Yes	416	386	2	JSON \| Text
Zork III	V3	7/7	Yes	241	216	1	JSON \| Text

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 Deadline/Suspect/ Witness mysteries, 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, played start to finish and reproducibly won. (Zork III scores "potential" out of 7; Planetfall's and Stationfall's move counters are their in-game Galactic Standard Time clocks and the Cutthroats/Deadline/Suspect clocks are their real-time game clocks; Wishbringer and Cutthroats are V3 "time" games whose true score lives in their own globals; Trinity's V4 SCORE/MOVES globals are mapped per build. "Win (unscored)" rows are verified by the game's true ending text; some are genuinely scoreless, others are internally scored and reach the documented max — Deephome 300/300, Reverberations 50/50, All Quiet on the Library Front 30/30 — but keep the score in a global the interpreter doesn't sample, so the ending text is the check.)

# reproduce locally
python3 scripts/replay_solve.py games/zcode/905.z5 walkthroughs/905_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/amfv.z4 walkthroughs/amfv_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/advent.z3 walkthroughs/advent_verified_350.txt --seeds 4
python3 scripts/replay_solve.py games/zcode/adventureland.z5 walkthroughs/adventureland_verified_100.txt --seeds 4
python3 scripts/replay_solve.py games/zcode/library.z5 walkthroughs/library_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/allroads.z5 walkthroughs/allroads_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/balances.z5 walkthroughs/balances_verified_51.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/ballyhoo.z3 walkthroughs/ballyhoo_verified_200.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/castle_adventure.z8 walkthroughs/castle_adventure_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/cloak.z3 walkthroughs/cloak_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/coldiron.z8 walkthroughs/coldiron_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/cutthroats.z3 walkthroughs/cutthroats_verified_250.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/deadline.z3 walkthroughs/deadline_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/deephome.z5 walkthroughs/deephome_verified_300.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/detective.z5 walkthroughs/detective_verified_360.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/enchanter.z3 walkthroughs/enchanter_verified_400.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/hollywood.z3 walkthroughs/hollywood_verified_150.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/infidel.z3 walkthroughs/infidel_verified_400.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/lgop.z3 walkthroughs/lgop_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/lostpig.z8 walkthroughs/lostpig_verified_7.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/minizork.z3 walkthroughs/minizork_verified_350.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/moonmist.z3 walkthroughs/moonmist_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/pentari.z5 walkthroughs/pentari_verified_70.txt --seeds 4
python3 scripts/replay_solve.py games/zcode/photopia.z5 walkthroughs/photopia_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/planetfall.z3 walkthroughs/planetfall_verified_80.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/plundered.z3 walkthroughs/plundered_verified_25.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/reverb.z5 walkthroughs/reverb_verified_50.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/shade.z5 walkthroughs/shade_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/sorcerer.z3 walkthroughs/sorcerer_verified_400.txt --seeds 3
python3 scripts/replay_solve.py games/zcode/spellbreaker.z3 walkthroughs/spellbreaker_verified_600.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/starcross.z3 walkthroughs/starcross_verified_400.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/stationfall.z3 walkthroughs/stationfall_verified_80.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/suspect.z3 walkthroughs/suspect_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/suspended.z3 walkthroughs/suspended_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/suveh_nux.z5 walkthroughs/suveh_nux_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/acorncourt.z5 walkthroughs/acorncourt_verified_30.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/dreamhold.z8 walkthroughs/dreamhold_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/edifice.z5 walkthroughs/edifice_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/hhgg.z3 walkthroughs/hhgg_verified_400.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/jewel.z5 walkthroughs/jewel_verified_90.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/lurking.z3 walkthroughs/lurking_verified_100.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/witness.z3 walkthroughs/witness_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/theatre.z5 walkthroughs/theatre_verified_50.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/trinity.z4 walkthroughs/trinity_verified_100.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/wearing_the_claw.z5 walkthroughs/wearing_the_claw_verified_win.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/wishbringer.z3 walkthroughs/wishbringer_verified_100.txt --seeds 2
python3 scripts/replay_solve.py games/zcode/zork1.z3 walkthroughs/zork1_verified_350.txt --seeds 4
python3 scripts/replay_solve.py games/zcode/zork1-r5.z1 walkthroughs/zork1-r5_verified_350.txt --seeds 5
python3 scripts/replay_solve.py games/zcode/zork2.z3 walkthroughs/zork2_verified_400.txt --seeds 3
python3 scripts/replay_solve.py games/zcode/zork_iii.z3 walkthroughs/zork3_verified_7.txt --seeds 2

Test Suite Results

CZECH - Automated Compliance Testing

Version	Total Tests	Passed	Pass Rate
v3	368	368	100%
v4	386	386	100%
v5	425	425	100%
v8	425	425	100%
TOTAL	1,604	1,604	100%

Interactive Test Suites

Suite	Tests	Status	Notes
GNTests	6	PASS	All Z-Spec reference tests passing
TerpEtude	14	VERIFIED	Critical tests (arithmetic, headers) verified

Game Index

The repository indexes 100+ game download sources and carries a corpus of 155 story files; 55 games have exploration data in the repo (40 walkthrough dumps in games/results/ plus tracked solution runs), plus the verified complete solves of Zork I and Zork II above.

Sample Exploration & Replay Runs (Jan 2026)

Early solver output — room mapping and command coverage for compiler testing, not complete solves.

Game	Format	Walkthrough	Z2JS	Status
Photopia	z5	View JSON	Compiled	3 rooms, 201 commands (smart solver)
Lost Pig	z8	View JSON	Compiled	2 rooms, 123 commands
Anchorhead	z8	View JSON	Compiled	298 commands (human walkthrough replay, unverified)
Trinity	z4	View JSON	Compiled	244 commands (human walkthrough replay, unverified)
Curses	z5	View JSON	Compiled	1 room, 76 commands

Classic Infocom Games

Series	Games	Source
Zork	Zork I, II, III	Eblong Archive
Enchanter	Enchanter, Sorcerer, Spellbreaker	Eblong Archive
Science Fiction	Planetfall, Stationfall, AMFV, Trinity	Eblong Archive
Comedy	Hitchhiker's Guide, Leather Goddesses, Wishbringer	Eblong Archive

View Complete Game Index (100+ games)

Walkthroughs

ZWalker generates walkthroughs for Interactive Fiction games using AI assistance: 50 verified complete solves and 55 exploration runs, all in JSON format with room tracking and command history.

Highlights

9:05 (verified win) - JSON | Text
A Mind Forever Voyaging (verified win) - JSON | Text
Adventure (Colossal Cave) (verified 350/350) - JSON | Text
Adventureland (verified 100/100) - JSON | Text
All Quiet on the Library Front (verified win) - JSON | Text
All Roads (verified win) - JSON | Text
Balances (verified 51/51) - JSON | Text
Ballyhoo (verified 200/200) - JSON | Text
Castle Adventure! (verified win) - JSON | Text
Cloak of Darkness (verified win) - JSON | Text
Cold Iron (verified win) - JSON | Text
Cutthroats (verified 250/250) - JSON | Text
Deadline (verified win) - JSON | Text
Deephome (verified win) - JSON | Text
Detective (verified 360/360) - JSON | Text
Enchanter (verified 400/400) - JSON | Text
Hollywood Hijinx (verified 150/150) - JSON | Text
Infidel (verified 400/400) - JSON | Text
Leather Goddesses of Phobos (verified win) - JSON | Text
Lost Pig (verified 7/7) - JSON | Text
Mini-Zork I (verified 350/350) - JSON | Text
Moonmist (verified win) - JSON | Text
Pentari (verified 70/70) - JSON | Text
Photopia (verified win) - JSON | Text
Planetfall (verified 80/80) - JSON | Text
Plundered Hearts (verified 25/25) - JSON | Text
Reverberations (verified win) - JSON | Text
Shade (verified win) - JSON | Text
Sorcerer (verified 400/400) - JSON | Text
Spellbreaker (verified 600/600) - JSON | Text
Starcross (verified 400/400) - JSON | Text
Stationfall (verified 80/80) - JSON | Text
Suspect (verified win) - JSON | Text
Suspended (verified win) - JSON | Text
Suveh Nux (verified win) - JSON | Text
The Acorn Court (verified 30/30) - JSON | Text
The Dreamhold (verified win) - JSON | Text
The Edifice (verified win) - JSON | Text
The Hitchhiker's Guide to the Galaxy (verified 400/400) - JSON | Text
The Jewel of Knowledge (verified 90/90) - JSON | Text
The Lurking Horror (verified 100/100) - JSON | Text
The Witness (verified win) - JSON | Text
Theatre (verified 50/50) - JSON | Text
Trinity (verified 100/100) - JSON | Text
Wearing the Claw (verified win) - JSON | Text
Wishbringer (verified 100/100) - JSON | Text
Zork I (verified 350/350) - JSON | Text
Zork I (Release 5) (verified 350/350) - JSON | Text
Zork II (verified 400/400) - JSON | Text
Zork III (verified 7/7) - JSON | Text
All 105 walkthroughs... View the full index

Walkthrough Format

Verified solves (solutions/*_verified.json):

{
  "game": "games/zcode/zork1.z3",
  "walkthrough": "walkthroughs/zork1_verified_350.txt",
  "solver": "replay+seed",
  "rng_seed": 3,
  "score": 350,
  "max_score": 350,
  "won": true,
  "turns": 499,
  "num_commands": 431,
  "score_timeline": [
    { "step": 3, "command": "enter window", "score": 10 },
    ...
  ],
  "commands": [ ... ]
}

Exploration runs (games/results/*_walkthrough.json):

{
  "format_version": 1,
  "commands": [ "north", "take lamp", ... ],
  "rooms": { "64": { "name": "West of House", ... }, ... },
  "objects": { ... },
  "stats": { "rooms_found": 10, "commands_tried": 136, ... }
}

Installation & Usage

Install from GitHub

Not yet published to PyPI — install from source:

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

Usage Examples

Play a game

zwalker play games/zcode/zork1.z3

Explore with AI

zwalker explore games/zcode/photopia.z5 --ai --ai-backend anthropic

Generate walkthrough

python scripts/solve_game.py games/zcode/lostpig.z8 --real-ai

Verify a walkthrough deterministically

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

View on GitHub Documentation