Rename Trigger to On

[Jondolf]

Objective

Currently, the observer API looks like this:

app.add_observer(|trigger: Trigger<Explode>| {
    info!("Entity {} exploded!", trigger.target());
});

Future plans for observers also include "multi-event observers" with a trigger that looks like this (see Cart's example):

trigger: Trigger<(
    OnAdd<Pressed>,
    OnRemove<Pressed>,
    OnAdd<InteractionDisabled>,
    OnRemove<InteractionDisabled>,
    OnInsert<Hovered>,
)>,

In scenarios like this, there is a lot of repetition of On. These are expected to be very high-traffic APIs especially in UI contexts, so ergonomics and readability are critical.

By renaming Trigger to On, we can make these APIs read more cleanly and get rid of the repetition:

app.add_observer(|trigger: On<Explode>| {
    info!("Entity {} exploded!", trigger.target());
});

trigger: On<(
    Add<Pressed>,
    Remove<Pressed>,
    Add<InteractionDisabled>,
    Remove<InteractionDisabled>,
    Insert<Hovered>,
)>,

Names like On<Add<Pressed>> emphasize the actual event listener nature more than Trigger<OnAdd<Pressed>>, and look cleaner. This also frees up the Trigger name if we want to use it for the observer event type, splitting them out from buffered events (bikeshedding this is out of scope for this PR though).

For prior art: bevy_eventlistener used On for its event listener type. Though in our case, the observer is the event listener, and On is just a type containing information about the triggered event.

Solution

Steal from bevy_event_listener by @aevyrie and use On.

• Rename Trigger to On
• Rename OnAdd to Add
• Rename OnInsert to Insert
• Rename OnReplace to Replace
• Rename OnRemove to Remove
• Rename OnDespawn to Despawn

Discussion

Naming Conflicts??

Using a name like Add might initially feel like a very bad idea, since it risks conflict with core::ops::Add. However, I don't expect this to be a big problem in practice.

• You rarely need to actually implement the Add trait, especially in modules that would use the Bevy ECS.
• In the rare cases where you do get a conflict, it is very easy to fix by just disambiguating, for example using ops::Add.
• The Add event is a struct while the Add trait is a trait (duh), so the compiler error should be very obvious.

For the record, renaming OnAdd to Add, I got exactly zero errors or conflicts within Bevy itself. But this is of course not entirely representative of actual projects using Bevy.

You might then wonder, why not use Added? This would conflict with the Added query filter, so it wouldn't work. Additionally, the current naming convention for observer events does not use past tense.

Documentation

This does make documentation slightly more awkward when referring to On or its methods. Previous docs often referred to Trigger::target or "sends a Trigger" (which is... a bit strange anyway), which would now be On::target and "sends an observer Event".

You can see the diff in this PR to see some of the effects. I think it should be fine though, we may just need to reword more documentation to read better.

[github-actions]

It looks like your PR has been selected for a highlight in the next release blog post, but you didn't provide a release note.

Please review the instructions for writing release notes, then expand or revise the content in the release notes directory to showcase your changes.

[Jondolf]

Marked as X-Blessed as per Cart's message on Discord earlier, but feel free to change :)

[NthTensor]

bevy_eventlistener is dead, long live bevy_eventlistener. Everything old is new again. Time is a flat circle.

I do think this is a better design.

[Jondolf]

To ease migration, I've added the OnX versions back as deprecated type aliases with the intent to fully remove them in 0.18. But let me know if I should leave them out

[alice-i-cecile]

To ease migration, I've added the OnX versions back as deprecated type aliases with the intent to fully remove them in 0.18. But let me know if I should leave them out

This is perfect, thank you. Can you do the same for Trigger please? This is relatively high impact so I'd like to cross my t's and dot my i's, as it were ;)

[Jondolf]

Done!