mirror of
https://github.com/bevyengine/bevy
synced 2024-11-22 20:53:53 +00:00
Clarify Commands
API docs (#5938)
# Objective - Make people stop believing that commands are applied immediately (hopefully). - Close #5913. - Alternative to #5930. ## Solution I added the clause “to perform impactful changes to the `World`” to the first line to subliminally help the reader accept the fact that some operations cannot be performed immediately without messing up everything. Then I explicitely said that applying a command requires exclusive `World` access, and finally I proceeded to show when these commands are automatically applied. I also added a brief paragraph about how commands can be applied manually, if they want. --- ### Further possibilities If you agree, we can also change the text of the method documentation (in a separate PR) to stress about enqueueing an action instead of just performing it. For example, in `Commands::spawn`: > Creates a new `Entity` would be changed to something like: > Issues a `Command` to spawn a new `Entity` This may even have a greater effect, since when typing in an IDE, the docs of the method pop up and the programmer can read them on the fly.
This commit is contained in:
parent
f83a9c23f2
commit
fc07557913
1 changed files with 10 additions and 2 deletions
|
@ -45,9 +45,14 @@ pub trait Command: Send + Sync + 'static {
|
|||
fn write(self, world: &mut World);
|
||||
}
|
||||
|
||||
/// A queue of [commands](Command) that get executed at the end of the stage of the system that called them.
|
||||
/// A [`Command`] queue to perform impactful changes to the [`World`].
|
||||
///
|
||||
/// Commands are executed one at a time in an exclusive fashion.
|
||||
/// Since each command requires exclusive access to the `World`,
|
||||
/// all queued commands are automatically applied in sequence
|
||||
/// only after each system in a [stage] has completed.
|
||||
///
|
||||
/// The command queue of a system can also be manually applied
|
||||
/// by calling [`System::apply_buffers`].
|
||||
///
|
||||
/// Each command can be used to modify the [`World`] in arbitrary ways:
|
||||
/// * spawning or despawning entities
|
||||
|
@ -88,6 +93,9 @@ pub trait Command: Send + Sync + 'static {
|
|||
/// });
|
||||
/// # }
|
||||
/// ```
|
||||
///
|
||||
/// [stage]: crate::schedule::SystemStage
|
||||
/// [`System::apply_buffers`]: crate::system::System::apply_buffers
|
||||
pub struct Commands<'w, 's> {
|
||||
queue: &'s mut CommandQueue,
|
||||
entities: &'w Entities,
|
||||
|
|
Loading…
Reference in a new issue