undercooked/README.md

Undercooked

A cooperative, in-browser, Overcooked-style kitchen game: 1–4 players share one kitchen over WebSockets, cook orders against the clock, and climb a campaign of levels that get progressively harder. Lobbies are anonymous — no accounts, no email, no password: you create a room, share the 5-character code, play.

Working title. "Overcooked" is a trademark of Ghost Town Games/Studio MDG; this project is an independent homage with its own art, code, and content.

Status

Phases 01 (runnable service scaffold) and 02 (level content, schema and validation) are complete; the next pending phase is 03_simulation_movement_and_interaction. What runs today:

• The service. The Python toolchain is locked (uv.lock), configuration is a single typed, validated Settings object (DEBUGPY support included), and uv run undercooked starts a FastAPI server that serves the client shell at /, the browser assets from app/static/, and GET /healthz — which answers {"status":"ok","version":"0.1.0","rooms":0} (rooms stays 0 until phase 05 owns a supervisor) — with the security headers (CSP default-src 'self') on every response.
• The content. The recipe book and the first two campaign levels live in levels/; sim/level.py parses them into typed models, sim/validation.py runs PLAN §8's named rules, and create_app loads + validates that bundle at startup and refuses to boot broken content — the named-rule report goes to stderr and undercooked exits 2 instead of serving a half-working kitchen. GET /api/levels, GET /api/levels/{id} and GET /api/config answer from it, and undercooked-levels gives authors the same gate from the command line (docs/LEVELS.md is the schema reference).
• The rules are tests, not promises. The no-external-asset rule is tests/unit/test_no_external_assets.py, "no level or recipe id in Python" is tests/unit/test_content_not_hardcoded.py, the documentation set is guarded by tests/unit/test_docs_index.py, and bash .agents/validate.sh is the gate the phase pipeline runs after every task.

What does not exist yet: the simulation (phases 03-04), rooms and the WebSocket protocol (05-06 — the lobby buttons answer "Not implemented until phase 05.") and the playable Canvas renderer (07). Execute phases with the phased-execution skill (auto-phase.sh); it always takes the lowest-numbered directory still in .agents/phases/todo/.

How to play

The intended loop, once the room flow ships: open the site, Create lobby, read out the 5-character code, everyone else Joins with it, the host picks a level, the room readies up, and the kitchen starts. Each cook has one movement control and one action button that picks up, uses and puts down whatever is in reach — one carried item at a time. Orders appear in the HUD with a shrinking deadline; assemble the dish and serve it at the window before the timer runs out. Levels escalate: more recipes, fewer stations, hostile floors. Nothing is saved between rounds and nothing identifies you: the browser keeps only a random per-tab token and the last code you typed, both in sessionStorage.

What actually works today is the shell of that: the page loads, normalises a typed code to five uppercase alphanumerics (codes themselves are Crockford base32, and only get issued once phase 05 runs the room supervisor), and answers "Not implemented until phase 05." Movement keys and touch controls are defined by the phase-07/08 client and documented in docs/CLIENT.md once that phase writes it.

Quickstart (development)

Requires uv, Python ≥ 3.12, and podman/docker for container builds. There is no database — all live game state is in memory.

uv sync --extra dev
uv run undercooked                 # http://127.0.0.1:8000 (shell page + /healthz)
uv run undercooked --host 0.0.0.0 --port 8000   # e.g. to reach it from a phone
uv run undercooked --reload        # dev reload
uv run undercooked --levels-dir levels          # point at another content dir
curl -fsS http://127.0.0.1:8000/api/levels      # the campaign cards the lobby will show
curl -fsS http://127.0.0.1:8000/api/config      # client-safe settings + protocol version

python -m undercooked is the same command (the container uses it). A flag always beats the environment, which beats the built-in default. There is no /docs or /openapi.json: FastAPI renders those pages from a public CDN, which this project forbids. The validation the server runs at startup (every level file loads, and no rule of PLAN §8 is broken) is a command too — undercooked-levels, see Authoring content below.

