Bevy Engine skill for Codex

Done well means: code compiles against the exact Bevy version in Cargo.toml (not a tutorial’s version), gameplay is split into plugins, systems are small and explicitly ordered where order matters, simulation runs in FixedUpdate, state-specific entities are cleaned up on exit, and logic is covered by headless App tests.

Version first

Bevy ships breaking releases every few months. Before writing anything:

1. Read AGENTS.md and Cargo.toml: note bevy = "0.x" and third-party Bevy crates (each supports specific Bevy versions; check their compatibility tables).
2. Grep the codebase for the idioms in use (EventWriter vs MessageWriter, Trigger vs On) and match them.
3. When upgrading, go one minor version at a time using the official migration guides on bevy.org (0.16 -> 0.17, then 0.17 -> 0.18, …). Network is needed to fetch the guides and crates; ask if the sandbox blocks it.

Topic	Older	Newer
Spawning sprites, cameras	Bundles (SpriteBundle, Camera2dBundle)	Required components: Sprite, Camera2d, Transform (0.15+)
Frame delta	time.delta_seconds()	time.delta_secs() (0.15+)
Single entity queries	query.single() panics	query.single() returns Result (0.16+); Single<&T> param skips the system if absent
System errors	Panics / unwrap	Systems may return Result and use ? (0.16+)
Buffered events	#[derive(Event)], EventWriter::send/write, EventReader	#[derive(Message)], MessageWriter::write, MessageReader::read, add_message (0.17+)
Observers	Trigger<OnAdd, T>	On<Add, T> (0.17+)
Despawn entities when leaving a state	StateScoped(state)	DespawnOnExit(state) component (0.17+)

If the version and an API disagree with this table, trust the compiler and the version’s docs (cargo doc --open -p bevy works offline once dependencies are fetched).

Project setup

[dependencies]
bevy = "0.20"          # use the project's version

[profile.dev]
opt-level = 1

[profile.dev.package."*"]
opt-level = 3          # optimise dependencies; Bevy is unplayably slow at opt-level 0

• Faster iteration: cargo run --features bevy/dynamic_linking (desktop dev only, never in release builds) and a fast linker (mold/lld on Linux; check the Bevy setup guide for the current recommendation per OS).
• Linux builds need system packages (ALSA and udev development headers); missing ones fail at link time.

App structure

use bevy::prelude::*;

