bevy-migration-0-17-to-0-18

Bevy 0.17 → 0.18 — Migration cheat sheet

Released 2026-01-13. Apply top-down — earlier items break later builds if skipped.

When to use this skill

• Compiler errors after a bevy = "0.17" → bevy = "0.18" bump.
• LLM emits 0.17-era API names from training data.
• Auditing a PR for hidden 0.18-incompatible patterns.
• Hot-fixing a downstream crate that hasn't shipped 0.18 yet.

The renames you'll hit first

Observers: Trigger<E> → On<E>

// 0.18 (also 0.17)
fn on_hit(on: On<Damage>) { let _e = on.event(); }

Buffered events: Event → Message

// 0.18
#[derive(Message)] struct Tick;
// app.add_message::<Tick>();
fn read(mut reader: MessageReader<Tick>) { for _ in reader.read() {} }
fn write(mut w: MessageWriter<Tick>) { w.write(Tick); }

Event is now reserved for observed, entity-targeted events (#[derive(EntityEvent)]).

Camera { target: ... } → RenderTarget component

// 0.18
commands.spawn((Camera3d::default(), RenderTarget::Image(handle.into())));

AmbientLight is no longer a resource

// 0.18: global default
app.insert_resource(GlobalAmbientLight { brightness: 2000.0, ..default() });
// Per-camera override:
commands.spawn((Camera3d::default(), AmbientLight { brightness: 5000.0, ..default() }));

MaterialPlugin<M> config moved to trait methods

// 0.18
impl Material for M {
    fn enable_prepass() -> bool { false }
    fn enable_shadows() -> bool { false }
}
app.add_plugins(MaterialPlugin::<M>::default());

AsBindGroup::label() is now required

impl AsBindGroup for MyMaterial {
    fn label() -> &'static str { "MyMaterial" }
}

AssetLoader must #[derive(TypePath)]

#[derive(TypePath)]
struct MyLoader;
impl AssetLoader for MyLoader { /* ... */ }

Mesh::insert_attribute is panicky — prefer try_insert_attribute

// 0.18 safe form — returns Result<(), MeshAccessError>
mesh.try_insert_attribute(Mesh::ATTRIBUTE_POSITION, positions)?;