Skip to content

Commit fc07557

Browse files
committed
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.
1 parent f83a9c2 commit fc07557

File tree

1 file changed

+10
-2
lines changed
  • crates/bevy_ecs/src/system/commands

1 file changed

+10
-2
lines changed

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

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,14 @@ pub trait Command: Send + Sync + 'static {
4545
fn write(self, world: &mut World);
4646
}
4747

48-
/// A queue of [commands](Command) that get executed at the end of the stage of the system that called them.
48+
/// A [`Command`] queue to perform impactful changes to the [`World`].
4949
///
50-
/// Commands are executed one at a time in an exclusive fashion.
50+
/// Since each command requires exclusive access to the `World`,
51+
/// all queued commands are automatically applied in sequence
52+
/// only after each system in a [stage] has completed.
53+
///
54+
/// The command queue of a system can also be manually applied
55+
/// by calling [`System::apply_buffers`].
5156
///
5257
/// Each command can be used to modify the [`World`] in arbitrary ways:
5358
/// * spawning or despawning entities
@@ -88,6 +93,9 @@ pub trait Command: Send + Sync + 'static {
8893
/// });
8994
/// # }
9095
/// ```
96+
///
97+
/// [stage]: crate::schedule::SystemStage
98+
/// [`System::apply_buffers`]: crate::system::System::apply_buffers
9199
pub struct Commands<'w, 's> {
92100
queue: &'s mut CommandQueue,
93101
entities: &'w Entities,

0 commit comments

Comments
 (0)