diff --git a/crates/bevy_ecs/src/schedule/schedule.rs b/crates/bevy_ecs/src/schedule/schedule.rs index b15860406b..667464ea8f 100644 --- a/crates/bevy_ecs/src/schedule/schedule.rs +++ b/crates/bevy_ecs/src/schedule/schedule.rs @@ -257,8 +257,16 @@ impl Chain { /// A collection of systems, and the metadata and executor needed to run them /// in a certain order under certain conditions. /// +/// # Schedule labels +/// +/// Each schedule has a [`ScheduleLabel`] value. This value is used to uniquely identify the +/// schedule when added to a [`World`]’s [`Schedules`], and may be used to specify which schedule +/// a system should be added to. +/// /// # Example +/// /// Here is an example of a `Schedule` running a "Hello world" system: +/// /// ``` /// # use bevy_ecs::prelude::*; /// fn hello_world() { println!("Hello world!") } @@ -273,6 +281,7 @@ impl Chain { /// ``` /// /// A schedule can also run several systems in an ordered way: +/// /// ``` /// # use bevy_ecs::prelude::*; /// fn system_one() { println!("System 1 works!") } @@ -291,6 +300,32 @@ impl Chain { /// schedule.run(&mut world); /// } /// ``` +/// +/// Schedules are often inserted into a [`World`] and identified by their [`ScheduleLabel`] only: +/// +/// ``` +/// # use bevy_ecs::prelude::*; +/// use bevy_ecs::schedule::ScheduleLabel; +/// +/// // Declare a new schedule label. +/// #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash, Default)] +/// struct Update; +/// +/// // This system shall be part of the schedule. +/// fn an_update_system() { +/// println!("Hello world!"); +/// } +/// +/// fn main() { +/// let mut world = World::new(); +/// +/// // Add a system to the schedule with that label (creating it automatically). +/// world.get_resource_or_init::().add_systems(Update, an_update_system); +/// +/// // Run the schedule, and therefore run the system. +/// world.run_schedule(Update); +/// } +/// ``` pub struct Schedule { label: InternedScheduleLabel, graph: ScheduleGraph, @@ -327,7 +362,8 @@ impl Schedule { this } - /// Get the `InternedScheduleLabel` for this `Schedule`. + /// Returns the [`InternedScheduleLabel`] for this `Schedule`, + /// corresponding to the [`ScheduleLabel`] this schedule was created with. pub fn label(&self) -> InternedScheduleLabel { self.label } diff --git a/crates/bevy_ecs/src/schedule/set.rs b/crates/bevy_ecs/src/schedule/set.rs index 896c7ed050..a652cd6df3 100644 --- a/crates/bevy_ecs/src/schedule/set.rs +++ b/crates/bevy_ecs/src/schedule/set.rs @@ -19,7 +19,39 @@ use crate::{ }; define_label!( - /// A strongly-typed class of labels used to identify a [`Schedule`](crate::schedule::Schedule). + /// A strongly-typed class of labels used to identify a [`Schedule`]. + /// + /// Each schedule in a [`World`] has a unique schedule label value, and + /// schedules can be automatically created from labels via [`Schedules::add_systems()`]. + /// + /// # Defining new schedule labels + /// + /// By default, you should use Bevy's premade schedule labels which implement this trait. + /// If you are using [`bevy_ecs`] directly or if you need to run a group of systems outside + /// the existing schedules, you may define your own schedule labels by using + /// `#[derive(ScheduleLabel)]`. + /// + /// ``` + /// use bevy_ecs::prelude::*; + /// use bevy_ecs::schedule::ScheduleLabel; + /// + /// // Declare a new schedule label. + /// #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash, Default)] + /// struct Update; + /// + /// let mut world = World::new(); + /// + /// // Add a system to the schedule with that label (creating it automatically). + /// fn a_system_function() {} + /// world.get_resource_or_init::().add_systems(Update, a_system_function); + /// + /// // Run the schedule, and therefore run the system. + /// world.run_schedule(Update); + /// ``` + /// + /// [`Schedule`]: crate::schedule::Schedule + /// [`Schedules::add_systems()`]: crate::schedule::Schedules::add_systems + /// [`World`]: crate::world::World #[diagnostic::on_unimplemented( note = "consider annotating `{Self}` with `#[derive(ScheduleLabel)]`" )] diff --git a/crates/bevy_ecs/src/world/mod.rs b/crates/bevy_ecs/src/world/mod.rs index 3a1195aea3..c6fdb4a345 100644 --- a/crates/bevy_ecs/src/world/mod.rs +++ b/crates/bevy_ecs/src/world/mod.rs @@ -3402,11 +3402,18 @@ impl World { // Schedule-related methods impl World { - /// Adds the specified [`Schedule`] to the world. The schedule can later be run + /// Adds the specified [`Schedule`] to the world. + /// If a schedule already exists with the same [label](Schedule::label), it will be replaced. + /// + /// The schedule can later be run /// by calling [`.run_schedule(label)`](Self::run_schedule) or by directly /// accessing the [`Schedules`] resource. /// /// The `Schedules` resource will be initialized if it does not already exist. + /// + /// An alternative to this is to call [`Schedules::add_systems()`] with some + /// [`ScheduleLabel`] and let the schedule for that label be created if it + /// does not already exist. pub fn add_schedule(&mut self, schedule: Schedule) { let mut schedules = self.get_resource_or_init::(); schedules.insert(schedule); @@ -3512,6 +3519,7 @@ impl World { /// and system state is cached. /// /// For simple testing use cases, call [`Schedule::run(&mut world)`](Schedule::run) instead. + /// This avoids the need to create a unique [`ScheduleLabel`]. /// /// # Panics ///