Commands::send_event

[robtfm]

Objective

sending events tends to be low-frequency so ergonomics can be prioritized over efficiency.
add Commands::send_event to send any type of event without needing a writer in hand.

i don't know how we feel about these kind of ergonomic things, i add this to all my projects and find it useful. adding mut this_particular_event_writer: EventWriter<ThisParticularEvent> every time i want to send something is unnecessarily cumbersome.
it also simplifies the "send and receive in the same system" pattern significantly.

basic example before:

fn my_func(
    q: Query<(Entity, &State)>,
    mut damage_event_writer: EventWriter<DamageEvent>,
    mut heal_event_writer: EventWriter<HealEvent>,
) {
    for (entity, state) in q.iter() {
        if let Some(damage) = state.get_damage() {
            damage_event_writer.send(DamageEvent { entity, damage });
        }

        if let Some(heal) = state.get_heal() {
            heal_event_writer.send(HealEvent { entity, heal });
        }
    }
}

basic example after:

import bevy::ecs::event::SendEventEx;

fn my_func(
    mut commands: Commands,
    q: Query<(Entity, &State)>,
) {
    for (entity, state) in q.iter() {
        if let Some(damage) = state.get_damage() {
            commands.send_event(DamageEvent { entity, damage });
        }

        if let Some(heal) = state.get_heal() {
            commands.send_event(HealEvent { entity, heal });
        }
    }
}

send/receive in the same system before:

fn send_and_receive_param_set(
    mut param_set: ParamSet<(EventReader<DebugEvent>, EventWriter<DebugEvent>)>,
) {
    // We must collect the events to resend, because we can't access the writer while we're iterating over the reader.
    let mut events_to_resend = Vec::new();

    // This is p0, as the first parameter in the `ParamSet` is the reader.
    for event in param_set.p0().read() {
        if event.resend_from_param_set {
            events_to_resend.push(event.clone());
        }
    }

    // This is p1, as the second parameter in the `ParamSet` is the writer.
    for mut event in events_to_resend {
        event.times_sent += 1;
        param_set.p1().send(event);
    }
}

after:

use bevy::ecs::event::SendEventEx;

fn send_via_commands_and_receive(
    mut reader: EventReader<DebugEvent>,
    mut commands: Commands,
) {
    for event in reader.read() {
        if event.resend_via_commands {
            commands.send_event(DebugEvent {
                times_sent: event.times_sent + 1,
                ..event.clone()
            });
        }
    }
}

[alice-i-cecile]

Since this is in bevy_ecs itself, we shouldn't use an extension trait.

I'm in favor of adding this though, provided we have a bit of docs laying out the drawbacks: I've seen this helper show up repeatedly in various projects I've reviewed.

The type-erased nature is genuinely useful for more complex patterns, and this is consistent with observers.

[alice-i-cecile]

FYI, #13818 adds another little helper for sending and receiving events in the same system.

[NiseVoid]

This pattern is indeed extremely common. Here's a few cursed variations from my game:

impl Command for MyEvent {
    fn apply(self, world: &mut World) {
        world.send_event(self);
    }
}

commands.add(|world: &mut World| world.send_event(event));

One possible footgun here could be that DeferredWorld has send_event but would also get commands().send_event, which would be less efficient.

[robtfm]

FYI, #13818 adds another little helper for sending and receiving events in the same system.

sorry, i don't see it?

One possible footgun here could be that DeferredWorld has send_event but would also get commands().send_event, which would be less efficient.

i can rename - i generally call it fire_event but i was trying to be a bit more vanilla with the naming..

[NiseVoid]

i can rename - i generally call it fire_event but i was trying to be a bit more vanilla with the naming..

I think send_event is fine, it does match better with the other ones, we can either assume people will know commands are slower, or have the docs tell people to use the one on World or DeferredWorld instead if they have access to it.

[ThomasAlban]

If this is merged, would it be the default way to send events or would there be 2 ways of doing the same thing? If so, which one would be preferred?

[alice-i-cecile]

The EventWriter approach is preferred: it has much lower overhead. The commands approach is good for lazy prototyping, cold loop code where you prefer the ergonomics, or working with heterogeneous event types.

[atornity]

thoughts on automatically registering the event type as well? So that people who use this pattern won't have to call App::add_event.

[alice-i-cecile]

We definitely shouldn't do that: add_event configures a specific kind of event clearing that not every event wants.

[robtfm]

We definitely shouldn't do that: add_event configures a specific kind of event clearing that not every event wants.

we could add it only if Events<E> isn't found; i believe the way to configure events manually is by adding the resource so it shouldn't interfere?

[janhohenheim]

Definitely wanted to use this pattern in the past for code running in unit tests! Thanks for the PR :)
No thoughts on the automatic registration of the passed event.
Got some minor suggestions before approval.

[alice-i-cecile]

Merging once CI is green: suggestions probably broke formatting.