zorkdemo

🌏 Open in the Cloud

Click any of the buttons below to start a new development environment to demo or contribute to the codebase without having to install anything on your machine:

Runs on Linux, Windows or Mac.

A (much simplified) port of a famous adventure game to help teach my daughter how to program in Python.

Two easy ways to launch the console project:

1. Click on the Open with GitHub Codespaces badge above to launch the project in a browser or on your desktop inside Visual Studio Code, then type uv run python zorkdemo.py in the terminal window.
2. Download one of the binary releases and run the file on your system.

NOTE: the MacOS version does not have code signing built into it yet (that's next on my list!). To run it, you will need to set the binary as executable with chmod 755 or similar, and after trying to run it once, go through System Preferences: Security and Privacy: General and "Allow the program to run anyway".

Monorepo Layout (Phase 0)

• adventure/: shared game engine logic
• backend/: FastAPI service scaffold (target Railway deploy)
• frontend/: TypeScript frontend scaffold (target GitHub Pages deploy)
• web/: current legacy Hug web app
• docs/architecture.md: migration architecture notes

Local Development Quickstart

Install tooling and Python dependencies:

• Install Python 3.10+
• Install uv
• Run uv sync --all-groups from repo root

Standardized environment variables:

• Backend: DATABASE_URL, CORS_ALLOW_ORIGINS (see backend/.env.example)
• Frontend: VITE_API_BASE_URL (see frontend/.env.example)

Run Backend (Current Legacy App)

uv run hug -m web.app

Navigate to http://localhost:8000/

Run Frontend (Phase 0 Placeholder)

cd frontend
python -m http.server 5173

Navigate to http://localhost:5173/

Legacy Hug Notes

The easiest option is to create a .env file in the root of the project with the contents:

SECRET_KEY="<some random key>"

Alternatively, you can manually set your environment variables for your terminal session, but you'll have to remember to do that for every new session.

export SECRET_KEY="<put something random here>"

Running the legacy development web server

In the root of the project, run:

uv run hug -m web.app

Navigate in your browser to:

http://localhost:8000/

Have fun!

If you want to restart delete your sid cookie from your browser and refresh the page.

NOTE: future versions should provide a link to an endpoint to achieve something like this.

Or, you could delete your session record from the Sqlite database.

Web TODO Items

• make endsession actually work
• provide link to endsession
• alignment between input and output for seamless experience
• figure out how to handle quit/exit
• wsgi file for hooking this up to a real web server and hosting