114 lines
2.6 KiB
Markdown
114 lines
2.6 KiB
Markdown
# 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
|