#[derive(States, Default, Debug, Clone, PartialEq, Eq, Hash)]
enum GameState { #[default] Menu, Playing, Paused }

#[derive(Component)] struct Player;
#[derive(Component)] struct LevelEntity;          // marker for cleanup on exit
#[derive(Component, Default)] struct Velocity(Vec2);

#[derive(Message)] struct CoinCollected { value: u32 }   // 0.17+ naming

#[derive(Resource, Default)] struct Score(u32);

pub struct GameplayPlugin;

impl Plugin for GameplayPlugin {
    fn build(&self, app: &mut App) {
        app.init_state::<GameState>()
            .init_resource::<Score>()
            .add_message::<CoinCollected>()
            .add_systems(Startup, spawn_camera)
            .add_systems(OnEnter(GameState::Playing), spawn_level)
            .add_systems(OnExit(GameState::Playing), despawn_with::<LevelEntity>)
            .add_systems(
                FixedUpdate,
                (player_input, apply_velocity, collect_coins)
                    .chain()
                    .run_if(in_state(GameState::Playing)),
            )
            .add_systems(Update, update_score.run_if(in_state(GameState::Playing)));
    }
}

fn main() {
    App::new().add_plugins((DefaultPlugins, GameplayPlugin)).run();
}

fn spawn_camera(mut commands: Commands) {
    commands.spawn(Camera2d);
}

fn spawn_level(mut commands: Commands, assets: Res<AssetServer>) {
    commands.spawn((
        Player,
        LevelEntity,
        Sprite::from_image(assets.load("sprites/hero.png")),
        Transform::from_xyz(0.0, 0.0, 1.0),
        Velocity::default(),
    ));
}

fn player_input(keys: Res<ButtonInput<KeyCode>>, mut player: Query<&mut Velocity, With<Player>>) -> Result {
    let mut v = player.single_mut()?;
    let mut dir = Vec2::ZERO;
    if keys.pressed(KeyCode::KeyA) { dir.x -= 1.0; }
    if keys.pressed(KeyCode::KeyD) { dir.x += 1.0; }
    if keys.pressed(KeyCode::KeyW) { dir.y += 1.0; }
    if keys.pressed(KeyCode::KeyS) { dir.y -= 1.0; }
    v.0 = dir.normalize_or_zero() * 200.0;
    Ok(())
}

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

fn collect_coins(/* ... */ mut collected: MessageWriter<CoinCollected>) {
    // on overlap: collected.write(CoinCollected { value: 1 });
}

fn update_score(mut reader: MessageReader<CoinCollected>, mut score: ResMut<Score>) {
    for msg in reader.read() { score.0 += msg.value; }
}

fn despawn_with<T: Component>(mut commands: Commands, q: Query<Entity, With<T>>) {
    for e in &q { commands.entity(e).despawn(); }
}

Decisions

Need	Use
Gameplay simulation, physics, anything needing stable steps	FixedUpdate (default 64 Hz; change with Time::<Fixed>::from_hz)
Rendering-side work, UI, camera smoothing	Update
Many-to-many decoupled notifications per frame	Messages (MessageWriter/MessageReader)
React immediately to something happening to an entity (spawned, clicked, damaged)	Observers (app.add_observer, entity.observe)
Data shared by many systems	Resource
Per-entity data	Component
Order between systems	.chain(), .before()/.after(), or SystemSets configured once
Skip systems by mode	States plus run_if(in_state(...)), or custom run conditions
Clean up a level when its state ends	DespawnOnExit(GameState::Playing) on spawned entities, or a marker plus an OnExit system as above
Physics	A Bevy physics crate (Avian, bevy_rapier) matching the Bevy version

Query and borrow rules

• Two queries in one system that could access the same component mutably conflict and panic at startup (“error[B0001]”). Fix with Without<T> filters to make them disjoint, or a ParamSet.
• Prefer Query<&T> (read) over &mut T wherever possible; the scheduler parallelises systems whose accesses do not overlap.
• Commands are deferred: an entity spawned with commands.spawn is not visible to queries until the next sync point. Systems later in a .chain() see it, because chains insert sync points.
• Change detection (Changed<T>, Added<T>, Ref<T>::is_changed) avoids per-frame work for rarely changing data. Mutable access through &mut marks a component changed even if the value is the same; guard with set_if_neq when it matters.

Assets

• AssetServer::load returns a handle immediately; the asset arrives later. Gate gameplay on a loading state that checks asset_server.is_loaded_with_dependencies(&handle) (or use bevy_asset_loader if the project has it).
• Paths are relative to the assets/ folder next to Cargo.toml (when run with cargo run).
• Hot reload during development with the file_watcher cargo feature.

Gotchas

• just_pressed input read in FixedUpdate can be missed or seen twice, because fixed steps do not align with frames. Read edge-triggered input in Update into a resource and consume it in FixedUpdate.
• A system registered but not running: check its run_if, the current state, and that its plugin was added. bevy::dev_tools and logging (info!) help confirm.
• Forgetting to clean up entities on state exit leaves menus or levels stacked.
• Third-party crates lag Bevy releases; upgrading Bevy may be blocked by one dependency. Check before promising an upgrade.
• Avoid Query::iter().count() and similar per frame on large queries just for UI; keep a counter.

Tests

#[cfg(test)]
mod tests {
    use super::*;
    use bevy::ecs::system::RunSystemOnce;

    #[test]
    fn coin_messages_increase_score() {
        let mut app = App::new();
        app.init_resource::<Score>().add_message::<CoinCollected>().add_systems(Update, update_score);
        app.world_mut().write_message(CoinCollected { value: 3 });
        app.update();
        assert_eq!(app.world().resource::<Score>().0, 3);
    }

    #[test]
    fn velocity_moves_transform() {
        let mut world = World::new();
        world.insert_resource(Time::<()>::default());
        let e = world.spawn((Transform::default(), Velocity(Vec2::X * 10.0))).id();
        world.resource_mut::<Time>().advance_by(std::time::Duration::from_secs(1));
        world.run_system_once(apply_velocity).unwrap();
        assert_eq!(world.get::<Transform>(e).unwrap().translation.x, 10.0);
    }
}

Use MinimalPlugins instead of DefaultPlugins in tests that need time or app plumbing; never open a window in CI.

Verification

cargo check
cargo clippy --all-targets -- -D warnings
cargo test
cargo run --features bevy/dynamic_linking     # manual play test

• Web builds: target wasm32-unknown-unknown with the project’s tool (Bevy CLI, trunk or wasm-bindgen); check that assets load over HTTP and audio starts after a user gesture.
• Upgrades: after each minor bump, cargo check clean, tests pass, and play every state once.

Hand-off summary

**Bevy:** 0.20 (Cargo.toml), crates: avian2d (release that supports 0.20)
**Plugins:** GameplayPlugin (states Menu/Playing/Paused, FixedUpdate chain input -> velocity -> coins)
**Messages/observers:** CoinCollected message; observer on Add<Enemy> sets up health bar
**Tests:** 6 headless tests (World + run_system_once, App::update)
**Build:** dev profile opt-level 1 / deps 3; dynamic_linking for local runs only