bevy-template/docs/ai/bevy-debug-playbook.md

Bevy Debug Playbook

When build fails

Run:

cargo check
cargo clippy --workspace --all-targets --all-features -- -D warnings

Quote exact compiler error. Fix smallest cause first.

When game opens but nothing visible

Check:

1. camera spawned?
2. entity has render component?
3. transform in view?
4. asset path correct?
5. window created?
6. alpha / color not invisible?
7. system registered in right schedule/state?

When movement broken

Check:

• input system runs?
• query matches entity?
• transform or velocity changed?
• another system overwrites transform?
• delta time used correctly?

When UI broken

Check:

• UI entity spawned?
• text component updated?
• wrong state schedule?
• score resource/event exists?
• UI and gameplay mixed too tightly?

When architecture feels messy

Refactor by:

• extracting plugin
• moving singleton data into resource
• replacing direct calls with events
• introducing state for flow
• shrinking system queries

Review output format for AI

When AI reviews code, demand:

1. top 3 bugs
2. top 3 architecture risks
3. concrete patch plan
4. exact commands to verify