Add World::trigger_ref and World::trigger_targets_ref (#14894)

# Objective

Closes #14888.

## Solution

Add non-consuming trigger functions:

```rust
impl World {
    pub fn trigger_ref(&mut self, event: &mut impl Event);
    pub fn trigger_targets_ref(&mut self, event: &mut impl Event, targets: impl TriggerTargets);
}
```

## Testing

- Added two new tests, `observer_trigger_ref` and
`observer_trigger_targets_ref`.

---------

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

crates/bevy_ecs/src/observer/mod.rs

@@ -349,16 +349,41 @@ impl World {
  self.spawn(Observer::new(system))
  }
 
- /// Triggers the given `event`, which will run any observers watching for it.
+ /// Triggers the given [`Event`], which will run any [`Observer`]s watching for it.
+ ///
+ /// While event types commonly implement [`Copy`],
+ /// those that don't will be consumed and will no longer be accessible.
+ /// If you need to use the event after triggering it, use [`World::trigger_ref`] instead.
  pub fn trigger(&mut self, event: impl Event) {
  TriggerEvent { event, targets: () }.trigger(self);
  }
 
- /// Triggers the given `event` for the given `targets`, which will run any observers watching for it.
+ /// Triggers the given [`Event`] as a mutable reference, which will run any [`Observer`]s watching for it.
+ ///
+ /// Compared to [`World::trigger`], this method is most useful when it's necessary to check
+ /// or use the event after it has been modified by observers.
+ pub fn trigger_ref(&mut self, event: &mut impl Event) {
+ TriggerEvent { event, targets: () }.trigger_ref(self);
+ }
+
+ /// Triggers the given [`Event`] for the given `targets`, which will run any [`Observer`]s watching for it.
+ ///
+ /// While event types commonly implement [`Copy`],
+ /// those that don't will be consumed and will no longer be accessible.
+ /// If you need to use the event after triggering it, use [`World::trigger_targets_ref`] instead.
  pub fn trigger_targets(&mut self, event: impl Event, targets: impl TriggerTargets) {
  TriggerEvent { event, targets }.trigger(self);
  }
 
+ /// Triggers the given [`Event`] as a mutable reference for the given `targets`,
+ /// which will run any [`Observer`]s watching for it.
+ ///
+ /// Compared to [`World::trigger_targets`], this method is most useful when it's necessary to check
+ /// or use the event after it has been modified by observers.
+ pub fn trigger_targets_ref(&mut self, event: &mut impl Event, targets: impl TriggerTargets) {
+ TriggerEvent { event, targets }.trigger_ref(self);
+ }
+
  /// Register an observer to the cache, called when an observer is created
  pub(crate) fn register_observer(&mut self, observer_entity: Entity) {
  // SAFETY: References do not alias.
@@ -507,6 +532,11 @@ mod tests {
  #[derive(Event)]
  struct EventA;
 
+ #[derive(Event)]
+ struct EventWithData {
+ counter: usize,
+ }
+
  #[derive(Resource, Default)]
  struct Order(Vec<&'static str>);
 
@@ -652,6 +682,39 @@ mod tests {
  );
  }
 
+ #[test]
+ fn observer_trigger_ref() {
+ let mut world = World::new();
+
+ world.observe(|mut trigger: Trigger<EventWithData>| trigger.event_mut().counter += 1);
+ world.observe(|mut trigger: Trigger<EventWithData>| trigger.event_mut().counter += 2);
+ world.observe(|mut trigger: Trigger<EventWithData>| trigger.event_mut().counter += 4);
+ // This flush is required for the last observer to be called when triggering the event,
+ // due to `World::observe` returning `WorldEntityMut`.
+ world.flush();
+
+ let mut event = EventWithData { counter: 0 };
+ world.trigger_ref(&mut event);
+ assert_eq!(7, event.counter);
+ }
+
+ #[test]
+ fn observer_trigger_targets_ref() {
+ let mut world = World::new();
+
+ world.observe(|mut trigger: Trigger<EventWithData, A>| trigger.event_mut().counter += 1);
+ world.observe(|mut trigger: Trigger<EventWithData, B>| trigger.event_mut().counter += 2);
+ world.observe(|mut trigger: Trigger<EventWithData, A>| trigger.event_mut().counter += 4);
+ // This flush is required for the last observer to be called when triggering the event,
+ // due to `World::observe` returning `WorldEntityMut`.
+ world.flush();
+
+ let mut event = EventWithData { counter: 0 };
+ let component_a = world.init_component::<A>();
+ world.trigger_targets_ref(&mut event, component_a);
+ assert_eq!(5, event.counter);
+ }
+
  #[test]
  fn observer_multiple_listeners() {
  let mut world = World::new();

crates/bevy_ecs/src/observer/trigger_event.rs

@@ -21,6 +21,13 @@ impl<E: Event, Targets: TriggerTargets> TriggerEvent<E, Targets> {
  }
 }
 
+impl<E: Event, Targets: TriggerTargets> TriggerEvent<&mut E, Targets> {
+ pub(super) fn trigger_ref(self, world: &mut World) {
+ let event_type = world.init_component::<E>();
+ trigger_event(world, event_type, self.event, self.targets);
+ }
+}
+
 impl<E: Event, Targets: TriggerTargets + Send + Sync + 'static> Command
  for TriggerEvent<E, Targets>
 {