Rename App/World::observe to add_observer, `EntityWorldMut::obser…

…ve_entity` to `observe`. (#15754)

# Objective

- Closes #15752

Calling the functions `App::observe` and `World::observe` doesn't make
sense because you're not "observing" the `App` or `World`, you're adding
an observer that listens for an event that occurs *within* the `World`.
We should rename them to better fit this.

## Solution

Renames:
- `App::observe` -> `App::add_observer`
- `World::observe` -> `World::add_observer`
- `Commands::observe` -> `Commands::add_observer`
- `EntityWorldMut::observe_entity` -> `EntityWorldMut::observe`

(Note this isn't a breaking change as the original rename was introduced
earlier this cycle.)

## Testing

Reusing current tests.

benches/benches/bevy_ecs/observers/propagation.rs

@@ -106,15 +106,15 @@ fn add_listeners_to_hierarchy<const DENSITY: usize, const N: usize>(
  world: &mut World,
 ) {
  for e in roots.iter() {
- world.entity_mut(*e).observe_entity(empty_listener::<N>);
+ world.entity_mut(*e).observe(empty_listener::<N>);
  }
  for e in leaves.iter() {
- world.entity_mut(*e).observe_entity(empty_listener::<N>);
+ world.entity_mut(*e).observe(empty_listener::<N>);
  }
  let mut rng = deterministic_rand();
  for e in nodes.iter() {
  if rng.gen_bool(DENSITY as f64 / 100.0) {
- world.entity_mut(*e).observe_entity(empty_listener::<N>);
+ world.entity_mut(*e).observe(empty_listener::<N>);
  }
  }
 }

benches/benches/bevy_ecs/observers/simple.rs

@@ -17,7 +17,7 @@ pub fn observe_simple(criterion: &mut Criterion) {
 
  group.bench_function("trigger_simple", |bencher| {
  let mut world = World::new();
- world.observe(empty_listener_base);
+ world.add_observer(empty_listener_base);
  bencher.iter(|| {
  for _ in 0..10000 {
  world.trigger(EventBase)
@@ -29,7 +29,7 @@ pub fn observe_simple(criterion: &mut Criterion) {
  let mut world = World::new();
  let mut entities = vec![];
  for _ in 0..10000 {
- entities.push(world.spawn_empty().observe_entity(empty_listener_base).id());
+ entities.push(world.spawn_empty().observe(empty_listener_base).id());
  }
  entities.shuffle(&mut deterministic_rand());
  bencher.iter(|| {

crates/bevy_app/src/app.rs

@@ -1267,19 +1267,19 @@ impl App {
  /// # struct Friend;
  /// #
  /// // An observer system can be any system where the first parameter is a trigger
- /// app.observe(|trigger: Trigger<Party>, friends: Query<Entity, With<Friend>>, mut commands: Commands| {
+ /// app.add_observer(|trigger: Trigger<Party>, friends: Query<Entity, With<Friend>>, mut commands: Commands| {
  /// if trigger.event().friends_allowed {
  /// for friend in friends.iter() {
  /// commands.trigger_targets(Invite, friend);
  /// }
  /// }
  /// });
  /// ```
- pub fn observe<E: Event, B: Bundle, M>(
+ pub fn add_observer<E: Event, B: Bundle, M>(
  &mut self,
  observer: impl IntoObserverSystem<E, B, M>,
  ) -> &mut Self {
- self.world_mut().observe(observer);
+ self.world_mut().add_observer(observer);
  self
  }
 }

crates/bevy_dev_tools/src/ci_testing/systems.rs

@@ -25,7 +25,7 @@ pub(crate) fn send_events(world: &mut World, mut current_frame: Local<u32>) {
  let path = format!("./screenshot-{}.png", *current_frame);
  world
  .spawn(Screenshot::primary_window())
- .observe_entity(save_to_disk(path));
+ .observe(save_to_disk(path));
  info!("Took a screenshot at frame {}.", *current_frame);
  }
  // Custom events are forwarded to the world.

crates/bevy_ecs/README.md

@@ -315,7 +315,7 @@ struct MyEvent {
 
 let mut world = World::new();
 
-world.observe(|trigger: Trigger<MyEvent>| {
+world.add_observer(|trigger: Trigger<MyEvent>| {
  println!("{}", trigger.event().message);
 });
 
@@ -339,7 +339,7 @@ struct Explode;
 let mut world = World::new();
 let entity = world.spawn_empty().id();
 
-world.observe(|trigger: Trigger<Explode>, mut commands: Commands| {
+world.add_observer(|trigger: Trigger<Explode>, mut commands: Commands| {
  println!("Entity {:?} goes BOOM!", trigger.entity());
  commands.entity(trigger.entity()).despawn();
 });