Observer EventPatterns

[ItsDoot]

Objective

On<E, B>'s B type parameter is the single most commonly confusing construct in bevy_ecs. The predominate use case is for filtering lifecycle event observers:

world.add_observer(|on: On<Add, A>| {
    // gets fired whenever component `A` is added to an entity
});

For most other use cases, like picking or custom user events, this type parameter is wholly unnecessary.

Therefore, it should be removed from view for the cases where it is not needed.

Solution

Introduce a tiny layer above Event called EventPattern, and update On's bounds:

pub trait EventPattern: 'static {
    type Event: Event;
    type Components: Bundle;
}

pub struct On<'w, 't, E: EventPattern> {
    observer: Entity,
    event: &'w mut E::Event,
    trigger: &'w mut EventPatternTrigger<'t, E>,
    trigger_context: &'w TriggerContext,
}

This allows us to lift the B type parameter in On<E, B> into the E type parameter. To ensure other events like picking continue to work, we introduce a blanket implementation for all Events:

// All events are implicitly EventPatterns, with no additional components.
impl<E: Event> EventPattern for E {
    type Event = Self;
    type Components = ();
}

To facilitate lifecycle events, we first rename them as follows:

• Add -> AddEvent
• Insert -> InsertEvent
• Discard -> DiscardEvent
• Remove -> RemoveEvent
• Despawn -> DespawnEvent

Then, we introduce new generic types in place of those old identifiers that are EventPatterns:

pub struct Add<B: Bundle>(PhantomData<B>);

impl<B: Bundle> EventPattern for Add<B> {
    type Event = AddEvent;
    type Components = B;
}

pub struct Insert<B: Bundle>(PhantomData<B>);

impl<B: Bundle> EventPattern for Insert<B> {
    type Event = InsertEvent;
    type Components = B;
}

pub struct Discard<B: Bundle>(PhantomData<B>);

impl<B: Bundle> EventPattern for Discard<B> {
    type Event = DiscardEvent;
    type Components = B;
}

pub struct Remove<B: Bundle>(PhantomData<B>);

impl<B: Bundle> EventPattern for Remove<B> {
    type Event = RemoveEvent;
    type Components = B;
}

pub struct Despawn<B: Bundle>(PhantomData<B>);

impl<B: Bundle> EventPattern for Despawn<B> {
    type Event = DespawnEvent;
    type Components = B;
}

This results in a slightly modified observer setup:

world.add_observer(|on: On<Add<A>>| {
    // gets fired whenever component `A` is added to an entity
});

Testing

No new tests have been added, we have decent coverage of observer tests as is.

[james-j-obrien]

Cool approach! Looks good.

[Diddykonga]

LGTM

Abstracts the E: Event and B: Bundle from On<E, B> into On<E> where E: EventMatcher
This allows the syntax to be like Add<C>, while the actual semantics use the Event and Components associated types on the EventMatcher. Similiar-ish to an custom WorldQuery.

[chescock]

Nice, this is an elegant way to solve this! I like how a bunch of B generics disappeared from places that don't care about them.

[alice-i-cecile]

I'm curious about the answers to @chescock's questions :)

FYI, I'm planning to hold off merging this until after we cut the 0.19-rc, so we can land this together with a F: QueryFilter generic in 0.20.

[SpecificProtagonist]

I think this section needs to be updated slightly?