Add top-level schedules

crates/bevy_app/src/lib.rs

@@ -25,8 +25,8 @@ pub mod prelude {
  pub use crate::{
  app::App,
  main_schedule::{
- First, FixedUpdate, Last, UpdateFlow, PostStartup, PostUpdate, PreStartup, PreUpdate, RenderFlow,
- Startup, StateTransition, Update,
+ Control, First, FixedUpdate, FrameReady, Last, PostStartup, PostUpdate, PreStartup,
+ PreUpdate, RenderFlow, Startup, StartupFlow, StateTransition, Update, UpdateFlow,
  },
  DynamicPlugin, Plugin, PluginGroup,
  };

crates/bevy_app/src/main_schedule.rs

@@ -1,48 +1,48 @@
 use crate::{App, Plugin};
 use bevy_ecs::{
  schedule::{ExecutorKind, Schedule, ScheduleLabel},
- system::{Local, Resource},
+ system::Resource,
  world::{Mut, World},
 };
 
-/// The schedule that contains the app logic that is evaluated each tick of event loop.
-///
-/// By default, it will run the following schedules in the given order:
-///
 /// On the first run of the schedule (and only on the first run), it will run:
 /// * [`PreStartup`]
 /// * [`Startup`]
 /// * [`PostStartup`]
-///
-/// Then it will run:
-/// * [`First`]
-/// * [`PreUpdate`]
-/// * [`StateTransition`]
-/// * [`RunFixedUpdateLoop`]
-/// * This will run [`FixedUpdate`] zero to many times, based on how much time has elapsed.
-/// * [`Update`]
-/// * [`PostUpdate`]
-/// * [`Last`]
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
-pub struct UpdateFlow;
+pub struct StartupFlow;
 
 /// The schedule that runs before [`Startup`].
-/// This is run by the [`Main`] schedule.
+/// This is run by the [`StartupFlow`] schedule.
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct PreStartup;
 
 /// The schedule that runs once when the app starts.
-/// This is run by the [`Main`] schedule.
+/// This is run by the [`StartupFlow`] schedule.
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct Startup;
 
 /// The schedule that runs once after [`Startup`].
-/// This is run by the [`Main`] schedule.
+/// This is run by the [`StartupFlow`] schedule.
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct PostStartup;
 
+/// The schedule that contains the app logic that is evaluated each tick of event loop.
+///
+/// By default, it will run the following schedules in the given order:
+/// * [`First`]
+/// * [`PreUpdate`]
+/// * [`StateTransition`]
+/// * [`RunFixedUpdateLoop`]
+/// * This will run [`FixedUpdate`] zero to many times, based on how much time has elapsed.
+/// * [`Update`]
+/// * [`PostUpdate`]
+/// * [`Last`]
+#[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
+pub struct UpdateFlow;
+
 /// Runs first in the schedule.
-/// This is run by the [`Main`] schedule.
+/// This is run by the [`UpdateFlow`] schedule.
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct First;
 
@@ -53,17 +53,17 @@ pub struct First;
 /// [`PreUpdate`] exists to do "engine/plugin preparation work" that ensures the APIs consumed in [`Update`] are "ready".
 /// [`PreUpdate`] abstracts out "pre work implementation details".
 ///
-/// This is run by the [`Main`] schedule.
+/// This is run by the [`UpdateFlow`] schedule.
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct PreUpdate;
 
 /// Runs [state transitions](bevy_ecs::schedule::States).
-/// This is run by the [`Main`] schedule.
+/// This is run by the [`UpdateFlow`] schedule.
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct StateTransition;
 
 /// Runs the [`FixedUpdate`] schedule in a loop according until all relevant elapsed time has been "consumed".
-/// This is run by the [`Main`] schedule.
+/// This is run by the [`UpdateFlow`] schedule.
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct RunFixedUpdateLoop;
 
@@ -75,7 +75,7 @@ pub struct RunFixedUpdateLoop;
 pub struct FixedUpdate;
 
 /// The schedule that contains app logic.
-/// This is run by the [`Main`] schedule.
+/// This is run by the [`UpdateFlow`] schedule.
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct Update;
 
@@ -86,16 +86,26 @@ pub struct Update;
 /// [`PostUpdate`] exists to do "engine/plugin response work" to things that happened in [`Update`].
 /// [`PostUpdate`] abstracts out "implementation details" from users defining systems in [`Update`].
 ///
-/// This is run by the [`Main`] schedule.
+/// This is run by the [`UpdateFlow`] schedule.
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct PostUpdate;
 
 /// Runs last in the schedule.
-/// This is run by the [`Main`] schedule.
+/// This is run by the [`UpdateFlow`] schedule.
 #[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
 pub struct Last;
 
-/// The main render schedule.
+/// Each time an event is received from windows and devices, this schedule is run.
+/// This is useful for responding to events regardless of whether tick updates take place.
+#[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
+pub struct Control;
+
+/// Each time a frame is ready to be updated, this schedule is run.
+/// This is the best place to decide whether to redraw.
+#[derive(ScheduleLabel, Clone, Debug, PartialEq, Eq, Hash)]
+pub struct FrameReady;
+
+/// The schedule that builds and sends drawing queries to the GPU.
 #[derive(ScheduleLabel, Debug, Hash, PartialEq, Eq, Clone)]
 pub struct RenderFlow;
 
@@ -135,16 +145,19 @@ impl UpdateFlowOrder {
  }
 }
 
