Refactor EntityEvent to support ContainsEntity

[Zeenobit]

This is related to #21384

Objective

The goal of this change is to enable EntityEvent to work with any Entity-like type which implements ContainsEntity.

Solution

• Change return type of EntityEvent::event_target from Entity to &impl ContainsEntity
• Change all appropriate call sites to use event_target().entity() instead of event_target()
• Refactor EntityEvent::event_target_mut into EntityEvent::set_event_target

I'm not fully happy with this solution yet, but I'm opening the PR to discuss the options from here.

Mainly the issue revolves around set_event_target. To make this work, we need the underlying type to be constructible from an entity. This may not always be safe from user's perspective (it wouldn't be with Instance<T> for example).

Based on my understanding of the system, an event's target is only mutated in the case of event propagation, which makes sense.

To work around this, I propose that we flag EntityEvents as immutable or not; or "not propagatable" or not (I'm open to other terminology! :P).

This would allow us to implement set_event_target as unreachable()! and throw an error instead if the user tries to propagate such an event. We could even maybe enforce this compile time but it'll require additional complexity (mostly in form of different permutations of trigger_* method family).

Testing

• Added test_derive_entity_event to cover all permutations

[github-actions]

It looks like your PR is a breaking change, but you didn't provide a migration guide.

Please review the instructions for writing migration guides, then expand or revise the content in the migration guides directory to reflect your changes.

[alice-i-cecile]

&impl ContainsEntity

I'm reluctant to do this as it will break object safety. That will be a pretty widespread problem when trying to fix this though.

[Zeenobit]

I'm reluctant to do this as it will break object safety. That will be a pretty widespread problem when trying to fix this though.

It won't be needed with @cart 's suggestion. I'll revise the CL.

How do we feel about immutable entity events though?

[alice-i-cecile]

How do we feel about immutable entity events though?

Generally open to it, but haven't thought about this hard enough to be convinced that they're the only solution :)

[Zeenobit]

I've updated the PR with the simplified implementation. Great idea! :)

Generally open to it, but haven't thought about this hard enough to be convinced that they're the only solution :)

I'm open to suggestions!

From my usage of the engine so far, I have yet to find a use case for propagating events, which as I understand, is the only reason entity events are mutable.

So from my perspective, I could easily envision all entity events being immutable by default, and only mutable if #[entity_event(propagate)] is specified. Attempting to propagate an event not flagged with #[entity_event(propagate)] seems like a degenerate case to me, and so we could easily treat it as an error.

If we do that, we could then implement set_event_target with unreachable!() for immutable events, since it would never be called. Additionally, I would go as far as marking set_event_target as unsafe. In my mind, this function should never be called externally.