From c02696b6092308cc198ce3aee032079245d94df4 Mon Sep 17 00:00:00 2001
From: Zachary Harrold <zac@harrold.com.au>
Date: Tue, 3 Dec 2024 09:16:58 +1100
Subject: [PATCH] Add `Commands::run_schedule` (#16537)

# Objective

- Fixes #16495

## Solution

- Added `Commands::run_schedule`, which internally calls
`World::try_run_schedule`, logging any issues.

## Testing

- Added doctest
- Ran CI

## Showcase

Instead of writing:

```rust
commands.queue(|world: &mut World| world.run_schedule(FooSchedule));
```

You can now write:

```rust
commands.run_schedule(FooSchedule);
```
---
 crates/bevy_ecs/src/system/commands/mod.rs | 48 ++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/crates/bevy_ecs/src/system/commands/mod.rs b/crates/bevy_ecs/src/system/commands/mod.rs
index 1480c200ab..289e37e3b4 100644
--- a/crates/bevy_ecs/src/system/commands/mod.rs
+++ b/crates/bevy_ecs/src/system/commands/mod.rs
@@ -14,6 +14,7 @@ use crate::{
     entity::{Entities, Entity},
     event::{Event, SendEvent},
     observer::{Observer, TriggerEvent, TriggerTargets},
+    schedule::ScheduleLabel,
     system::{input::SystemInput, RunSystemWithInput, SystemId},
     world::{
         command_queue::RawCommandQueue, unsafe_world_cell::UnsafeWorldCell, Command, CommandQueue,
@@ -973,6 +974,53 @@ impl<'w, 's> Commands<'w, 's> {
         self.queue(SendEvent { event });
         self
     }
+
+    /// Runs the schedule corresponding to the given [`ScheduleLabel`].
+    ///
+    /// Calls [`World::try_run_schedule`](World::try_run_schedule).
+    ///
+    /// This will log an error if the schedule is not available to be run.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use bevy_ecs::prelude::*;
+    /// # use bevy_ecs::schedule::ScheduleLabel;
+    /// #
+    /// # #[derive(Default, Resource)]
+    /// # struct Counter(u32);
+    /// #
+    /// #[derive(ScheduleLabel, Hash, Debug, PartialEq, Eq, Clone, Copy)]
+    /// struct FooSchedule;
+    ///
+    /// # fn foo_system(mut counter: ResMut<Counter>) {
+    /// #     counter.0 += 1;
+    /// # }
+    /// #
+    /// # let mut schedule = Schedule::new(FooSchedule);
+    /// # schedule.add_systems(foo_system);
+    /// #
+    /// # let mut world = World::default();
+    /// #
+    /// # world.init_resource::<Counter>();
+    /// # world.add_schedule(schedule);
+    /// #
+    /// # assert_eq!(world.resource::<Counter>().0, 0);
+    /// #
+    /// # let mut commands = world.commands();
+    /// commands.run_schedule(FooSchedule);
+    /// #
+    /// # world.flush();
+    /// #
+    /// # assert_eq!(world.resource::<Counter>().0, 1);
+    /// ```
+    pub fn run_schedule(&mut self, label: impl ScheduleLabel) {
+        self.queue(|world: &mut World| {
+            if let Err(error) = world.try_run_schedule(label) {
+                panic!("Failed to run schedule: {error}");
+            }
+        });
+    }
 }
 
 /// A [`Command`] which gets executed for a given [`Entity`].