Rename Command's "write" method to "apply" (#8814)

# Objective

- Fixes #8811 .

## Solution

- Rename "write" method to "apply" in Command trait definition.
- Rename other implementations of command trait throughout bevy's code
base.

---

## Changelog

- Changed: `Command::write` has been changed to `Command::apply`
- Changed: `EntityCommand::write` has been changed to
`EntityCommand::apply`

## Migration Guide

- `Command::write` implementations need to be changed to implement
`Command::apply` instead. This is a mere name change, with no further
actions needed.
- `EntityCommand::write` implementations need to be changed to implement
`EntityCommand::apply` instead. This is a mere name change, with no
further actions needed.

---------

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

benches/benches/bevy_ecs/world/commands.rs

@@ -125,14 +125,14 @@ struct FakeCommandA;
 struct FakeCommandB(u64);
 
 impl Command for FakeCommandA {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         black_box(self);
         black_box(world);
     }
 }
 
 impl Command for FakeCommandB {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         black_box(self);
         black_box(world);
     }
@@ -169,7 +169,7 @@ pub fn fake_commands(criterion: &mut Criterion) {
 struct SizedCommand<T: Default + Send + Sync + 'static>(T);
 
 impl<T: Default + Send + Sync + 'static> Command for SizedCommand<T> {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         black_box(self);
         black_box(world);
     }

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

@@ -57,7 +57,7 @@ impl CommandQueue {
                 // SAFETY: According to the invariants of `CommandMeta.apply_command_and_get_size`,
                 // `command` must point to a value of type `C`.
                 let command: C = unsafe { command.read_unaligned() };
-                command.write(world);
+                command.apply(world);
                 std::mem::size_of::<C>()
             },
         };
@@ -165,7 +165,7 @@ mod test {
     }
 
     impl Command for DropCheck {
-        fn write(self, _: &mut World) {}
+        fn apply(self, _: &mut World) {}
     }
 
     #[test]
