bevyengine / bevyengine/bevy-website
Add section to book about `Mut` wrappers and the ergonomics
- Dominant language
- JavaScript
- Stars
- 249
- Forks
- 450
- Avg merge
- 16h 20m
- Merged PRs (30d)
- 6
Description
> So what you're running into is when you request a `&mut Position` in your system, Bevy hands you `Mut` instead.
>
> [`Mut`](https://docs.rs/bevy/latest/bevy/ecs/change_detection/struct.Mut.html) is a "smart pointer" used to implement change detection. When it's mutably dereferenced, Bevy says "hey, this value was probably changed!". The downside of this is that the ergonomics are sometimes surprising.
>
> `Mut` implements `Deref` and `DerefMut`, so fields and methods are "forwarded" to the internal type. That's why setting the field values works. But to assign to the internal value (and not the smart pointer), you need to dereference it first. Same with doing things like adding or subtracting the values with straightforward trait impls
- by [me](https://discord.com/channels/691052431525675048/691052431974465548/1246565347377680515)
We should probably talk about matching as well.
I'm not sure what section of the book this belongs in, maybe a "frequently encountered problems" section? Maybe an aside in the section on queries?
Contributor guide
Research direction
Start with the Bevy book's query section and the linked `Mut` documentation. Decide whether this belongs in a frequently encountered problems section or as an aside, then cover `Mut` dereferencing ergonomics and matching. Done means the section is placed appropriately and explains the stated surprises clearly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100