diff --git a/crates/bevy_ecs/src/system/commands/mod.rs b/crates/bevy_ecs/src/system/commands/mod.rs index 1476f32db1..fca9e8f94b 100644 --- a/crates/bevy_ecs/src/system/commands/mod.rs +++ b/crates/bevy_ecs/src/system/commands/mod.rs @@ -338,6 +338,9 @@ impl<'w, 's> Commands<'w, 's> { /// Pushes a [`Command`] to the queue for creating a new entity with the given [`Bundle`]'s components, /// and returns its corresponding [`EntityCommands`]. /// + /// In case multiple bundles of the same [`Bundle`] type need to be spawned, + /// [`spawn_batch`](Self::spawn_batch) should be used for better performance. + /// /// # Example /// /// ``` diff --git a/crates/bevy_ecs/src/system/commands/parallel_scope.rs b/crates/bevy_ecs/src/system/commands/parallel_scope.rs index 582825aa79..82a00ceac2 100644 --- a/crates/bevy_ecs/src/system/commands/parallel_scope.rs +++ b/crates/bevy_ecs/src/system/commands/parallel_scope.rs @@ -14,7 +14,12 @@ struct ParallelCommandQueue { thread_queues: Parallel, } -/// An alternative to [`Commands`] that can be used in parallel contexts, such as those in [`Query::par_iter`](crate::system::Query::par_iter) +/// An alternative to [`Commands`] that can be used in parallel contexts, such as those +/// in [`Query::par_iter`](crate::system::Query::par_iter). +/// +/// For cases where multiple non-computation-heavy (lightweight) bundles of the same +/// [`Bundle`](crate::prelude::Bundle) type need to be spawned, consider using +/// [`Commands::spawn_batch`] for better performance. /// /// Note: Because command application order will depend on how many threads are ran, non-commutative commands may result in non-deterministic results. /// diff --git a/crates/bevy_ecs/src/world/mod.rs b/crates/bevy_ecs/src/world/mod.rs index 7e0d194442..80a05e2a18 100644 --- a/crates/bevy_ecs/src/world/mod.rs +++ b/crates/bevy_ecs/src/world/mod.rs @@ -921,7 +921,8 @@ impl World { /// Spawns a new [`Entity`] with a given [`Bundle`] of [components](`Component`) and returns /// a corresponding [`EntityWorldMut`], which can be used to add components to the entity or - /// retrieve its id. + /// retrieve its id. In case large batches of entities need to be spawned, consider using + /// [`World::spawn_batch`] instead. /// /// ``` /// use bevy_ecs::{bundle::Bundle, component::Component, world::World}; @@ -1018,9 +1019,9 @@ impl World { /// Spawns a batch of entities with the same component [`Bundle`] type. Takes a given /// [`Bundle`] iterator and returns a corresponding [`Entity`] iterator. - /// This is more efficient than spawning entities and adding components to them individually, - /// but it is limited to spawning entities with the same [`Bundle`] type, whereas spawning - /// individually is more flexible. + /// This is more efficient than spawning entities and adding components to them individually + /// using [`World::spawn`], but it is limited to spawning entities with the same [`Bundle`] + /// type, whereas spawning individually is more flexible. /// /// ``` /// use bevy_ecs::{component::Component, entity::Entity, world::World};