A Z-machine interpreter in Python, targeting v3 story files

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for scwilcox from gravatar.com scwilcox

Unverified details

These details have not been verified by PyPI
Meta
  • Requires: Python >=3.12
Report project as malware

Project description

yazm-py

Yet Another Z-Machine in Python — an interpreter for Infocom interactive fiction games.

Currently targets version 3 story files (.z3), such as the original Zork trilogy, Hitchhiker's Guide, and other classic Infocom titles.

Features

  • Fetch-decode-execute VM for Z-machine v3 bytecode
  • Full object system with tree traversal (parent/child/sibling)
  • ZSCII text decoding with alphabet tables, abbreviations, and Unicode extensions
  • Dictionary tokenization and input parsing
  • Terminal UI with ANSI status bar and optional object highlighting
  • Plain output mode (--plain) for clean piped/diffable output
  • Interactive debugger with commands like $tree, $dict, $room, $find
  • Pure Python 3.12+ with no runtime dependencies

Installation

Requires uv:

uv sync

Usage

# Run a game
yazm minizork.z3

# Disable object name highlighting
yazm --no-highlight lurkinghorror.z3

# Plain mode (no ANSI codes, suitable for piping)
yazm --plain czech.z3

# Run directly without installing
python -m yazm.main minizork.z3

Development

# Run all tests
pytest

# Run a single test file
pytest tests/test_zdata.py

# Lint and format
ruff check src/ tests/
ruff format src/ tests/

# Type check
uvx ty check

Architecture

The interpreter follows a fetch-decode-execute VM pattern:

File Role
zmachine.py Core ZMachine class: memory, object system, instruction loop, dictionary/tokenization
zinstruction.py Decodes variable-length bytecode (LONG, SHORT, VAR, EXT forms) into Instruction dataclasses
ops.py ~50 opcode handlers dispatched via DISPATCH_TABLE (control flow, arithmetic, objects, I/O, etc.)
zdata.py ZData(bytearray) with big-endian u8/u16 reads/writes and sequential Reader/Writer helpers
zheader.py Parses the 64-byte story file header (version, memory layout, flags)
frame.py Call stack Frame: resume address, local variables, evaluation stack, argument count
zscii.py ZSCII text encoding: 5-bit packed characters, 3 alphabet tables, abbreviation expansion
zui_std.py Terminal UI: ANSI status bar, styled output, plain mode
zdebug.py Interactive debugger ($tree, $dict, $room, $find, etc.)
enums.py Opcode IntEnum (~100 opcodes), operand type enums, opcode name mappings
options.py Options dataclass for runtime config (save dir, RNG seed, highlighting)

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for scwilcox from gravatar.com scwilcox

Unverified details

These details have not been verified by PyPI
Meta
  • Requires: Python >=3.12

Release history Release notifications | RSS feed

This version

0.2.0

0.1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

yazm_py-0.2.0.tar.gz (44.3 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

yazm_py-0.2.0-py3-none-any.whl (30.2 kB view details)

Uploaded Python 3

File details

Details for the file yazm_py-0.2.0.tar.gz.

File metadata

  • Download URL: yazm_py-0.2.0.tar.gz
  • Upload date:
  • Size: 44.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for yazm_py-0.2.0.tar.gz
Algorithm Hash digest
SHA256 c1fddfe99d3ecc76b1f8fe0ac82f354b31d6e467ab5de685701330c757cff1bd
MD5 4303fd9a709d0f0a47022be9e112a68c
BLAKE2b-256 cfcc496ccd26ee042fc0134ed4a2013ca80d653dc63fe84347d65c0f1185e1da

See more details on using hashes here.

Provenance

The following attestation bundles were made for yazm_py-0.2.0.tar.gz:

Publisher: publish.yml on swilcox/yazm-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file yazm_py-0.2.0-py3-none-any.whl.

File metadata

  • Download URL: yazm_py-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 30.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for yazm_py-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 011b173900bca4397b78b4a65874dfd34cb6523827fd9691784715cbecbe814d
MD5 189761569383a73c047850990f2ae1cb
BLAKE2b-256 40f94cbb7d5ec84c7081f96b0f5645706a772deabca3f12c511436f304f9e23b

See more details on using hashes here.

Provenance

The following attestation bundles were made for yazm_py-0.2.0-py3-none-any.whl:

Publisher: publish.yml on swilcox/yazm-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page