Flush commands after every mutation in WorldEntityMut

[nakedible]

Objective

• Currently adding observers spawns an entity which implicitly flushes the command queue, which can cause undefined behaviour if the WorldEntityMut is used after this
• The reason WorldEntityMut attempted to (unsuccessfully) avoid flushing commands until finished was that such commands may move or despawn the entity being referenced, invalidating the cached location.
• With the introduction of hooks and observers, this isn't sensible anymore as running the commands generated by hooks immediately is required to maintain correct ordering of operations and to not expose the world in an inconsistent state
• Objective is to make command flushing deterministic and fix the related issues
• Fixes observe on WorldEntityMut may cause the reference to be invalidated #16212
• Fixes Commands apply at unexpected times with exclusive World access #14621
• Fixes Commands queued by component hooks are not applied during exclusive world access #16034

Solution

• Allow WorldEntityMut to exist even when it refers to a despawned entity by allowing EntityLocation to be marked invalid
• Add checks to all methods to warn if trying to access a despawned entity, but behave as if entity wouldn't have any components
• Flush command queue after every operation that might trigger hooks or observers
• Update entity location always after flushing command queue

Testing

• Added test cases for currently broken behaviour
• Added test cases that flushes happen in all operations
• Added test cases to ensure hooks and commands are run exactly in correct order when nested

---

Migration Guide

FIXME: Is a note desired to let users know about the extra flushes and change in behaviour?

[alice-i-cecile]

Yes please, I'd like a small Migration Guide note here.

[maniwani]

Yes, this is pretty much what I was thinking. I assume branch prediction should hide any overhead from this since the condition should basically never be true.

I think hitting this case should issue a warning. And we might want to have a #[track_caller] on the affected EntityWorldMut methods so that anyone who sees the warning knows where to start looking.

Something like...

#[inline(never)]
#[cold]
fn on_entity_invalid(entity: Entity, caller: &'static Location) {
    warn!("error[B<insert-error-number-here>]: {caller} tried to modify the entity {:?}, but it no longer exists. See: https://bevyengine.org/learn/errors/b<insert-error-number-here>", entity);
}

[maniwani]

Ah, wait. Since EntityWorldMut can be converted into the other kinds of entity references, we may need to add the invalid location check to them as well (or make the conversion fallible).

Some of the UnsafeEntityCell methods those references use probably assume its location is valid.

[nakedible]

warn or warn_once?