From fcaddc1a2a476b64cfd3bf2faa9de6eb85aee358 Mon Sep 17 00:00:00 2001 From: Manuel Fuchs Date: Thu, 25 Jan 2024 18:51:53 +0100 Subject: [PATCH] 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 | 11 +++++ crates/bevy_app/src/app.rs | 4 +- examples/README.md | 1 + examples/ecs/custom_schedule.rs | 82 +++++++++++++++++++++++++++++++++ 4 files changed, 96 insertions(+), 2 deletions(-) create mode 100644 examples/ecs/custom_schedule.rs diff --git a/Cargo.toml b/Cargo.toml index 65bf72603684f5..d6d0cac752eb00 100644 --- a/Cargo.toml +++ b/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" diff --git a/crates/bevy_app/src/app.rs b/crates/bevy_app/src/app.rs index f117db2e77e405..28c8f11b6baa05 100644 --- a/crates/bevy_app/src/app.rs +++ b/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::(); diff --git a/examples/README.md b/examples/README.md index e03d0a0db27d2c..4f671aa2cef3e7 100644 --- a/examples/README.md +++ b/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 diff --git a/examples/ecs/custom_schedule.rs b/examples/ecs/custom_schedule.rs new file mode 100644 index 00000000000000..f85da26e8fed97 --- /dev/null +++ b/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::(); + 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::(); + 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"); +}