Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-12-18 09:03:07 +00:00
Code Issues Projects Releases Packages Wiki Activity

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

Browse source 
# 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`
This commit is contained in:
Aevyrie 2024-12-08 13:55:09 -08:00 committed by GitHub
parent 1d3950a82a
commit 61b98ec80f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
19 changed files with 73 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
crates/bevy_ecs/README.md
View file

@ -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();

45
crates/bevy_ecs/src/observer/mod.rs
View file

@ -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");
}
},

6
crates/bevy_ecs/src/observer/runner.rs
View file

@ -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| {

12
crates/bevy_ecs/src/world/deferred_world.rs
View file

@ -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;
}

4
crates/bevy_ecs/src/world/entity_ref.rs
View file

@ -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();

6
crates/bevy_pbr/src/render/light.rs
View file

@ -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) {

6
crates/bevy_picking/src/lib.rs
View file

@ -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);

8
crates/bevy_render/src/sync_world.rs
View file

@ -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));
};
},

2
crates/bevy_scene/src/scene_spawner.rs
View file

@ -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"
);

2
crates/bevy_winit/src/cursor.rs
View file

@ -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),
))));

2
examples/animation/animated_fox.rs
View file

@ -48,7 +48,7 @@ fn observe_on_step(
transforms: Query<&GlobalTransform>,
mut seeded_rng: ResMut<SeededRng>,
) {
let translation = transforms.get(trigger.entity()).unwrap().translation();
let translation = transforms.get(trigger.target()).unwrap().translation();
// Spawn a bunch of particles.
for _ in 0..14 {
let horizontal = seeded_rng.0.gen::<Dir2>() * seeded_rng.0.gen_range(8.0..12.0);

8
examples/ecs/observer_propagation.rs
View file

@ -78,14 +78,14 @@ fn attack_armor(entities: Query<Entity, With<Armor>>, mut commands: Commands) {
}
fn attack_hits(trigger: Trigger<Attack>, name: Query<&Name>) {
if let Ok(name) = name.get(trigger.entity()) {
if let Ok(name) = name.get(trigger.target()) {
info!("Attack hit {}", name);
}
}
/// A callback placed on [`Armor`], checking if it absorbed all the [`Attack`] damage.
fn block_attack(mut trigger: Trigger<Attack>, armor: Query<(&Armor, &Name)>) {
let (armor, name) = armor.get(trigger.entity()).unwrap();
let (armor, name) = armor.get(trigger.target()).unwrap();
let attack = trigger.event_mut();
let damage = attack.damage.saturating_sub(**armor);
if damage > 0 {
@ -110,14 +110,14 @@ fn take_damage(
mut app_exit: EventWriter<AppExit>,
) {
let attack = trigger.event();
let (mut hp, name) = hp.get_mut(trigger.entity()).unwrap();
let (mut hp, name) = hp.get_mut(trigger.target()).unwrap();
**hp = hp.saturating_sub(attack.damage);
if **hp > 0 {
info!("{} has {:.1} HP", name, hp.0);
} else {
warn!("💀 {} has died a gruesome death", name);
commands.entity(trigger.entity()).despawn_recursive();
commands.entity(trigger.target()).despawn_recursive();
app_exit.send(AppExit::Success);
}

10
examples/ecs/observers.rs
View file

@ -117,12 +117,12 @@ fn on_add_mine(
query: Query<&Mine>,
mut index: ResMut<SpatialIndex>,
) {
let mine = query.get(trigger.entity()).unwrap();
let mine = query.get(trigger.target()).unwrap();
let tile = (
(mine.pos.x / CELL_SIZE).floor() as i32,
(mine.pos.y / CELL_SIZE).floor() as i32,
);
index.map.entry(tile).or_default().insert(trigger.entity());
index.map.entry(tile).or_default().insert(trigger.target());
}
// Remove despawned mines from our index
@ -131,19 +131,19 @@ fn on_remove_mine(
query: Query<&Mine>,
mut index: ResMut<SpatialIndex>,
) {
let mine = query.get(trigger.entity()).unwrap();
let mine = query.get(trigger.target()).unwrap();
let tile = (
(mine.pos.x / CELL_SIZE).floor() as i32,
(mine.pos.y / CELL_SIZE).floor() as i32,
);
index.map.entry(tile).and_modify(|set| {
set.remove(&trigger.entity());
set.remove(&trigger.target());
});
}
fn explode_mine(trigger: Trigger<Explode>, query: Query<&Mine>, mut commands: Commands) {
// If a triggered event is targeting a specific entity you can access it with `.entity()`
let id = trigger.entity();
let id = trigger.target();
let Some(mut entity) = commands.get_entity(id) else {
return;
};

2
examples/ecs/removal_detection.rs
View file

@ -50,7 +50,7 @@ fn remove_component(
fn react_on_removal(trigger: Trigger<OnRemove, MyComponent>, mut query: Query<&mut Sprite>) {
// The `OnRemove` trigger was automatically called on the `Entity` that had its `MyComponent` removed.
let entity = trigger.entity();
let entity = trigger.target();
if let Ok(mut sprite) = query.get_mut(entity) {
sprite.color = Color::srgb(0.5, 1., 1.);
}

4
examples/picking/mesh_picking.rs
View file

@ -164,7 +164,7 @@ fn update_material_on<E>(
// versions of this observer, each triggered by a different event and with a different hardcoded
// material. Instead, the event type is a generic, and the material is passed in.
move |trigger, mut query| {
if let Ok(mut material) = query.get_mut(trigger.entity()) {
if let Ok(mut material) = query.get_mut(trigger.target()) {
material.0 = new_material.clone();
}
}
@ -191,7 +191,7 @@ fn rotate(mut query: Query<&mut Transform, With<Shape>>, time: Res<Time>) {
/// An observer to rotate an entity when it is dragged
fn rotate_on_drag(drag: Trigger<Pointer<Drag>>, mut transforms: Query<&mut Transform>) {
let mut transform = transforms.get_mut(drag.entity()).unwrap();
let mut transform = transforms.get_mut(drag.target()).unwrap();
transform.rotate_y(drag.delta.x * 0.02);
transform.rotate_x(drag.delta.y * 0.02);
}

6
examples/picking/simple_picking.rs
View file

@ -28,13 +28,13 @@ fn setup_scene(
.observe(on_click_spawn_cube)
.observe(
|out: Trigger<Pointer<Out>>, mut texts: Query<&mut TextColor>| {
let mut text_color = texts.get_mut(out.entity()).unwrap();
let mut text_color = texts.get_mut(out.target()).unwrap();
text_color.0 = Color::WHITE;
},
)
.observe(
|over: Trigger<Pointer<Over>>, mut texts: Query<&mut TextColor>| {
let mut color = texts.get_mut(over.entity()).unwrap();
let mut color = texts.get_mut(over.target()).unwrap();
color.0 = bevy::color::palettes::tailwind::CYAN_400.into();
},
);
@ -81,7 +81,7 @@ fn on_click_spawn_cube(
}
fn on_drag_rotate(drag: Trigger<Pointer<Drag>>, mut transforms: Query<&mut Transform>) {
if let Ok(mut transform) = transforms.get_mut(drag.entity()) {
if let Ok(mut transform) = transforms.get_mut(drag.target()) {
transform.rotate_y(drag.delta.x * 0.02);
transform.rotate_x(drag.delta.y * 0.02);
}

2
examples/picking/sprite_picking.rs
View file

@ -150,7 +150,7 @@ fn setup_atlas(
// An observer listener that changes the target entity's color.
fn recolor_on<E: Debug + Clone + Reflect>(color: Color) -> impl Fn(Trigger<E>, Query<&mut Sprite>) {
move |ev, mut sprites| {
let Ok(mut sprite) = sprites.get_mut(ev.entity()) else {
let Ok(mut sprite) = sprites.get_mut(ev.target()) else {
return;
};
sprite.color = color;

2
examples/testbed/3d.rs
View file

@ -284,7 +284,7 @@ mod animation {
animation: Res<Animation>,
mut players: Query<(Entity, &mut AnimationPlayer)>,
) {
let entity = children.get(trigger.entity()).unwrap()[0];
let entity = children.get(trigger.target()).unwrap()[0];
let entity = children.get(entity).unwrap()[0];
let (entity, mut player) = players.get_mut(entity).unwrap();

2
examples/ui/scroll.rs
View file

@ -93,7 +93,7 @@ fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
mut commands: Commands
| {
if trigger.event().button == PointerButton::Primary {
commands.entity(trigger.entity()).despawn_recursive();
commands.entity(trigger.target()).despawn_recursive();
}
});
}