0.4 -> 0.5 Migration Guide

[cart]

0.5 will have breaking changes, and some of them will not be intuitive. We should have an official migration guide to help our users upgrade.

Lets use this issue as a way to track the important breaking changes to include. I'll start with:

1. commands: &mut Commands has changed back to mut commands: Commands. This will cause previously valid foo.system() calls to fail to compile.
2. The max number of SystemParams has gone from 15 to 12. This is because they now rely on Rust's Default impl for tuples, which only extends to tuples of length 12. Users can use nested tuples and/or SystemParam derives to work around this. Both options help organize parameters, which is a good thing to do anyway for systems with a large number of params.
3. commands.insert_one(component) is now commands.insert(component). commands.insert(bundle) is now commands.insert_bundle(bundle). This means that 0.4 code that does commands.insert(bundle) will now attempt to insert bundle as a component instead of a bundle, which will cause breakage. This will cause confusion, but this change was made to help make bundles less easy to confuse with components, so I think that it is ultimately the right call.

[alice-i-cecile]

4. Event changes in Make EventReader a SystemParam #1244 and [Merged by Bors] - Add EventWriter #1575.
5. add_resource changed to insert_resource in Rename add_resource to insert_resource #1356.
6. System dependencies and ambiguities in System sets and parallel executor v2 #1144.
7. Timer changes in [Merged by Bors] - ♻️ Timer refactor to duration.✨ Add Stopwatch struct. #1151.
8. init_resource no longer overwrites in Update init_resource to not overwrite #1349 (no one should have been relying on this, but it may cause hard-to-track down breakages).

Tentative:
9. State rework in #1424.
10. Mutated removed in #1471.
11. All of the stage overhaul work that is likely to come out of #1466.

[alice-i-cecile]

12. ChangedRes removed in [Merged by Bors] - Get rid of ChangedRes #1313.
13. Stage labels have been changed in Add Label type #1423.
14. Thread-local resources -> NonSend resources in System sets and parallel executor v2 #1144.
15. Thread-local systems -> exclusive systems in System sets and parallel executor v2 #1144.
16. Orthographic projection changes in OrthographicProjection scaling mode + camera bundle refactoring #400.
17. Box<dyn System> is now BoxedSystem

Okay, I've reviewed the closed PRs going back to the 0.4 release so I think that's most of the breaking changes, other than :thepr:.

[rparrett]

99. New query conflict stuff

[alice-i-cecile]

From #1525:

