# 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).