battery/CLAUDE.md

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.

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