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.
This commit is contained in:
parent
7ee5143d45
commit
29edad4690
@ -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,
|
/// Pushes a [`Command`] to the queue for creating a new entity with the given [`Bundle`]'s components,
|
||||||
/// and returns its corresponding [`EntityCommands`].
|
/// 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
|
/// # Example
|
||||||
///
|
///
|
||||||
/// ```
|
/// ```
|
||||||
|
|||||||
@ -14,7 +14,12 @@ struct ParallelCommandQueue {
|
|||||||
thread_queues: Parallel<CommandQueue>,
|
thread_queues: Parallel<CommandQueue>,
|
||||||
}
|
}
|
||||||
|
|
||||||
/// 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.
|
/// Note: Because command application order will depend on how many threads are ran, non-commutative commands may result in non-deterministic results.
|
||||||
///
|
///
|
||||||
|
|||||||
@ -921,7 +921,8 @@ impl World {
|
|||||||
|
|
||||||
/// Spawns a new [`Entity`] with a given [`Bundle`] of [components](`Component`) and returns
|
/// 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
|
/// 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};
|
/// 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
|
/// Spawns a batch of entities with the same component [`Bundle`] type. Takes a given
|
||||||
/// [`Bundle`] iterator and returns a corresponding [`Entity`] iterator.
|
/// [`Bundle`] iterator and returns a corresponding [`Entity`] iterator.
|
||||||
/// This is more efficient than spawning entities and adding components to them individually,
|
/// 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
|
/// using [`World::spawn`], but it is limited to spawning entities with the same [`Bundle`]
|
||||||
/// individually is more flexible.
|
/// type, whereas spawning individually is more flexible.
|
||||||
///
|
///
|
||||||
/// ```
|
/// ```
|
||||||
/// use bevy_ecs::{component::Component, entity::Entity, world::World};
|
/// use bevy_ecs::{component::Component, entity::Entity, world::World};
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user