System Stepping implemented as Resource

crates/bevy_app/src/app.rs

@@ -388,6 +388,7 @@ impl App {
             schedule.add_systems(systems);
         } else {
             let mut new_schedule = Schedule::new();
+            new_schedule.set_label(schedule.dyn_clone());
             new_schedule.add_systems(systems);
             schedules.insert(schedule, new_schedule);
         }
@@ -459,6 +460,7 @@ impl App {
             schedule.configure_set(set);
         } else {
             let mut new_schedule = Schedule::new();
+            new_schedule.set_label(schedule.dyn_clone());
             new_schedule.configure_set(set);
             schedules.insert(schedule, new_schedule);
         }
@@ -476,6 +478,7 @@ impl App {
             schedule.configure_sets(sets);
         } else {
             let mut new_schedule = Schedule::new();
+            new_schedule.set_label(schedule.dyn_clone());
             new_schedule.configure_sets(sets);
             schedules.insert(schedule, new_schedule);
         }
@@ -869,8 +872,11 @@ impl App {
     /// # Warning
     /// This method will overwrite any existing schedule at that label.
     /// To avoid this behavior, use the `init_schedule` method instead.
-    pub fn add_schedule(&mut self, label: impl ScheduleLabel, schedule: Schedule) -> &mut Self {
+    pub fn add_schedule(&mut self, label: impl ScheduleLabel, mut schedule: Schedule) -> &mut Self {
         let mut schedules = self.world.resource_mut::<Schedules>();
+        if schedule.label().is_none() {
+            schedule.set_label(label.dyn_clone());
+        }
         schedules.insert(label, schedule);
 
         self
@@ -882,7 +888,9 @@ impl App {
     pub fn init_schedule(&mut self, label: impl ScheduleLabel) -> &mut Self {
         let mut schedules = self.world.resource_mut::<Schedules>();
         if !schedules.contains(&label) {
-            schedules.insert(label, Schedule::new());
+            let mut schedule = Schedule::new();
+            schedule.set_label(label.dyn_clone());
+            schedules.insert(label, schedule);
         }
         self
     }
@@ -912,7 +920,9 @@ impl App {
         let mut schedules = self.world.resource_mut::<Schedules>();
 
         if schedules.get(&label).is_none() {
-            schedules.insert(label.dyn_clone(), Schedule::new());
+            let mut schedule = Schedule::new();
+            schedule.set_label(label.dyn_clone());
+            schedules.insert(label.dyn_clone(), schedule);
         }
 
         let schedule = schedules.get_mut(&label).unwrap();

crates/bevy_app/src/main_schedule.rs

@@ -154,6 +154,8 @@ pub struct MainSchedulePlugin;
 
 impl Plugin for MainSchedulePlugin {
     fn build(&self, app: &mut App) {
+        use bevy_ecs::schedule::{IntoSystemConfigs, Stepping};
+
         // simple "facilitator" schedules benefit from simpler single threaded scheduling
         let mut main_schedule = Schedule::new();
         main_schedule.set_executor_kind(ExecutorKind::SingleThreaded);
@@ -163,6 +165,6 @@ impl Plugin for MainSchedulePlugin {
         app.add_schedule(Main, main_schedule)
             .add_schedule(RunFixedUpdateLoop, fixed_update_loop_schedule)
             .init_resource::<MainScheduleOrder>()
-            .add_systems(Main, Main::run_main);
+            .add_systems(Main, (Stepping::begin_frame, Main::run_main).chain());
     }
 }

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_buffers(&mut self, value: bool);
 }
 

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

@@ -161,7 +161,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 {
@@ -179,6 +184,30 @@ impl SystemExecutor for MultiThreadedExecutor {
             }
         }
 
+        // If stepping is enabled, make sure we skip those systems that should
+        // not be run.
+        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

@@ -34,7 +34,19 @@ 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.
+        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

@@ -44,7 +44,19 @@ 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.
+        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

@@ -6,6 +6,7 @@ mod graph_utils;
 mod schedule;
 mod set;
 mod state;
+mod stepping;
 
 pub use self::condition::*;
 pub use self::config::*;
@@ -708,4 +709,102 @@ mod tests {
             assert!(matches!(result, Err(ScheduleBuildError::Ambiguity)));
         }
     }
+
+    mod stepping {
+        use super::*;
+        use bevy_ecs::system::SystemState;
+
+        #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
+        pub struct TestSchedule;
+
+        /// verify the [`SimpleExecutor`] supports stepping
+        #[test]
+        fn simple_executor() {
+            // create a test schedule
+            let mut schedule = Schedule::default();
+            schedule
+                .set_label(TestSchedule)
+                .set_executor_kind(ExecutorKind::Simple)
+                .add_systems(|| panic!("test failed; system should not run"));
+
+            // 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 [`SingleThreadedExecutor`] supports stepping
+        #[test]
+        fn single_threaded_executor() {
+            // create a test schedule
+            let mut schedule = Schedule::default();
+            schedule
+                .set_label(TestSchedule)
+                .set_executor_kind(ExecutorKind::SingleThreaded)
+                .add_systems(|| panic!("test failed; system should not run"));
+
+            // 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 [`MultiThreadedExecutor`] supports stepping
+        #[test]
+        fn multi_threaded_executor() {
+            // create a test schedule
+            let mut schedule = Schedule::default();
+            schedule
+                .set_label(TestSchedule)
+                .set_executor_kind(ExecutorKind::MultiThreaded)
+                .add_systems(|| panic!("test failed; system should not run"));
+
+            // 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);
+        }
+    }
 }