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);
```
This commit is contained in:
Zachary Harrold 2024-12-03 09:16:58 +11:00 committed by GitHub
parent 793e2f2000
commit c02696b609
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -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`].