Add closure-based EntityEvent triggers (#21284)

# Objective

Some developers would prefer being able to trigger EntityEvents in the
old "chained" way.

## Solution

Add support for the following:

```rust
commands.entity(e1).trigger(|entity| Explode { entity })
// alternatively if From<Entity> is implemented
commands.entity(e1).trigger(Explode::from)
// alternatively if it is Explode(Entity)
commands.entity(e1).trigger(Explode)
```

---------

Co-authored-by: Alice Cecile <[email protected]>
Co-authored-by: akimakinai <[email protected]>
Co-authored-by: Jan Hohenheim <[email protected]>

Author: 4 people

crates/bevy_ecs/src/system/commands/mod.rs

@@ -2259,17 +2259,49 @@ impl<'a> EntityCommands<'a> {
         self.queue(entity_command::move_components::<B>(target))
     }
 
-    /// Deprecated. Use [`Commands::trigger`] instead.
+    /// Passes the current entity into the given function, and triggers the [`EntityEvent`] returned by that function.
+    ///
+    /// # Example
+    ///
+    /// A surprising number of functions meet the trait bounds for `event_fn`:
+    ///
+    /// ```rust
+    /// # use bevy_ecs::prelude::*;
+    ///
+    /// #[derive(EntityEvent)]
+    /// struct Explode(Entity);
+    ///
+    /// impl From<Entity> for Explode {
+    ///    fn from(entity: Entity) -> Self {
+    ///       Explode(entity)
+    ///    }
+    /// }
+    ///
+    ///
+    /// fn trigger_via_constructor(mut commands: Commands) {
+    ///     // The fact that `Epxlode` is a single-field tuple struct
+    ///     // ensures that `Explode(entity)` is a function that generates
+    ///     // an EntityEvent, meeting the trait bounds for `event_fn`.
+    ///     commands.spawn_empty().trigger(Explode);
+    ///
+    /// }
+    ///
+    ///
+    /// fn trigger_via_from_trait(mut commands: Commands) {
+    ///     // This variant also works for events like `struct Explode { entity: Entity }`
+    ///     commands.spawn_empty().trigger(Explode::from);
+    /// }
+    ///
+    /// fn trigger_via_closure(mut commands: Commands) {
+    ///     commands.spawn_empty().trigger(|entity| Explode(entity));
+    /// }
+    /// ```
     #[track_caller]
-    #[deprecated(
-        since = "0.17.0",
-        note = "Use Commands::trigger with an EntityEvent instead."
-    )]
-    pub fn trigger<'t, E: EntityEvent>(
+    pub fn trigger<'t, E: EntityEvent<Trigger<'t>: Default>>(
         &mut self,
-        event: impl EntityEvent<Trigger<'t>: Default>,
+        event_fn: impl FnOnce(Entity) -> E,
     ) -> &mut Self {
-        log::warn!("EntityCommands::trigger is deprecated and no longer triggers the event for the current EntityCommands entity. Use Commands::trigger instead with an EntityEvent.");
+        let event = (event_fn)(self.entity);
         self.commands.trigger(event);
         self
     }

crates/bevy_ecs/src/world/entity_ref.rs

@@ -3165,16 +3165,23 @@ impl<'w> EntityWorldMut<'w> {
         })
     }
 
-    /// Deprecated. Use [`World::trigger`] instead.
+    /// Passes the current entity into the given function, and triggers the [`EntityEvent`] returned by that function.
+    /// See [`EntityCommands::trigger`] for usage examples
+    ///
+    /// [`EntityCommands::trigger`]: crate::system::EntityCommands::trigger
     #[track_caller]
-    #[deprecated(
-        since = "0.17.0",
-        note = "Use World::trigger with an EntityEvent instead."
-    )]
-    pub fn trigger<'t>(&mut self, event: impl EntityEvent<Trigger<'t>: Default>) -> &mut Self {
-        log::warn!("EntityWorldMut::trigger is deprecated and no longer triggers the event for the current EntityWorldMut entity. Use World::trigger instead with an EntityEvent.");
+    pub fn trigger<'t, E: EntityEvent<Trigger<'t>: Default>>(
+        &mut self,
+        event_fn: impl FnOnce(Entity) -> E,
+    ) -> &mut Self {
+        let mut event = (event_fn)(self.entity);
+        let caller = MaybeLocation::caller();
         self.world_scope(|world| {
-            world.trigger(event);
+            world.trigger_ref_with_caller(
+                &mut event,
+                &mut <E::Trigger<'_> as Default>::default(),
+                caller,
+            );
         });
         self
     }