58 lines
2.5 KiB
Markdown
58 lines
2.5 KiB
Markdown
# CLAUDE.md
|
||
|
||
Guidance for working in this repo. **`SPEC.md` is the source of truth for engine
|
||
behavior and the level format** — read it before changing mechanics, and update
|
||
it (and `README.md`) when behavior changes. This file only covers workflow and
|
||
conventions not found there.
|
||
|
||
## Commands
|
||
|
||
The working virtualenv is `.venv` (Python 3.13). Prefix commands with
|
||
`.venv/bin/` or activate it first.
|
||
|
||
```bash
|
||
.venv/bin/python main.py # play every level in ./levels
|
||
.venv/bin/python main.py levels/foo.yaml # play specific level(s), in order
|
||
.venv/bin/python main.py --debug # force the debug view (see SPEC §14)
|
||
.venv/bin/python -m pytest # run the test suite
|
||
.venv/bin/black main.py game tests tools # format (do this before committing)
|
||
```
|
||
|
||
The test suite runs headless — `conftest.py` sets the SDL dummy video/audio
|
||
drivers, so no window opens and nothing needs a display.
|
||
|
||
## Conventions
|
||
|
||
- **Formatting: `black`** (default 88-col line length, no config file). Run it on
|
||
any Python you touch. It's in `requirements-dev.txt`.
|
||
- The game must stay **fully playable with zero art assets**: every sprite falls
|
||
back to a labeled colored rectangle (see `game/assets.py`). Don't add a hard
|
||
dependency on any PNG.
|
||
- **Physics/collision live in true coordinates.** `Level.render_offset` is a
|
||
draw-only translation for the debug overscan — never fold it into gameplay
|
||
math.
|
||
- All tunables (physics, timing, colors, the placeholder table) belong in
|
||
`game/settings.py`, not scattered as literals.
|
||
|
||
## Adding a trap type
|
||
|
||
Subclass `Trap` in `game/traps.py`, implement only the hooks it needs
|
||
(`solid_rects`, `hazard_rects`, `carriers`, `update`, `draw`, `reset`, …), and
|
||
register the class in the `TRAP_TYPES` factory map. Nothing else in the engine
|
||
needs to change. See SPEC §11–13 for the hook contract and the trap catalog.
|
||
|
||
## Tests
|
||
|
||
`tests/` mirrors the behavior described in `SPEC.md` (physics, every trap and
|
||
trigger, mounting, crush/shove, game-flow states). When you change behavior, add
|
||
or update the matching test — several existing tests are regression guards for
|
||
specific bugs (corner-warp, fits-under-no-crush, ride-into-wall-no-crush), so
|
||
read the test's comment before altering its expectations.
|
||
|
||
## Module map
|
||
|
||
See SPEC §15 for the full layout. In short: `game/game.py` (loop/states/HUD),
|
||
`game/level.py` (YAML → geometry + traps), `game/player.py` (physics &
|
||
collision), `game/traps.py` (triggers + all trap types), `game/settings.py`
|
||
(tunables), `game/assets.py` (sprites + placeholders).
|