Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/other-engines/bevy-ecs

bevy-ecs

Verified

Builds and debugs Bevy 0.20 games in Rust: components, Query and Commands systems, schedules, States, observers and headless tests. Use when Cargo.toml depends on bevy, on a B0001 query-conflict panic, or pre-0.20 code (EventReader, SpriteBundle). Not for engine-neutral AI, generation, physics or shaders (`game-ai`, `procedural-gen`, `physics-tuning`, `shader-programming`).

Bevy ECS

Structure and debug a Bevy game around its ECS. New code targets Bevy 0.20 (bevy = "0.20", which resolves to the latest 0.20.x patch). Bevy breaks APIs in every minor release, so the version the project pins decides which syntax is right.

When to use

  • Wiring an App, defining components and resources, writing systems, ordering them, gating them on state or timers, or passing data with messages and observers.
  • Fixing query-conflict panics, entities that seem missing, order bugs, or code copied from an older Bevy release.

When not to use: rendering pipelines, custom shaders, UI layout and audio are outside this skill; AI and generation algorithms go to game-ai / procedural-gen.

Workflow

  1. Read the pinned version first. Cargo.toml gives the requirement and Cargo.lock the resolved bevy version. Keep it; a minor-release migration is a separate task that follows that release's migration guide. Never mix snippets from two minors.
  2. Model the data. Per-entity data is a #[derive(Component)]; one-of-a-kind data (score, settings) is a #[derive(Resource)]. Spawn entities as tuples of components; required components fill in the rest (commands.spawn(Camera2d) adds Transform, Camera and friends).
  3. Write systems as plain functions whose parameters declare access: Query<D, F>, Res/ResMut, Commands, MessageReader/MessageWriter, Single. Systems with non-conflicting access run in parallel, in no guaranteed order.
  4. Order only what must be ordered (.chain(), .before/.after, SystemSets) and gate with run_if. Group features into Plugins. Scale motion by time.delta_secs() or put it in FixedUpdate.
  5. Verify. Run cargo check, then cargo test with a headless App test (pattern below) for each rule you changed, then cargo run and read the first panic: Bevy reports conflicting system parameters when a schedule first runs, with an error code and a link. Report which of these you ran; a clean cargo check proves only that it compiles. When the change is visual, ask the user to run the game and report what they see.

Patterns

Spawning and filtering

#[derive(Component)]
struct Player;
#[derive(Component)]
struct Velocity(Vec2);

fn setup(mut commands: Commands) {
    commands.spawn(Camera2d);
    commands.spawn((Player, Velocity(Vec2::new(150.0, 0.0)), Transform::default()));
}

fn move_players(time: Res<Time>, mut q: Query<(&Velocity, &mut Transform)>) {
    for (v, mut t) in &mut q {
        t.translation += v.0.extend(0.0) * time.delta_secs();
    }
}

// Two &mut Transform queries in one system must be provably disjoint.
fn separate(
    mut players: Query<&mut Transform, With<Player>>,
    mut others: Query<&mut Transform, Without<Player>>,
) { /* ... */ }

Ordering, run conditions, plugins

struct GameplayPlugin;
impl Plugin for GameplayPlugin {
    fn build(&self, app: &mut App) {
        app.insert_resource(Score(0))
            .add_systems(Startup, setup)
            // damage must resolve before deaths are checked
            .add_systems(Update, (apply_damage, check_deaths).chain())
            .add_systems(Update, spawn_wave.run_if(in_state(AppState::Playing)));
    }
}

Headless test (the check to run)

MinimalPlugins gives time and a schedule runner with no window or GPU, so this runs under plain cargo test. Drive time by hand to make movement deterministic.

#[cfg(test)]
mod tests {
    use super::*;
    use bevy::time::TimeUpdateStrategy;
    use std::time::Duration;

    #[test]
    fn player_moves_at_its_velocity() {
        let mut app = App::new();
        app.add_plugins(MinimalPlugins)
            .insert_resource(TimeUpdateStrategy::ManualDuration(Duration::from_millis(100)))
            .add_systems(Update, move_players);
        let id = app.world_mut().spawn((Velocity(Vec2::X * 10.0), Transform::default())).id();
        for _ in 0..5 {
            app.update();
        }
        // The first update has a zero delta, so 5 updates advance 4 x 0.1 s.
        let x = app.world().get::<Transform>(id).unwrap().translation.x;
        assert!((x - 4.0).abs() < 1e-4, "x = {x}");
    }
}

