update bevy_app, bevy_core and a whole lotta docs

Author: maniwani

crates/bevy_app/src/app.rs

@@ -12,6 +12,7 @@ mod ci_testing;
 
 pub use app::*;
 pub use bevy_derive::DynamicPlugin;
+pub use bevy_ecs::event::*;
 pub use plugin::*;
 pub use plugin_group::*;
 pub use schedule_runner::*;
@@ -20,45 +21,7 @@ pub use schedule_runner::*;
 pub mod prelude {
     #[doc(hidden)]
     pub use crate::{
-        app::App, CoreStage, DynamicPlugin, Plugin, PluginGroup, StartupSchedule, StartupStage,
+        app::{App, AppSet},
+        DynamicPlugin, Plugin, PluginGroup,
     };
 }
-
-use bevy_ecs::schedule::StageLabel;
-
-/// The names of the default App stages
-///
-/// The relative stages are added by [`App::add_default_stages`].
-#[derive(Debug, Hash, PartialEq, Eq, Clone, StageLabel)]
-pub enum CoreStage {
-    /// Name of app stage that runs before all other app stages
-    First,
-    /// Name of app stage responsible for performing setup before an update. Runs before UPDATE.
-    PreUpdate,
-    /// Name of app stage responsible for doing most app logic. Systems should be registered here
-    /// by default.
-    Update,
-    /// Name of app stage responsible for processing the results of UPDATE. Runs after UPDATE.
-    PostUpdate,
-    /// Name of app stage that runs after all other app stages
-    Last,
-}
-
-/// The label for the Startup [`Schedule`](bevy_ecs::schedule::Schedule),
-/// which runs once at the beginning of the app.
-///
-/// When targeting a [`Stage`](bevy_ecs::schedule::Stage) inside this Schedule,
-/// you need to use [`StartupStage`] instead.
-#[derive(Debug, Hash, PartialEq, Eq, Clone, StageLabel)]
-pub struct StartupSchedule;
-
-/// The names of the default App startup stages
-#[derive(Debug, Hash, PartialEq, Eq, Clone, StageLabel)]
-pub enum StartupStage {
-    /// Name of app stage that runs once before the startup stage
-    PreStartup,
-    /// Name of app stage that runs once when an app starts up
-    Startup,
-    /// Name of app stage that runs once after the startup stage
-    PostStartup,
-}

crates/bevy_app/src/lib.rs

@@ -1,20 +1,21 @@
 use crate::App;
 use std::any::Any;
 
-/// A collection of Bevy App logic and configuration
+/// Portable [`App`] configuration.
 ///
-/// Plugins configure an [`App`](crate::App). When an [`App`](crate::App) registers
-/// a plugin, the plugin's [`Plugin::build`] function is run.
+/// Plugins make it easy to export (and re-import) systems, systems sets, and resources.
+///
+/// After you import a plugin to an [`App`](crate::App) using [`add_plugin`](App::add_plugin), the app will run its [`build`](Plugin::build) function.
 pub trait Plugin: Any + Send + Sync {
-    /// Configures the [`App`] to which this plugin is added.
+    /// Applies the stored configuration to the given [`App`].
     fn build(&self, app: &mut App);
-    /// Configures a name for the [`Plugin`]. Primarily for debugging.
+    /// Returns the name of this plugin.
     fn name(&self) -> &str {
         std::any::type_name::<Self>()
     }
 }
 
-/// Type representing an unsafe function that returns a mutable pointer to a [`Plugin`].
-/// Used for dynamically loading plugins. See
-/// `bevy_dynamic_plugin/src/loader.rs#dynamically_load_plugin`
+/// An alias for an unsafe function that returns a pointer to a [`Plugin`].
+/// Used for dynamically loading plugins,
+/// as shown in [this example][`bevy_dynamic_plugin/src/loader.rs#dynamically_load_plugin`].
 pub type CreatePlugin = unsafe fn() -> *mut dyn Plugin;

crates/bevy_app/src/plugin.rs

@@ -2,28 +2,28 @@ use crate::{App, Plugin};
 use bevy_utils::{tracing::debug, HashMap};
 use std::any::TypeId;
 
-/// Combines multiple [`Plugin`]s into a single unit.
+/// Combines multiple [`Plugin`] instances into one.
 pub trait PluginGroup {
-    /// Configures the [`Plugin`]s that are to be added.
+    /// Builds all the plugins in the group.
     fn build(&mut self, group: &mut PluginGroupBuilder);
 }
 
+/// A [`Plugin`] that is part of a [`PluginGroup`].
 struct PluginEntry {
     plugin: Box<dyn Plugin>,
     enabled: bool,
 }
 
 /// Facilitates the creation and configuration of a [`PluginGroup`].
