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% compliance with all major Z-machine test suites and can automatically generate walkthroughs for Interactive Fiction games.

100% CZECH Compliance

1,604 Tests Passing

43 Games Tested

4 Z-Machine Versions

Features

Complete Z-machine interpreter (versions 3, 4, 5, 8)
AI-powered game solving with Claude/OpenAI
Automatic walkthrough generation
Game exploration and mapping
100% test suite compliance (CZECH, GNTests, TerpEtude)
z2js compiler validation

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

ZWalker has been tested with 100+ Z-machine games. Below are the top 50 games from IFDB rankings and classic Infocom titles.

Top 5 AI Walkthrough Tests

Game	Format	Walkthrough	Z2JS	Status
Photopia	z5	View JSON	Compiled	2 rooms, 4 commands
Lost Pig	z8	View JSON	Compiled	2 rooms, 123 commands
Anchorhead	z8	View JSON	Compiled	1 room, 174 commands (stuck)
Trinity	z4	View JSON	Compiled	Menu-based (limited)
Curses	z5	View JSON	Compiled	Complex puzzle (limited)

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 can automatically generate walkthroughs for Interactive Fiction games using AI assistance. All walkthroughs are in JSON format with room tracking and command history.

Available Walkthroughs (43 games)

Walkthroughs have been generated for the following games:

Zork I - JSON
Adventure (Colossal Cave) - JSON
Photopia - JSON
Lost Pig - JSON
Shade - JSON
Aisle - JSON
Detective - JSON
Blue Chairs - JSON
And 35 more... View all

Walkthrough Format

{
  "game": "photopia.z5",
  "total_rooms": 2,
  "total_commands": 4,
  "commands": [
    "look",
    "inventory",
    "examine room",
    "wait"
  ],
  "rooms_visited": [
    "Alley",
    "Corner"
  ]
}

Installation & Usage

Install from PyPI

pip install zwalker

Install from GitHub

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

View on GitHub PyPI Package Documentation