init repo

docs/ai/bevy-quick-reference.md

@@ -0,0 +1,112 @@
+# Bevy Quick Reference
+
+## Core mental model
+
+Bevy app = plugins + schedules + systems + ECS data.
+
+- **Entity**: ID
+- **Component**: data attached to entity
+- **System**: function operating on ECS data
+- **Resource**: singleton global-ish state
+- **Event**: decoupled message
+- **State**: app/game phase control
+- **Plugin**: feature boundary
+
+## Default 2D startup
+
+Typical minimum:
+
+- add `DefaultPlugins`
+- spawn `Camera2d`
+- later: sprites, transforms, input systems
+
+## Good first feature order
+
+1. camera
+2. player entity
+3. movement
+4. bounds / collision
+5. score / HUD
+6. game state
+7. win / lose loop
+8. juice: audio, particles, animation
+
+## ECS rules
+
+Good:
+
+- data-only components
+- small systems
+- clear queries
+- events for cross-feature signaling
+
+Bad:
+
+- single mega resource for all state
+- one system doing input + movement + combat + UI
+- hidden state mutation in many places
+- coupling features through direct queries everywhere
+
+## Naming
+
+Prefer:
+
+- `Player`
+- `Velocity`
+- `Health`
+- `Score`
+- `GameState`
+- `spawn_player`
+- `move_player`
+- `update_score_ui`
+
+Avoid vague names:
+
+- `Data`
+- `Info`
+- `do_stuff`
+- `manager`
+
+## Common patterns
+
+### Resource pattern
+Use for global config, score, timers, handles, current run state.
+
+### Event pattern
+Use when one system announces and another reacts:
+- enemy died
+- score changed
+- level completed
+- damage taken
+
+### State pattern
+Use for flow:
+- `Loading`
+- `Menu`
+- `Playing`
+- `Paused`
+- `GameOver`
+
+### Plugin pattern
+Use for feature isolation:
+- player
+- UI
+- combat
+- level
+
+## Performance-first habits
+
+- query only data needed
+- avoid expensive string churn each frame
+- keep UI rebuilds scoped
+- avoid asset reloading loops
+- prefer change detection / explicit triggers when useful
+
+## Workshop-safe scope
+
+Keep small:
+- one-screen loop
+- one mechanic
+- one UI counter
+- one win/lose condition
+- one polish pass