Initial commit: ZIL source + Python game engine

Original ZIL source code for The Hitchhiker's Guide to the Galaxy (Infocom, 1984) plus a native Python text adventure engine with the Earth opening sequence playable (Bedroom → Front Porch → Front of House → Country Lane → Pub). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-03 20:46:54 +02:00
commit f55286db8e
49 changed files with 17531 additions and 0 deletions
@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+This is the original source code for **The Hitchhiker's Guide to the Galaxy** (1984), an interactive fiction game by Infocom (designed by Douglas Adams and Steve Meretzky). The code is written in **ZIL** (Zork Implementation Language), Infocom's proprietary Lisp-like language that compiles to Z-machine bytecode.
+
+Release 60 (October 2, 1986) — the final release version. The compiled game runs as a `.z5` Z-machine story file (a copy is at `docs/The-Hitchhikers-Guide-to-the-Galaxy_DOS_EN_Z5-format/hitchhik.z5`).
+
+## Building
+
+ZIL source requires the **ZILF** compiler (open-source ZIL-to-Z-machine compiler) or Infocom's original toolchain. There is no build system or Makefile in this repo. To compile with ZILF:
+
+```
+zilf s4.zil
+zapf s4.zap
+```
+
+This produces a `.z5` story file playable in any Z-machine interpreter (Frotz, Lectrote, etc.).
+
+## Architecture
+
+**Entry point:** `s4.zil` — includes all other source files via `<INSERT-FILE>`.
+
+**Source files by function:**
+
+| File | Purpose |
+|------|---------|
+| `s4.zil` | Main file; game title, file includes, property defaults |
+| `globals.zil` | Global variables, directions, meta-objects (ROOMS, IT, NOT-HERE-OBJECT, LOCAL-GLOBALS) |
+| `parser.zil` | Text parser — tokenizing input, resolving nouns/adjectives, disambiguation |
+| `syntax.zil` | Vocabulary: BUZZ words, SYNONYMs, direction aliases, verb SYNTAX definitions |
+| `verbs.zil` | Verb handler routines (`V-TAKE`, `V-DROP`, `V-EXAMINE`, etc.) and game commands |
+| `misc.zil` | Utility routines, interrupt/clock system, macros |
+| `earth.zil` | Earth locations — Arthur's bedroom, front of house, pub, country lane |
+| `vogon.zil` | Vogon ship — hold, guard's room, airlock, poetry appreciation |
+| `heart.zil` | Heart of Gold — bridge, engine room, corridors, Infinite Improbability Drive |
+| `unearth.zil` | Off-Earth locations — Traal (Ravenous Bugblatter Beast), Damogran, Magrathea |
+
+**Assembly files (`.xzap`):** `s4.xzap` is the assembly include order; `s4freq.xzap` defines frequently-used strings (Huffman-compressed). `s4.errors` is the assembler output log.
+
+## ZIL Conventions
+
+- **`<OBJECT ...>`** defines game objects with properties (DESC, SYNONYM, FLAGS, ACTION, etc.)
+- **`<ROOM ...>`** defines locations (rooms are objects with directional exits)
+- **`<ROUTINE ...>`** defines functions; `-F` suffix indicates an action handler (e.g., `HOME-F`)
+- **`<GLOBAL ...>`** defines global variables; parser globals are prefixed `P-`
+- **Flags on objects** control behavior: `TAKEBIT` (takeable), `OPENBIT` (open), `ONBIT` (lit/on), `TOUCHBIT` (seen), etc.
+- **`PRSA` / `PRSO` / `PRSI`** — parsed action verb, direct object, indirect object
+- **`<TELL ...>`** outputs text to the player; `CR` = carriage return
+- Comments use `;"..."` syntax; `;<...>` comments out an entire form
+
+## docs/
+
+Contains the original MS-DOS executable, Z5 story file, game manuals (PDF), hint book, game maps, and photos of physical game "feelies" (props included with the boxed game).