# The Hitchhiker's Guide to the Galaxy

A Python text adventure engine for the classic 1984 Infocom interactive fiction game, built from the original ZIL source code. The long-term goal is an accessible version for blind players via TTS/STT.

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)

## Install & Run

```bash
# Clone the repo
git clone https://gitea.smashconsult.be/seppedl/h2g2.git
cd h2g2

# Install dependencies and run
uv run h2g2
```

Or install it into an environment:

```bash
uv pip install -e .
h2g2
```

You can also run it directly as a module without installing:

```bash
uv run python -m h2g2.main
```

## Audio features

### Text-to-speech (TTS)

The game can read all output aloud using [Piper](https://github.com/rhasspy/piper), a fast offline TTS engine. A British English voice model is included in the repo.

```bash
uv run h2g2 --audio
```

Use `--voice /path/to/model.onnx` to use a different Piper voice model.

### Speech-to-text (STT)

You can play the game hands-free using voice input powered by [Vosk](https://alphacephei.com/vosk/), a lightweight offline speech recognition engine. The Vosk model (~50 MB) downloads automatically on first use.

```bash
uv run h2g2 --stt
```

Use `--stt-model /path/to/vosk-model/` to use a different Vosk model.

Combine both flags for full voice interaction:

```bash
uv run h2g2 --audio --stt
```

### Audio prerequisites

STT requires PortAudio for microphone access. Install the system library for your platform before running with `--stt`:

**Linux (Debian/Ubuntu):**

```bash
sudo apt install libportaudio2 portaudio19-dev
```

**macOS:**

```bash
brew install portaudio
```

**Windows:**

PyAudio ships with PortAudio bundled on Windows, so no extra system package is needed. If you run into build issues, install a prebuilt wheel:

```bash
uv pip install pipwin
pipwin install pyaudio
```

After installing the system dependency, sync the Python packages:

```bash
uv sync
```

## What's playable

The Earth opening sequence: wake up in your bedroom, find your gown and aspirin, make your way downstairs, head to the pub, and meet Ford Prefect.

## Project structure

```text
h2g2/
    engine/          # Core game engine (parser, object model, game loop)
    content/         # Game content (rooms, objects, puzzles)
    main.py          # Entry point
*.zil                # Original ZIL source code (Infocom, 1984)
docs/                # Original game manuals, maps, and story file (.z5)
```

---

## Additional information Infocom Games

- Library of all Infocom games https://eblong.com/infocom/
- Open source Z-file game engine: https://gitlab.com/DavidGriffith/frotz