Repository navigation
0.4 -> 0.5 Migration Guide #1601
Description
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:
commands: &mut Commandshas changed back tomut commands: Commands. This will cause previously validfoo.system()calls to fail to compile.- 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.
commands.insert_one(component)is nowcommands.insert(component).commands.insert(bundle)is nowcommands.insert_bundle(bundle). This means that 0.4 code that doescommands.insert(bundle)will now attempt to insertbundleas 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.
Activity
alice-i-cecile commentedon Mar 9, 2021
add_resourcechanged toinsert_resourcein Rename add_resource to insert_resource #1356.Timerrefactor to duration.✨ AddStopwatchstruct. #1151.init_resourceno 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 commentedon Mar 9, 2021
ChangedResremoved in [Merged by Bors] - Get rid of ChangedRes #1313.NonSendresources in System sets and parallel executor v2 #1144.Box<dyn System>is nowBoxedSystemOkay, 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 commentedon Mar 9, 2021
alice-i-cecile commentedon Mar 9, 2021
From #1525:
unsafe.Mut<T>in favor of&mut Tcart commentedon Mar 9, 2021
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 commentedon Mar 9, 2021
I think this should probably be a new section of the book that we link to from the 0.5 release blog post
cart commentedon Mar 9, 2021
Theres enough items here that we should do this piece by piece (which will also help us distribute the work)
cart commentedon Mar 9, 2021
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 commentedon Mar 9, 2021
@cart want to create a draft PR for this that we can make pull requests onto? Seems like a good way to collaborate.
cart commentedon Mar 9, 2021
Good call! Putting that together now.
bitshifter commentedon Mar 9, 2021
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 newMat4::project_point3(Vec3)method for that, if you need to transform points by a perspective projection matrix.dmtaub commentedon Mar 9, 2021
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 commentedon Mar 10, 2021
12 remaining items
lassade commentedon Mar 25, 2021
'Camera' uniform should be renamed to 'CameraViewProj'
Byteron commentedon Mar 25, 2021
I'm not entirely sure if I'm happy with
commands.insert()andcommands.insert_bundle().IMO if there is multiple things that can be inserted they should be stated explicitly.
if you have
commands.insert_bundlethat's cool, but then if you seecommands.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 commentedon Mar 25, 2021
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 commentedon Mar 28, 2021
New example from today: handling migration of WorldQuery generic parameters. Link.
foxzool commentedon Mar 31, 2021
SuperSamus commentedon Apr 7, 2021
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 commentedon Apr 9, 2021
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 commentedon Apr 9, 2021
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 commentedon Apr 9, 2021
Added bevyengine/bevy-website#129 which covers number 12 and somewhat minimally, number 22.
szunami commentedon Apr 18, 2021
I just opened bevyengine/bevy-website#133, very glad to see this kind of content being prioritized!
alice-i-cecile commentedon Apr 18, 2021
cart commentedon May 6, 2021
I think we can safely close this one out :)