18. Resources merged into World.
19. Several functions and traits are now appropriately unsafe.
20. Removed Mut<T> in favor of &mut T
21. New RemovedComponents SystemParam that replaces query.removed::()
22. New World and Command API changes (assuming Adapt Commands apis for consistency with new World apis #1562 lands as planned)

[cart]

Thanks yall! If anyone wants to volunteer to write the guide, that would be much appreciated. Otherwise I'll get to it eventually 😄

Each migration item should have a description of the change (with rationale if you anticipate a negative response), descriptions of breakage symptoms (when that is relevant and non-obvious), and small before/after code snippets where relevant

[cart]

I think this should probably be a new section of the book that we link to from the 0.5 release blog post

[cart]

Theres enough items here that we should do this piece by piece (which will also help us distribute the work)

[cart]

So I'm looking for someone to create the template others can build off of. And people should claim numbered items in this thread before working on them.

[alice-i-cecile]

@cart want to create a draft PR for this that we can make pull requests onto? Seems like a good way to collaborate.

[cart]

Good call! Putting that together now.

[bitshifter]

There are a few breaking changes in glam 0.13.0 documented here https://github.com/bitshifter/glam-rs/blob/master/CHANGELOG.md. The one people might get caught out by is Mat4::transform_point3(Vec3) no longer performs perspective divide, there's a new Mat4::project_point3(Vec3) method for that, if you need to transform points by a perspective projection matrix.

[dmtaub]

I can take a stab at 2 & 3 -- will also add a small note about Commands' extra lifetime to 1) -- may not be a super common case but it bit me the other day...

[alice-i-cecile]

23. Painful upstream change from glam: glam 0.13: behavior of transform_point3() changed, old behavior is in project_point3()

[hymm]

Would it make sense to mention the branch name change from master -> main? Still seeing a decent amount of people in #help on master.

[alice-i-cecile]

24. Branch name changed from master to main (thanks @hymm)
25. par_iter and par_iter_mut replaced by .par_for_each in [Merged by Bors] - Bevy ECS V2 #1525

[aevyrie]

26. FromResources -> FromWorld

[ilyvion]

I don't know if it's helpful, but these are the changes I had to make to my project when upgrading from 0.4 to latest main commit just now:

• bevy_ecs::{Schedule, System, SystemStage} moved to bevy_ecs::schedule::{Schedule, SystemStage} and bevy_ecs::system::System.
• bevy_ecs::{Commands, IntoSystem, Query, Res, ResMut} moved to bevy_ecs::system::{Commands, IntoSystem, Query, Res, ResMut}.
• bevy_ecs::Bundle moved to bevy_ecs::bundle::Bundle.
• bevy_ecs::Entity moved to bevy_ecs::entity::Bundle.
• SystemStage::serial() changed to SystemStage::single_threaded(). (Although supposedly not quite the same thing.)
• App::resources removed; resource manipulation is instead done on App::world.
• AppBuilder::add_resource -> AppBuilder::insert_resource.
• EventReader replaced with ManualEventReader and EventReader::latest(&Event<T>) replaced with ManualEventReader::iter(&Event<T>).last().
• Schedule::initialize_and_run -> Schedule::run.

Sorry if some (or all) of these are already mentioned above.

[alice-i-cecile]

Thanks @alexschrod; this is very helpful. The simple code re-organization changes I think are too small to be worth listing on their own, and are trivial enough to figure out how to fix for any user that isn't just glob-importing from the prelude.

27. SystemStage::serial() changed to SystemStage::single_threaded()
28. Schedule::initialize_and_run -> Schedule::run.

[alice-i-cecile]

Created by @jakobhellermann: a little cleanup script for doing the basic migration!

[NiklasEi]

I will write something for 4 & 5

[MinerSebas]

29. Rust 1.50 is now required -> run rustup update

[CleanCut]

7. Timer changes in [Merged by Bors] - ♻️ Timer refactor to duration.✨ Add Stopwatch struct. #1151.

I'll look into documenting this today.

Update:

• "7" done in Section 7: Timer and Stopwatch cart/bevy-website#3
• Also tried to bring style to parity with latest blog post: Documentation Improvements cart/bevy-website#4

[Ixentus]

30. Text breaking change from Rich text #1245

[rparrett]

Finally, something I know about. I'll take 30.

[juanmait]

1. FromResources -> FromWorld

I had to make this change:

From:

impl FromResources for MyResource {
    fn from_resources(resources: &Resources) -> Self {
        Self {  }
    }
}

To:

impl FromWorld for MyResource {
    fn from_world(world: &mut World) -> Self {
        Self {  }
    }
}

[lassade]

'Camera' uniform should be renamed to 'CameraViewProj'

[Byteron]

I'm not entirely sure if I'm happy with commands.insert() and commands.insert_bundle().
IMO if there is multiple things that can be inserted they should be stated explicitly.
if you have commands.insert_bundle that's cool, but then if you see commands.insert() you gotta ask "insert what?".
I do understand however that commands.insert_component() is rather verbose, and it's something that will be called a lot.
That's why I'm unsure.

[CleanCut]

I'm not entirely sure if I'm happy with commands.insert() and commands.insert_bundle().

I am happy with it! I think it fits well. In both cases the unstated subject is component(s). How do you insert a component? .insert(). How do you insert a whole bundle of components? .insert_bundle().

A few months back I got stuck for an hour before I figured out the old API's unstated subject was "bundle of components" for the short method (while the long method was completely explicit--not great symmetry there). I was trying to add a single component with the method that required a bundle 🤦🏼‍♂️ --it was confusing.

[alice-i-cecile]

New example from today: handling migration of WorldQuery generic parameters. Link.

[foxzool]

get_mut -> get_resource_mut
insert_thread_local -> insert_non_send
get_thread_local -> get_non_send_resource
get_thread_local_mut -> get_non_send_resource_mut

[SuperSamus]

Pull request #1703 made a breaking change by moving some methods from Commands to EntityCommands.

There is already a question about it on StackOverflow.

[BorisBoutillier]

The Commands.spawn method has changed from 0.4 to 0.5 as far as I see.
Commands.spawn calls should be replaced by Commands.spawn_bundle

[rparrett]

The changes to commands that are not currently covered in the migration guide are documented pretty well here: #1703 (and mentioned speculatively above in "number 22")

An awesome first contribution to Bevy would be a PR that adds this info (and the many other points not covered) to the migration guide.

[rparrett]

Added bevyengine/bevy-website#129 which covers number 12 and somewhat minimally, number 22.

[szunami]

I just opened bevyengine/bevy-website#133, very glad to see this kind of content being prioritized!

[alice-i-cecile]

32. Note that vsync is turned on by default, which may be limiting performance.

[cart]

I think we can safely close this one out :)