# 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).
