# Bevy Game Project Rules

## Mission

Build game features fast, but keep code clean enough to survive workshop iteration.
Target stack:

- Rust `1.95.0`
- Bevy `0.18.1`
- 2D first
- local assets in `assets/`

## Hard rules

- Use Bevy `0.18.1` APIs only.
- Prefer Bevy built-ins before adding third-party crates.
- Keep compile loop short. Small steps. Small diffs.
- No giant god-systems. Split logic into focused systems and plugins.
- Keep rendering, input, gameplay, UI, and debug concerns separate.
- New feature must include:
  - code change
  - short reason
  - how to run
  - what to test manually
- After code edits run, in order:
  1. `cargo fmt --all`
  2. `cargo check`
  3. `cargo clippy --workspace --all-targets --all-features -- -D warnings`
- If command fails, quote exact error.
- Do not migrate versions unless asked.
- Do not invent APIs. Check local files first, then docs index in `docs/ai/bevy-source-index.md`.

## Bevy design rules

- App setup in `main.rs` stays thin.
- Put features in plugins under `src/` when project grows.
- Use:
  - Components for entity data
  - Resources for singleton state
  - Events for loose coupling
  - States for game flow
- For temporary prototypes, prefer explicit code over macro cleverness.
- Keep startup systems idempotent where possible.
- Use `Name` on important entities in debug-heavy scenes.
- Asset paths relative to `assets/`.

## Architecture defaults

When adding real gameplay, move toward this split:

- `src/game/` core gameplay plugin
- `src/player/` player components + systems
- `src/ui/` UI plugin
- `src/state/` app/game states
- `src/debug/` debug helpers

## Review checklist

Before final answer:

- Is ECS layout sane?
- Are system names specific?
- Are queries minimal?
- Is state transition explicit?
- Is UI separate from gameplay?
- Are commands deferred only where needed?
- Is code Bevy-idiomatic for `0.18.1`?
- Did you list exact run/test commands?

## AI context files

Read when useful:

- `docs/ai/bevy-quick-reference.md`
- `docs/ai/bevy-project-patterns.md`
- `docs/ai/bevy-debug-playbook.md`
- `docs/ai/workshop-scope.md`
- `ai/context/project-context.md`