For whole-world assertions use app.world_mut().query_filtered::<&Health, With<Player>>() and .single(world). States need bevy::state::app::StatesPlugin next to MinimalPlugins.

Gotchas

  • Panic error[B0001]: Query<…> in system … accesses component(s) Transform in a way that conflicts with a previous system parameter → two queries in one system can both reach the same component mutably. Make them disjoint with With/Without, or use ParamSet.
  • Query<EntityMut> (or a broad Query<Entity> despawn loop) next to a Res<T> panics → since 0.19 every resource lives on an entity tagged IsResource, so broad queries match resources too. The error is B0002 when the Res comes after the query and B0001 when it comes first. Query your own marker, or add Without<IsResource> (use bevy::ecs::resource::IsResource).
  • "conflicting implementations of trait Component" after deriving Resource and Component on one type → since 0.19 Resource implies Component; derive Resource alone.
  • A spawned entity is missing from a query in the same system → Commands are deferred to the next sync point. Read it in a later system, or order the reader after the spawner.
  • Something works only by luck of system order → unordered systems run in an arbitrary but stable order, which an unrelated change can reshuffle. Add a real constraint, and shake out hidden ones in tests with ScheduleBuildSettings::shuffle_seed (0.20, debug feature; see the reference).
  • Headless test sees no movement on the first update → the first app.update() has a zero delta. Run one extra update or assert on N−1 steps, as in the test above.
  • delta_seconds() not found → renamed to delta_secs() / elapsed_secs() in 0.15; the old names are gone.
  • Camera2dBundle / SpriteBundle not found → bundles were removed in 0.16. Spawn the components (Camera2d, Sprite, Transform) and let required components fill in.
  • EventReader / EventWriter / add_event not found → buffered events became messages: #[derive(Message)], MessageReader, MessageWriter::write, app.add_message::<T>(). Push-style events use #[derive(Event)] with observers.
  • On<Add, Player>: "struct takes 1 generic argument but 2 generic arguments were supplied" → 0.20 moved the component into the lifecycle event: On<Add<Player>> (also Insert<T>, Discard<T>, Remove<T>, Despawn<T>).
  • Pointer<Click> not found in a picking observer → 0.20 flattened pointer events: observe On<PointerClick> / On<PointerPress> and read click.pointer.position (a Vec2).
  • OnExit/OnEnter run when "switching" to the current state → NextState::set always transitions. Use set_if_different (0.20 name). The old set_if_neq now resolves to an unrelated change-detection method and fails with "can't compare NextState<S>".
  • "text does not live long enough" from Name::new(text.as_str()) → since 0.20 Name takes a &'static str or an owned String: Name::new(format!("Enemy {id}")).
  • Overlapping sprites swap draw order after moving to 0.20 → sprites render through the Mesh2d path and equal-z order was never guaranteed. Give overlapping sprites distinct z values.

References

  • Read references/queries-and-scheduling.md when the task needs more than the patterns above: query filters and single(), iter_many results, ParamSet, schedules and SystemSets, 0.20 weak ordering and schedule shuffling, States with DespawnOnExit, change detection and summary ticks, the Commands lifecycle and despawn_all, exclusive &mut World systems, and message/observer syntax.

Related skills

  • game-ai, procedural-gen — portable algorithms to implement as systems.
  • physics-tuning — fixed-step and collision feel; shader-programming — shader technique.
  • pygame-core, love2d-core — lighter engines for small projects.

Version notes

Last verified: 2026-11-11.

  • Bevy 0.20.0 shipped on 2026-10-08 and 0.20.1 on 2026-10-28. 0.20.1 is a maintenance release (bug fixes, no API changes this skill relies on); 0.19.0 shipped 2026-06-19.
  • Every 0.20 API in this skill and its reference, the panic texts in Gotchas and the headless test were compiled and run against bevy = "=0.20.1" (default features off, bevy_state, bevy_log, debug) with Rust 1.99. Camera2d, Sprite and pointer events were checked against the release notes and migration guide only.
  • Sources: crates.io bevy, v0.20.1 release, Bevy 0.20 release notes, 0.19 to 0.20 migration guide.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall