Add insertion/removal reason to lifecycle events

[Jondolf]

What problem does this solve or what need does it fill?

My physics engine Avian has a lot of state management logic that uses observers or hooks. This logic must be robust, or the simulation can crash or otherwise fail due to invariants not being upheld.

Several instances of this need to know whether Add or Insert was triggered because the entity was spawned, or because the component was explicitly inserted via insert after spawn. Or similarly, whether Replace or Remove was triggered because the entity was despawned, or because the component was explicitly removed via remove.

As an example: When Disabled is removed from a collider entity, I need to insert the collider back into a BVH for it to participate in collision detection. However, if the removal actually happened because the entity was despawned, I don't want to do this, or I'd be inserting a non-existent entity into the BVH. I cannot check if the entity really exists in the Remove observer, because at that point, queries still have access to the entity. I could first insert the entity and then remove it in a Despawn observer, but this is just unnecessary work that can get costly for bulk removal.

What solution would you like?

• InsertionReason enum for Add and Insert, with Spawned and Inserted variants
• RemovalReason enum for Replace and Remove, with Despawned and Inserted variants

Naming can be bikeshed, and we could also make these bools or bitflags if we wanted to, though I think an enum makes the most sense.

We should probably add these for the on_add, on_insert, on_replace, and on_remove hooks as well. However these don't currently have their own types where we could store the property without breaking changes, so it might be more controversial. I have less personal need for this right now, so I would be content with only providing the reason enums for observers.

What alternative(s) have you considered?

You can sometimes work around the problem by (ab)using the fact that e.g. Replace runs before Remove, and split logic into several different observers, but it's ugly and often increases overhead. I haven't figured out a good general alternative.

I don't know if/how flecs solves this, but it could be useful to look at them for guidance too.

[alice-i-cecile]

I'm strongly in favor of this, assuming we don't seriously regress performance in cases where this information is not desired.

I think that we could probably improve this via something like #20817, or some splitting / renaming (see #20188), but this is a solid backwards-compatible improvement. IMO performance is the only reason why we might not want to do this.

[urben1680]

For my reversible crate I keep mentioning but never get around getting to a public release the undo/redo step also triggers hooks or observers of components getting reinserted or removed. I think it is interesting for the user to find out about that within a hook, so I made something like an enum mentioned here. In my crate this enum is a resource and I have something like a... reverse resource scope with it. RevOp::Undo.scope(world, |world| { world.spawn(Foo); } for example spawns an entity with Foo and its hook will here now find RevOp::Undo in the resources.

Obviously this is not an ideal first party solution, and not fully equivalent with the issue here. But might be a temporal fix for until this here gets an implementation.

On a personal note, it is a bit weird hooks/observers cover multiple cases. Like there are situations where both insert and add run, and situations where it is only insert. Adding an enum here to distinguish the case for insert seems like a band-aid. I would like more if we could say "run this fn in these specific situations". Then you do not need to check some enum, your hook simple does not trigger for when you do want it to. But that is just a quick idea that might not be good for several reasons.

[Jondolf]

Sander on Discord (link) about how flecs solves this:

Observers have access to the destination archetype. If it’s a despawn it will be set to null