System Stepping implemented as Resource (#8453)

# Objective

Add interactive system debugging capabilities to bevy, providing
step/break/continue style capabilities to running system schedules.

* Original implementation: #8063
    - `ignore_stepping()` everywhere was too much complexity
* Schedule-config & Resource discussion: #8168
    - Decided on selective adding of Schedules & Resource-based control

## Solution
Created `Stepping` Resource. This resource can be used to enable
stepping on a per-schedule basis. Systems within schedules can be
individually configured to:
* AlwaysRun: Ignore any stepping state and run every frame
* NeverRun: Never run while stepping is enabled
    - this allows for disabling of systems while debugging
* Break: If we're running the full frame, stop before this system is run

Stepping provides two modes of execution that reflect traditional
debuggers:
* Step-based: Only execute one system at a time
* Continue/Break: Run all systems, but stop before running a system
marked as Break

### Demo

https://user-images.githubusercontent.com/857742/233630981-99f3bbda-9ca6-4cc4-a00f-171c4946dc47.mov

Breakout has been modified to use Stepping. The game runs normally for a
couple of seconds, then stepping is enabled and the game appears to
pause. A list of Schedules & Systems appears with a cursor at the first
System in the list. The demo then steps forward full frames using the
spacebar until the ball is about to hit a brick. Then we step system by
system as the ball impacts a brick, showing the cursor moving through
the individual systems. Finally the demo switches back to frame stepping
as the ball changes course.


### Limitations
Due to architectural constraints in bevy, there are some cases systems
stepping will not function as a user would expect.

#### Event-driven systems
Stepping does not support systems that are driven by `Event`s as events
are flushed after 1-2 frames. Although game systems are not running
while stepping, ignored systems are still running every frame, so events
will be flushed.

This presents to the user as stepping the event-driven system never
executes the system. It does execute, but the events have already been
flushed.

This can be resolved by changing event handling to use a buffer for
events, and only dropping an event once all readers have read it.

The work-around to allow these systems to properly execute during
stepping is to have them ignore stepping:
`app.add_systems(event_driven_system.ignore_stepping())`. This was done
in the breakout example to ensure sound played even while stepping.

#### Conditional Systems
When a system is stepped, it is given an opportunity to run. If the
conditions of the system say it should not run, it will not.

Similar to Event-driven systems, if a system is conditional, and that
condition is only true for a very small time window, then stepping the
system may not execute the system. This includes depending on any sort
of external clock.

This exhibits to the user as the system not always running when it is
stepped.

A solution to this limitation is to ensure any conditions are consistent
while stepping is enabled. For example, all systems that modify any
state the condition uses should also enable stepping.

#### State-transition Systems
Stepping is configured on the per-`Schedule` level, requiring the user
to have a `ScheduleLabel`.

To support state-transition systems, bevy generates needed schedules
dynamically. Currently it’s very difficult (if not impossible, I haven’t
verified) for the user to get the labels for these schedules.

Without ready access to the dynamically generated schedules, and a
resolution for the `Event` lifetime, **stepping of the state-transition
systems is not supported**

---

## Changelog
- `Schedule::run()` updated to consult `Stepping` Resource to determine
which Systems to run each frame
- Added `Schedule.label` as a `BoxedSystemLabel`, along with supporting
`Schedule::set_label()` and `Schedule::label()` methods
- `Stepping` needed to know which `Schedule` was running, and prior to
this PR, `Schedule` didn't track its own label
- Would have preferred to add `Schedule::with_label()` and remove
`Schedule::new()`, but this PR touches enough already
- Added calls to `Schedule.set_label()` to `App` and `World` as needed
- Added `Stepping` resource
- Added `Stepping::begin_frame()` system to `MainSchedulePlugin`
    - Run before `Main::run_main()`
    - Notifies any `Stepping` Resource a new render frame is starting
    
## Migration Guide
- Add a call to `Schedule::set_label()` for any custom `Schedule`
    - This is only required if the `Schedule` will be stepped

---------

Co-authored-by: Carter Anderson <mcanders1@gmail.com>

Cargo.toml

@@ -71,6 +71,7 @@ default = [
   "tonemapping_luts",
   "default_font",
   "webgl2",
+  "bevy_debug_stepping",
 ]
 
 # Force dynamic linking, which improves iterative compile times
@@ -295,6 +296,9 @@ file_watcher = ["bevy_internal/file_watcher"]
 # Enables watching in memory asset providers for Bevy Asset hot-reloading
 embedded_watcher = ["bevy_internal/embedded_watcher"]
 
+# Enable stepping-based debugging of Bevy systems
+bevy_debug_stepping = ["bevy_internal/bevy_debug_stepping"]
+
 [dependencies]
 bevy_dylib = { path = "crates/bevy_dylib", version = "0.12.0", default-features = false, optional = true }
 bevy_internal = { path = "crates/bevy_internal", version = "0.12.0", default-features = false }
@@ -1566,6 +1570,17 @@ description = "Illustrates creating custom system parameters with `SystemParam`"
 category = "ECS (Entity Component System)"
 wasm = false
 
+[[example]]
+name = "system_stepping"
+path = "examples/ecs/system_stepping.rs"
+doc-scrape-examples = true
+
+[package.metadata.example.system_stepping]
+name = "System Stepping"
+description = "Demonstrate stepping through systems in order of execution"
+category = "ECS (Entity Component System)"
+wasm = false
+
 # Time
 [[example]]
 name = "time"

crates/bevy_app/Cargo.toml

@@ -11,7 +11,8 @@ keywords = ["bevy"]
 [features]
 trace = []
 bevy_ci_testing = ["serde", "ron"]
-default = ["bevy_reflect"]
+bevy_debug_stepping = []
+default = ["bevy_reflect", "bevy_debug_stepping"]
 bevy_reflect = ["dep:bevy_reflect", "bevy_ecs/bevy_reflect"]
 
 [dependencies]

crates/bevy_app/src/main_schedule.rs

@@ -256,6 +256,12 @@ impl Plugin for MainSchedulePlugin {
             .init_resource::<FixedMainScheduleOrder>()
             .add_systems(Main, Main::run_main)
             .add_systems(FixedMain, FixedMain::run_fixed_main);
+
+        #[cfg(feature = "bevy_debug_stepping")]
+        {
+            use bevy_ecs::schedule::{IntoSystemConfigs, Stepping};
+            app.add_systems(Main, Stepping::begin_frame.before(Main::run_main));
+        }
     }
 }
 

