bevy-template/docs/ai/bevy-quick-reference.md

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