Base Sets (#7466)

# Objective

NOTE: This depends on #7267 and should not be merged until #7267 is merged. If you are reviewing this before that is merged, I highly recommend viewing the Base Sets commit instead of trying to find my changes amongst those from #7267.

"Default sets" as described by the [Stageless RFC](bevyengine/rfcs#45) have some [unfortunate consequences](#7365).

## Solution

This adds "base sets" as a variant of `SystemSet`:

A set is a "base set" if `SystemSet::is_base` returns `true`. Typically this will be opted-in to using the `SystemSet` derive:

```rust
#[derive(SystemSet, Clone, Hash, Debug, PartialEq, Eq)]
#[system_set(base)]
enum MyBaseSet {
  A,
  B,
}
``` 

**Base sets are exclusive**: a system can belong to at most one "base set". Adding a system to more than one will result in an error. When possible we fail immediately during system-config-time with a nice file + line number. For the more nested graph-ey cases, this will fail at the final schedule build. 

**Base sets cannot belong to other sets**: this is where the word "base" comes from

Systems and Sets can only be added to base sets using `in_base_set`. Calling `in_set` with a base set will fail. As will calling `in_base_set` with a normal set.

```rust
app.add_system(foo.in_base_set(MyBaseSet::A))
       // X must be a normal set ... base sets cannot be added to base sets
       .configure_set(X.in_base_set(MyBaseSet::A))
```

Base sets can still be configured like normal sets:

```rust
app.add_system(MyBaseSet::B.after(MyBaseSet::Ap))
``` 

The primary use case for base sets is enabling a "default base set":

```rust
schedule.set_default_base_set(CoreSet::Update)
  // this will belong to CoreSet::Update by default
  .add_system(foo)
  // this will override the default base set with PostUpdate
  .add_system(bar.in_base_set(CoreSet::PostUpdate))
```

This allows us to build apis that work by default in the standard Bevy style. This is a rough analog to the "default stage" model, but it use the new "stageless sets" model instead, with all of the ordering flexibility (including exclusive systems) that it provides.

---

## Changelog

- Added "base sets" and ported CoreSet to use them.

## Migration Guide

TODO

Author: cart

crates/bevy_animation/src/lib.rs

@@ -552,7 +552,7 @@ impl Plugin for AnimationPlugin {
             .register_type::<AnimationPlayer>()
             .add_system(
                 animation_player
-                    .in_set(CoreSet::PostUpdate)
+                    .in_base_set(CoreSet::PostUpdate)
                     .before(TransformSystem::TransformPropagate),
             );
     }

crates/bevy_app/src/app.rs

@@ -328,14 +328,14 @@ impl App {
                 apply_state_transition::<S>,
             )
                 .chain()
-                .in_set(CoreSet::StateTransitions),
+                .in_base_set(CoreSet::StateTransitions),
         );
 
         let main_schedule = self.get_schedule_mut(CoreSchedule::Main).unwrap();
         for variant in S::variants() {
             main_schedule.configure_set(
                 OnUpdate(variant.clone())
-                    .in_set(CoreSet::StateTransitions)
+                    .in_base_set(CoreSet::StateTransitions)
                     .run_if(state_equals(variant))
                     .after(apply_state_transition::<S>),
             );
@@ -580,7 +580,7 @@ impl App {
     {
         if !self.world.contains_resource::<Events<T>>() {
             self.init_resource::<Events<T>>()
-                .add_system(Events::<T>::update_system.in_set(CoreSet::First));
+                .add_system(Events::<T>::update_system.in_base_set(CoreSet::First));
         }
         self
     }

crates/bevy_app/src/lib.rs

@@ -29,8 +29,8 @@ pub mod prelude {
 
 use bevy_ecs::{
     schedule_v3::{
-        apply_system_buffers, IntoSystemConfig, IntoSystemSetConfig, Schedule, ScheduleLabel,
-        SystemSet,
+        apply_system_buffers, IntoSystemConfig, IntoSystemSetConfig, IntoSystemSetConfigs,
+        Schedule, ScheduleLabel, SystemSet,
     },
     system::Local,
     world::World,
@@ -90,6 +90,7 @@ impl CoreSchedule {
 /// that runs immediately after the matching system set.
 /// These can be useful for ordering, but you almost never want to add your systems to these sets.
 #[derive(Debug, Hash, PartialEq, Eq, Clone, SystemSet)]
+#[system_set(base)]
 pub enum CoreSet {
     /// Runs before all other members of this set.
     First,
@@ -129,20 +130,30 @@ impl CoreSet {
         let mut schedule = Schedule::new();
 
         // Create "stage-like" structure using buffer flushes + ordering
-        schedule.add_system(apply_system_buffers.in_set(FirstFlush));
-        schedule.add_system(apply_system_buffers.in_set(PreUpdateFlush));
-        schedule.add_system(apply_system_buffers.in_set(UpdateFlush));
-        schedule.add_system(apply_system_buffers.in_set(PostUpdateFlush));
-        schedule.add_system(apply_system_buffers.in_set(LastFlush));
-
-        schedule.configure_set(First.before(FirstFlush));
-        schedule.configure_set(PreUpdate.after(FirstFlush).before(PreUpdateFlush));
-        schedule.configure_set(StateTransitions.after(PreUpdateFlush).before(FixedUpdate));
-        schedule.configure_set(FixedUpdate.after(StateTransitions).before(Update));
-        schedule.configure_set(Update.after(FixedUpdate).before(UpdateFlush));
-        schedule.configure_set(PostUpdate.after(UpdateFlush).before(PostUpdateFlush));
-        schedule.configure_set(Last.after(PostUpdateFlush).before(LastFlush));
-
+        schedule
+            .set_default_base_set(Update)
+            .add_system(apply_system_buffers.in_base_set(FirstFlush))
+            .add_system(apply_system_buffers.in_base_set(PreUpdateFlush))
+            .add_system(apply_system_buffers.in_base_set(UpdateFlush))
+            .add_system(apply_system_buffers.in_base_set(PostUpdateFlush))
+            .add_system(apply_system_buffers.in_base_set(LastFlush))
+            .configure_sets(
+                (
+                    First,
+                    FirstFlush,
+                    PreUpdate,
+                    PreUpdateFlush,
+                    StateTransitions,
+                    FixedUpdate,
+                    Update,
+                    UpdateFlush,
+                    PostUpdate,
+                    PostUpdateFlush,
+                    Last,
+                    LastFlush,
+                )
+                    .chain(),
+            );
         schedule
     }
 }

crates/bevy_asset/src/asset_server.rs

@@ -644,7 +644,7 @@ pub fn free_unused_assets_system(asset_server: Res<AssetServer>) {
 mod test {
     use super::*;
     use crate::{loader::LoadedAsset, update_asset_storage_system};
-    use bevy_app::{App, CoreSet};
+    use bevy_app::App;
     use bevy_ecs::prelude::*;
     use bevy_reflect::TypeUuid;
     use bevy_utils::BoxedFuture;
@@ -852,16 +852,8 @@ mod test {
         let mut app = App::new();
         app.insert_resource(assets);
         app.insert_resource(asset_server);
-        app.add_system(
-            free_unused_assets_system
-                .in_set(FreeUnusedAssets)
-                .in_set(CoreSet::Update),
-        );
-        app.add_system(
-            update_asset_storage_system::<PngAsset>
-                .after(FreeUnusedAssets)
-                .in_set(CoreSet::Update),
-        );
+        app.add_system(free_unused_assets_system.in_set(FreeUnusedAssets));
+        app.add_system(update_asset_storage_system::<PngAsset>.after(FreeUnusedAssets));
 
         fn load_asset(path: AssetPath, world: &World) -> HandleUntyped {
             let asset_server = world.resource::<AssetServer>();

crates/bevy_asset/src/assets.rs

@@ -331,8 +331,8 @@ impl AddAsset for App {
         };
 
         self.insert_resource(assets)
-            .add_system(Assets::<T>::asset_event_system.in_set(AssetSet::AssetEvents))
-            .add_system(update_asset_storage_system::<T>.in_set(AssetSet::LoadAssets))
+            .add_system(Assets::<T>::asset_event_system.in_base_set(AssetSet::AssetEvents))
+            .add_system(update_asset_storage_system::<T>.in_base_set(AssetSet::LoadAssets))
             .register_type::<Handle<T>>()
             .add_event::<AssetEvent<T>>()
     }

crates/bevy_asset/src/debug_asset_server.rs

@@ -2,7 +2,7 @@
 //!
 //! Internal assets (e.g. shaders) are bundled directly into an application and can't be hot
 //! reloaded using the conventional API.
-use bevy_app::{App, CoreSet, Plugin};
+use bevy_app::{App, Plugin};
 use bevy_ecs::{prelude::*, system::SystemState};
 use bevy_tasks::{IoTaskPool, TaskPoolBuilder};
 use bevy_utils::HashMap;
@@ -75,7 +75,7 @@ impl Plugin for DebugAssetServerPlugin {
             watch_for_changes: true,
         });
         app.insert_non_send_resource(DebugAssetApp(debug_asset_app));
-        app.add_system(run_debug_asset_app.in_set(CoreSet::Update));
+        app.add_system(run_debug_asset_app);
     }
 }
 

crates/bevy_asset/src/diagnostic/asset_count_diagnostics_plugin.rs

@@ -19,7 +19,7 @@ impl<T: Asset> Default for AssetCountDiagnosticsPlugin<T> {
 impl<T: Asset> Plugin for AssetCountDiagnosticsPlugin<T> {
     fn build(&self, app: &mut App) {
         app.add_startup_system(Self::setup_system.in_set(StartupSet::Startup))
-            .add_system(Self::diagnostic_system.in_set(CoreSet::Update));
+            .add_system(Self::diagnostic_system);
     }
 }
 

crates/bevy_asset/src/lib.rs

@@ -51,6 +51,7 @@ use bevy_ecs::prelude::*;
 
 /// [`SystemSet`]s for asset loading in an [`App`] schedule.
 #[derive(Debug, Hash, PartialEq, Eq, Clone, SystemSet)]
+#[system_set(base)]
 pub enum AssetSet {
     /// Asset storages are updated.
     LoadAssets,
@@ -109,22 +110,20 @@ impl Plugin for AssetPlugin {
 
         app.configure_set(
             AssetSet::LoadAssets
-                .no_default_set()
                 .before(CoreSet::PreUpdate)
                 .after(CoreSet::First),
         )
         .configure_set(
             AssetSet::AssetEvents
-                .no_default_set()
                 .after(CoreSet::PostUpdate)
                 .before(CoreSet::Last),
         )
-        .add_system(asset_server::free_unused_assets_system.in_set(CoreSet::PreUpdate));
+        .add_system(asset_server::free_unused_assets_system.in_base_set(CoreSet::PreUpdate));
 
         #[cfg(all(
             feature = "filesystem_watcher",
             all(not(target_arch = "wasm32"), not(target_os = "android"))
         ))]
-        app.add_system(io::filesystem_watcher_system.in_set(AssetSet::LoadAssets));
+        app.add_system(io::filesystem_watcher_system.in_base_set(AssetSet::LoadAssets));
     }
 }

crates/bevy_audio/src/lib.rs

@@ -56,7 +56,7 @@ impl Plugin for AudioPlugin {
             .add_asset::<AudioSource>()
             .add_asset::<AudioSink>()
             .init_resource::<Audio<AudioSource>>()
-            .add_system(play_queued_audio_system::<AudioSource>.in_set(CoreSet::PostUpdate));
+            .add_system(play_queued_audio_system::<AudioSource>.in_base_set(CoreSet::PostUpdate));
 
         #[cfg(any(feature = "mp3", feature = "flac", feature = "wav", feature = "vorbis"))]
         app.init_asset_loader::<AudioLoader>();
@@ -71,6 +71,6 @@ impl AddAudioSource for App {
         self.add_asset::<T>()
             .init_resource::<Audio<T>>()
             .init_resource::<AudioOutput<T>>()
-            .add_system(play_queued_audio_system::<T>.in_set(CoreSet::PostUpdate))
+            .add_system(play_queued_audio_system::<T>.in_base_set(CoreSet::PostUpdate))
     }
 }

crates/bevy_core/src/lib.rs

@@ -107,7 +107,7 @@ impl Plugin for TaskPoolPlugin {
         self.task_pool_options.create_default_pools();
 
         #[cfg(not(target_arch = "wasm32"))]
-        app.add_system(tick_global_task_pools.in_set(bevy_app::CoreSet::Last));
+        app.add_system(tick_global_task_pools.in_base_set(bevy_app::CoreSet::Last));
     }
 }
 /// A dummy type that is [`!Send`](Send), to force systems to run on the main thread.
@@ -142,7 +142,7 @@ pub struct FrameCountPlugin;
 impl Plugin for FrameCountPlugin {
     fn build(&self, app: &mut App) {
         app.init_resource::<FrameCount>();
-        app.add_system(update_frame_count.in_set(CoreSet::Last));
+        app.add_system(update_frame_count.in_base_set(CoreSet::Last));
     }
 }