Add methods to bulk replace relationships on a entity

[Brezak]

Objective

Add a way to efficiently replace a set of specifically related entities with a new set.
Closes #18041

Solution

Add new replace_(related/children) to EntityWorldMut and friends.

Testing

Added a new test to hierarchy.rs that specifically check if replace_children actually correctly replaces the children on a entity while keeping the original one.

---

Showcase

EntityWorldMut and EntityCommands can now be used to efficiently replace the entities a entity is related to.

/// `parent` has 2 children. `entity_a` and `entity_b`.
assert_eq!([entity_a, entity_b], world.entity(parent).get::<Children>());

/// Replace `parent`s children with `entity_a` and `entity_c`
world.entity_mut(parent).replace_related(&[entity_a, entity_c]);

/// `parent` now has 2 children. `entity_a` and `entity_c`.
///
/// `replace_children` has saved time by not removing and reading
/// the relationship between `entity_a` and `parent`
assert_eq!([entity_a, entity_c], world.entity(parent).get::<Children>());

[villor]

A problem with this approach is that the resulting target collection may not result in the same order as the passed in related.

As a user of replace_related I would assume I can pass in a new order of the same set of entities to reorder them (for relationships requiring a stable ordering, e.g. Children).

I'm also curious about the performance benefits of this approach (allocating hashsets) over just removing the target collection and calling add_children (archetype moves?).

[viridia]

In the original issue I posted (#18041), I proposed a method to do this without using hash sets, however it entails a more complex API in which the caller does the work of determining which entities are added and removed. This puts the responsibility on the caller to ensure that the arguments are consistent.

In my various reactive experiments, I need to do this computation anyway (for example foreach computes the diff as part of its operation), so it's relatively easy for me to pass that information along to the replace_related API. Having replace_related do the calculation internally means that the set operations get done twice.

That being said, I may be overly/prematurely optimizing here. Maybe using hash sets is OK? I can't really say one way or the other.

[villor]

Maybe an optimized replace could benefit from the new RelationshipInsertHookMode in #17858

[villor]

I'm not too fond of requiring the user to pass correct lists. Seems like this can easily be misunderstood/lead to bugs.

For more specialized scenarios (like tree rendering mechanisms) where the caller already knows the “diff”, there could be an alternative function taking the new_related and deleted with a name that communicates the “riskiness”.

Or those use cases can update the relationship components directly, and use the hook mode to avoid archetype moves.

[Brezak]

A problem with this approach is that the resulting target collection may not result in the same order as the passed in related.

We could directly modify the target collection to change the ordering but that would conflict with users overriding relationship on_insert hooks. My opinion is that a user will break any assumptions we make if given the chance. Imagine for example a on_insert hook that filters what entities can be inserted into a relationship. If we then manually insert entities into this collection we would be bypassing this filtering.

For more specialized scenarios (like tree rendering mechanisms) where the caller already knows the “diff”, there could be an alternative function taking the new_related and deleted with a name that communicates the “riskiness”.

I'd be willing to add this method too, but such a method requires #17858. Otherwise the method would be left with just calculating a difference between the insert and remove entity sets and inserting that (if we add any existing relationships the on_add hook will cause a double insert). Exactly what the current implementation does (and calculating a difference either requires a allocated set or the ability to sort the passed in slices. i.e. either allocating or breaking ordering).

[alice-i-cecile]

#17858 has been merged now :)

[viridia]

Looks good. This will be a fundamental building block for entity templating systems.

[Brezak]

This is mostly done. The documentation needs some editing and the naming could use some bikeshedding. Sadly I'm spent for today. See you tomorrow.

[villor]

Nice job on the optimized version! 👍 Really liking the debug_assertions too.

Still have some concerns about the ordering for replace_related. And some minor perf comments etc.

[Brezak]

This should be done now. There's still some performance left on the table (see #18300) but otherwise everything works and tests pass.

One thing we should do is write down all the assumptions we make about relationship hooks. They're currently publicly accessible and a motivated user could override them and make them do some wild stuff. Alternatively we could add #[doc(hidden)] to them.

[villor]

LGTM 👍

[villor]

One thing we should do is write down all the assumptions we make about relationship hooks. They're currently publicly accessible and a motivated user could override them and make them do some wild stuff. Alternatively we could add #[doc(hidden)] to them.

I don't think hooks are overridable. And the derive macro stops you from adding hooks that are already used for relationship components.

[Brezak]

I don't think hooks are overridable. And the derive macro stops you from adding hooks that are already used for relationship components.

We allow users to impl Component without the macro. We even have an example doing just that. And if a user is doing that they would also need to manually implement the Relationship trait at which point they can override whatever they want.

[alice-i-cecile]

Sensible and well-tested. I've fixed a grammar issue, but now I'm comfortable merging this.