bevy-template/AGENTS.md

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