references/bevy.md

GitHub

Bevy (digest)

Sources: the Bevy 0.20 API docs (https://docs.rs/bevy/0.20.0 and https://docs.rs/bevy_ecs/0.20.0), Bevy's own lint configuration in its published Cargo.toml, and the migration guides at https://bevy.org/learn/migration-guides/. Checked against bevy 0.20.0 (October 2026); every behavior below was confirmed with a test on that version. Read this when Cargo.toml depends on bevy or bevy_ecs.

Check the project's Bevy version first. Bevy breaks its API every release (0.17 renamed events to messages, 0.20 changed the observer generics), so follow the version in Cargo.lock, not this file, when they disagree.

Bevy calls your systems and builds their arguments, so a few general rules don't fit system functions. The exceptions below replace them for Bevy code only. Everything else in the skill (errors, panics, naming, tests, unsafe) still applies.

Keep Bevy's conventions

System parameters are taken by value. Res<T>, ResMut<T>, Query<D, F>, Single<D, F>, Commands, Local<T>, MessageReader<M>, and MessageWriter<M> are already borrows that Bevy hands the system for one run. Don't change them to &Res<T> or report them as needless pass-by-value. Normal borrowing advice still holds inside a system and for helper functions it calls: pass &Health, not a whole Query.

Use use bevy::prelude::*. The prelude is Bevy's documented import pattern, and clippy's wildcard_imports already exempts paths that contain prelude. The rule against glob imports still applies to your own modules, so don't invent an application prelude.

Plain-data components and resources may have public fields. Health(pub u32) and Velocity(pub Vec2) are passive data that many systems read and write, which is the passive-data exception in SKILL.md section 4. Keep fields private only when the fields must hold an invariant together, such as a list that must stay sorted. Settings such as a regeneration rate and a cap are plain data: enforce the cap in the system that applies it, not with getters and a panicking constructor.

Complex queries and many parameters are normal. Bevy's own workspace allows clippy::type_complexity and clippy::too_many_arguments. Allow them at the crate level, or give a query reused by several systems a type alias. Don't split a system or wrap its queries in a custom SystemParam only to silence the lint; derive SystemParam when a group of parameters is reused and deserves a name.

Lints. The BeautifulRust lints in lints/lints.toml turn on rust_2018_idioms and clippy's pedantic group, which flag every idiomatic system signature. In a Bevy crate, add these lines to the existing [lints.rust] and [lints.clippy] tables:

# under [lints.rust]
elided_lifetimes_in_paths = "allow"   # write Res<Time>, not Res<'_, Time>

# under [lints.clippy]
needless_pass_by_value = "allow"      # system parameters are passed by value
type_complexity = "allow"             # query types; Bevy's own workspace allows this
too_many_arguments = "allow"          # systems take many parameters; so does Bevy

Correctness checks

These are the Bevy bugs that compile cleanly. Check every system for them when writing or reviewing.

Conflicting queries panic. Two parameters of one system that could reach the same component mutably compile, but the system panics with error B0001 the first time it runs. Query<&mut Health, With<Player>> and Query<&mut Health, With<Enemy>> conflict, because one entity could have both markers. A Res<T> next to a ResMut<T> of the same type panics the same way (B0002). Make the queries disjoint with Without, or put them in a ParamSet when they really overlap and are used one at a time. Choose the filter that matches the game's rules, not whichever one compiles.

fn apply_hits(
    mut players: Query<&mut Health, (With<Player>, Without<Enemy>)>,
    mut enemies: Query<&mut Health, (With<Enemy>, Without<Player>)>,
) {
    // Each query now covers a separate set of entities.
}

Commands are deferred. spawn, insert, and despawn are queued and take effect at the next sync point (ApplyDeferred). Bevy inserts one automatically between two systems that have an explicit order (.chain(), .before(), .after()) when the earlier one has Commands. Without an order, another system can run before the queued changes apply and see the old world. A system that must see another system's spawns or despawns needs an explicit order.

Order systems that depend on each other. Systems added in one tuple without .chain() have no order, and Bevy may run them either way, frame to frame. If one system reads what another writes in the same frame (a resource, a message, a component, or a spawn), give them an order: .chain() for a pipeline, .after() for one edge, or system sets for larger groups.

// check_wave_cleared must not run after spawn_wave's spawns are queued but not
// yet applied, or it sees no enemies and starts a second wave.
app.add_systems(Update, (check_wave_cleared, spawn_wave).chain());

Don't unwrap queries. Query::single() and get(entity) return Result, and .unwrap() crashes the game when the player dies or a second camera appears. Use Single<D, F>, which skips the system unless exactly one entity matches, or let Ok(..) = .. else { return };. A system can also return Result and use ?, but Bevy's default error handler panics on the error. Install a quieter one if that's what you want: app.insert_resource(FallbackErrorHandler(warn)).

fn contact_damage(player: Single<(Entity, &Position), With<Player>>) {
    let (player, position) = *player;
    // Runs only while exactly one player exists.
}

Commands on an entity that may be gone. A command on an entity that was despawned earlier in the frame is an error when it applies, and the default handler panics. Guard against despawning twice (two hits killing the same enemy in one frame), or use try_insert and try_despawn when the entity may already be gone.

Messages are read once per reader. Each MessageReader sees a message once. A reader that runs before the writer in a frame sees that message in the next frame, so order a reader after its writer when it must react in the same frame.

Testing systems

Drive systems through a headless App without DefaultPlugins. Insert the resources the systems need, and advance Time by hand so the test is deterministic.

#[test]
fn units_move_by_velocity() {
    let mut app = App::new();
    app.init_resource::<Time>().add_systems(Update, move_units);
    let unit = app.world_mut().spawn((Position(Vec2::ZERO), Velocity(Vec2::X * 10.0))).id();
    app.world_mut().resource_mut::<Time>().advance_by(Duration::from_secs(2));

    app.update();

    assert_eq!(app.world().get::<Position>(unit), Some(&Position(Vec2::X * 20.0)));
}

Also add one smoke test that adds the whole plugin and calls app.update() twice. Conflicting queries and missing resources only show up when a system first runs, so tests that add systems one at a time can all pass while the plugin panics on its first frame.