init repo

docs/ai/bevy-project-patterns.md

@@ -0,0 +1,94 @@
+# Bevy Project Patterns
+
+## Start small
+
+For workshop speed, stay in one crate.
+When code grows, split by feature modules, not by technical layer only.
+
+Good early structure:
+
+```text
+src/
+├── main.rs
+├── player.rs
+├── ui.rs
+├── state.rs
+└── game.rs
+```
+
+Later:
+
+```text
+src/
+├── main.rs
+├── game/
+│   ├── mod.rs
+│   ├── plugin.rs
+│   ├── events.rs
+│   └── state.rs
+├── player/
+│   ├── mod.rs
+│   ├── components.rs
+│   ├── systems.rs
+│   └── plugin.rs
+└── ui/
+    ├── mod.rs
+    ├── components.rs
+    ├── systems.rs
+    └── plugin.rs
+```
+
+## Thin main
+
+`main.rs` should mostly:
+
+- create `App`
+- add plugins
+- init resources
+- add states
+- run
+
+Business logic lives in feature plugins.
+
+## Plugin boundaries
+
+Each plugin should own:
+
+- components
+- resources
+- events
+- systems
+- setup hooks
+
+## Event flow example
+
+Input system -> movement system -> collision system -> score event -> UI system
+
+Good because:
+- no direct UI coupling in gameplay code
+- each step easy to test and inspect
+
+## State flow example
+
+`Loading -> Menu -> Playing -> GameOver`
+
+Each state should have:
+- enter setup
+- update systems
+- exit cleanup if needed
+
+## Asset handling
+
+- keep asset paths stable
+- store handles in resources or components
+- preload if startup hitches matter
+- keep workshop assets tiny and few
+
+## Debug helpers
+
+Worth adding early:
+
+- `Name` components on important entities
+- debug print on critical events
+- optional debug plugin
+- one place for feature flags and tuning constants