references/bevy.md
GitHubBevy (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.