https://github.com/bcorfman/zorkdemo
Can you code a Zork adventure game demo in Python and have fun too? Why yes.
https://github.com/bcorfman/zorkdemo
adventure-game-engine devops fastapi github-actions postgres python react rich typescript uv vite webapp zork
Last synced: 3 days ago
JSON representation
Can you code a Zork adventure game demo in Python and have fun too? Why yes.
- Host: GitHub
- URL: https://github.com/bcorfman/zorkdemo
- Owner: bcorfman
- License: mit
- Created: 2021-02-11T17:37:28.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2026-06-01T23:52:53.000Z (19 days ago)
- Last Synced: 2026-06-02T01:20:57.032Z (19 days ago)
- Topics: adventure-game-engine, devops, fastapi, github-actions, postgres, python, react, rich, typescript, uv, vite, webapp, zork
- Language: Python
- Homepage: https://bcorfman.github.io/zorkdemo/
- Size: 1.62 MB
- Stars: 3
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# zorkdemo
[](https://github.com/bcorfman/zorkdemo/actions/workflows/build-test.yml)
#### 🌏 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:
[](https://vscode.dev/github/bcorfman/zorkdemo)
[](https://glitch.com/edit/#!/import/github/bcorfman/zorkdemo)
[](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=338102781&machine=standardLinux32gb&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=EastUs)
[](https://stackblitz.com/github/bcorfman/zorkdemo)
[](https://codesandbox.io/s/github/bcorfman/zorkdemo)
[](https://replit.com/github/bcorfman/zorkdemo)
[](https://app.codeanywhere.com/#https://github.com/bcorfman/zorkdemo)
[](https://gitpod.io/#https://github.com/bcorfman/zorkdemo)
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 (SQLAlchemy + Alembic, target Railway deploy)
- `frontend/`: TypeScript frontend app (target GitHub Pages deploy)
- `docs/architecture.md`: migration architecture notes
## Local Development Quickstart
Install tooling and Python dependencies:
- Install [Python](https://www.python.org) 3.10+
- Install [uv](https://docs.astral.sh/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`)
## Makefile Workflow
Key targets:
- `make setup`: install project tooling (`uv`, and Node/npm if missing)
- `make install`: install runtime dependencies only
- `make devinstall`: install full dev/test dependencies
- `make lint`: run `ruff check`
- `make format`: run `ruff format`
- `make test`: run Python + frontend tests
- `make run`: ensure local backend is up, launch frontend dev server, and open browser (Linux/macOS/Windows)
`make run` uses `uv run python -m backend.app.dev_runner` for cross-platform process startup, health checks, and browser opening.
Optional `make run` variables:
- `BACKEND_HOST`, `BACKEND_PORT`, `FRONTEND_HOST`, `FRONTEND_PORT`
- `DATABASE_URL`, `CORS_ALLOW_ORIGINS`
- `BACKEND_LOG` (default: `.tmp/zorkdemo-backend.log`)
## Deployment (Phase 4)
### Frontend (GitHub Pages)
- Workflow: [.github/workflows/deploy-frontend-pages.yml](/home/bcorfman/dev/zorkdemo/.github/workflows/deploy-frontend-pages.yml)
- Set repository variable `VITE_API_BASE_URL` to your Railway backend URL (example: `https://.up.railway.app`).
- Push to `main` to build and publish `frontend/dist`.
### Backend (Railway)
- Deployment config: [railway.toml](/home/bcorfman/dev/zorkdemo/railway.toml)
- Health endpoint used by deployment config: `/api/v1/health`
- Required Railway env vars:
- `DATABASE_URL` (from Railway Postgres plugin)
- `CORS_ALLOW_ORIGINS` (must include your GitHub Pages URL)
- Optional GitHub Actions deploy workflow: [.github/workflows/deploy-backend-railway.yml](/home/bcorfman/dev/zorkdemo/.github/workflows/deploy-backend-railway.yml)
- Requires secret `RAILWAY_TOKEN`
- Requires repo variable `RAILWAY_SERVICE`
- Optional repo variable `BACKEND_HEALTHCHECK_URL`
## Extending The Game
For adding new locations, items, and commands, see:
- [docs/extending-game.md](/home/bcorfman/dev/zorkdemo/docs/extending-game.md)
### Run Backend (FastAPI v1 API)
```sh
uv run alembic -c backend/alembic.ini upgrade head
uv run uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --reload
```
API endpoints:
- `GET /api/v1/health`
- `POST /api/v1/session`
- `POST /api/v1/command`
- `POST /api/v1/session/reset`
### Run Frontend (TypeScript App)
```sh
cd frontend
npm install
npm run dev
```
Navigate to [http://localhost:5173/](http://localhost:5173/)