Add methods Observer::with_entities and Observer::watch_entities (#20274)

# Objective

From time to time, I find myself observing multiple entities with the
same `Observer`. Right now this can only be achieved by calling
[`with_entity`](https://docs.rs/bevy/latest/bevy/ecs/observer/struct.Observer.html#method.with_entity)
or
[`watch_entity`](https://docs.rs/bevy/latest/bevy/ecs/observer/struct.Observer.html#method.watch_entity)
for each entity to watch. This PR provides versions of these two methods
to watch multiple entities with a single call.

## Testing

Added a simple test.

---------

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

Author: gwafotapa

crates/bevy_ecs/src/observer/distributed_storage.rs

@@ -200,8 +200,7 @@ use crate::prelude::ReflectComponent;
 ///
 /// Note that the [`Observer`] component is not added to the entity it is observing. Observers should always be their own entities!
 ///
-/// You can call [`Observer::watch_entity`] more than once, which allows you to watch multiple entities with the same [`Observer`].
-/// serves as the "source of truth" of the observer.
+/// You can call [`Observer::watch_entity`] more than once or [`Observer::watch_entities`] to watch multiple entities with the same [`Observer`].
 ///
 /// [`SystemParam`]: crate::system::SystemParam
 pub struct Observer {
@@ -269,28 +268,44 @@ impl Observer {
         }
     }
 
-    /// Observe the given `entity`. This will cause the [`Observer`] to run whenever the [`Event`] is triggered
-    /// for the `entity`.
+    /// Observes the given `entity` (in addition to any entity already being observed).
+    /// This will cause the [`Observer`] to run whenever the [`Event`] is triggered for the `entity`.
+    /// Note that if this is called _after_ an [`Observer`] is spawned, it will produce no effects.
     pub fn with_entity(mut self, entity: Entity) -> Self {
-        self.descriptor.entities.push(entity);
+        self.watch_entity(entity);
         self
     }
 
-    /// Observe the given `entity`. This will cause the [`Observer`] to run whenever the [`Event`] is triggered
-    /// for the `entity`.
+    /// Observes the given `entities` (in addition to any entity already being observed).
+    /// This will cause the [`Observer`] to run whenever the [`Event`] is triggered for any of these `entities`.
+    /// Note that if this is called _after_ an [`Observer`] is spawned, it will produce no effects.
+    pub fn with_entities<I: IntoIterator<Item = Entity>>(mut self, entities: I) -> Self {
+        self.watch_entities(entities);
+        self
+    }
+
+    /// Observes the given `entity` (in addition to any entity already being observed).
+    /// This will cause the [`Observer`] to run whenever the [`Event`] is triggered for the `entity`.
     /// Note that if this is called _after_ an [`Observer`] is spawned, it will produce no effects.
     pub fn watch_entity(&mut self, entity: Entity) {
         self.descriptor.entities.push(entity);
     }
 
-    /// Observe the given `component`. This will cause the [`Observer`] to run whenever the [`Event`] is triggered
+    /// Observes the given `entity` (in addition to any entity already being observed).
+    /// This will cause the [`Observer`] to run whenever the [`Event`] is triggered for any of these `entities`.
+    /// Note that if this is called _after_ an [`Observer`] is spawned, it will produce no effects.
+    pub fn watch_entities<I: IntoIterator<Item = Entity>>(&mut self, entities: I) {
+        self.descriptor.entities.extend(entities);
+    }
+
+    /// Observes the given `component`. This will cause the [`Observer`] to run whenever the [`Event`] is triggered
     /// with the given component target.
     pub fn with_component(mut self, component: ComponentId) -> Self {
         self.descriptor.components.push(component);
         self
     }
 
-    /// Observe the given `event_key`. This will cause the [`Observer`] to run whenever an event with the given [`EventKey`]
+    /// Observes the given `event_key`. This will cause the [`Observer`] to run whenever an event with the given [`EventKey`]
     /// is triggered.
     /// # Safety
     /// The type of the `event_key` [`EventKey`] _must_ match the actual value
@@ -300,7 +315,7 @@ impl Observer {
         self
     }
 
-    /// Set the error handler to use for this observer.
+    /// Sets the error handler to use for this observer.
     ///
     /// See the [`error` module-level documentation](crate::error) for more information.
     pub fn with_error_handler(mut self, error_handler: fn(BevyError, ErrorContext)) -> Self {

crates/bevy_ecs/src/observer/mod.rs

@@ -1381,4 +1381,22 @@ mod tests {
         assert_eq!(4, *counter.0.get(&a_id).unwrap());
         assert_eq!(3, *counter.0.get(&b_id).unwrap());
     }
+
+    #[test]
+    fn observer_watch_entities() {
+        let mut world = World::new();
+        world.init_resource::<Order>();
+        let entities = world
+            .spawn_batch(core::iter::repeat_n((), 4))
+            .collect::<Vec<_>>();
+        let observer = Observer::new(|_: On<EventA>, mut order: ResMut<Order>| {
+            order.observed("a");
+        });
+        world.spawn(observer.with_entities(entities.iter().copied().take(2)));
+
+        world.trigger_targets(EventA, [entities[0], entities[1]]);
+        assert_eq!(vec!["a", "a"], world.resource::<Order>().0);
+        world.trigger_targets(EventA, [entities[2], entities[3]]);
+        assert_eq!(vec!["a", "a"], world.resource::<Order>().0);
+    }
 }

release-content/release-notes/observer_overhaul.md

@@ -1,7 +1,7 @@
 ---
 title: Observer Overhaul
-authors: ["@Jondolf", "@alice-i-cecile", "@hukasu", "oscar-benderstone", "Zeophlite"]
-pull_requests: [19596, 19663, 19611, 19935]
+authors: ["@Jondolf", "@alice-i-cecile", "@hukasu", "oscar-benderstone", "Zeophlite", "gwafotapa"]
+pull_requests: [19596, 19663, 19611, 19935, 20274]
 ---
 
 ## Rename `Trigger` to `On`
@@ -50,3 +50,7 @@ this opens up the possibility for the debug tools to show more meaningful names
 
 Internally, each `Event` type would generate a `Component` type, allowing us to use the corresponding `ComponentId` to track the event.
 We have newtyped this to `EventKey` to help separate these concerns.
+
+## Watch multiple entities
+
+To watch multiple entities with the same observer you previously had to call `Observer::with_entity` or `Observer::watch_entity` for each entity. New methods `Observer::with_entities` and `Observer::watch_entities` have been added for your convenience.