Fast and correct one-shot systems with a system registry resource

Cargo.toml

@@ -788,6 +788,16 @@ description = "Shows how to iterate over combinations of query results"
 category = "ECS (Entity Component System)"
 wasm = true
 
+[[example]]
+name = "one_shot_systems"
+path = "examples/ecs/one_shot_systems.rs"
+
+[package.metadata.example.one_shot_systems]
+name = "One Shot Systems"
+description = "Shows how to flexibly run systems without scheduling them"
+category = "ECS (Entity Component System)"
+wasm = false
+
 [[example]]
 name = "parallel_query"
 path = "examples/ecs/parallel_query.rs"

crates/bevy_app/src/lib.rs

@@ -6,6 +6,7 @@ mod app;
 mod plugin;
 mod plugin_group;
 mod schedule_runner;
+mod system_registry;
 
 #[cfg(feature = "bevy_ci_testing")]
 mod ci_testing;

crates/bevy_app/src/system_registry.rs

@@ -0,0 +1,68 @@
+use crate::App;
+use bevy_ecs::prelude::*;
+use bevy_ecs::system::SystemRegistryError;
+
+impl App {
+    /// Registers the supplied system in the [`SystemRegistry`](bevy_ecs::system::SystemRegistry) resource.
+    ///
+    /// Calls the method of the same name on [`SystemRegistry`](bevy_ecs::system::SystemRegistry).
+    #[inline]
+    pub fn register_system<Params, S: IntoSystem<(), (), Params> + 'static>(
+        &mut self,
+        system: S,
+    ) -> &mut Self {
+        self.world.register_system(system);
+        self
+    }
+
+    /// Register system a system with any number of [`SystemLabel`]s.
+    ///
+    /// Calls the method of the same name on [`SystemRegistry`].
+    pub fn register_system_with_labels<
+        Params,
+        S: IntoSystem<(), (), Params> + 'static,
+        LI: IntoIterator<Item = L>,
+        L: SystemLabel,
+    >(
+        &mut self,
+        system: S,
+        labels: LI,
+    ) -> &mut Self {
+        self.world.register_system_with_labels(system, labels);
+        self
+    }
+
+    /// Runs the supplied system on the [`World`] a single time.
+    ///
+    /// Calls the method of the same name on [`SystemRegistry`](bevy_ecs::system::SystemRegistry).
+    #[inline]
+    pub fn run_system<Params, S: IntoSystem<(), (), Params> + 'static>(
+        &mut self,
+        system: S,
+    ) -> &mut Self {
+        self.world.run_system(system);
+        self
+    }
+
+    /// Runs the systems corresponding to the supplied [`SystemLabel`] on the [`World`] a single time.
+    ///
+    /// Calls the method of the same name on [`SystemRegistry`](bevy_ecs::system::SystemRegistry).
+    #[inline]
+    pub fn run_systems_by_label<L: SystemLabel>(
+        &mut self,
+        label: L,
+    ) -> Result<(), SystemRegistryError> {
+        self.world.run_systems_by_label(label)
+    }
+
+    /// A trait-object compatible version of `run_systems_by_label`.
+    ///
+    /// Calls the method of the same name on [`SystemRegistry`](bevy_ecs::system::SystemRegistry).
+    #[inline]
+    pub fn run_systems_by_boxed_label(
+        &mut self,
+        boxed_label: Box<dyn SystemLabel>,
+    ) -> Result<(), SystemRegistryError> {
+        self.world.run_systems_by_boxed_label(boxed_label)
+    }
+}

crates/bevy_ecs/src/system/commands/mod.rs

@@ -5,6 +5,8 @@ use crate::{
     bundle::Bundle,
     component::Component,
     entity::{Entities, Entity},
+    schedule::SystemLabel,
+    system::{IntoSystem, RunSystemCommand, RunSystemsByLabelCommand},
     world::{FromWorld, World},
 };
 use bevy_utils::tracing::{error, warn};
@@ -362,6 +364,36 @@ impl<'w, 's> Commands<'w, 's> {
         });
     }
 
