ZorkAI

An AI-powered take on the classic Infocom text adventure Zork I — the original game runs on a real Z-machine interpreter, with an AI layer on top that turns room descriptions into generated scene art and lets you interact by drawing/painting on the scene, not just typing commands.

Repository layout

zorkai/
├── visual-zork/              # Main application (FastAPI backend + JS frontend)
├── zilf/                     # ZIL compiler toolchain (vendored, not tracked here)
├── zork1/                    # Zork I source + zork1.zip game file (vendored, not tracked here)
├── comfy_single.json         # Example ComfyUI workflow export
├── THIRD_PARTY_NOTICES.md    # Attribution for incorporated third-party material
└── config.env                # Local secrets (Gemini API key) — never committed

The visual-zork/ directory is the actual project: a FastAPI backend that drives a Z-machine interpreter for zork1.zip, generates scene images via ComfyUI, and uses Gemini as a VLM to interpret drawn/painted input. See visual-zork/README.md for full setup, architecture, and API details.

zilf/ and zork1/ are vendored clones of upstream repositories, not part of this project's own history — see Getting the dependencies below.

Quick start

1. Clone this repo and fetch the dependencies (below).
2. Follow visual-zork/README.md to install Python dependencies, set up ComfyUI, and configure your Gemini API key.
3. Run the backend:

   cd visual-zork/backend
   python main.py

4. Open http://localhost:8000.

Getting the dependencies

zilf/ and zork1/ are excluded from this repo (they're large/independent upstream projects with their own git history). Clone them into the repo root:

git clone https://github.com/taradinoc/zilf.git
git clone https://github.com/historicalsource/zork1.git

visual-zork expects the compiled game file at zork1/zork1.zip, which is already present in the historicalsource/zork1 repo.

Configuration

Create a config.env (or export environment variables, see visual-zork/README.md) with your Gemini API key:

GEMINI_API_KEY=your_api_key_here

This file is gitignored — never commit API keys.

License

ZorkAI's own code is MIT licensed — see LICENSE.

This repository also incorporates third-party material, and a full set of notices is in THIRD_PARTY_NOTICES.md. In summary:

Component	License
visual-zork/	MIT — this project's own code
Zork I game content (room_data.json, derived from 1dungeon.zil)	MIT, Copyright (c) 2025 Microsoft
zork1/ (cloned separately)	MIT, Copyright (c) 2025 Microsoft
zilf/ (cloned separately)	GPLv3, plus the separate ZILF Library and Runtime Library licenses — Tara McGrew
zwalker (pip dependency)	GPLv3-or-later

Microsoft, with Xbox and Activision, released the Zork I source code under the MIT License on 20 November 2025. visual-zork/backend/zmachine/room_data.json contains room descriptions and exit data extracted verbatim from that source by visual-zork/tools/extract_rooms.py, and is redistributed here under those terms.

ZORK is a trademark of Microsoft / Activision Publishing, Inc. This project is an independent, unofficial work, not affiliated with, sponsored by, or endorsed by Microsoft, Xbox, Activision, or Infocom.