reliquary/plugins/bevy/skills/bevy-upgrade/references/0.17-to-0.18.md

0.17 → 0.18

The largest recent transition. Its centerpiece — the Event/Message split — is architectural, not just a rename. Official guide for the long tail: https://bevy.org/learn/migration-guides/0-17-to-0-18/.

The Event/Message split

The old buffered event system was split in two:

Old (≤0.17)	New (0.18)
#[derive(Event)] (buffered use)	#[derive(Message)]
EventWriter<T> / .send(e)	MessageWriter<T> / .write(m)
EventReader<T>	MessageReader<T>
Events<T>	Messages<T>
on_event::<T>() run condition	on_message::<T>()

Event still exists but now means observer-events only (commands.trigger() + On<E> observers, immediate push). This is the transition's biggest trap: a type ported to #[derive(Event)] and written with a MessageWriter won't compile, but a type left as Event with a forgotten reader silently does nothing.

Port rule: every buffered event → Message. Only convert to Event+observer deliberately, during post-migration cleanup, where immediate reaction is actually wanted.

New in 0.18: #[derive(EntityEvent)] with #[event_target] for entity-targeted events, optionally #[entity_event(propagate)] to bubble up ChildOf.

Renames & moves (mechanical)

Old	New
remove_child / remove_children / clear_children	detach_child / detach_children / detach_all_children
bevy::render::render_resource::ShaderRef	bevy::shader::ShaderRef
WinitPlugin::<WakeUp>	WinitPlugin (no longer generic)
AmbientLight (single type)	GlobalAmbientLight resource + AmbientLight camera component
Camera.target field	RenderTarget required component
GltfPlugin use_model_forward_direction	convert_coordinates + rotate_scene_entity / rotate_meshes flags

API shape changes

• Fallible systems: systems may return Result (= Result<(), BevyError>); errors are logged and the system continues running on its normal schedule. Adopt during the bump wherever it deletes unwrap()s cheaply; systematically during cleanup.
• Mesh accessors became try_* returning Result<_, MeshAccessError>.
• MaterialPlugin fields prepass_enabled / shadows_enabled became Material trait methods.
• LoadContext::path() returns AssetPath, not Path; image reinterpret_* methods return Result.
• Immutable components: #[component(immutable)] available.
• Input feature gates: mouse, keyboard, gamepad, touch, gestures are now cargo features. Default-on, but builds with default-features = false must list them — otherwise input silently stops arriving.

Semantic shifts (audit, don't just compile)

• NextState::set() same-state transitions fire. set(Playing) while in Playing now triggers OnExit(Playing) + OnEnter(Playing) (previously a no-op). One-time setup in OnEnter (spawn camera, load level) re-runs. Audit every next_state.set(...) reachable while already in that state; use set_if_neq() where the old behavior is wanted.
• Material shader bind groups: material bindings are @group(3); @group(2) is the mesh storage buffer. Old custom shaders using @group(2) fail with Storage class Storage doesn't match the shader Uniform. Update all .wgsl material shaders.
• MouseMotion, MouseWheel and other input streams are Messages now — readers must be MessageReader.

Porting checklist

1. grep -rn "EventWriter\|EventReader\|on_event\|Events<" — rename to Message equivalents; .send( → .write(.
2. grep -rn "derive(Event)" — decide per type: buffered (→ Message) or observed (stays Event, needs a trigger + observer).
3. grep -rn "remove_child\|clear_children" — rename to detach_*.
4. grep -rn "next_state.set\|NextState" — audit same-state re-fire.
5. grep -rn "@group(2)" --include="*.wgsl" — move material bindings to group 3.
6. grep -rn "AmbientLight" — split into resource vs camera component usage.
7. Check Cargo.toml for default-features = false on bevy → add input features.