Bevy ECS
Structure a Bevy game in Rust around the Entity Component System: the App and
plugins, components and resources, systems with queries, scheduling, and
frame-rate-independent updates. New examples target Bevy 0.20. If the project
already pins another release, keep that release and use its matching migration guide.
When to use
- Use when wiring a Bevy
App, defining Component/Resource types, writing
systems that query entities, ordering/filtering systems, or fixing
borrow-conflict panics and frame-dependent movement.
- Use when
Cargo.toml depends on bevy and code calls App::new(),
add_systems, Query, or Commands.
When not to use: this is the ECS core. Deep rendering, custom shaders/
pipelines, UI layout, and audio are separate concerns. For engine-agnostic AI or
procedural algorithms, pair with game-ai / procedural-gen.
Core workflow
- Detect and pin the version. Read
Cargo.toml and Cargo.lock first. For a
new project use bevy = "0.20"; never silently migrate an existing project
across a Bevy minor release. Treat the matching docs and migration guides as truth.
- Build the
App. App::new().add_plugins(DefaultPlugins) gives windowing,
input, rendering, time, etc. Register systems into schedules: Startup (once)
and Update (every frame).
- Model data as components, globals as resources.
#[derive(Component)] for
per-entity data; #[derive(Resource)] for one-of-a-kind data (score, settings,
the Time clock). Since 0.19 Resource extends Component and each resource is
stored on its own entity, so do not derive both.
- Write systems as plain functions. Parameters declare data access:
Query<...>
for entities, Res<T>/ResMut<T> for resources, Commands for deferred
spawn/despawn. Systems run in parallel when their accesses don't conflict.
- Drive motion by
time.delta_secs() so speed is frame-rate independent.
- Order only what must be ordered with
.chain() or explicit constraints;
gate systems with run_if. Group related setup into Plugins. Build with
cargo run and read the panics — Bevy reports conflicting queries at startup.
Patterns
1. Cargo.toml + minimal App
# Cargo.toml — pin the version; the API differs across minor releases.
[dependencies]
bevy = "0.20"
// main.rs
use bevy::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins) // window, input, render, time, ...
.add_systems(Startup, setup) // runs once at startup
.add_systems(Update, move_players) // runs every frame
.run();
}
2. Components, resources, and spawning
#[derive(Component)]
struct Player;
#[derive(Component)]
struct Velocity(Vec2);
#[derive(Resource)]
struct Score(u32);
fn setup(mut commands: Commands) {
commands.insert_resource(Score(0));
// Camera2d is a component with required components (bundles removed in 0.16);
// spawning it pulls in Transform, Camera, etc. automatically.
commands.spawn(Camera2d);
// Spawn an entity as a tuple of components.
commands.spawn((
Player,
Velocity(Vec2::new(150.0, 0.0)),
Transform::from_xyz(0.0, 0.0, 0.0),
));
}
3. A system with a query + the Time resource
// Iterate every entity that has BOTH Velocity and Transform; mutate Transform.
fn move_players(time: Res<Time>, mut query: Query<(&Velocity, &mut Transform)>) {
for (velocity, mut transform) in &mut query {
// delta_secs() is f32 seconds (renamed from delta_seconds() in 0.16).
transform.translation += velocity.0.extend(0.0) * time.delta_secs();
}
}
4. Query filters (With / Without / Changed)
// Only entities tagged Player (the Player component itself isn't read).
fn aim_player(mut q: Query<&mut Transform, With<Player>>) { /* ... */ }
// Disjoint two mutable Transform queries so they don't conflict at runtime.
fn separate(
mut players: Query<&mut Transform, With<Player>>,
mut enemies: Query<&mut Transform, Without<Player>>,
) { /* ... */ }
// React only when Health changed since last run (change detection).
fn on_health_change(q: Query<&Health, Changed<Health>>) {
for health in &q { /* update the HUD, etc. */ }
}
5. Resources: read and write
fn add_points(mut score: ResMut<Score>) {
score.0 += 10; // ResMut = write access
}
fn show_score(score: Res<Score>) {
info!("score: {}", score.0); // Res = read access
}
6. Ordering, run conditions, and plugins
fn main() {
App::new()
.add_plugins((DefaultPlugins, GameplayPlugin))
// .chain() forces order: damage resolves before death is checked.
.add_systems(Update, (apply_damage, check_deaths).chain())
// run_if gates a system on a condition each frame.
.add_systems(Update, spawn_wave.run_if(wave_timer_finished))
.run();
}
struct GameplayPlugin;
impl Plugin for GameplayPlugin {
fn build(&self, app: &mut App) {
app.insert_resource(Score(0))
.add_systems(Startup, setup)
.add_systems(Update, (move_players, add_points));
}
}
Pitfalls
delta_seconds() not found → it was renamed to time.delta_secs() (and
elapsed_secs()) in 0.16. Using the old name fails to compile.
- Movement speed scales with frame rate → multiply per-frame changes by
time.delta_secs(). Never assume a fixed frame time.
- Panic
error[B0001]: "... accesses component(s) Transform in a way that conflicts
with a previous system parameter" → two Querys in one system both write the same
component, or one reads while another writes overlapping entities. Make them disjoint
with With/Without, or use ParamSet.
Camera2dBundle/SpriteBundle not found → bundles were deprecated in 0.15 and
removed in 0.16.
Spawn the components directly (Camera2d, Sprite, Transform); required
components fill in the rest.
- "trait
Component is not implemented" → you forgot #[derive(Component)]
(or #[derive(Resource)] for a resource).
- Spawned entity not visible to a later query in the same frame →
Commands are
deferred and applied at the next sync point. Read the entity in a subsequent system,
not the one that spawned it.
- System order assumed but not enforced → systems run in parallel by default.
If
B must follow A, add (A, B).chain() or an explicit ordering constraint.
To find order dependencies that only work by accident, shuffle the schedule in tests
with ScheduleBuildSettings::shuffle_seed (0.20, debug feature; see the reference).
- "conflicting implementations of trait
Component" after deriving both Resource
and Component → since 0.19 Resource extends Component; derive Resource alone.
- "Despawn everything" panics, or
Query<EntityMut> next to a Res<T> panics with
error[B0002] (or B0001, depending on parameter order) → since 0.19 every
resource lives on an entity tagged IsResource,
so Query<Entity>/EntityRef/EntityMut match those entities too. Query your own
marker component, or add Without<IsResource> (use bevy::ecs::resource::IsResource).
On<Add, Player> fails with "struct takes 1 generic argument but 2 generic
arguments were supplied" → 0.20 moved the component into the lifecycle event:
write On<Add<Player>> (likewise Insert<T>, Discard<T>, Remove<T>, Despawn<T>).
Pointer<Click> / Pointer<Press> not found in a picking observer → 0.20
flattened pointer events: observe On<PointerClick> / On<PointerPress>, and read
click.pointer.position (a Vec2) instead of the old pointer_location.
OnExit/OnEnter run again when "switching" to the current state →
NextState::set always runs the transition schedules. Use set_if_different to skip
same-state transitions (renamed from set_if_neq in 0.20; calling set_if_neq on a
ResMut<NextState<_>> picks up the unrelated change-detection method and fails with
"can't compare NextState").
- "
text does not live long enough" from Name::new(text.as_str()) → since 0.20
Name takes a &'static str literal or an owned String, not a borrowed &str;
pass Name::new(text.clone()) or Name::new(format!("Enemy {id}")).
- Overlapping sprites swap draw order after upgrading to 0.20 → sprites now render
through the
Mesh2d backend, and draw order at equal z was never guaranteed. Give
sprites that can overlap distinct Transform z values.
- Copy-pasting older Bevy snippets → APIs shift between minor versions. The
buffered event system became the message system:
EventReader/EventWriter/
add_event no longer exist, so use #[derive(Message)], MessageReader/
MessageWriter, and app.add_message::<T>(). Verify against the docs and migration
guide for your pinned version; don't mix versions.
References
- For schedules and
SystemSet ordering (including 0.20 weak ordering and schedule
shuffling), States/OnEnter/OnExit and state-scoped despawning, change
detection, Commands lifecycle and sync points, ParamSet and resource-entity
conflicts, iter_many results, and messages/observers in 0.20 syntax, read
references/queries-and-scheduling.md.
Related skills
game-ai — FSMs/behavior trees/steering as portable concepts to implement in ECS.
procedural-gen — noise/RNG/generation algorithms to drive from systems.
pygame-core / love2d-core — lighter-weight engines for smaller projects.
1---2name: bevy-ecs3description: >4 Structure a Bevy app around its Entity Component System: build the App with5 plugins, define Component/Resource types, write systems with Query/Res/Commands,6 filter and order systems, and use the Time resource for frame-rate-independent7 motion. Use when building or debugging a Bevy game in Rust — when the user8 mentions Bevy, ECS, App::new, add_systems, Query, Commands, components/systems,9 or a Cargo.toml depending on bevy.10metadata:11 source: https://skillmd.com/skills/junmystery/bevy-ecs12---1314# Bevy ECS1516Structure a Bevy game in Rust around the Entity Component System: the `App` and17plugins, components and resources, systems with queries, scheduling, and18frame-rate-independent updates. New examples target **Bevy 0.20**. If the project19already pins another release, keep that release and use its matching migration guide.2021## When to use2223- Use when wiring a Bevy `App`, defining `Component`/`Resource` types, writing24 systems that query entities, ordering/filtering systems, or fixing25 borrow-conflict panics and frame-dependent movement.26- Use when `Cargo.toml` depends on `bevy` and code calls `App::new()`,27 `add_systems`, `Query`, or `Commands`.2829**When *not* to use:** this is the ECS core. Deep rendering, custom shaders/30pipelines, UI layout, and audio are separate concerns. For engine-agnostic AI or31procedural algorithms, pair with `game-ai` / `procedural-gen`.3233## Core workflow34351. **Detect and pin the version.** Read `Cargo.toml` and `Cargo.lock` first. For a36 new project use `bevy = "0.20"`; never silently migrate an existing project37 across a Bevy minor release. Treat the matching docs and migration guides as truth.382. **Build the `App`.** `App::new().add_plugins(DefaultPlugins)` gives windowing,39 input, rendering, time, etc. Register systems into schedules: `Startup` (once)40 and `Update` (every frame).413. **Model data as components, globals as resources.** `#[derive(Component)]` for42 per-entity data; `#[derive(Resource)]` for one-of-a-kind data (score, settings,43 the `Time` clock). Since 0.19 `Resource` extends `Component` and each resource is44 stored on its own entity, so do not derive both.454. **Write systems as plain functions.** Parameters declare data access: `Query<...>`46 for entities, `Res<T>`/`ResMut<T>` for resources, `Commands` for deferred47 spawn/despawn. Systems run in parallel when their accesses don't conflict.485. **Drive motion by `time.delta_secs()`** so speed is frame-rate independent.496. **Order only what must be ordered** with `.chain()` or explicit constraints;50 gate systems with `run_if`. Group related setup into `Plugin`s. Build with51 `cargo run` and read the panics — Bevy reports conflicting queries at startup.5253## Patterns5455### 1. Cargo.toml + minimal App5657```toml58# Cargo.toml — pin the version; the API differs across minor releases.59[dependencies]60bevy = "0.20"61```6263```rust64// main.rs65use bevy::prelude::*;6667fn main() {68 App::new()69 .add_plugins(DefaultPlugins) // window, input, render, time, ...70 .add_systems(Startup, setup) // runs once at startup71 .add_systems(Update, move_players) // runs every frame72 .run();73}74```7576### 2. Components, resources, and spawning7778```rust79#[derive(Component)]80struct Player;8182#[derive(Component)]83struct Velocity(Vec2);8485#[derive(Resource)]86struct Score(u32);8788fn setup(mut commands: Commands) {89 commands.insert_resource(Score(0));9091 // Camera2d is a component with required components (bundles removed in 0.16);92 // spawning it pulls in Transform, Camera, etc. automatically.93 commands.spawn(Camera2d);9495 // Spawn an entity as a tuple of components.96 commands.spawn((97 Player,98 Velocity(Vec2::new(150.0, 0.0)),99 Transform::from_xyz(0.0, 0.0, 0.0),100 ));101}102```103104### 3. A system with a query + the Time resource105106```rust107// Iterate every entity that has BOTH Velocity and Transform; mutate Transform.108fn move_players(time: Res<Time>, mut query: Query<(&Velocity, &mut Transform)>) {109 for (velocity, mut transform) in &mut query {110 // delta_secs() is f32 seconds (renamed from delta_seconds() in 0.16).111 transform.translation += velocity.0.extend(0.0) * time.delta_secs();112 }113}114```115116### 4. Query filters (With / Without / Changed)117118```rust119// Only entities tagged Player (the Player component itself isn't read).120fn aim_player(mut q: Query<&mut Transform, With<Player>>) { /* ... */ }121122// Disjoint two mutable Transform queries so they don't conflict at runtime.123fn separate(124 mut players: Query<&mut Transform, With<Player>>,125 mut enemies: Query<&mut Transform, Without<Player>>,126) { /* ... */ }127128// React only when Health changed since last run (change detection).129fn on_health_change(q: Query<&Health, Changed<Health>>) {130 for health in &q { /* update the HUD, etc. */ }131}132```133134### 5. Resources: read and write135136```rust137fn add_points(mut score: ResMut<Score>) {138 score.0 += 10; // ResMut = write access139}140141fn show_score(score: Res<Score>) {142 info!("score: {}", score.0); // Res = read access143}144```145146### 6. Ordering, run conditions, and plugins147148```rust149fn main() {150 App::new()151 .add_plugins((DefaultPlugins, GameplayPlugin))152 // .chain() forces order: damage resolves before death is checked.153 .add_systems(Update, (apply_damage, check_deaths).chain())154 // run_if gates a system on a condition each frame.155 .add_systems(Update, spawn_wave.run_if(wave_timer_finished))156 .run();157}158159struct GameplayPlugin;160impl Plugin for GameplayPlugin {161 fn build(&self, app: &mut App) {162 app.insert_resource(Score(0))163 .add_systems(Startup, setup)164 .add_systems(Update, (move_players, add_points));165 }166}167```168169## Pitfalls170171- **`delta_seconds()` not found** → it was renamed to `time.delta_secs()` (and172 `elapsed_secs()`) in 0.16. Using the old name fails to compile.173- **Movement speed scales with frame rate** → multiply per-frame changes by174 `time.delta_secs()`. Never assume a fixed frame time.175- **Panic `error[B0001]`: "... accesses component(s) Transform in a way that conflicts176 with a previous system parameter"** → two `Query`s in one system both write the same177 component, or one reads while another writes overlapping entities. Make them disjoint178 with `With`/`Without`, or use `ParamSet`.179- **`Camera2dBundle`/`SpriteBundle` not found** → bundles were deprecated in 0.15 and180 removed in 0.16.181 Spawn the components directly (`Camera2d`, `Sprite`, `Transform`); required182 components fill in the rest.183- **"trait `Component` is not implemented"** → you forgot `#[derive(Component)]`184 (or `#[derive(Resource)]` for a resource).185- **Spawned entity not visible to a later query in the same frame** → `Commands` are186 deferred and applied at the next sync point. Read the entity in a subsequent system,187 not the one that spawned it.188- **System order assumed but not enforced** → systems run in parallel by default.189 If `B` must follow `A`, add `(A, B).chain()` or an explicit ordering constraint.190 To find order dependencies that only work by accident, shuffle the schedule in tests191 with `ScheduleBuildSettings::shuffle_seed` (0.20, `debug` feature; see the reference).192- **"conflicting implementations of trait `Component`" after deriving both `Resource`193 and `Component`** → since 0.19 `Resource` extends `Component`; derive `Resource` alone.194- **"Despawn everything" panics, or `Query<EntityMut>` next to a `Res<T>` panics with195 `error[B0002]` (or `B0001`, depending on parameter order)** → since 0.19 every196 resource lives on an entity tagged `IsResource`,197 so `Query<Entity>`/`EntityRef`/`EntityMut` match those entities too. Query your own198 marker component, or add `Without<IsResource>` (`use bevy::ecs::resource::IsResource`).199- **`On<Add, Player>` fails with "struct takes 1 generic argument but 2 generic200 arguments were supplied"** → 0.20 moved the component into the lifecycle event:201 write `On<Add<Player>>` (likewise `Insert<T>`, `Discard<T>`, `Remove<T>`, `Despawn<T>`).202- **`Pointer<Click>` / `Pointer<Press>` not found in a picking observer** → 0.20203 flattened pointer events: observe `On<PointerClick>` / `On<PointerPress>`, and read204 `click.pointer.position` (a `Vec2`) instead of the old `pointer_location`.205- **`OnExit`/`OnEnter` run again when "switching" to the current state** →206 `NextState::set` always runs the transition schedules. Use `set_if_different` to skip207 same-state transitions (renamed from `set_if_neq` in 0.20; calling `set_if_neq` on a208 `ResMut<NextState<_>>` picks up the unrelated change-detection method and fails with209 "can't compare `NextState`").210- **"`text` does not live long enough" from `Name::new(text.as_str())`** → since 0.20211 `Name` takes a `&'static str` literal or an owned `String`, not a borrowed `&str`;212 pass `Name::new(text.clone())` or `Name::new(format!("Enemy {id}"))`.213- **Overlapping sprites swap draw order after upgrading to 0.20** → sprites now render214 through the `Mesh2d` backend, and draw order at equal `z` was never guaranteed. Give215 sprites that can overlap distinct `Transform` z values.216- **Copy-pasting older Bevy snippets** → APIs shift between minor versions. The217 buffered event system became the message system: `EventReader`/`EventWriter`/218 `add_event` no longer exist, so use `#[derive(Message)]`, `MessageReader`/219 `MessageWriter`, and `app.add_message::<T>()`. Verify against the docs and migration220 guide for *your* pinned version; don't mix versions.221222## References223224- For schedules and `SystemSet` ordering (including 0.20 weak ordering and schedule225 shuffling), `States`/`OnEnter`/`OnExit` and state-scoped despawning, change226 detection, `Commands` lifecycle and sync points, `ParamSet` and resource-entity227 conflicts, `iter_many` results, and messages/observers in 0.20 syntax, read228 `references/queries-and-scheduling.md`.229230## Related skills231232- `game-ai` — FSMs/behavior trees/steering as portable concepts to implement in ECS.233- `procedural-gen` — noise/RNG/generation algorithms to drive from systems.234- `pygame-core` / `love2d-core` — lighter-weight engines for smaller projects.