diff --git a/crates/bevy_ecs/src/system/commands/mod.rs b/crates/bevy_ecs/src/system/commands/mod.rs index d7e87de4e8..26b1fdedf3 100644 --- a/crates/bevy_ecs/src/system/commands/mod.rs +++ b/crates/bevy_ecs/src/system/commands/mod.rs @@ -102,7 +102,11 @@ pub struct Commands<'w, 's> { } impl<'w, 's> Commands<'w, 's> { - /// Create a new `Commands` from a queue and a world. + /// Returns a new `Commands` instance from a [`CommandQueue`] and a [`World`]. + /// + /// It is not required to call this constructor when using `Commands` as a [system parameter]. + /// + /// [system parameter]: crate::system::SystemParam pub fn new(queue: &'s mut CommandQueue, world: &'w World) -> Self { Self { queue, @@ -110,15 +114,17 @@ impl<'w, 's> Commands<'w, 's> { } } - /// Create a new `Commands` from a queue and an [`Entities`] reference. + /// Returns a new `Commands` instance from a [`CommandQueue`] and an [`Entities`] reference. + /// + /// It is not required to call this constructor when using `Commands` as a [system parameter]. + /// + /// [system parameter]: crate::system::SystemParam pub fn new_from_entities(queue: &'s mut CommandQueue, entities: &'w Entities) -> Self { Self { queue, entities } } - /// Creates a new empty [`Entity`] and returns an [`EntityCommands`] builder for it. - /// - /// To directly spawn an entity with a [`Bundle`] included, you can use - /// [`spawn_bundle`](Self::spawn_bundle) instead of `.spawn().insert_bundle()`. + /// Pushes a [`Command`] to the queue for creating a new empty [`Entity`], + /// and returns its corresponding [`EntityCommands`]. /// /// See [`World::spawn`] for more details. /// @@ -147,6 +153,11 @@ impl<'w, 's> Commands<'w, 's> { /// } /// # bevy_ecs::system::assert_is_system(example_system); /// ``` + /// + /// # See also + /// + /// - [`spawn_bundle`](Self::spawn_bundle) to spawn an entity with a bundle. + /// - [`spawn_batch`](Self::spawn_batch) to spawn entities with a bundle each. pub fn spawn<'a>(&'a mut self) -> EntityCommands<'w, 's, 'a> { let entity = self.entities.reserve_entity(); EntityCommands { @@ -155,10 +166,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. + /// Pushes a [`Command`] to the queue for creating a new [`Entity`] if the given one does not exists, + /// and returns its corresponding [`EntityCommands`]. + /// + /// See [`World::get_or_spawn`] for more details. /// /// # 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 @@ -171,14 +185,8 @@ impl<'w, 's> Commands<'w, 's> { } } - /// Creates a new entity with the components contained in `bundle`. - /// - /// This returns an [`EntityCommands`] builder, which enables inserting more components and - /// bundles using a "builder pattern". - /// - /// Note that `bundle` is a [`Bundle`], which is a collection of components. [`Bundle`] is - /// automatically implemented for tuples of components. You can also create your own bundle - /// types by deriving [`derive@Bundle`]. + /// Pushes a [`Command`] to the queue for creating a new entity with the given [`Bundle`]'s components, + /// and returns its corresponding [`EntityCommands`]. /// /// # Example /// @@ -219,13 +227,22 @@ impl<'w, 's> Commands<'w, 's> { /// } /// # bevy_ecs::system::assert_is_system(example_system); /// ``` + /// + /// # See also + /// + /// - [`spawn`](Self::spawn) to just spawn an entity without any component. + /// - [`spawn_batch`](Self::spawn_batch) to spawn entities with a bundle each. pub fn spawn_bundle<'a, T: Bundle>(&'a mut self, bundle: T) -> EntityCommands<'w, 's, 'a> { let mut e = self.spawn(); e.insert_bundle(bundle); e } - /// Returns an [`EntityCommands`] builder for the requested [`Entity`]. + /// Returns the [`EntityCommands`] for the requested [`Entity`]. + /// + /// # Panics + /// + /// This method panics if the requested entity does not exist. /// /// # Example /// @@ -238,7 +255,7 @@ impl<'w, 's> Commands<'w, 's> { /// struct Strength(u32); /// #[derive(Component)] /// struct Agility(u32); - + /// /// fn example_system(mut commands: Commands) { /// // Create a new, empty entity /// let entity = commands.spawn().id(); @@ -251,6 +268,10 @@ impl<'w, 's> Commands<'w, 's> { /// } /// # bevy_ecs::system::assert_is_system(example_system); /// ``` + /// + /// # See also + /// + /// - [`get_entity`](Self::get_entity) for the fallible version. #[inline] #[track_caller] pub fn entity<'a>(&'a mut self, entity: Entity) -> EntityCommands<'w, 's, 'a> { @@ -262,8 +283,12 @@ impl<'w, 's> Commands<'w, 's> { }) } - /// Returns an option containing an [`EntityCommands`] builder for the requested [`Entity`] if it exists, otherwise `None`. - /// This does not ensure that the commands will succeed as the entity may no longer exist by the time the associated commands are executed. + /// Returns the [`EntityCommands`] for the requested [`Entity`], if it exists. + /// + /// Returns `None` if the entity does not exist. + /// + /// This method does not guarantee that `EntityCommands` will be successfully applied, + /// since another command in the queue may delete the entity before them. /// /// # Example /// @@ -285,6 +310,10 @@ impl<'w, 's> Commands<'w, 's> { /// } /// # bevy_ecs::system::assert_is_system(example_system); /// ``` + /// + /// # See also + /// + /// - [`entity`](Self::entity) for the panicking version. #[inline] #[track_caller] pub fn get_entity<'a>(&'a mut self, entity: Entity) -> Option> { @@ -294,12 +323,14 @@ impl<'w, 's> Commands<'w, 's> { }) } - /// Spawns entities to the [`World`] according to the given iterator (or a type that can - /// be converted to it). + /// Pushes a [`Command`] to the queue for creating entities with a particular [`Bundle`] type. /// - /// The end result of this command is equivalent to iterating `bundles_iter` and calling - /// [`spawn`](Self::spawn) on each bundle, but it is more performant due to memory - /// pre-allocation. + /// `bundles_iter` is a type that can be converted into a `Bundle` iterator + /// (it can also be a collection). + /// + /// This method is equivalent to iterating `bundles_iter` + /// and calling [`spawn`](Self::spawn) on each bundle, + /// but it is faster due to memory pre-allocation. /// /// # Example /// @@ -325,6 +356,11 @@ impl<'w, 's> Commands<'w, 's> { /// # } /// # bevy_ecs::system::assert_is_system(system); /// ``` + /// + /// # See also + /// + /// - [`spawn`](Self::spawn) to just spawn an entity without any component. + /// - [`spawn_bundle`](Self::spawn_bundle) to spawn an entity with a bundle. pub fn spawn_batch(&mut self, bundles_iter: I) where I: IntoIterator + Send + Sync + 'static, @@ -333,10 +369,21 @@ impl<'w, 's> Commands<'w, 's> { self.queue.push(SpawnBatch { bundles_iter }); } - /// 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). + /// Pushes a [`Command`] to the queue for creating entities, if needed, + /// and for adding a bundle to each entity. /// - /// This is faster than doing equivalent operations one-by-one. + /// `bundles_iter` is a type that can be converted into an ([`Entity`], [`Bundle`]) iterator + /// (it can also be a collection). + /// + /// When the command is applied, + /// for each (`Entity`, `Bundle`) pair in the given `bundles_iter`, + /// the `Entity` is spawned, if it does not exist already. + /// Then, the `Bundle` is added to the entity. + /// + /// This method is equivalent to iterating `bundles_iter`, + /// calling [`get_or_spawn`](Self::get_or_spawn) for each bundle, + /// and passing it to [`insert_bundle`](EntityCommands::insert_bundle), + /// but it is faster due to memory pre-allocation. /// /// # Note /// @@ -352,17 +399,13 @@ impl<'w, 's> Commands<'w, 's> { self.queue.push(InsertOrSpawnBatch { bundles_iter }); } - /// Inserts a resource with standard starting values to the [`World`]. + /// Pushes a [`Command`] to the queue for inserting a [`Resource`] in the [`World`] with an inferred value. /// - /// If the resource already exists, nothing happens. - /// - /// The value given by the [`FromWorld::from_world`] method will be used. - /// Note that any resource with the `Default` trait automatically implements `FromWorld`, - /// and those default values will be here instead. + /// The inferred value is determined by the [`FromWorld`] trait of the resource. + /// When the command is applied, + /// if the resource already exists, nothing happens. /// /// See [`World::init_resource`] for more details. - /// Note that commands do not take effect immediately. - /// When possible, prefer the equivalent methods on `App` or `World`. /// /// # Example /// @@ -386,11 +429,11 @@ impl<'w, 's> Commands<'w, 's> { }); } - /// Inserts a resource to the [`World`], overwriting any previous value of the same type. + /// Pushes a [`Command`] to the queue for inserting a [`Resource`] in the [`World`] with a specific value. + /// + /// This will overwrite any previous value of the same resource type. /// /// See [`World::insert_resource`] for more details. - /// Note that commands do not take effect immediately. - /// When possible, prefer the equivalent methods on `App` or `World`. /// /// # Example /// @@ -415,7 +458,7 @@ impl<'w, 's> Commands<'w, 's> { self.queue.push(InsertResource { resource }); } - /// Removes a resource from the [`World`]. + /// Pushes a [`Command`] to the queue for removing a [`Resource`] from the [`World`]. /// /// See [`World::remove_resource`] for more details. /// @@ -441,7 +484,7 @@ impl<'w, 's> Commands<'w, 's> { }); } - /// Adds a command directly to the command queue. + /// Pushes a generic [`Command`] to the command queue. /// /// `command` can be a built-in command, custom struct that implements [`Command`] or a closure /// that takes [`&mut World`](World) as an argument.