使用方法
- 复制安装命令,在自己的智能体环境安装前先检查源码包。
- 从原始文档核对所需工具、凭据和支持的宿主。
- 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill bevy-ecs开始前需了解
- 安装不包含模型订阅、API 额度或访问文件的权限。
- 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。
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
- Read the pinned version first.
Cargo.tomlgives the requirement andCargo.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.
- 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).
- 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.
- 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.
- Verify. Run
cargo check, thencargo testwith a headlessApptest (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 broadQuery<Entity>despawn loop) next to aRes<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
Resourceand
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 →
Commandsare
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.mdwhen 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.