Home › Pygame › Pygame (pygame-ce) AGENTS.md

Pygame (pygame-ce) AGENTS.md

AGENTS.md for 2D games in Python with pygame-ce 2.5+: game loop, scenes, sprites, assets, and testable logic.

AGENTS.mdPygame

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

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