crates/bevy_ecs/Cargo.toml

@@ -12,7 +12,8 @@ categories = ["game-engines", "data-structures"]
 [features]
 trace = []
 multi-threaded = ["bevy_tasks/multi-threaded"]
-default = ["bevy_reflect"]
+bevy_debug_stepping = []
+default = ["bevy_reflect", "bevy_debug_stepping"]
 
 [dependencies]
 bevy_ptr = { path = "../bevy_ptr", version = "0.12.0" }

crates/bevy_ecs/src/schedule/executor/mod.rs

@@ -18,7 +18,12 @@ use crate::{
 pub(super) trait SystemExecutor: Send + Sync {
     fn kind(&self) -> ExecutorKind;
     fn init(&mut self, schedule: &SystemSchedule);
-    fn run(&mut self, schedule: &mut SystemSchedule, world: &mut World);
+    fn run(
+        &mut self,
+        schedule: &mut SystemSchedule,
+        skip_systems: Option<FixedBitSet>,
+        world: &mut World,
+    );
     fn set_apply_final_deferred(&mut self, value: bool);
 }
 

crates/bevy_ecs/src/schedule/executor/multi_threaded.rs

@@ -163,7 +163,12 @@ impl SystemExecutor for MultiThreadedExecutor {
         self.num_dependencies_remaining = Vec::with_capacity(sys_count);
     }
 
-    fn run(&mut self, schedule: &mut SystemSchedule, world: &mut World) {
+    fn run(
+        &mut self,
+        schedule: &mut SystemSchedule,
+        _skip_systems: Option<FixedBitSet>,
+        world: &mut World,
+    ) {
         // reset counts
         self.num_systems = schedule.systems.len();
         if self.num_systems == 0 {
@@ -181,6 +186,31 @@ impl SystemExecutor for MultiThreadedExecutor {
             }
         }
 
+        // If stepping is enabled, make sure we skip those systems that should
+        // not be run.
+        #[cfg(feature = "bevy_debug_stepping")]
+        if let Some(mut skipped_systems) = _skip_systems {
+            debug_assert_eq!(skipped_systems.len(), self.completed_systems.len());
+            // mark skipped systems as completed
+            self.completed_systems |= &skipped_systems;
+            self.num_completed_systems = self.completed_systems.count_ones(..);
+
+            // signal the dependencies for each of the skipped systems, as
+            // though they had run
+            for system_index in skipped_systems.ones() {
+                self.signal_dependents(system_index);
+            }
+
+            // Finally, we need to clear all skipped systems from the ready
+            // list.
+            //
+            // We invert the skipped system mask to get the list of systems
+            // that should be run.  Then we bitwise AND it with the ready list,
+            // resulting in a list of ready systems that aren't skipped.
+            skipped_systems.toggle_range(..);
+            self.ready_systems &= skipped_systems;
+        }
+
         let thread_executor = world
             .get_resource::<MainThreadExecutor>()
             .map(|e| e.0.clone());

crates/bevy_ecs/src/schedule/executor/simple.rs

@@ -30,7 +30,20 @@ impl SystemExecutor for SimpleExecutor {
         self.completed_systems = FixedBitSet::with_capacity(sys_count);
     }
 
-    fn run(&mut self, schedule: &mut SystemSchedule, world: &mut World) {
+    fn run(
+        &mut self,
+        schedule: &mut SystemSchedule,
+        _skip_systems: Option<FixedBitSet>,
+        world: &mut World,
+    ) {
+        // If stepping is enabled, make sure we skip those systems that should
+        // not be run.
+        #[cfg(feature = "bevy_debug_stepping")]
+        if let Some(skipped_systems) = _skip_systems {
+            // mark skipped systems as completed
+            self.completed_systems |= &skipped_systems;
+        }
+
         for system_index in 0..schedule.systems.len() {
             #[cfg(feature = "trace")]
             let name = schedule.systems[system_index].name();

crates/bevy_ecs/src/schedule/executor/single_threaded.rs

@@ -38,7 +38,20 @@ impl SystemExecutor for SingleThreadedExecutor {
         self.unapplied_systems = FixedBitSet::with_capacity(sys_count);
     }
 
-    fn run(&mut self, schedule: &mut SystemSchedule, world: &mut World) {
+    fn run(
+        &mut self,
+        schedule: &mut SystemSchedule,
+        _skip_systems: Option<FixedBitSet>,
+        world: &mut World,
+    ) {
+        // If stepping is enabled, make sure we skip those systems that should
+        // not be run.
+        #[cfg(feature = "bevy_debug_stepping")]
+        if let Some(skipped_systems) = _skip_systems {
+            // mark skipped systems as completed
+            self.completed_systems |= &skipped_systems;
+        }
+
         for system_index in 0..schedule.systems.len() {
             #[cfg(feature = "trace")]
             let name = schedule.systems[system_index].name();

crates/bevy_ecs/src/schedule/mod.rs

@@ -8,6 +8,7 @@ mod graph_utils;
 mod schedule;
 mod set;
 mod state;
+mod stepping;
 
 pub use self::condition::*;
 pub use self::config::*;
@@ -1098,4 +1099,60 @@ mod tests {
             assert!(schedule.graph().conflicting_systems().is_empty());
         }
     }
+
+    #[cfg(feature = "bevy_debug_stepping")]
+    mod stepping {
+        use super::*;
+        use bevy_ecs::system::SystemState;
+
+        #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
+        pub struct TestSchedule;
+
+        macro_rules! assert_executor_supports_stepping {
+            ($executor:expr) => {
+                // create a test schedule
+                let mut schedule = Schedule::new(TestSchedule);
+                schedule
+                    .set_executor_kind($executor)
+                    .add_systems(|| panic!("Executor ignored Stepping"));
+
+                // Add our schedule to stepping & and enable stepping; this should
+                // prevent any systems in the schedule from running
+                let mut stepping = Stepping::default();
+                stepping.add_schedule(TestSchedule).enable();
+
+                // create a world, and add the stepping resource
+                let mut world = World::default();
+                world.insert_resource(stepping);
+
+                // start a new frame by running ihe begin_frame() system
+                let mut system_state: SystemState<Option<ResMut<Stepping>>> =
+                    SystemState::new(&mut world);
+                let res = system_state.get_mut(&mut world);
+                Stepping::begin_frame(res);
+
+                // now run the schedule; this will panic if the executor doesn't
+                // handle stepping
+                schedule.run(&mut world);
+            };
+        }
+
+        /// verify the [`SimpleExecutor`] supports stepping
+        #[test]
+        fn simple_executor() {
+            assert_executor_supports_stepping!(ExecutorKind::Simple);
+        }
+
+        /// verify the [`SingleThreadedExecutor`] supports stepping
+        #[test]
+        fn single_threaded_executor() {
+            assert_executor_supports_stepping!(ExecutorKind::SingleThreaded);
+        }
+
+        /// verify the [`MultiThreadedExecutor`] supports stepping
+        #[test]
+        fn multi_threaded_executor() {
+            assert_executor_supports_stepping!(ExecutorKind::MultiThreaded);
+        }
+    }
 }

crates/bevy_ecs/src/schedule/schedule.rs

@@ -25,6 +25,8 @@ use crate::{
     world::World,
 };
 
+pub use stepping::Stepping;
+
 /// Resource that stores [`Schedule`]s mapped to [`ScheduleLabel`]s excluding the current running [`Schedule`].
 #[derive(Default, Resource)]
 pub struct Schedules {
@@ -238,6 +240,11 @@ impl Schedule {
         }
     }
 
+    /// Get the `InternedScheduleLabel` for this `Schedule`.
+    pub fn label(&self) -> InternedScheduleLabel {
+        self.label
+    }
+
     /// Add a collection of systems to the schedule.
     pub fn add_systems<M>(&mut self, systems: impl IntoSystemConfigs<M>) -> &mut Self {
         self.graph.process_configs(systems.into_configs(), false);
@@ -324,7 +331,17 @@ impl Schedule {
         world.check_change_ticks();
         self.initialize(world)
             .unwrap_or_else(|e| panic!("Error when initializing schedule {:?}: {e}", self.label));
-        self.executor.run(&mut self.executable, world);
+
+        #[cfg(not(feature = "bevy_debug_stepping"))]
+        let skip_systems = None;
+
+        #[cfg(feature = "bevy_debug_stepping")]
+        let skip_systems = match world.get_resource_mut::<Stepping>() {
+            None => None,
+            Some(mut stepping) => stepping.skipped_systems(self),
+        };
+
+        self.executor.run(&mut self.executable, skip_systems, world);
     }
 
     /// Initializes any newly-added systems and conditions, rebuilds the executable schedule,
@@ -366,6 +383,11 @@ impl Schedule {
         &mut self.graph
     }
 
+    /// Returns the [`SystemSchedule`].
+    pub(crate) fn executable(&self) -> &SystemSchedule {
+        &self.executable
+    }
+
     /// Iterates the change ticks of all systems in the schedule and clamps any older than
     /// [`MAX_CHANGE_AGE`](crate::change_detection::MAX_CHANGE_AGE).
     /// This prevents overflow and thus prevents false positives.
@@ -402,6 +424,36 @@ impl Schedule {
             system.apply_deferred(world);
         }
     }
+
+    /// Returns an iterator over all systems in this schedule.
+    ///
+    /// Note: this method will return [`ScheduleNotInitialized`] if the
+    /// schedule has never been initialized or run.
+    pub fn systems(
+        &self,
+    ) -> Result<impl Iterator<Item = (NodeId, &BoxedSystem)> + Sized, ScheduleNotInitialized> {
+        if !self.executor_initialized {
+            return Err(ScheduleNotInitialized);
+        }
+
+        let iter = self
+            .executable
+            .system_ids
+            .iter()
+            .zip(&self.executable.systems)
+            .map(|(node_id, system)| (*node_id, system));
+
+        Ok(iter)
+    }
+
+    /// Returns the number of systems in this schedule.
+    pub fn systems_len(&self) -> usize {
+        if !self.executor_initialized {
+            self.graph.systems.len()
+        } else {
+            self.executable.systems.len()
+        }
+    }
 }
 
 /// A directed acyclic graph structure.
@@ -1939,6 +1991,12 @@ impl ScheduleBuildSettings {
     }
 }
 
+/// Error to denote that [`Schedule::initialize`] or [`Schedule::run`] has not yet been called for
+/// this schedule.
+#[derive(Error, Debug)]
+#[error("executable schedule has not been built")]
+pub struct ScheduleNotInitialized;
+
 #[cfg(test)]
 mod tests {
     use crate::{

crates/bevy_internal/Cargo.toml

@@ -156,6 +156,12 @@ file_watcher = ["bevy_asset?/file_watcher"]
 # Enables watching embedded files for Bevy Asset hot-reloading
 embedded_watcher = ["bevy_asset?/embedded_watcher"]
 
+# Enable system stepping support
+bevy_debug_stepping = [
+  "bevy_ecs/bevy_debug_stepping",
+  "bevy_app/bevy_debug_stepping",
+]
+
 [dependencies]
 # bevy
 bevy_a11y = { path = "../bevy_a11y", version = "0.12.0" }

docs/cargo_features.md

@@ -17,6 +17,7 @@ The default feature set enables most of the expected features of a game engine,
 |bevy_asset|Provides asset functionality|
 |bevy_audio|Provides audio functionality|
 |bevy_core_pipeline|Provides cameras and other basic render pipeline features|
+|bevy_debug_stepping|Enable stepping-based debugging of Bevy systems|
 |bevy_gilrs|Adds gamepad support|
 |bevy_gizmos|Adds support for rendering gizmos|
 |bevy_gltf|[glTF](https://www.khronos.org/gltf/) support|

examples/README.md

@@ -246,6 +246,7 @@ Example | Description
 [System Closure](../examples/ecs/system_closure.rs) | Show how to use closures as systems, and how to configure `Local` variables by capturing external state
 [System Parameter](../examples/ecs/system_param.rs) | Illustrates creating custom system parameters with `SystemParam`
 [System Piping](../examples/ecs/system_piping.rs) | Pipe the output of one system into a second, allowing you to handle any errors gracefully
+[System Stepping](../examples/ecs/system_stepping.rs) | Demonstrate stepping through systems in order of execution
 
 ## Games
 

examples/ecs/system_stepping.rs

@@ -0,0 +1,204 @@
+use bevy::{ecs::schedule::Stepping, log::LogPlugin, prelude::*};
+
+fn main() {
+    let mut app = App::new();
+
+    app
+        // to display log messages from Stepping resource
+        .add_plugins(LogPlugin::default())
+        .add_systems(
+            Update,
+            (
+                update_system_one,
+                // establish a dependency here to simplify descriptions below
+                update_system_two.after(update_system_one),
+                update_system_three.after(update_system_two),
+                update_system_four,
+            ),
+        )
+        .add_systems(PreUpdate, pre_update_system);
+
+    // For the simplicity of this example, we directly modify the `Stepping`
+    // resource here and run the systems with `App::update()`.  Each call to
+    // `App::update()` is the equivalent of a single frame render when using
+    // `App::run()`.
+    //
+    // In a real-world situation, the `Stepping` resource would be modified by
+    // a system based on input from the user.  A full demonstration of this can
+    // be found in the breakout example.
+    println!(
+        r#"
+    Actions: call app.update()
+     Result: All systems run normally"#
+    );
+    app.update();
+
+    println!(
+        r#"
+    Actions: Add the Stepping resource then call app.update()
+     Result: All systems run normally.  Stepping has no effect unless explicitly
+             configured for a Schedule, and Stepping has been enabled."#
+    );
+    app.insert_resource(Stepping::new());
+    app.update();
+
+    println!(
+        r#"
+    Actions: Add the Update Schedule to Stepping; enable Stepping; call
+             app.update()
+     Result: Only the systems in PreUpdate run.  When Stepping is enabled,
+             systems in the configured schedules will not run unless:
+             * Stepping::step_frame() is called
+             * Stepping::continue_frame() is called
+             * System has been configured to always run"#
+    );
+    let mut stepping = app.world.resource_mut::<Stepping>();
+    stepping.add_schedule(Update).enable();
+    app.update();
+
+    println!(
+        r#"
+    Actions: call Stepping.step_frame(); call app.update()
+     Result: The PreUpdate systems run, and one Update system will run.  In
+             Stepping, step means run the next system across all the schedules 
+             that have been added to the Stepping resource."#
+    );
+    let mut stepping = app.world.resource_mut::<Stepping>();
+    stepping.step_frame();
+    app.update();
+
+    println!(
+        r#"
+    Actions: call app.update()
+     Result: Only the PreUpdate systems run.  The previous call to
+             Stepping::step_frame() only applies for the next call to
+             app.update()/the next frame rendered.
+    "#
+    );
+    app.update();
+
+    println!(
+        r#"
+    Actions: call Stepping::continue_frame(); call app.update()
+     Result: PreUpdate system will run, and all remaining Update systems will
+             run.  Stepping::continue_frame() tells stepping to run all systems
+             starting after the last run system until it hits the end of the
+             frame, or it encounters a system with a breakpoint set.  In this
+             case, we previously performed a step, running one system in Update.
+             This continue will cause all remaining systems in Update to run."#
+    );
+    let mut stepping = app.world.resource_mut::<Stepping>();
+    stepping.continue_frame();
+    app.update();
+
+    println!(
+        r#"
+    Actions: call Stepping::step_frame() & app.update() four times in a row
+     Result: PreUpdate system runs every time we call app.update(), along with
+             one system from the Update schedule each time.  This shows what
+             execution would look like to step through an entire frame of 
+             systems."#
+    );
+    for _ in 0..4 {
+        let mut stepping = app.world.resource_mut::<Stepping>();
+        stepping.step_frame();
+        app.update();
+    }
+
+    println!(
+        r#"
+    Actions: Stepping::always_run(Update, update_system_two); step through all
+             systems
+     Result: PreUpdate system and update_system_two() will run every time we
+             call app.update().  We'll also only need to step three times to
+             execute all systems in the frame.  Stepping::always_run() allows
+             us to granularly allow systems to run when stepping is enabled."#
+    );
+    let mut stepping = app.world.resource_mut::<Stepping>();
+    stepping.always_run(Update, update_system_two);
+    for _ in 0..3 {
+        let mut stepping = app.world.resource_mut::<Stepping>();
+        stepping.step_frame();
+        app.update();
+    }
+
+    println!(
+        r#"
+    Actions: Stepping::never_run(Update, update_system_two); continue through
+             all systems
+     Result: All systems except update_system_two() will execute.
+             Stepping::never_run() allows us to disable systems while Stepping
+             is enabled."#
+    );
+    let mut stepping = app.world.resource_mut::<Stepping>();
+    stepping.never_run(Update, update_system_two);
+    stepping.continue_frame();
+    app.update();
+
+    println!(
+        r#"
+    Actions: Stepping::set_breakpoint(Update, update_system_two); continue,
+             step, continue
+     Result: During the first continue, pre_update_system() and
+             update_system_one() will run.  update_system_four() may also run
+             as it has no dependency on update_system_two() or
+             update_system_three().  Nether update_system_two() nor
+             update_system_three() will run in the first app.update() call as
+             they form a chained dependency on update_system_one() and run
+             in order of one, two, three.  Stepping stops system execution in
+             the Update schedule when it encounters the breakpoint for
+             update_system_three().
+             During the step we run update_system_two() along with the
+             pre_update_system().
+             During the final continue pre_update_system() and
+             update_system_three() run."#
+    );
+    let mut stepping = app.world.resource_mut::<Stepping>();
+    stepping.set_breakpoint(Update, update_system_two);
+    stepping.continue_frame();
+    app.update();
+    let mut stepping = app.world.resource_mut::<Stepping>();
+    stepping.step_frame();
+    app.update();
+    let mut stepping = app.world.resource_mut::<Stepping>();
+    stepping.continue_frame();
+    app.update();
+
+    println!(
+        r#"
+    Actions: Stepping::clear_breakpoint(Update, update_system_two); continue
+             through all systems
+     Result: All systems will run"#
+    );
+    let mut stepping = app.world.resource_mut::<Stepping>();
+    stepping.clear_breakpoint(Update, update_system_two);
+    stepping.continue_frame();
+    app.update();
+
+    println!(
+        r#"
+    Actions: Stepping::disable(); app.update()
+     Result: All systems will run.  With Stepping disabled, there's no need to
+             call Stepping::step_frame() or Stepping::continue_frame() to run
+             systems in the Update schedule."#
+    );
+    let mut stepping = app.world.resource_mut::<Stepping>();
+    stepping.disable();
+    app.update();
+}
+
+fn pre_update_system() {
+    println!("▶ pre_update_system");
+}
+fn update_system_one() {
+    println!("▶ update_system_one");
+}
+fn update_system_two() {
+    println!("▶ update_system_two");
+}
+fn update_system_three() {
+    println!("▶ update_system_three");
+}
+fn update_system_four() {
+    println!("▶ update_system_four");
+}

examples/games/breakout.rs

@@ -6,6 +6,8 @@ use bevy::{
     sprite::MaterialMesh2dBundle,
 };
 
+mod stepping;
+
 // These constants are defined in `Transform` units.
 // Using the default 2D camera they correspond 1:1 with screen pixels.
 const PADDLE_SIZE: Vec3 = Vec3::new(120.0, 20.0, 0.0);
@@ -50,6 +52,12 @@ const SCORE_COLOR: Color = Color::rgb(1.0, 0.5, 0.5);
 fn main() {
     App::new()
         .add_plugins(DefaultPlugins)
+        .add_plugins(
+            stepping::SteppingPlugin::default()
+                .add_schedule(Update)
+                .add_schedule(FixedUpdate)
+                .at(Val::Percent(35.0), Val::Percent(50.0)),
+        )
         .insert_resource(Scoreboard { score: 0 })
         .insert_resource(ClearColor(BACKGROUND_COLOR))
         .add_event::<CollisionEvent>()
@@ -170,6 +178,9 @@ struct Scoreboard {
     score: usize,
 }
 
+#[derive(Component)]
+struct ScoreboardUi;
+
 // Add the game's entities to our world
 fn setup(
     mut commands: Commands,
@@ -218,7 +229,8 @@ fn setup(
     ));
 
     // Scoreboard
-    commands.spawn(
+    commands.spawn((
+        ScoreboardUi,
         TextBundle::from_sections([
             TextSection::new(
                 "Score: ",
@@ -240,7 +252,7 @@ fn setup(
             left: SCOREBOARD_TEXT_PADDING,
             ..default()
         }),
-    );
+    ));
 
     // Walls
     commands.spawn(WallBundle::new(WallLocation::Left));
@@ -338,7 +350,7 @@ fn apply_velocity(mut query: Query<(&mut Transform, &Velocity)>, time: Res<Time>
     }
 }
 
-fn update_scoreboard(scoreboard: Res<Scoreboard>, mut query: Query<&mut Text>) {
+fn update_scoreboard(scoreboard: Res<Scoreboard>, mut query: Query<&mut Text, With<ScoreboardUi>>) {
     let mut text = query.single_mut();
     text.sections[1].value = scoreboard.score.to_string();
 }

examples/games/stepping.rs

@@ -0,0 +1,273 @@
+use bevy::{app::MainScheduleOrder, ecs::schedule::*, prelude::*};
+
+/// Independent [`Schedule`] for stepping systems.
+///
+/// The stepping systems must run in their own schedule to be able to inspect
+/// all the other schedules in the [`App`].  This is because the currently
+/// executing schedule is removed from the [`Schedules`] resource while it is
+/// being run.
+#[derive(Debug, Hash, PartialEq, Eq, Clone, ScheduleLabel)]
+struct DebugSchedule;
+
+/// Plugin to add a stepping UI to an example
+#[derive(Default)]
+pub struct SteppingPlugin {
+    schedule_labels: Vec<InternedScheduleLabel>,
+    top: Val,
+    left: Val,
+}
+
+impl SteppingPlugin {
+    /// add a schedule to be stepped when stepping is enabled
+    pub fn add_schedule(mut self, label: impl ScheduleLabel) -> SteppingPlugin {
+        self.schedule_labels.push(label.intern());
+        self
+    }
+
+    /// Set the location of the stepping UI when activated
+    pub fn at(self, left: Val, top: Val) -> SteppingPlugin {
+        SteppingPlugin { top, left, ..self }
+    }
+}
+
+impl Plugin for SteppingPlugin {
+    fn build(&self, app: &mut App) {
+        // create and insert our debug schedule into the main schedule order.
+        // We need an independent schedule so we have access to all other
+        // schedules through the `Stepping` resource
+        app.init_schedule(DebugSchedule);
+        let mut order = app.world.resource_mut::<MainScheduleOrder>();
+        order.insert_after(Update, DebugSchedule);
+
+        // create our stepping resource
+        let mut stepping = Stepping::new();
+        for label in &self.schedule_labels {
+            stepping.add_schedule(*label);
+        }
+        app.insert_resource(stepping);
+
+        // add our startup & stepping systems
+        app.insert_resource(State {
+            ui_top: self.top,
+            ui_left: self.left,
+            systems: Vec::new(),
+        })
+        .add_systems(Startup, build_help)
+        .add_systems(
+            DebugSchedule,
+            (
+                build_ui.run_if(not(initialized)),
+                handle_input,
+                update_ui.run_if(initialized),
+            )
+                .chain(),
+        );
+    }
+}
+
+/// Struct for maintaining stepping state
+#[derive(Resource, Debug)]
+struct State {
+    // vector of schedule/nodeid -> text index offset
+    systems: Vec<(InternedScheduleLabel, NodeId, usize)>,
+
+    // ui positioning
+    ui_top: Val,
+    ui_left: Val,
+}
+
+/// condition to check if the stepping UI has been constructed
+fn initialized(state: Res<State>) -> bool {
+    !state.systems.is_empty()
+}
+
+const FONT_SIZE: f32 = 20.0;
+const FONT_COLOR: Color = Color::rgb(0.2, 0.2, 0.2);
+const FONT_BOLD: &str = "fonts/FiraSans-Bold.ttf";
+const FONT_MEDIUM: &str = "fonts/FiraMono-Medium.ttf";
+
+#[derive(Component)]
+struct SteppingUi;
+
+/// Construct the stepping UI elements from the [`Schedules`] resource.
+///
+/// This system may run multiple times before constructing the UI as all of the
+/// data may not be available on the first run of the system.  This happens if
+/// one of the stepping schedules has not yet been run.
+fn build_ui(
+    mut commands: Commands,
+    asset_server: Res<AssetServer>,
+    schedules: Res<Schedules>,
+    mut stepping: ResMut<Stepping>,
+    mut state: ResMut<State>,
+) {
+    let mut text_sections = Vec::new();
+    let mut always_run = Vec::new();
+
+    let Ok(schedule_order) = stepping.schedules() else {
+        return;
+    };
+
+    // go through the stepping schedules and construct a list of systems for
+    // each label
+    for label in schedule_order {
+        let schedule = schedules.get(*label).unwrap();
+        text_sections.push(TextSection::new(
+            format!("{:?}\n", label),
+            TextStyle {
+                font: asset_server.load(FONT_BOLD),
+                font_size: FONT_SIZE,
+                color: FONT_COLOR,
+            },
+        ));
+
+        // grab the list of systems in the schedule, in the order the
+        // single-threaded executor would run them.
+        let Ok(systems) = schedule.systems() else {
+            return;
+        };
+
+        for (node_id, system) in systems {
+            // skip bevy default systems; we don't want to step those
+            if system.name().starts_with("bevy") {
+                always_run.push((*label, node_id));
+                continue;
+            }
+
+            // Add an entry to our systems list so we can find where to draw
+            // the cursor when the stepping cursor is at this system
+            state.systems.push((*label, node_id, text_sections.len()));
+
+            // Add a text section for displaying the cursor for this system
+            text_sections.push(TextSection::new(
+                "   ",
+                TextStyle {
+                    font: asset_server.load(FONT_MEDIUM),
+                    font_size: FONT_SIZE,
+                    color: FONT_COLOR,
+                },
+            ));
+
+            // add the name of the system to the ui
+            text_sections.push(TextSection::new(
+                format!("{}\n", system.name()),
+                TextStyle {
+                    font: asset_server.load(FONT_MEDIUM),
+                    font_size: FONT_SIZE,
+                    color: FONT_COLOR,
+                },
+            ));
+        }
+    }
+
+    for (label, node) in always_run.drain(..) {
+        stepping.always_run_node(label, node);
+    }
+
+    commands.spawn((
+        SteppingUi,
+        TextBundle {
+            text: Text::from_sections(text_sections),
+            style: Style {
+                position_type: PositionType::Absolute,
+                top: state.ui_top,
+                left: state.ui_left,
+                padding: UiRect::all(Val::Px(10.0)),
+                ..default()
+            },
+            background_color: BackgroundColor(Color::rgba(1.0, 1.0, 1.0, 0.33)),
+            visibility: Visibility::Hidden,
+            ..default()
+        },
+    ));
+}
+
+fn build_help(mut commands: Commands, asset_server: Res<AssetServer>) {
+    // stepping description box
+    commands.spawn((TextBundle::from_sections([TextSection::new(
+        "Press ` to toggle stepping mode (S: step system, Space: step frame)",
+        TextStyle {
+            font: asset_server.load(FONT_MEDIUM),
+            font_size: 18.0,
+            color: FONT_COLOR,
+        },
+    )])
+    .with_style(Style {
+        position_type: PositionType::Absolute,
+        bottom: Val::Px(5.0),
+        left: Val::Px(5.0),
+        ..default()
+    }),));
+}
+
+fn handle_input(keyboard_input: Res<ButtonInput<KeyCode>>, mut stepping: ResMut<Stepping>) {
+    if keyboard_input.just_pressed(KeyCode::Slash) {
+        info!("{:#?}", stepping);
+    }
+    // grave key to toggle stepping mode for the FixedUpdate schedule
+    if keyboard_input.just_pressed(KeyCode::Backquote) {
+        if stepping.is_enabled() {
+            stepping.disable();
+            debug!("disabled stepping");
+        } else {
+            stepping.enable();
+            debug!("enabled stepping");
+        }
+    }
+
+    if !stepping.is_enabled() {
+        return;
+    }
+
+    // space key will step the remainder of this frame
+    if keyboard_input.just_pressed(KeyCode::Space) {
+        debug!("continue");
+        stepping.continue_frame();
+    } else if keyboard_input.just_pressed(KeyCode::KeyS) {
+        debug!("stepping frame");
+        stepping.step_frame();
+    }
+}
+
+fn update_ui(
+    mut commands: Commands,
+    state: Res<State>,
+    stepping: Res<Stepping>,
+    mut ui: Query<(Entity, &mut Text, &Visibility), With<SteppingUi>>,
+) {
+    if ui.is_empty() {
+        return;
+    }
+
+    // ensure the UI is only visible when stepping is enabled
+    let (ui, mut text, vis) = ui.single_mut();
+    match (vis, stepping.is_enabled()) {
+        (Visibility::Hidden, true) => {
+            commands.entity(ui).insert(Visibility::Inherited);
+        }
+        (Visibility::Hidden, false) | (_, true) => (),
+        (_, false) => {
+            commands.entity(ui).insert(Visibility::Hidden);
+        }
+    }
+
+    // if we're not stepping, there's nothing more to be done here.
+    if !stepping.is_enabled() {
+        return;
+    }
+
+    let (cursor_schedule, cursor_system) = match stepping.cursor() {
+        // no cursor means stepping isn't enabled, so we're done here
+        None => return,
+        Some(c) => c,
+    };
+
+    for (schedule, system, text_index) in &state.systems {
+        let mark = if &cursor_schedule == schedule && *system == cursor_system {
+            "-> "
+        } else {
+            "   "
+        };
+        text.sections[*text_index].value = mark.to_string();
+    }
+}