Debug the server with a real debugger attached (dev only - the listener binds 0.0.0.0, so never enable it on a public host):

DEBUGPY=1 uv run undercooked       # opens a debugpy listener on :5678, then serves as usual

Authoring content:

uv run undercooked-levels list                        # the campaign, in campaign order
uv run undercooked-levels show 01_first_kitchen --grid  # resolved level + reachability overlay
uv run undercooked-levels validate                    # the content gate; --json for scripts
uv run undercooked-levels new 03_riverboat            # scaffold a level from the recipe book
uv run undercooked-levels axes                        # escalation-axis table (phase 11's curve)

undercooked-levels is a thin shell over the loader and the PLAN §8 rules create_app runs at startup, so a green validate is a server that boots. It finds content through the settings (--dir > UNDERCOOKED_LEVELS_DIR > levels, plus --recipes > UNDERCOOKED_RECIPES_PATH > <dir>/recipes.yaml) and never from the current directory, so it works from any path. Exit codes: 0 ok, 1 a level breaks a rule, 2 nothing usable to work with (load failure, unknown id, refused overwrite, usage error). The schema, every field, the overlay trick and a "which rule did I just hit" table live in docs/LEVELS.md; tests/unit/test_content_not_hardcoded.py is what keeps levels and recipes out of the Python.

Run the checks:

uv run ruff check .
uv run pyright
uv run pytest                              # everything, coverage floor included
uv run pytest -m "not e2e"                 # the quick loop: no browser launches
uv run playwright install chromium         # once, before the first e2e run
uv run pytest -m e2e                       # browser suites only
bash .agents/validate.sh                   # the pipeline gate: full suite + ruff + pyright

pytest with no -m runs the browser suites too, so chromium has to be installed for the pipeline gate. Those suites start the app themselves on a free loopback port (live_server in tests/conftest.py) — nothing needs to be running first, and no test ever listens on a routable interface.

bash .agents/validate.sh is the gate a phase task must pass before it moves to .agents/phases/complete/. It stops at the first failure, in this order: ruff check ., pyright, undercooked-levels validate (unconditional: the same loader and PLAN §8 rules create_app runs at startup, so a campaign that cannot validate cannot commit), the full pytest suite with the 90 % coverage floor, then repo-hygiene checks (nothing tracked that .gitignore excludes, no log drops or key material committed). Run it from the repo root or from .agents/.

Container

podman build -t undercooked -f Containerfile .
podman run --rm -p 8000:8000 undercooked
# or
podman compose up -d

Configuration

All settings come from the environment, parsed once into undercooked.config.Settings — the only module that reads the environment, so nothing else in the codebase touches os.environ. Precedence: undercooked CLI flags, then exported environment variables, then a local .env (found from the current directory upwards; never commit it), then the built-in defaults. A blank value counts as unset. Invalid values (UNDERCOOKED_TICK_HZ=99) raise ConfigError at startup instead of half-configuring the server, and unusable content is refused the same way — an unreadable UNDERCOOKED_LEVELS_DIR or a level that breaks a PLAN §8 rule prints the named-rule report and exits 2 (under --reload the reload child reports and restarts instead; docs/LEVELS.md). .env.example and the table below list every variable with its default; tests keep both in sync with config.py.

