Add custom schedule example (#11527)

# Objective

Fixes #11411

## Solution

- Added a simple example how to create and configure custom schedules
that are run by the `Main` schedule.
- Spot checked some of the API docs used, fixed `App::add_schedule` docs
that referred to a function argument that was removed by #9600.

## Open Questions

- While spot checking the docs, I noticed that the `Schedule` label is
stored in a field called `name` instead of `label`. This seems
unintuitive since the term label is used everywhere else. Should we
change that field name? It was introduced in #9600. If so, I do think
this change would be out of scope for this PR that mainly adds the
example.

Cargo.toml

@@ -1341,6 +1341,17 @@ description = "Change detection on components"
 category = "ECS (Entity Component System)"
 wasm = false
 
+[[example]]
+name = "custom_schedule"
+path = "examples/ecs/custom_schedule.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.custom_schedule]
+name = "Custom Schedule"
+description = "Demonstrates how to add custom schedules"
+category = "ECS (Entity Component System)"
+wasm = false
+
 [[example]]
 name = "custom_query_param"
 path = "examples/ecs/custom_query_param.rs"

crates/bevy_app/src/app.rs

@@ -853,10 +853,10 @@ impl App {
             .ok_or(label)
     }
 
-    /// Adds a new `schedule` to the [`App`] under the provided `label`.
+    /// Adds a new `schedule` to the [`App`].
     ///
     /// # Warning
-    /// This method will overwrite any existing schedule at that label.
+    /// This method will overwrite any existing schedule with the same name.
     /// To avoid this behavior, use the `init_schedule` method instead.
     pub fn add_schedule(&mut self, schedule: Schedule) -> &mut Self {
         let mut schedules = self.world.resource_mut::<Schedules>();

examples/README.md

@@ -225,6 +225,7 @@ Example | Description
 --- | ---
 [Component Change Detection](../examples/ecs/component_change_detection.rs) | Change detection on components
 [Custom Query Parameters](../examples/ecs/custom_query_param.rs) | Groups commonly used compound queries and query filters into a single type
+[Custom Schedule](../examples/ecs/custom_schedule.rs) | Demonstrates how to add custom schedules
 [Dynamic ECS](../examples/ecs/dynamic.rs) | Dynamically create components, spawn entities with those components and query those components
 [ECS Guide](../examples/ecs/ecs_guide.rs) | Full guide to Bevy's ECS
 [Event](../examples/ecs/event.rs) | Illustrates event creation, activation, and reception

examples/ecs/custom_schedule.rs

@@ -0,0 +1,82 @@
+//! Demonstrates how to add custom schedules that run in Bevy's `Main` schedule, ordered relative to Bevy's built-in
+//! schedules such as `Update` or `Last`.
+
+use bevy::app::MainScheduleOrder;
+use bevy::ecs::schedule::{ExecutorKind, ScheduleLabel};
+use bevy::prelude::*;
+
+#[derive(ScheduleLabel, Debug, Hash, PartialEq, Eq, Clone)]
+struct SingleThreadedUpdate;
+
+#[derive(ScheduleLabel, Debug, Hash, PartialEq, Eq, Clone)]
+struct CustomStartup;
+
+fn main() {
+    let mut app = App::new();
+
+    // Create a new [`Schedule`]. For demonstration purposes, we configure it to use a single threaded executor so that
+    // systems in this schedule are never run in parallel. However, this is not a requirement for custom schedules in
+    // general.
+    let mut custom_update_schedule = Schedule::new(SingleThreadedUpdate);
+    custom_update_schedule.set_executor_kind(ExecutorKind::SingleThreaded);
+
+    // Adding the schedule to the app does not automatically run the schedule. This merely registers the schedule so
+    // that systems can look it up using the `Schedules` resource.
+    app.add_schedule(custom_update_schedule);
+
+    // Bevy `App`s have a `main_schedule_label` field that configures which schedule is run by the App's `runner`.
+    // By default, this is `Main`. The `Main` schedule is responsible for running Bevy's main schedules such as
+    // `Update`, `Startup` or `Last`.
+    //
+    // We can configure the `Main` schedule to run our custom update schedule relative to the existing ones by modifying
+    // the `MainScheduleOrder` resource.
+    //
+    // Note that we modify `MainScheduleOrder` directly in `main` and not in a startup system. The reason for this is
+    // that the `MainScheduleOrder` cannot be modified from systems that are run as part of the `Main` schedule.
+    let mut main_schedule_order = app.world.resource_mut::<MainScheduleOrder>();
+    main_schedule_order.insert_after(Update, SingleThreadedUpdate);
+
+    // Adding a custom startup schedule works similarly, but needs to use `insert_startup_after`
+    // instead of `insert_after`.
+    app.add_schedule(Schedule::new(CustomStartup));
+
+    let mut main_schedule_order = app.world.resource_mut::<MainScheduleOrder>();
+    main_schedule_order.insert_startup_after(PreStartup, CustomStartup);
+
+    app.add_systems(SingleThreadedUpdate, single_threaded_update_system)
+        .add_systems(CustomStartup, custom_startup_system)
+        .add_systems(PreStartup, pre_startup_system)
+        .add_systems(Startup, startup_system)
+        .add_systems(First, first_system)
+        .add_systems(Update, update_system)
+        .add_systems(Last, last_system)
+        .run();
+}
+
+fn pre_startup_system() {
+    println!("Pre Startup");
+}
+
+fn startup_system() {
+    println!("Startup");
+}
+
+fn custom_startup_system() {
+    println!("Custom Startup");
+}
+
+fn first_system() {
+    println!("First");
+}
+
+fn update_system() {
+    println!("Update");
+}
+
+fn single_threaded_update_system() {
+    println!("Single Threaded Update");
+}
+
+fn last_system() {
+    println!("Last");
+}