Per entity Events

[alice-i-cecile]

Closes #2070. Introduces the ability to ergonomically store events as components on entities, creating an event channel like abstraction.

This PR is intended to be merged after #2145, which adds EventConsumer and contains assorted Event-related code cleanup.

Will be much improved by #2073; the example should be updated by whichever PR is merged second.

Adds:

1. Automatic event cleanup of componentized events when added via add_event.
2. An example of how you might use this pattern that covers both the sugary and explicit forms.
3. EventWriter query parameter.
4. EventReader query parameter, which stores per-entity data about which events have been read.
5. EventConsumer query parameter. See Add EventConsumer #2145.

To do:

• Add query parameters for EventWriter.
• Add query parameter for EventReader. Should probably wait for ParamState
• Add query parameters for EventConsumer.

For a follow-up PR, we should add a more complex example as a game. The current example is contrived and over-engineered, but at least demonstrates the functionality in an interactive way. In particular, I think it would be nice to demonstrate complex flows of events between entities by combining this feature with Relations. An interactive neural net demo would be a cute way to do so IMO.

[NathanSWard]

All of this formatting stuff should probably be its own PR?

[alice-i-cecile]

Probably. It was just a nuisance to do as a separate PR due to format-on-save settings in my IDE. I can split it though if you think it's worth it :/

[mockersf]

those tables should not be formatted that way actually, otherwise as soon as someone adds a new example with a longer column, you have to change all the lines which break the diff

[alice-i-cecile]

Sad. Okay, I'll fix it.

[mockersf]

Small change for nice feature 👍 (not small anymore)

I feel the example is overly complicated to show it though

[alice-i-cecile]

I feel the example is overly complicated to show it though

Yeah :/ I wasn't sure how to balance "not minimal" vs. "why would you ever want this" and ended up somewhere in the middle.

It might make sense to strip this down to the bare minimum somehow and then demonstrate its value in a game example.

[Nilirad]

Maybe entity_events is a more suitable name here, since, as far as I understand, "component" is quite a general term, that can include the concept of "resource" and "event" (which is a resource). Maybe this is not a concern for the public interface, but internally Events are Resources, and Resources are Components.

[mockersf]

I would be curious to know the perf and memory impact of using entity events

maybe the difference between

struct MyEvent(EntityId);
fn system(mut events: EventReader<MyEvent>, query: Query<Entity>) {
    for event in events.iter() {
        let entity = query.get(event.0).unwrap();
        do_something_with(entity);
    }
}

and

(note sure of the syntax needed here)

struct MyEvent;
fn system(query: Query<(Entity, &Events<MyEvent>)>, extra_parameter_needed_to_read_events: Something) {
    for (entity, events) in query.iter() {
        for event in events.iter(extra_parameter_needed_to_read_events) {
            do_something_with(entity);
        }
    }
}

[alice-i-cecile]

I would be curious to know the perf and memory impact of using entity events

Agreed, this would be a nice little benchmark to include. To be fair, I think we'll also want to vary how often we're searching through the list, since that's one of the most compelling uses of this pattern.

#2073 will also help our perf a ton.

[alice-i-cecile]

Closing this out; I'll make a new PR once we have an accepted RFC.