-/// Provides a build ordering to ensure that [`Plugin`]s which produce/require a resource
-/// are built before/after dependent/depending [`Plugin`]s.
+/// Defines a [`Plugin`] build order to enable plugins being dependent on other plugins.
 #[derive(Default)]
 pub struct PluginGroupBuilder {
     plugins: HashMap<TypeId, PluginEntry>,
     order: Vec<TypeId>,
 }
 
 impl PluginGroupBuilder {
-    /// Appends a [`Plugin`] to the [`PluginGroupBuilder`].
+    /// Appends the [`Plugin`] to the end of the current set.
     pub fn add<T: Plugin>(&mut self, plugin: T) -> &mut Self {
         self.order.push(TypeId::of::<T>());
         self.plugins.insert(
@@ -36,7 +36,7 @@ impl PluginGroupBuilder {
         self
     }
 
-    /// Configures a [`Plugin`] to be built before another plugin.
+    /// Configures the [`Plugin`] to be built before the `Target` plugin.
     pub fn add_before<Target: Plugin, T: Plugin>(&mut self, plugin: T) -> &mut Self {
         let target_index = self
             .order
@@ -61,7 +61,7 @@ impl PluginGroupBuilder {
         self
     }
 
-    /// Configures a [`Plugin`] to be built after another plugin.
+    /// Configures the [`Plugin`] to be built after the `Target` plugin.
     pub fn add_after<Target: Plugin, T: Plugin>(&mut self, plugin: T) -> &mut Self {
         let target_index = self
             .order
@@ -86,10 +86,10 @@ impl PluginGroupBuilder {
         self
     }
 
-    /// Enables a [`Plugin`]
+    /// Enables the [`Plugin`].
     ///
-    /// [`Plugin`]s within a [`PluginGroup`] are enabled by default. This function is used to
-    /// opt back in to a [`Plugin`] after [disabling](Self::disable) it.
+    /// Plugins within a [`PluginGroup`] are enabled by default. This function will
+    /// re-activate a plugin if [`disable`](Self::disable) was called earlier.
     pub fn enable<T: Plugin>(&mut self) -> &mut Self {
         let mut plugin_entry = self
             .plugins
@@ -99,7 +99,7 @@ impl PluginGroupBuilder {
         self
     }
 
-    /// Disables a [`Plugin`], preventing it from being added to the `App` with the rest of the [`PluginGroup`].
+    /// Disables the [`Plugin`], stopping it from being built by an [`App`] with the rest of the [`PluginGroup`].
     pub fn disable<T: Plugin>(&mut self) -> &mut Self {
         let mut plugin_entry = self
             .plugins
@@ -109,7 +109,8 @@ impl PluginGroupBuilder {
         self
     }
 
-    /// Consumes the [`PluginGroupBuilder`] and [builds](Plugin::build) the contained [`Plugin`]s.
+    /// Consumes the [`PluginGroupBuilder`] and runs the [`build`](Plugin::build) function of each
+    /// contained [`Plugin`] in the specified order.
     pub fn finish(self, app: &mut App) {
         for ty in self.order.iter() {
             if let Some(entry) = self.plugins.get(ty) {

crates/bevy_app/src/plugin_group.rs

@@ -10,16 +10,16 @@ use std::{cell::RefCell, rc::Rc};
 #[cfg(target_arch = "wasm32")]
 use wasm_bindgen::{prelude::*, JsCast};
 
-/// Determines the method used to run an [App]'s  [`Schedule`](bevy_ecs::schedule::Schedule).
+/// Determines the method used to run an [`App`] schedule.
 #[derive(Copy, Clone, Debug)]
 pub enum RunMode {
-    /// Indicates that the [`App`]'s schedule should run repeatedly.
+    /// The schedule should be run repeatedly.
     Loop {
-        /// Minimum duration to wait after a schedule has completed before repeating.
+        /// Minimum duration to wait after an update has completed before running another.
         /// A value of [`None`] will not wait.
         wait: Option<Duration>,
     },
-    /// Indicates that the [`App`]'s schedule should run only once.
+    /// The schedule should be run a single time.
     Once,
 }
 
@@ -54,8 +54,7 @@ impl ScheduleRunnerSettings {
     }
 }
 
-/// Configures an `App` to run its [`Schedule`](bevy_ecs::schedule::Schedule) according to a given
-/// [`RunMode`]
+/// Configures an [`App`] to run its schedule according to a given [`RunMode`].
 #[derive(Default)]
 pub struct ScheduleRunnerPlugin;
 

crates/bevy_app/src/schedule_runner.rs

@@ -16,32 +16,78 @@ pub mod prelude {
     //! The Bevy Core Prelude.
     #[doc(hidden)]
     pub use crate::{
-        DefaultTaskPoolOptions, FixedTime, FixedTimestep, FixedTimestepState, Name, Time, Timer,
+        CoreSet, DefaultTaskPoolOptions, FixedTime, FixedTimestepState, Name, Time, Timer,
     };
 }
 
-use bevy_app::prelude::*;
+use bevy_app::{prelude::*, AppSystem};
 use bevy_ecs::{
     entity::Entity,
-    schedule::{IntoSystemDescriptor, SystemLabel},
+    schedule::{apply_buffers, chain, IntoScheduledSet, IntoScheduledSystem, SystemLabel},
 };
 use bevy_utils::HashSet;
+
 use std::ops::Range;
 
-/// Adds core functionality to Apps.
+/// [`Plugin`] that adds a standard system execution sequence.
 #[derive(Default)]
 pub struct CorePlugin;
 
-/// A `SystemLabel` enum for ordering systems relative to core Bevy systems.
+/// Systems sets comprising the standard execution sequence.
+#[derive(Debug, Hash, PartialEq, Eq, Clone, SystemLabel)]
+pub enum CoreSet {
+    /// Systems that run before the systems in the other core sets (but after [`Time`] is updated).
+    First,
+    /// Systems that run with the fixed timestep. Intended for most gameplay systems (e.g. physics).
+    ///
+    /// **Note:** Fixed timestep does not mean fixed *interval*. This set can repeat several times in a single frame. Use [`FixedTime`] instead of [`Time`] to ensure correct behavior.
+    FixedUpdate,
+    /// Systems that run before systems in [`Update`](CoreSet::Update).
+    /// Intended for systems that need to perform setup for systems in [`Update`](CoreSet::Update).
+    PreUpdate,
+    /// Systems that run each frame.
+    ///
+    /// **Note:** By default, systems and sets with no parent set specified are added here.
+    Update,
+    /// Systems that run after systems in [`Update`](CoreSet::Update).
+    /// Intended for systems that need to process the results of systems in [`Update`](CoreSet::Update).
+    PostUpdate,
+    /// Systems that run after the systems in the other core sets.
+    Last,
+}
+
+/// Systems comprising the standard execution sequence.
+#[doc(hidden)]
 #[derive(Debug, PartialEq, Eq, Clone, Hash, SystemLabel)]
 pub enum CoreSystem {
-    /// Advances time. Any system that interacts with the [`Time`] resource should run after this.
+    /// Advances [`Time`]. First thing that runs in a frame.
     Time,
+    /// Advances [`FixedTime`] and runs the systems under [`FixedUpdate`](CoreSet::FixedUpdate).
+    FixedUpdate,
+    /// Calls [`apply_buffers`] after the systems under [`First`](CoreSet::First).
+    ApplyFirst,
+    /// Calls [`apply_buffers`] after the systems under [`FixedUpdate`](CoreSet::FixedUpdate).
+    ApplyFixedUpdate,
+    /// Calls [`apply_buffers`] after the systems under [`PreUpdate`](CoreSet::PreUpdate).
+    ApplyPreUpdate,
+    /// Calls [`apply_buffers`] after the systems under [`Update`](CoreSet::Update).
+    ApplyUpdate,
+    /// Calls [`apply_buffers`] after the systems under [`PostUpdate`](CoreSet::PostUpdate).
+    ApplyPostUpdate,
+    /// Calls [`apply_buffers`] after the systems under [`Last`](CoreSet::Last).
+    ApplyLast,
+}
+
+/// Internal system sets needed to bypass limitations with [`apply_buffers`].
+#[doc(hidden)]
+#[derive(Debug, Hash, PartialEq, Eq, Clone, SystemLabel)]
+pub(crate) enum CoreInternalSet {
+    /// Encompasses [`CoreSet::FixedUpdate`] and [`CoreSystem::ApplyFixedUpdate`].
+    FixedUpdate,
 }
 
 impl Plugin for CorePlugin {
     fn build(&self, app: &mut App) {
-        // Setup the default bevy task pools
         app.world
             .get_resource::<DefaultTaskPoolOptions>()
             .cloned()
@@ -57,11 +103,31 @@ impl Plugin for CorePlugin {
             .register_type::<Name>()
             .register_type::<Range<f32>>()
             .register_type::<Timer>()
-            // time system is added to the "AtStart" set to ensure it runs before other systems
-            // in CoreStage::First
-            .add_system_to_stage(
-                CoreStage::First,
-                time_system.at_start().label(CoreSystem::Time),
+            .add_many(
+                chain![
+                    update_time.named(CoreSystem::Time),
+                    CoreSet::First,
+                    apply_buffers.named(CoreSystem::ApplyFirst),
+                    fixed_update.named(CoreSystem::FixedUpdate),
+                    CoreSet::PreUpdate,
+                    apply_buffers.named(CoreSystem::ApplyPreUpdate),
+                    CoreSet::Update,
+                    apply_buffers.named(CoreSystem::ApplyUpdate),
+                    CoreSet::PostUpdate,
+                    apply_buffers.named(CoreSystem::ApplyPostUpdate),
+                    CoreSet::Last,
+                    apply_buffers.named(CoreSystem::ApplyLast),
+                ]
+                .to(AppSet::Update)
+                .after(AppSet::UpdateEvents)
+                .before(AppSystem::ClearTrackers),
+            )
+            .add_many(
+                chain![
+                    CoreSet::FixedUpdate,
+                    apply_buffers.named(CoreSystem::ApplyFixedUpdate),
+                ]
+                .to(CoreInternalSet::FixedUpdate),
             );
 
         register_rust_types(app);