Variable	Default	Meaning
UNDERCOOKED_HOST	127.0.0.1	Bind address
UNDERCOOKED_PORT	8000	Bind port
UNDERCOOKED_TICK_HZ	20	Server simulation rate (5-60)
UNDERCOOKED_SNAPSHOT_HZ	20	Snapshot broadcast rate to players (<= tick rate)
UNDERCOOKED_MAX_PLAYERS	4	Players per room (1-4)
UNDERCOOKED_MAX_ROOMS	200	Concurrent rooms before new rooms are refused
UNDERCOOKED_LEVELS_DIR	levels	Directory of level YAML files (~ is expanded)
UNDERCOOKED_RECIPES_PATH	(derived)	Recipe book file; empty = recipes.yaml inside UNDERCOOKED_LEVELS_DIR (here: levels/recipes.yaml)
UNDERCOOKED_STATIC_DIR	(derived)	Directory served at /static; empty = app/static/ beside the source (containers set it)
UNDERCOOKED_LOBBY_IDLE_TIMEOUT_S	900	Close empty/idle lobbies
UNDERCOOKED_GUEST_IDLE_TIMEOUT_S	45	Drop a disconnected player's seat after this
UNDERCOOKED_MAX_MESSAGE_BYTES	4096	Hard cap on inbound WS frame size
UNDERCOOKED_MAX_INPUTS_PER_S	40	Per-connection inbound message rate limit
UNDERCOOKED_SIM_LATENCY_MS	0	Injected server-side downlink latency (netcode tests)
UNDERCOOKED_ALLOWED_ORIGINS	(empty)	Comma-separated Origins accepted on the WebSocket handshake; empty = same-host only
DEBUGPY	0	1 = open a debugpy listener on DEBUGPY_PORT at startup
DEBUGPY_PORT	5678	debugpy listen port

Layout

src/undercooked/        server: FastAPI app, rooms, WebSocket protocol, simulation
src/undercooked/__main__.py  the `undercooked` command (CLI > env > default)
src/undercooked/config.py  typed env settings (the only `os.environ` reader)
src/undercooked/debug.py   DEBUGPY-gated debugger bootstrap
src/undercooked/sim/       pure simulation kernel: entities (`model`), grid geometry
                           (`grid`), content schema + loader (`recipe`, `level`,
                           `content` — the YAML contract is docs/LEVELS.md), the
                           level validator (`validation` — PLAN §8 named rules;
                           rule table in docs/LEVELS.md), and the
                           A5 purity guard (`purity`, test-enforced). There is no
                           `step()` yet: the tick arrives with phase 03
src/undercooked/tools/levels.py   the `undercooked-levels` author CLI — validate, list,
                        show [--grid], new, axes; same loader, same rules, no
                        hard-coded content list (docs/LEVELS.md "Authoring workflow")
src/undercooked/server/app.py     app factory, `/healthz`, `/`, `/static`, mounts the content API
src/undercooked/server/routes_content.py  `/api/levels`, `/api/levels/{id}`, `/api/config`,
                        plus the startup gate: broken content refuses startup
src/undercooked/server/headers.py the security-header middleware
.env.example            every configuration variable, with its default
levels/                 data-driven content (YAML): the recipe book (A8) and the
                        first two campaign levels (01_first_kitchen, 02_double_shift)
app/static/             browser client: the ES-module shell today; Canvas 2D renderer
                        and this repo's SVG art arrive with phase 07
tests/                  unit/, integration/, e2e/ (one Playwright suite per story) and
                        sim/ (the pure kernel: grid, entities, purity guard, validation);
                        fixtures/levels/ is the content dir tests see (a recipe book and no
                        levels; `_bad/` holds the deliberately-broken campaign the `_`
                        discovery rule ignores); conftest.py
docs/                   DESIGN.md, LEVELS.md (the level & recipe YAML contract),
                        TESTING.md (how this project is verified), DEPLOYMENT.md;
                        PROTOCOL / SIMULATION / CLIENT land with their own phases
                        (the index is PLAN.md §13)
.agents/                PLAN.md, user_stories/, phases/, validate.sh — the phased-execution plan

No external CDNs. Every byte of JS, CSS, font, and image is served by this app from app/static/. tests/unit/test_no_external_assets.py enforces it, and the e2e suite fails if loading the page ever issues a request off-origin.

Contributing

Read AGENTS.md first: it points at .agents/PLAN.md (LOCKED decisions) and the phase protocol. Code changes land by executing phase task files, not by editing ad hoc.