Rename trigger.entity() to trigger.target() (bevyengine#16716)

# Objective

- A `Trigger` has multiple associated `Entity`s - the entity observing
the event, and the entity that was targeted by the event.
- The field `entity: Entity` encodes no semantic information about what
the entity is used for, you can already tell that it's an `Entity` by
the type signature!

## Solution

- Rename `trigger.entity()` to `trigger.target()`

---

## Changelog

- `Trigger`s are associated with multiple entities. `Trigger::entity()`
has been renamed to `Trigger::target()` to reflect the semantics of the
entity being returned.

## Migration Guide

- Rename `Trigger::entity()` to `Trigger::target()`.
- Rename `ObserverTrigger::entity` to `ObserverTrigger::target`

Author: aevyrie

crates/bevy_ecs/README.md

@@ -340,8 +340,8 @@ let mut world = World::new();
 let entity = world.spawn_empty().id();
 
 world.add_observer(|trigger: Trigger<Explode>, mut commands: Commands| {
-    println!("Entity {:?} goes BOOM!", trigger.entity());
-    commands.entity(trigger.entity()).despawn();
+    println!("Entity {:?} goes BOOM!", trigger.target());
+    commands.entity(trigger.target()).despawn();
 });
 
 world.flush();

crates/bevy_ecs/src/observer/mod.rs

@@ -67,9 +67,22 @@ impl<'w, E, B: Bundle> Trigger<'w, E, B> {
         Ptr::from(&self.event)
     }
 
-    /// Returns the [`Entity`] that triggered the observer, could be [`Entity::PLACEHOLDER`].
-    pub fn entity(&self) -> Entity {
-        self.trigger.entity
+    /// Returns the [`Entity`] that was targeted by the `event` that triggered this observer. It may
+    /// be [`Entity::PLACEHOLDER`].
+    ///
+    /// Observable events can target specific entities. When those events fire, they will trigger
+    /// any observers on the targeted entities. In this case, the `target()` and `observer()` are
+    /// the same, because the observer that was triggered is attached to the entity that was
+    /// targeted by the event.
+    ///
+    /// However, it is also possible for those events to bubble up the entity hierarchy and trigger
+    /// observers on *different* entities, or trigger a global observer. In these cases, the
+    /// observing entity is *different* from the entity being targeted by the event.
+    ///
+    /// This is an important distinction: the entity reacting to an event is not always the same as
+    /// the entity triggered by the event.
+    pub fn target(&self) -> Entity {
+        self.trigger.target
     }
 
     /// Returns the components that triggered the observer, out of the
@@ -207,7 +220,7 @@ pub struct ObserverTrigger {
     /// The [`ComponentId`]s the trigger targeted.
     components: SmallVec<[ComponentId; 2]>,
     /// The entity the trigger targeted.
-    pub entity: Entity,
+    pub target: Entity,
 }
 
 impl ObserverTrigger {
@@ -277,7 +290,7 @@ impl Observers {
     pub(crate) fn invoke<T>(
         mut world: DeferredWorld,
         event_type: ComponentId,
-        entity: Entity,
+        target: Entity,
         components: impl Iterator<Item = ComponentId> + Clone,
         data: &mut T,
         propagate: &mut bool,
@@ -304,7 +317,7 @@ impl Observers {
                     observer,
                     event_type,
                     components: components.clone().collect(),
-                    entity,
+                    target,
                 },
                 data.into(),
                 propagate,
@@ -314,8 +327,8 @@ impl Observers {
         observers.map.iter().for_each(&mut trigger_observer);
 
         // Trigger entity observers listening for this kind of trigger
-        if entity != Entity::PLACEHOLDER {
-            if let Some(map) = observers.entity_observers.get(&entity) {
+        if target != Entity::PLACEHOLDER {
+            if let Some(map) = observers.entity_observers.get(&target) {
                 map.iter().for_each(&mut trigger_observer);
             }
         }
@@ -328,8 +341,8 @@ impl Observers {
                     .iter()
                     .for_each(&mut trigger_observer);
 
-                if entity != Entity::PLACEHOLDER {
-                    if let Some(map) = component_observers.entity_map.get(&entity) {
+                if target != Entity::PLACEHOLDER {
+                    if let Some(map) = component_observers.entity_map.get(&target) {
                         map.iter().for_each(&mut trigger_observer);
                     }
                 }
@@ -733,20 +746,20 @@ mod tests {
         world.add_observer(
             |obs: Trigger<OnAdd, A>, mut res: ResMut<Order>, mut commands: Commands| {
                 res.observed("add_a");
-                commands.entity(obs.entity()).insert(B);
+                commands.entity(obs.target()).insert(B);
             },
         );
         world.add_observer(
             |obs: Trigger<OnRemove, A>, mut res: ResMut<Order>, mut commands: Commands| {
                 res.observed("remove_a");
-                commands.entity(obs.entity()).remove::<B>();
+                commands.entity(obs.target()).remove::<B>();
             },
         );
 
         world.add_observer(
             |obs: Trigger<OnAdd, B>, mut res: ResMut<Order>, mut commands: Commands| {
                 res.observed("add_b");
-                commands.entity(obs.entity()).remove::<A>();
+                commands.entity(obs.target()).remove::<A>();
             },
         );
         world.add_observer(|_: Trigger<OnRemove, B>, mut res: ResMut<Order>| {
@@ -915,7 +928,7 @@ mod tests {
             .spawn_empty()
             .observe(|_: Trigger<EventA>| panic!("Trigger routed to non-targeted entity."));
         world.add_observer(move |obs: Trigger<EventA>, mut res: ResMut<Order>| {
-            assert_eq!(obs.entity(), Entity::PLACEHOLDER);
+            assert_eq!(obs.target(), Entity::PLACEHOLDER);
             res.observed("event_a");
         });
 
@@ -940,7 +953,7 @@ mod tests {
             .observe(|_: Trigger<EventA>, mut res: ResMut<Order>| res.observed("a_1"))
             .id();
         world.add_observer(move |obs: Trigger<EventA>, mut res: ResMut<Order>| {
-            assert_eq!(obs.entity(), entity);
+            assert_eq!(obs.target(), entity);
             res.observed("a_2");
         });
 
@@ -1247,7 +1260,7 @@ mod tests {
 
         world.add_observer(
             |trigger: Trigger<EventPropagating>, query: Query<&A>, mut res: ResMut<Order>| {
-                if query.get(trigger.entity()).is_ok() {
+                if query.get(trigger.target()).is_ok() {
                     res.observed("event");
                 }
             },

crates/bevy_ecs/src/observer/runner.rs

@@ -197,8 +197,8 @@ pub type ObserverRunner = fn(DeferredWorld, ObserverTrigger, PtrMut, propagate:
 /// struct Explode;
 ///
 /// world.add_observer(|trigger: Trigger<Explode>, mut commands: Commands| {
-///     println!("Entity {:?} goes BOOM!", trigger.entity());
-///     commands.entity(trigger.entity()).despawn();
+///     println!("Entity {:?} goes BOOM!", trigger.target());
+///     commands.entity(trigger.target()).despawn();
 /// });
 ///
 /// world.flush();
@@ -231,7 +231,7 @@ pub type ObserverRunner = fn(DeferredWorld, ObserverTrigger, PtrMut, propagate:
 /// # struct Explode;
 /// world.entity_mut(e1).observe(|trigger: Trigger<Explode>, mut commands: Commands| {
 ///     println!("Boom!");
-///     commands.entity(trigger.entity()).despawn();
+///     commands.entity(trigger.target()).despawn();
 /// });
 ///
 /// world.entity_mut(e2).observe(|trigger: Trigger<Explode>, mut commands: Commands| {

crates/bevy_ecs/src/world/deferred_world.rs

@@ -508,13 +508,13 @@ impl<'w> DeferredWorld<'w> {
     pub(crate) unsafe fn trigger_observers(
         &mut self,
         event: ComponentId,
-        entity: Entity,
+        target: Entity,
         components: impl Iterator<Item = ComponentId> + Clone,
     ) {
         Observers::invoke::<_>(
             self.reborrow(),
             event,
-            entity,
+            target,
             components,
             &mut (),
             &mut false,
@@ -529,7 +529,7 @@ impl<'w> DeferredWorld<'w> {
     pub(crate) unsafe fn trigger_observers_with_data<E, T>(
         &mut self,
         event: ComponentId,
-        mut entity: Entity,
+        mut target: Entity,
         components: &[ComponentId],
         data: &mut E,
         mut propagate: bool,
@@ -540,7 +540,7 @@ impl<'w> DeferredWorld<'w> {
             Observers::invoke::<_>(
                 self.reborrow(),
                 event,
-                entity,
+                target,
                 components.iter().copied(),
                 data,
                 &mut propagate,
@@ -549,12 +549,12 @@ impl<'w> DeferredWorld<'w> {
                 break;
             }
             if let Some(traverse_to) = self
-                .get_entity(entity)
+                .get_entity(target)
                 .ok()
                 .and_then(|entity| entity.get_components::<T>())
                 .and_then(|item| T::traverse(item, data))
             {
-                entity = traverse_to;
+                target = traverse_to;
             } else {
                 break;
             }

crates/bevy_ecs/src/world/entity_ref.rs

@@ -4703,7 +4703,7 @@ mod tests {
         let entity = world
             .spawn_empty()
             .observe(|trigger: Trigger<TestEvent>, mut commands: Commands| {
-                commands.entity(trigger.entity()).insert(TestComponent(0));
+                commands.entity(trigger.target()).insert(TestComponent(0));
             })
             .id();
 
@@ -4725,7 +4725,7 @@ mod tests {
         let mut world = World::new();
         world.add_observer(
             |trigger: Trigger<OnAdd, TestComponent>, mut commands: Commands| {
-                commands.entity(trigger.entity()).despawn();
+                commands.entity(trigger.target()).despawn();
             },
         );
         let entity = world.spawn_empty().id();

crates/bevy_pbr/src/render/light.rs

@@ -496,7 +496,7 @@ pub(crate) fn add_light_view_entities(
     trigger: Trigger<OnAdd, (ExtractedDirectionalLight, ExtractedPointLight)>,
     mut commands: Commands,
 ) {
-    if let Some(mut v) = commands.get_entity(trigger.entity()) {
+    if let Some(mut v) = commands.get_entity(trigger.target()) {
         v.insert(LightViewEntities::default());
     }
 }
@@ -506,7 +506,7 @@ pub(crate) fn extracted_light_removed(
     trigger: Trigger<OnRemove, (ExtractedDirectionalLight, ExtractedPointLight)>,
     mut commands: Commands,
 ) {
-    if let Some(mut v) = commands.get_entity(trigger.entity()) {
+    if let Some(mut v) = commands.get_entity(trigger.target()) {
         v.remove::<LightViewEntities>();
     }
 }
@@ -516,7 +516,7 @@ pub(crate) fn remove_light_view_entities(
     query: Query<&LightViewEntities>,
     mut commands: Commands,
 ) {
-    if let Ok(entities) = query.get(trigger.entity()) {
+    if let Ok(entities) = query.get(trigger.target()) {
         for v in entities.0.values() {
             for e in v.iter().copied() {
                 if let Some(mut v) = commands.get_entity(e) {

crates/bevy_picking/src/lib.rs

@@ -49,13 +49,13 @@
 //!         // Spawn your entity here, e.g. a Mesh.
 //!         // When dragged, mutate the `Transform` component on the dragged target entity:
 //!         .observe(|trigger: Trigger<Pointer<Drag>>, mut transforms: Query<&mut Transform>| {
-//!             let mut transform = transforms.get_mut(trigger.entity()).unwrap();
+//!             let mut transform = transforms.get_mut(trigger.target()).unwrap();
 //!             let drag = trigger.event();
 //!             transform.rotate_local_y(drag.delta.x / 50.0);
 //!         })
 //!         .observe(|trigger: Trigger<Pointer<Click>>, mut commands: Commands| {
-//!             println!("Entity {:?} goes BOOM!", trigger.entity());
-//!             commands.entity(trigger.entity()).despawn();
+//!             println!("Entity {:?} goes BOOM!", trigger.target());
+//!             commands.entity(trigger.target()).despawn();
 //!         })
 //!         .observe(|trigger: Trigger<Pointer<Over>>, mut events: EventWriter<Greeting>| {
 //!             events.send(Greeting);

crates/bevy_render/src/sync_world.rs

@@ -93,14 +93,14 @@ impl Plugin for SyncWorldPlugin {
         app.init_resource::<PendingSyncEntity>();
         app.add_observer(
             |trigger: Trigger<OnAdd, SyncToRenderWorld>, mut pending: ResMut<PendingSyncEntity>| {
-                pending.push(EntityRecord::Added(trigger.entity()));
+                pending.push(EntityRecord::Added(trigger.target()));
             },
         );
         app.add_observer(
             |trigger: Trigger<OnRemove, SyncToRenderWorld>,
              mut pending: ResMut<PendingSyncEntity>,
              query: Query<&RenderEntity>| {
-                if let Ok(e) = query.get(trigger.entity()) {
+                if let Ok(e) = query.get(trigger.target()) {
                     pending.push(EntityRecord::Removed(*e));
                 };
             },
@@ -487,14 +487,14 @@ mod tests {
 
         main_world.add_observer(
             |trigger: Trigger<OnAdd, SyncToRenderWorld>, mut pending: ResMut<PendingSyncEntity>| {
-                pending.push(EntityRecord::Added(trigger.entity()));
+                pending.push(EntityRecord::Added(trigger.target()));
             },
         );
         main_world.add_observer(
             |trigger: Trigger<OnRemove, SyncToRenderWorld>,
              mut pending: ResMut<PendingSyncEntity>,
              query: Query<&RenderEntity>| {
-                if let Ok(e) = query.get(trigger.entity()) {
+                if let Ok(e) = query.get(trigger.target()) {
                     pending.push(EntityRecord::Removed(*e));
                 };
             },

crates/bevy_scene/src/scene_spawner.rs

@@ -594,7 +594,7 @@ mod tests {
                     "`SceneInstanceReady` contains the wrong `InstanceId`"
                 );
                 assert_eq!(
-                    trigger.entity(),
+                    trigger.target(),
                     scene_entity,
                     "`SceneInstanceReady` triggered on the wrong parent entity"
                 );

crates/bevy_winit/src/cursor.rs

@@ -185,7 +185,7 @@ fn update_cursors(
 fn on_remove_cursor_icon(trigger: Trigger<OnRemove, CursorIcon>, mut commands: Commands) {
     // Use `try_insert` to avoid panic if the window is being destroyed.
     commands
-        .entity(trigger.entity())
+        .entity(trigger.target())
         .try_insert(PendingCursor(Some(CursorSource::System(
             convert_system_cursor_icon(SystemCursorIcon::Default),
         ))));