Imported from ZhangStudyLife/py_work (
3games_python/AGENTS.md). Install upstream withnpx skills add ZhangStudyLife/py_work --skill 3games_python. Copyright stays with the author.
Repository Guidelines
Project Structure & Module Organization
This repository is a Python mini-game collection with procedural rendering and no external asset directory.
main.pystarts Pygame, opens the window, and loads the menu scene.core/contains shared engine code: scene management, rendering helpers, input, particles, transitions, and storage.scenes/contains game-specific modules. Current games live inscenes/snake/,scenes/puzzle/, andscenes/tank/;scenes/menu.pyconnects them.utils/contains small shared helpers such as colors and math utilities.build.shandbuild.batpackage the app with PyInstaller.
Keep new game logic inside its scene package. Put reusable framework behavior in core/ only when at least two games need it.
Build, Test, and Development Commands
pip install -r requirements.txtinstalls runtime and packaging dependencies.python main.pyruns the game locally../build.shbuilds a one-file executable on Unix-like shells.build.batbuildsdist\MiniGamesCollection.exeon Windows.pyinstaller --clean --noconsole --onefile --name MiniGamesCollection main.pyis the underlying packaging command.
Run from the repository root so imports such as core.scene and scenes.menu resolve correctly.
Coding Style & Naming Conventions
Use standard Python style with 4-space indentation. Prefer clear module-level constants for fixed dimensions, colors, speeds, and tuning values. Name files and modules in snake_case.py; classes in PascalCase; functions, methods, and variables in snake_case.
Keep code simple and local to the feature being changed. Avoid speculative abstractions, broad rewrites, or unrelated formatting churn. Rendering should remain procedural unless an asset pipeline is intentionally introduced.
Testing Guidelines
No automated test suite is currently present. For now, verify changes manually with python main.py and exercise the affected game from the menu. For logic-heavy changes, especially AI, collision, scoring, or board updates, add focused pytest tests under a future tests/ directory using names like test_snake_score.py.
Before packaging, run the app locally once and confirm the relevant scene starts, updates, and exits cleanly.
Commit & Pull Request Guidelines
Recent history uses short descriptions and occasional Conventional Commit prefixes, for example feat: .... Keep commits concise and action-oriented, such as fix: correct tank collision or refactor: simplify puzzle rendering.
Pull requests should include a brief summary, affected game or module, manual test steps, and screenshots or recordings for visible UI/gameplay changes. Link related issues when available and call out any packaging impact.
