[Merged by Bors] - Spawn specific entities: spawn or insert operations, refactor spawn internals, world clearing

crates/bevy_ecs/src/system/commands/mod.rs

@@ -58,6 +58,13 @@ impl<'w, 's> Commands<'w, 's> {
  }
  }
 
+ /// Returns an [EntityCommands] for the given `entity` (if it exists) or spawns one if it doesn't exist.
+ /// This will return [None] if the `entity` exists with a different generation.
+ ///
+ /// # Note
+ /// Spawning a specific `entity` value is rarely the right choice. Most apps should favor [`Commands::spawn`].
+ /// This method should generally only be used for sharing entities across apps, and only when they have a
+ /// scheme worked out to share an ID space (which doesn't happen by default).
  pub fn get_or_spawn<'a>(&'a mut self, entity: Entity) -> EntityCommands<'w, 's, 'a> {
  self.add(GetOrSpawn { entity });
  EntityCommands {
@@ -66,6 +73,8 @@ impl<'w, 's> Commands<'w, 's> {
  }
  }
 
+ /// Spawns a [Bundle] without pre-allocating an [Entity]. The [Entity] will be allocated when
+ /// this [Command] is applied.
  pub fn spawn_and_forget(&mut self, bundle: impl Bundle) {
  self.queue.push(Spawn { bundle })
  }
@@ -152,8 +161,14 @@ impl<'w, 's> Commands<'w, 's> {
  self.queue.push(SpawnBatch { bundles_iter });
  }
 
- /// For an iterator of (Entity, Bundle) pairs, inserts the Bundle into the Entity,
- /// if the entity exists, and spawns the entity with the Bundle if it does not exist.
+ /// For a given batch of ([Entity], [Bundle]) pairs, either spawns each [Entity] with the given
+ /// bundle (if the entity does not exist), or inserts the [Bundle] (if the entity already exists).
+ /// This is faster than doing equivalent operations one-by-one.
+ ///
+ /// # Note
+ /// Spawning a specific `entity` value is rarely the right choice. Most apps should use [`Commands::spawn_batch`].
+ /// This method should generally only be used for sharing entities across apps, and only when they have a scheme
+ /// worked out to share an ID space (which doesn't happen by default).
  pub fn insert_or_spawn_batch<I, B>(&mut self, bundles_iter: I)
  where
  I: IntoIterator + Send + Sync + 'static,

crates/bevy_ecs/src/world/mod.rs

@@ -220,8 +220,13 @@ impl World {
  self.get_entity_mut(entity).expect("Entity does not exist")
  }
 
- /// Returns an EntityMut for an existing entity or creates one if it doesn't exist.
- /// This will return `None` if the entity exists with a different generation.
+ /// Returns an [EntityMut] for the given `entity` (if it exists) or spawns one if it doesn't exist.
+ /// This will return [None] if the `entity` exists with a different generation.
+ ///
+ /// # Note
+ /// Spawning a specific `entity` value is rarely the right choice. Most apps should favor [`World::spawn`].
+ /// This method should generally only be used for sharing entities across apps, and only when they have a
+ /// scheme worked out to share an ID space (which doesn't happen by default).
  #[inline]
  pub fn get_or_spawn(&mut self, entity: Entity) -> Option<EntityMut> {
  self.flush();
@@ -698,6 +703,28 @@ impl World {
  self.get_non_send_unchecked_mut_with_id(component_id)
  }
 
+ /// For a given batch of ([Entity], [Bundle]) pairs, either spawns each [Entity] with the given
+ /// bundle (if the entity does not exist), or inserts the [Bundle] (if the entity already exists).
+ /// This is faster than doing equivalent operations one-by-one.
+ ///
+ /// # Note
+ /// Spawning a specific `entity` value is rarely the right choice. Most apps should use [`World::spawn_batch`].
+ /// This method should generally only be used for sharing entities across apps, and only when they have a scheme
+ /// worked out to share an ID space (which doesn't happen by default).
+ ///
+ /// ```
+ /// use bevy_ecs::{entity::Entity, world::World};
+ ///
+ /// let mut world = World::new();
+ /// let e0 = world.spawn().id();
+ /// let e1 = world.spawn().id();
+ /// world.insert_or_spawn_batch(vec![
+ /// (e0, ("a", 0.0)), // the first entity
+ /// (e1, ("b", 1.0)), // the second entity
+ /// ]);
+ ///
+ /// assert_eq!(world.get::<f64>(e0), Some(&0.0));
+ /// ```
  pub fn insert_or_spawn_batch<I, B>(&mut self, iter: I)
  where
  I: IntoIterator,