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
 ///