-impl UpdateFlow {
- /// A system that runs the "main schedule"
- pub fn run_main(world: &mut World, mut run_at_least_once: Local<bool>) {
- if !*run_at_least_once {
- let _ = world.try_run_schedule(PreStartup);
- let _ = world.try_run_schedule(Startup);
- let _ = world.try_run_schedule(PostStartup);
- *run_at_least_once = true;
- }
+/// Initializes the [`StartupFlow`] schedule, [`UpdateFlow`] schedule, sub schedules, and resources for a given [`App`].
+pub struct MainSchedulePlugin;
 
+impl MainSchedulePlugin {
+ /// A system that runs the `StartupFlow` sub schedules
+ pub fn run_startup(world: &mut World) {
+ let _ = world.try_run_schedule(PreStartup);
+ let _ = world.try_run_schedule(Startup);
+ let _ = world.try_run_schedule(PostStartup);
+ }
+
+ /// A system that runs the `UpdateFlow` sub schedules
+ pub fn run_update(world: &mut World) {
  world.resource_scope(|world, order: Mut<UpdateFlowOrder>| {
  for label in &order.labels {
  let _ = world.try_run_schedule(&**label);
@@ -153,20 +166,21 @@ impl UpdateFlow {
  }
 }
 
-/// Initializes the [`Main`] schedule, sub schedules, and resources for a given [`App`].
-pub struct MainSchedulePlugin;
-
 impl Plugin for MainSchedulePlugin {
  fn build(&self, app: &mut App) {
  // simple "facilitator" schedules benefit from simpler single threaded scheduling
- let mut main_schedule = Schedule::new();
- main_schedule.set_executor_kind(ExecutorKind::SingleThreaded);
+ let mut startup_schedule = Schedule::new();
+ startup_schedule.set_executor_kind(ExecutorKind::SingleThreaded);
+ let mut update_schedule = Schedule::new();
+ update_schedule.set_executor_kind(ExecutorKind::SingleThreaded);
  let mut fixed_update_loop_schedule = Schedule::new();
  fixed_update_loop_schedule.set_executor_kind(ExecutorKind::SingleThreaded);
 
- app.add_schedule(UpdateFlow, main_schedule)
+ app.add_schedule(StartupFlow, startup_schedule)
+ .add_schedule(UpdateFlow, update_schedule)
  .add_schedule(RunFixedUpdateLoop, fixed_update_loop_schedule)
  .init_resource::<UpdateFlowOrder>()
- .add_systems(UpdateFlow, UpdateFlow::run_main);
+ .add_systems(StartupFlow, Self::run_startup)
+ .add_systems(UpdateFlow, Self::run_update);
  }
 }

crates/bevy_app/src/schedule_runner.rs

@@ -1,7 +1,7 @@
 use crate::{
  app::{App, AppExit},
  plugin::Plugin,
- UpdateFlow,
+ StartupFlow, UpdateFlow,
 };
 use bevy_ecs::{
  event::{Events, ManualEventReader},
@@ -53,18 +53,22 @@ impl Default for RunMode {
 pub struct ScheduleRunnerPlugin {
  /// Determines whether the [`Schedule`](bevy_ecs::schedule::Schedule) is run once or repeatedly.
  pub run_mode: RunMode,
- /// The schedule to run by default.
+ /// This schedule is run only once at startup.
  ///
- /// This is initially set to [`Main`].
- pub main_schedule_label: BoxedScheduleLabel,
+ /// The default is [`StartupFlow`].
+ pub startup_schedule_label: BoxedScheduleLabel,
+ /// This schedule is run for each tick.
+ ///
+ /// The default is [`UpdateFlow`].
+ pub update_schedule_label: BoxedScheduleLabel,
 }
 
 impl ScheduleRunnerPlugin {
  /// See [`RunMode::Once`].
  pub fn run_once() -> Self {
  ScheduleRunnerPlugin {
  run_mode: RunMode::Once,
- main_schedule_label: Box::new(UpdateFlow),
+ ..Default::default()
  }
  }
 
@@ -74,7 +78,7 @@ impl ScheduleRunnerPlugin {
  run_mode: RunMode::Loop {
  wait: Some(wait_duration),
  },
- main_schedule_label: Box::new(UpdateFlow),
+ ..Default::default()
  }
  }
 }
@@ -83,27 +87,36 @@ impl Default for ScheduleRunnerPlugin {
  fn default() -> Self {
  ScheduleRunnerPlugin {
  run_mode: RunMode::Loop { wait: None },
- main_schedule_label: Box::new(UpdateFlow),
+ startup_schedule_label: Box::new(StartupFlow),
+ update_schedule_label: Box::new(UpdateFlow),
  }
  }
 }
 
 impl Plugin for ScheduleRunnerPlugin {
  fn build(&self, app: &mut App) {
  let run_mode = self.run_mode;
- let main_schedule_label = self.main_schedule_label.clone();
+ let startup_schedule_label = self.startup_schedule_label.clone();
+ let update_schedule_label = self.update_schedule_label.clone();
  app.set_runner(move |mut app: App| {
  // Prevent panic when schedules do not exist
- app.init_schedule(main_schedule_label.clone());
+ app.init_schedule(startup_schedule_label.clone());
+ app.init_schedule(update_schedule_label.clone());
+
+ {
+ #[cfg(feature = "trace")]
+ let _ = info_span!("run top schedule", name = ?startup_schedule_label).entered();
+ app.world.run_schedule(startup_schedule_label);
+ }
 
  let mut app_exit_event_reader = ManualEventReader::<AppExit>::default();
  match run_mode {
  RunMode::Once => {
  {
  #[cfg(feature = "trace")]
- let _main_schedule_span =
- info_span!("main schedule", name = ?main_schedule_label).entered();
- app.world.run_schedule(main_schedule_label);
+ let _ =
+ info_span!("run top schedule", name = ?update_schedule_label).entered();
+ app.world.run_schedule(update_schedule_label);
  }
  app.update_sub_apps();
  }
@@ -124,9 +137,9 @@ impl Plugin for ScheduleRunnerPlugin {
 
  {
  #[cfg(feature = "trace")]
- let _main_schedule_span =
- info_span!("main schedule", name = ?main_schedule_label).entered();
- app.world.run_schedule(&main_schedule_label);
+ let _ = info_span!("run top schedule", name = ?update_schedule_label)
+ .entered();
+ app.world.run_schedule(&update_schedule_label);
  }
  app.update_sub_apps();
  app.world.clear_trackers();

crates/bevy_window/src/lib.rs

@@ -95,17 +95,17 @@ impl Plugin for WindowPlugin {
 
  match self.exit_condition {
  ExitCondition::OnPrimaryClosed => {
- app.add_systems(PostUpdate, exit_on_primary_closed);
+ app.add_systems(Control, exit_on_primary_closed);
  }
  ExitCondition::OnAllClosed => {
- app.add_systems(PostUpdate, exit_on_all_closed);
+ app.add_systems(Control, exit_on_all_closed);
  }
  ExitCondition::DontExit => {}
  }
 
  if self.close_when_requested {
  // Need to run before `exit_on_*` systems
- app.add_systems(Update, close_when_requested);
+ app.add_systems(Control, close_when_requested);
  }
 
  // Register event types