bevyengine / bevyengine/bevy-website

Add section to book about `Mut` wrappers and the ergonomics

Open
#1,275 0 comments 0 reactions 0 assignees View on GitHub
A-Book C-Content
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.