@@ -191,7 +191,7 @@ mod test {
     struct SpawnCommand;
 
     impl Command for SpawnCommand {
-        fn write(self, world: &mut World) {
+        fn apply(self, world: &mut World) {
             world.spawn_empty();
         }
     }
@@ -219,7 +219,7 @@ mod test {
     // some data added to it.
     struct PanicCommand(String);
     impl Command for PanicCommand {
-        fn write(self, _: &mut World) {
+        fn apply(self, _: &mut World) {
             panic!("command is panicking");
         }
     }
@@ -267,7 +267,7 @@ mod test {
 
     struct CommandWithPadding(u8, u16);
     impl Command for CommandWithPadding {
-        fn write(self, _: &mut World) {}
+        fn apply(self, _: &mut World) {}
     }
 
     #[cfg(miri)]

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

@@ -32,7 +32,7 @@ use super::{Deferred, Resource, SystemBuffer, SystemMeta};
 /// struct AddToCounter(u64);
 ///
 /// impl Command for AddToCounter {
-///     fn write(self, world: &mut World) {
+///     fn apply(self, world: &mut World) {
 ///         let mut counter = world.get_resource_or_insert_with(Counter::default);
 ///         counter.0 += self.0;
 ///     }
@@ -43,8 +43,12 @@ use super::{Deferred, Resource, SystemBuffer, SystemMeta};
 /// }
 /// ```
 pub trait Command: Send + 'static {
-    /// Executes this command.
-    fn write(self, world: &mut World);
+    /// Applies this command, causing it to mutate the provided `world`.
+    ///
+    /// This method is used to define what a command "does" when it is ultimately applied.
+    /// Because this method takes `self`, you can store data or settings on the type that implements this trait.
+    /// This data is set by the system or other source of the command, and then ultimately read in this method.
+    fn apply(self, world: &mut World);
 }
 
 /// A [`Command`] queue to perform impactful changes to the [`World`].
@@ -522,7 +526,7 @@ impl<'w, 's> Commands<'w, 's> {
     /// struct AddToCounter(u64);
     ///
     /// impl Command for AddToCounter {
-    ///     fn write(self, world: &mut World) {
+    ///     fn apply(self, world: &mut World) {
     ///         let mut counter = world.get_resource_or_insert_with(Counter::default);
     ///         counter.0 += self.0;
     ///     }
@@ -569,7 +573,7 @@ impl<'w, 's> Commands<'w, 's> {
 /// struct CountName;
 ///
 /// impl EntityCommand for CountName {
-///     fn write(self, id: Entity, world: &mut World) {
+///     fn apply(self, id: Entity, world: &mut World) {
 ///         // Get the current value of the counter, and increment it for next time.
 ///         let mut counter = world.resource_mut::<Counter>();
 ///         let i = counter.0;
@@ -605,7 +609,7 @@ impl<'w, 's> Commands<'w, 's> {
 /// ```
 pub trait EntityCommand: Send + 'static {
     /// Executes this command for the given [`Entity`].
-    fn write(self, id: Entity, world: &mut World);
+    fn apply(self, id: Entity, world: &mut World);
     /// Returns a [`Command`] which executes this [`EntityCommand`] for the given [`Entity`].
     fn with_entity(self, id: Entity) -> WithEntity<Self>
     where
@@ -623,8 +627,8 @@ pub struct WithEntity<C: EntityCommand> {
 
 impl<C: EntityCommand> Command for WithEntity<C> {
     #[inline]
-    fn write(self, world: &mut World) {
-        self.cmd.write(self.id, world);
+    fn apply(self, world: &mut World) {
+        self.cmd.apply(self.id, world);
     }
 }
 
@@ -829,7 +833,7 @@ impl<F> Command for F
 where
     F: FnOnce(&mut World) + Send + 'static,
 {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         self(world);
     }
 }
@@ -838,7 +842,7 @@ impl<F> EntityCommand for F
 where
     F: FnOnce(Entity, &mut World) + Send + 'static,
 {
-    fn write(self, id: Entity, world: &mut World) {
+    fn apply(self, id: Entity, world: &mut World) {
         self(id, world);
     }
 }
@@ -854,7 +858,7 @@ impl<T> Command for Spawn<T>
 where
     T: Bundle,
 {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         world.spawn(self.bundle);
     }
 }
@@ -876,7 +880,7 @@ where
     I: IntoIterator + Send + Sync + 'static,
     I::Item: Bundle,
 {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         world.spawn_batch(self.bundles_iter);
     }
 }
@@ -901,7 +905,7 @@ where
     B: Bundle,
     I::IntoIter: Iterator<Item = (Entity, B)>,
 {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         if let Err(invalid_entities) = world.insert_or_spawn_batch(self.bundles_iter) {
             error!(
                 "Failed to 'insert or spawn' bundle of type {} into the following invalid entities: {:?}",
@@ -921,7 +925,7 @@ pub struct Despawn {
 }
 
 impl Command for Despawn {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         world.despawn(self.entity);
     }
 }
@@ -938,7 +942,7 @@ impl<T> Command for Insert<T>
 where
     T: Bundle + 'static,
 {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         if let Some(mut entity) = world.get_entity_mut(self.entity) {
             entity.insert(self.bundle);
         } else {
@@ -961,7 +965,7 @@ impl<T> Command for Remove<T>
 where
     T: Bundle,
 {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         if let Some(mut entity_mut) = world.get_entity_mut(self.entity) {
             entity_mut.remove::<T>();
         }
@@ -985,7 +989,7 @@ pub struct InitResource<R: Resource + FromWorld> {
 }
 
 impl<R: Resource + FromWorld> Command for InitResource<R> {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         world.init_resource::<R>();
     }
 }
@@ -1006,7 +1010,7 @@ pub struct InsertResource<R: Resource> {
 }
 
 impl<R: Resource> Command for InsertResource<R> {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         world.insert_resource(self.resource);
     }
 }
@@ -1017,7 +1021,7 @@ pub struct RemoveResource<R: Resource> {
 }
 
 impl<R: Resource> Command for RemoveResource<R> {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         world.remove_resource::<R>();
     }
 }
@@ -1037,7 +1041,7 @@ pub struct LogComponents {
 }
 
 impl Command for LogComponents {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         let debug_infos: Vec<_> = world
             .inspect_entity(self.entity)
             .into_iter()

crates/bevy_hierarchy/src/child_builder.rs

@@ -169,7 +169,7 @@ pub struct AddChild {
 }
 
 impl Command for AddChild {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         world.entity_mut(self.parent).add_child(self.child);
     }
 }
@@ -183,7 +183,7 @@ pub struct InsertChildren {
 }
 
 impl Command for InsertChildren {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         world
             .entity_mut(self.parent)
             .insert_children(self.index, &self.children);
@@ -198,7 +198,7 @@ pub struct PushChildren {
 }
 
 impl Command for PushChildren {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         world.entity_mut(self.parent).push_children(&self.children);
     }
 }
@@ -210,7 +210,7 @@ pub struct RemoveChildren {
 }
 
 impl Command for RemoveChildren {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         remove_children(self.parent, &self.children, world);
     }
 }
@@ -222,7 +222,7 @@ pub struct ClearChildren {
 }
 
 impl Command for ClearChildren {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         clear_children(self.parent, world);
     }
 }
@@ -234,7 +234,7 @@ pub struct ReplaceChildren {
 }
 
 impl Command for ReplaceChildren {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         clear_children(self.parent, world);
         world.entity_mut(self.parent).push_children(&self.children);
     }
@@ -247,7 +247,7 @@ pub struct RemoveParent {
 }
 
 impl Command for RemoveParent {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         world.entity_mut(self.child).remove_parent();
     }
 }

crates/bevy_hierarchy/src/hierarchy.rs

@@ -55,7 +55,7 @@ fn despawn_children_recursive(world: &mut World, entity: Entity) {
 }
 
 impl Command for DespawnRecursive {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         #[cfg(feature = "trace")]
         let _span = bevy_utils::tracing::info_span!(
             "command",
@@ -68,7 +68,7 @@ impl Command for DespawnRecursive {
 }
 
 impl Command for DespawnChildrenRecursive {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         #[cfg(feature = "trace")]
         let _span = bevy_utils::tracing::info_span!(
             "command",

crates/bevy_scene/src/dynamic_scene.rs

@@ -208,7 +208,7 @@ mod tests {
             parent: original_parent_entity,
             child: original_child_entity,
         }
-        .write(&mut world);
+        .apply(&mut world);
 
         // We then write this relationship to a new scene, and then write that scene back to the
         // world to create another parent and child relationship
@@ -229,7 +229,7 @@ mod tests {
             parent: original_child_entity,
             child: from_scene_parent_entity,
         }
-        .write(&mut world);
+        .apply(&mut world);
 
         // We then reload the scene to make sure that from_scene_parent_entity's parent component
         // isn't updated with the entity map, since this component isn't defined in the scene.

crates/bevy_scene/src/scene_spawner.rs

@@ -284,7 +284,7 @@ impl SceneSpawner {
                             parent,
                             child: entity,
                         }
-                        .write(world);
+                        .apply(world);
                     }
                 }
             } else {

crates/bevy_transform/src/commands.rs

@@ -21,12 +21,12 @@ pub struct AddChildInPlace {
     pub child: Entity,
 }
 impl Command for AddChildInPlace {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         let hierarchy_command = AddChild {
             child: self.child,
             parent: self.parent,
         };
-        hierarchy_command.write(world);
+        hierarchy_command.apply(world);
         // FIXME: Replace this closure with a `try` block. See: https://github.com/rust-lang/rust/issues/31436.
         let mut update_transform = || {
             let parent = *world.get_entity(self.parent)?.get::<GlobalTransform>()?;
@@ -49,9 +49,9 @@ pub struct RemoveParentInPlace {
     pub child: Entity,
 }
 impl Command for RemoveParentInPlace {
-    fn write(self, world: &mut World) {
+    fn apply(self, world: &mut World) {
         let hierarchy_command = RemoveParent { child: self.child };
-        hierarchy_command.write(world);
+        hierarchy_command.apply(world);
         // FIXME: Replace this closure with a `try` block. See: https://github.com/rust-lang/rust/issues/31436.
         let mut update_transform = || {
             let child_global = *world.get_entity(self.child)?.get::<GlobalTransform>()?;