Skip to content

Commit 29edad4

Browse files
authored
Improve unclear docs about spawn(_batch) and ParallelCommands (#15491)
> [!NOTE] > This is my first PR, so if something is incorrect > or missing, please let me know :3 # Objective - Clarifies `spawn`, `spawn_batch` and `ParallelCommands` docs about performance and use cases - Fixes #15472 ## Solution Add comments to `spawn`, `spawn_batch` and `ParallelCommands` to clarify the intended use case and link to other/better ways of doing spawning things for certain use cases.
1 parent 7ee5143 commit 29edad4

File tree

3 files changed

+14
-5
lines changed

3 files changed

+14
-5
lines changed

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -338,6 +338,9 @@ impl<'w, 's> Commands<'w, 's> {
338338
/// Pushes a [`Command`] to the queue for creating a new entity with the given [`Bundle`]'s components,
339339
/// and returns its corresponding [`EntityCommands`].
340340
///
341+
/// In case multiple bundles of the same [`Bundle`] type need to be spawned,
342+
/// [`spawn_batch`](Self::spawn_batch) should be used for better performance.
343+
///
341344
/// # Example
342345
///
343346
/// ```

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

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,12 @@ struct ParallelCommandQueue {
1414
thread_queues: Parallel<CommandQueue>,
1515
}
1616

17-
/// An alternative to [`Commands`] that can be used in parallel contexts, such as those in [`Query::par_iter`](crate::system::Query::par_iter)
17+
/// An alternative to [`Commands`] that can be used in parallel contexts, such as those
18+
/// in [`Query::par_iter`](crate::system::Query::par_iter).
19+
///
20+
/// For cases where multiple non-computation-heavy (lightweight) bundles of the same
21+
/// [`Bundle`](crate::prelude::Bundle) type need to be spawned, consider using
22+
/// [`Commands::spawn_batch`] for better performance.
1823
///
1924
/// Note: Because command application order will depend on how many threads are ran, non-commutative commands may result in non-deterministic results.
2025
///

crates/bevy_ecs/src/world/mod.rs

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -921,7 +921,8 @@ impl World {
921921

922922
/// Spawns a new [`Entity`] with a given [`Bundle`] of [components](`Component`) and returns
923923
/// a corresponding [`EntityWorldMut`], which can be used to add components to the entity or
924-
/// retrieve its id.
924+
/// retrieve its id. In case large batches of entities need to be spawned, consider using
925+
/// [`World::spawn_batch`] instead.
925926
///
926927
/// ```
927928
/// use bevy_ecs::{bundle::Bundle, component::Component, world::World};
@@ -1018,9 +1019,9 @@ impl World {
10181019

10191020
/// Spawns a batch of entities with the same component [`Bundle`] type. Takes a given
10201021
/// [`Bundle`] iterator and returns a corresponding [`Entity`] iterator.
1021-
/// This is more efficient than spawning entities and adding components to them individually,
1022-
/// but it is limited to spawning entities with the same [`Bundle`] type, whereas spawning
1023-
/// individually is more flexible.
1022+
/// This is more efficient than spawning entities and adding components to them individually
1023+
/// using [`World::spawn`], but it is limited to spawning entities with the same [`Bundle`]
1024+
/// type, whereas spawning individually is more flexible.
10241025
///
10251026
/// ```
10261027
/// use bevy_ecs::{component::Component, entity::Entity, world::World};

0 commit comments

Comments
 (0)