+    /// Runs the supplied system on the [`World`] a single time.
+    ///
+    /// Calls the method of the same name on [`SystemRegistry`](crate::system::SystemRegistry).
+    pub fn run_system<
+        Params: Send + Sync + 'static,
+        S: IntoSystem<(), (), Params> + Send + Sync + 'static,
+    >(
+        &mut self,
+        system: S,
+    ) {
+        self.queue.push(RunSystemCommand::new(system));
+    }
+
+    /// Runs the systems corresponding to the supplied [`SystemLabel`] on the [`World`] a single time.
+    ///
+    /// Calls the method of the same name on [`SystemRegistry`](crate::system::SystemRegistry).
+    pub fn run_systems_by_label(&mut self, label: impl SystemLabel) {
+        self.queue.push(RunSystemsByLabelCommand {
+            label: Box::new(label),
+        });
+    }
+
+    /// A trait-object compatible version of `run_systems_by_label`.
+    ///
+    /// Calls the method of the same name on [`SystemRegistry`](crate::system::SystemRegistry).
+    pub fn run_systems_by_boxed_label(&mut self, boxed_label: Box<dyn SystemLabel>) {
+        self.queue
+            .push(RunSystemsByLabelCommand { label: boxed_label });
+    }
+
     /// Adds a command directly to the command list.
     ///
     /// # Example

crates/bevy_ecs/src/system/function_system.rs

@@ -56,8 +56,10 @@ impl SystemMeta {
 // (to avoid the need for unwrapping to retrieve SystemMeta)
 /// Holds on to persistent state required to drive [`SystemParam`] for a [`System`].
 ///
-/// This is a very powerful and convenient tool for working with exclusive world access,
+/// This is a powerful and convenient tool for working with exclusive world access,
 /// allowing you to fetch data from the [`World`] as if you were running a [`System`].
+/// However, simply calling `world::run_system(my_system)` using a [`SystemRegistry`](crate::system::SystemRegistry)
+/// can be significantly simpler and more reliable.
 ///
 /// Borrow-checking is handled for you, allowing you to mutably access multiple compatible system parameters at once,
 /// and arbitrary system parameters (like [`EventWriter`](crate::event::EventWriter)) can be conveniently fetched.
@@ -73,6 +75,8 @@ impl SystemMeta {
 /// - [`Local`](crate::system::Local) variables that hold state
 /// - [`EventReader`](crate::event::EventReader) system parameters, which rely on a [`Local`](crate::system::Local) to track which events have been seen
 ///
+/// Note that this is automatically handled for you when using a [`SystemRegistry`](crate::system::SystemRegistry).
+///
 /// # Example
 ///
 /// Basic usage:
@@ -444,14 +448,27 @@ where
             self.system_meta.name.as_ref(),
         );
     }
+
+    #[inline]
     fn default_labels(&self) -> Vec<Box<dyn SystemLabel>> {
         vec![Box::new(self.func.as_system_label())]
     }
 }
 
 /// A [`SystemLabel`] that was automatically generated for a system on the basis of its `TypeId`.
+#[derive(Default)]
 pub struct SystemTypeIdLabel<T: 'static>(PhantomData<fn() -> T>);
 
+impl<T: 'static> SystemTypeIdLabel<T> {
+    /// Constructs a new copy of the [`SystemTypeIdLabel`] for the type `T`
+    ///
+    /// You can also construct this by using [`.as_system_label()`](crate::system::AsSystemLabel) on a concrete instance
+    /// of your function type.
+    pub fn new() -> Self {
+        Self(PhantomData::default())
+    }
+}
+
 impl<T> Debug for SystemTypeIdLabel<T> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_tuple("SystemTypeIdLabel")

crates/bevy_ecs/src/system/mod.rs

@@ -74,6 +74,7 @@ mod query;
 mod system;
 mod system_chaining;
 mod system_param;
+mod system_registry;
 
 pub use commands::*;
 pub use exclusive_system::*;
@@ -82,6 +83,7 @@ pub use query::*;
 pub use system::*;
 pub use system_chaining::*;
 pub use system_param::*;
+pub use system_registry::*;
 
 /// Ensure that a given function is a system
 ///