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) |
1 maintainer
Metadata
1 maintainer
Release files for yazm-py 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| yazm_py-0.2.0.tar.gz | 44.3 kB | With provenance | Details for yazm_py-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| yazm_py-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for yazm_py-0.2.0-py3-none-any.whl |
Total release size: 74.5 kB
Release files / yazm_py-0.2.0.tar.gz
| Download URL | yazm_py-0.2.0.tar.gz |
|---|---|
| Size | 44.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c1fddfe99d3ecc76b1f8fe0ac82f354b31d6e467ab5de685701330c757cff1bd
|
|
BLAKE2b-256 checksum How to use checksums |
cfcc496ccd26ee042fc0134ed4a2013ca80d653dc63fe84347d65c0f1185e1da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 14, 2026.
Transparency logRelease files / yazm_py-0.2.0-py3-none-any.whl
| Download URL | yazm_py-0.2.0-py3-none-any.whl |
|---|---|
| Size | 30.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
011b173900bca4397b78b4a65874dfd34cb6523827fd9691784715cbecbe814d
|
|
BLAKE2b-256 checksum How to use checksums |
40f94cbb7d5ec84c7081f96b0f5645706a772deabca3f12c511436f304f9e23b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 14, 2026.
Transparency logSecurity for yazm-py 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for yazm_py-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
