Added with_component to EntityWorldMut, DeferredWorld, and World

[bushrat011899]

Objective

• Make working with immutable components more ergonomic
• Assist Make Parent and Children components immutable #16662

Solution

Added with_component to World and EntityWorldMut. This method "removes" a component from an entity, gives a mutable reference to it to a provided closure, and then "re-inserts" the component back onto the entity. This replacement triggers the OnReplace and OnInsert hooks, but does not cause an archetype move, as the removal is purely simulated.

Testing

• Added doc-tests and a unit test.

---

Showcase

use bevy_ecs::prelude::*;

/// An immutable component.
#[derive(Component, PartialEq, Eq, Debug)]
#[component(immutable)]
struct Foo(bool);

let mut world = World::default();

let mut entity = world.spawn(Foo(false));

assert_eq!(entity.get::<Foo>(), Some(&Foo(false)));

// Before the closure is executed, the `OnReplace` hooks/observers are triggered
entity.with_component(|foo: &mut Foo| {
    foo.0 = true;
});
// After the closure is executed, `OnInsert` hooks/observers are triggered

assert_eq!(entity.get::<Foo>(), Some(&Foo(true)));

Notes

• If the component is not available on the entity, the closure and hooks aren't executed, and None is returned. I chose this as an alternative to returning an error or panicking, but I'm open to changing that based on feedback.
• This relies on unsafe, in particular for accessing the Archetype to trigger hooks. All the unsafe operations are contained within DeferredWorld::with_component, and I would appreciate that this function is given special attention to ensure soundness.
• The OnAdd hook can never be triggered by this method, since the component must already be inserted. I have chosen to not trigger OnRemove, as I believe it makes sense that this method is purely a replacement operation, not an actual removal/insertion.

[chescock]

Would it make sense to have a with_component_by_id method that works with dynamic components?

... oh, there's no get_mut_assume_mutable_by_id. Should we add that?

[bushrat011899]

That definitely could make sense! I'd rather spin that into a follow-up if this gets accepted though.

[chescock]

Would it be useful to pass an EntityMutExcept<T> to let the closure access the other components on the entity?

Or maybe that's dangerous because we triggered the "on replace" hooks but didn't flush their commands, so f could see an inconsistent world?

[bushrat011899]

Yeah I see room for issues if you had access to the rest of the entity too. In my mind, if you need this you'd actually remove the component instead.

[Diddykonga]

What about component_scope?
Seems to match the functionality for that terminology.

[bushrat011899]

What about component_scope? Seems to match the functionality for that terminology.

The reason I chose with_component is World::resource_scope gives you access to the World still, whereas with_component does not give you access to the rest of the entity.