Use CommandContext and update docs

Author: NathanSWard

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

@@ -60,23 +60,23 @@ impl CommandErrorHandler {
     ///
     /// ## Note
     /// This is the default behavior if no error handler is specified.
-    pub fn log<E: Debug>(error: E, _world: &mut World) {
+    pub fn log<E: Debug>(error: E, _ctx: CommandContext) {
         error!("Commands failed with error: {:?}", error)
     }
 
     /// If the command failed, [`panic!`] with the error.
-    pub fn panic<E: Debug>(error: E, _world: &mut World) {
+    pub fn panic<E: Debug>(error: E, _ctx: CommandContext) {
         panic!("Commands failed with error: {:?}", error)
     }
 
     /// If the command failed, ignore the error and silently succeed.
-    pub fn ignore<E: Debug>(_error: E, _world: &mut World) {}
+    pub fn ignore<E>(_error: E, _ctx: CommandContext) {}
 }
 
 pub(crate) struct HandledErrorCommand<C, F>
 where
     C: FallibleCommand,
-    F: FnOnce(C::Error, &mut World) + Send + Sync + 'static,
+    F: FnOnce(C::Error, CommandContext) + Send + Sync + 'static,
 {
     pub(crate) command: C,
     pub(crate) error_handler: F,
@@ -85,7 +85,7 @@ where
 impl<C, F> Command for HandledErrorCommand<C, F>
 where
     C: FallibleCommand,
-    F: FnOnce(C::Error, &mut World) + Send + Sync + 'static,
+    F: FnOnce(C::Error, CommandContext) + Send + Sync + 'static,
 {
     fn write(self: Box<Self>, world: &mut World) {
         let HandledErrorCommand {
@@ -94,11 +94,16 @@ where
         } = *self;
 
         if let Err(error) = command.try_write(world) {
-            error_handler(error, world);
+            error_handler(error, CommandContext { world });
         }
     }
 }
 
+#[non_exhaustive]
+pub struct CommandContext<'a> {
+    pub world: &'a mut World,
+}
+
 /// Similar to [`FallibleCommandConfig`] however does not
 /// implement [`DerefMut`] nor return `&mut T` of the underlying
 /// Commands type.
@@ -147,10 +152,8 @@ macro_rules! impl_fallible_commands {
             /// If the command failed, run the provided `error_handler`.
             ///
             /// ## Note
-            /// This is normally used in conjunction with [`Handlers`].
-            /// However, this can also be used with custom error handler (e.g. closure)
-            /// if the parameter type is specific. You can use `on_err_do` if you don't
-            /// want to specify the type.
+            /// This is normally used in conjunction with [`CommandErrorHandler`].
+            /// However, this can also be used with custom error handlers (e.g. closures).
             ///
             /// # Examples
             /// ```
@@ -161,17 +164,20 @@ macro_rules! impl_fallible_commands {
             ///     commands.spawn().insert(42).on_err(CommandErrorHandler::ignore);
             ///
             ///     // custom error handler
-            ///     commands.spawn().insert(42).on_err(|error, world| {});
+            ///     commands.spawn().insert(42).on_err(|error, ctx| {});
             /// }
             /// ```
             pub fn on_err(
                 &mut self,
-                handler: impl FnOnce(C::Error, &mut World) + Send + Sync + 'static,
+                error_handler: impl FnOnce(C::Error, CommandContext) + Send + Sync + 'static,
             ) -> $returnty {
-                let command = self.command.take().unwrap();
+                let command = self
+                    .command
+                    .take()
+                    .expect("Cannot call `on_err` multiple times for a command error handler.");
                 self.inner.add_command(HandledErrorCommand {
                     command,
-                    error_handler: handler,
+                    error_handler,
                 });
                 self.$returnfunc()
             }

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

@@ -531,7 +531,7 @@ impl<T> Debug for RemoveBundleError<T> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_struct("RemoveBundleError")
             .field("entity", &self.entity)
-            .field("component_type", &std::any::type_name::<T>())
+            .field("bundle_type", &std::any::type_name::<T>())
             .finish()
     }
 }

examples/ecs/command_error_handling.rs

@@ -42,16 +42,17 @@ fn log_failed_despawn_attempts(attempts: Res<FailedDespawnAttempts>) {
 
 fn despawn_all_entities(mut commands: Commands, query: Query<Entity>) {
     for e in query.iter() {
-        // `on_err_do` allows you to provide a custom error handler!
-        commands.entity(e).despawn().on_err(|error, world| {
+        // `on_err` also allows you to provide a custom error handler!
+        commands.entity(e).despawn().on_err(|error, ctx| {
             // You'll notice that the `error` will also give you back the entity
             // you tried to despawn.
             let entity = error.entity;
 
             warn!("Sadly our entity '{:?}' didn't despawn :(", entity);
 
             // error handlers have mutable access to `World`
-            if let Some(mut failed_despawns) = world.get_resource_mut::<FailedDespawnAttempts>() {
+            if let Some(mut failed_despawns) = ctx.world.get_resource_mut::<FailedDespawnAttempts>()
+            {
                 failed_despawns.0 += 1;
             }
         });