# AGENTS.md: Pygame game

## Commands
`uv run python -m game` · `uv run pytest -q` · `uv run ruff check .`

## Structure
- `game/main.py` owns the loop; `game/scenes/` has one class per scene (`Menu`, `Level`, `GameOver`) with `handle_event`, `update(dt)`, `draw(surface)`.
- Pure game logic (collision rules, scoring, AI) lives in modules that don't import pygame so it can be unit tested.
- Assets in `assets/`, loaded once through an `assets.py` cache with paths built from `Path(__file__)`. Call `.convert()` / `.convert_alpha()` after loading images.

## Loop rules
- `dt = clock.tick(60) / 1000` and multiply all movement by `dt`.
- Handle `pygame.QUIT` and `Esc`; call `pygame.quit()` on exit.
- Use `pygame.sprite.Group` and `Rect`/`FRect` collisions (`colliderect`, `spritecollide`); masks only when pixel-perfect is required.
- Draw order: clear, world, sprites, UI, then `pygame.display.flip()` once per frame.
- No blocking calls (sleep, input(), network) inside the loop.
- Fonts and sounds created once, not every frame.
- Support window resize or scaling via a fixed logical surface scaled to the window.

## Notes
- This project uses `pygame-ce` (`import pygame` still works); don't install classic `pygame` alongside it.
- Tests run headless: set `SDL_VIDEODRIVER=dummy` in `conftest.py`.