One Shot Systems

Cargo.toml

@@ -1254,6 +1254,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

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

crates/bevy_app/src/system_registry.rs

@@ -0,0 +1,43 @@
+use crate::App;
+use bevy_ecs::prelude::*;
+use bevy_ecs::system::RemovedSystem;
+use bevy_ecs::system::{RunSystem, SystemId, SystemRegistryError};
+
+impl App {
+    /// Register a system in the [`SystemRegistry`](bevy_ecs::system::SystemRegistry)
+    ///
+    /// Calls [`SystemRegistry::register_system`](bevy_ecs::system::SystemRegistry::register).
+    pub fn register_system<M, S: IntoSystem<(), (), M> + 'static>(
+        &mut self,
+        system: S,
+    ) -> &mut Self {
+        self.world.register_system(system);
+        self
+    }
+
+    /// Removes a registered system in the [`SystemRegistry`](bevy_ecs::system::SystemRegistry).
+    /// It returns nothing if id has no corresponding system.
+    ///
+    /// Calls [`SystemRegistry::remove_system`](bevy_ecs::system::SystemRegistry::remove).
+    #[inline]
+    pub fn remove_system(&mut self, id: SystemId) -> Result<RemovedSystem, SystemRegistryError> {
+        self.world.remove_system(id)
+    }
+
+    /// Runs the supplied system on the [`World`] a single time.
+    ///
+    /// Calls [`RunSystem::run_system`](bevy_ecs::system::RunSystem::run_system).
+    #[inline]
+    pub fn run_system<M, S: IntoSystem<(), (), M> + 'static>(&mut self, system: S) -> &mut Self {
+        self.world.run_system(system);
+        self
+    }
+
+    /// Run the systems corresponding to the id.
+    ///
+    /// Calls [`SystemRegistry::run_system_by_id`](bevy_ecs::system::SystemRegistry::run_by_id).
+    #[inline]
+    pub fn run_system_by_id(&mut self, system_id: SystemId) -> Result<(), SystemRegistryError> {
+        self.world.run_system_by_id(system_id)
+    }
+}

crates/bevy_ecs/src/schedule/set.rs

@@ -81,6 +81,7 @@ impl<T> Hash for SystemTypeSet<T> {
         // all systems of a given type are the same
     }
 }
+
 impl<T> Clone for SystemTypeSet<T> {
     fn clone(&self) -> Self {
         *self

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

@@ -5,6 +5,7 @@ use crate::{
     self as bevy_ecs,
     bundle::Bundle,
     entity::{Entities, Entity},
+    system::{IntoSystem, RunSystemById, RunSystemCommand, SystemId},
     world::{EntityWorldMut, FromWorld, World},
 };
 use bevy_ecs_macros::SystemParam;
@@ -519,11 +520,30 @@ impl<'w, 's> Commands<'w, 's> {
         self.queue.push(RemoveResource::<R>::new());
     }
 
+    /// Runs the supplied system on the [`World`] a single time.
+    ///
+    /// Calls [`SystemRegistry::run_system`](crate::system::RunSystem::run_system).
+    pub fn run_system<
+        M: Send + Sync + 'static,
+        S: IntoSystem<(), (), M> + Send + Sync + 'static,
+    >(
+        &mut self,
+        system: S,
+    ) {
+        self.queue.push(RunSystemCommand::new(system));
+    }
+
+    /// Runs the system corresponding to the given [`SystemId`].
+    ///
+    /// Calls [`SystemRegistry::run_system_by_id`](crate::system::SystemRegistry::run_by_id).
+    pub fn run_system_by_id(&mut self, id: SystemId) {
+        self.queue.push(RunSystemById::new(id));
+    }
+
     /// Pushes a generic [`Command`] to the command queue.
     ///
     /// `command` can be a built-in command, custom struct that implements [`Command`] or a closure
     /// that takes [`&mut World`](World) as an argument.
-    ///
     /// # Example
     ///
     /// ```

crates/bevy_ecs/src/system/function_system.rs

@@ -60,8 +60,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 ensures that change detection and command flushing work as expected.
 ///
 /// 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.
@@ -77,6 +79,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:

crates/bevy_ecs/src/system/mod.rs

@@ -112,6 +112,7 @@ mod query;
 #[allow(clippy::module_inception)]
 mod system;
 mod system_param;
+mod system_registry;
 
 use std::borrow::Cow;
 
@@ -124,6 +125,7 @@ pub use function_system::*;
 pub use query::*;
 pub use system::*;
 pub use system_param::*;
+pub use system_registry::*;
 
 use crate::world::World;
 

crates/bevy_ecs/src/system/system.rs

@@ -1,7 +1,9 @@
 use bevy_utils::tracing::warn;
 use core::fmt::Debug;
+use std::marker::PhantomData;
 
 use crate::component::Tick;
+use crate::system::Command;
 use crate::world::unsafe_world_cell::UnsafeWorldCell;
 use crate::{archetype::ArchetypeComponentId, component::ComponentId, query::Access, world::World};
 
@@ -165,6 +167,30 @@ impl<In: 'static, Out: 'static> Debug for dyn System<In = In, Out = Out> {
 /// This function is not an efficient method of running systems and its meant to be used as a utility
 /// for testing and/or diagnostics.
 ///
+/// Systems called through [`run_system`](crate::system::RunSystem::run_system) do not hold onto any state,
+/// as they are created and destroyed every time [`run_system`](crate::system::RunSystem::run_system) is called.
+/// Practically, this means that [`Local`](crate::system::Local) variables are
+/// reset on every run and change detection does not work.
+///
+/// ```
+/// # use bevy_ecs::prelude::*;
+/// # use bevy_ecs::system::RunSystem;
+/// #[derive(Resource, Default)]
+/// struct Counter(u8);
+///
+/// fn increment(mut counter: Local<Counter>) {
+///    counter.0 += 1;
+///    println!("{}", counter.0);
+/// }
+///
+/// let mut world = World::default();
+/// world.run_system(increment); // prints 1
+/// world.run_system(increment); // still prints 1
+/// ```
+///
+/// If you do need systems to hold onto state between runs, use the [`SystemRegistry`](crate::system::SystemRegistry)
+/// and run the system by their [`SystemId`](crate::system::SystemId).
+///
 /// # Usage
 /// Typically, to test a system, or to extract specific diagnostics information from a world,
 /// you'd need a [`Schedule`](crate::schedule::Schedule) to run the system. This can create redundant boilerplate code
@@ -258,9 +284,43 @@ impl RunSystem for &mut World {
     }
 }
 
+/// The [`Command`] type for [`RunSystem`]
+#[derive(Debug, Clone)]
+pub struct RunSystemCommand<
+    M: Send + Sync + 'static,
+    S: IntoSystem<(), (), M> + Send + Sync + 'static,
+> {
+    _phantom_marker: PhantomData<M>,
+    system: S,
+}
+
+impl<M: Send + Sync + 'static, S: IntoSystem<(), (), M> + Send + Sync + 'static>
+    RunSystemCommand<M, S>
+{
+    /// Creates a new [`Command`] struct, which can be added to [`Commands`](crate::system::Commands)
+    #[inline]
+    #[must_use]
+    pub fn new(system: S) -> Self {
+        Self {
+            _phantom_marker: PhantomData,
+            system,
+        }
+    }
+}
+
+impl<M: Send + Sync + 'static, S: IntoSystem<(), (), M> + Send + Sync + 'static> Command
+    for RunSystemCommand<M, S>
+{
+    #[inline]
+    fn apply(self, world: &mut World) {
+        world.run_system(self.system);
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate as bevy_ecs;
     use crate::prelude::*;
 
     #[test]
@@ -279,4 +339,79 @@ mod tests {
         assert_eq!(n, 2);
         assert_eq!(world.resource::<T>().0, 1);
     }
+
+    #[derive(Resource, Default, PartialEq, Debug)]
+    struct Counter(u8);
+
+    #[allow(dead_code)]
+    fn count_up(mut counter: ResMut<Counter>) {
+        counter.0 += 1;
+    }
+
+    #[test]
+    /// We need to ensure that the system registry is accessible
+    /// even after being used once.
+    fn run_two_systems() {
+        let mut world = World::new();
+        world.init_resource::<Counter>();
+        assert_eq!(*world.resource::<Counter>(), Counter(0));
+        world.run_system(count_up);
+        assert_eq!(*world.resource::<Counter>(), Counter(1));
+        world.run_system(count_up);
+        assert_eq!(*world.resource::<Counter>(), Counter(2));
+    }
+
+    #[allow(dead_code)]
+    fn spawn_entity(mut commands: Commands) {
+        commands.spawn_empty();
+    }
+
+    #[test]
+    fn command_processing() {
+        let mut world = World::new();
+        assert_eq!(world.entities.len(), 0);
+        world.run_system(spawn_entity);
+        assert_eq!(world.entities.len(), 1);
+    }
+
+    #[test]
+    fn non_send_resources() {
+        fn non_send_count_down(mut ns: NonSendMut<Counter>) {
+            ns.0 -= 1;
+        }
+
+        let mut world = World::new();
+        world.insert_non_send_resource(Counter(10));
+        assert_eq!(*world.non_send_resource::<Counter>(), Counter(10));
+        world.run_system(non_send_count_down);
+        assert_eq!(*world.non_send_resource::<Counter>(), Counter(9));
+    }
+
+    #[test]
+    fn run_system_through_command() {
+        use crate::system::commands::Command;
+        use crate::system::RunSystemCommand;
+
+        let mut world = World::new();
+        let command = RunSystemCommand::new(spawn_entity);
+        assert_eq!(world.entities.len(), 0);
+        command.apply(&mut world);
+        assert_eq!(world.entities.len(), 1);
+    }
+
+    #[test]
+    fn system_recursion() {
+        fn count_to_ten(mut counter: ResMut<Counter>, mut commands: Commands) {
+            counter.0 += 1;
+            if counter.0 < 10 {
+                commands.run_system(count_to_ten);
+            }
+        }
+
+        let mut world = World::new();
+        world.init_resource::<Counter>();
+        assert_eq!(*world.resource::<Counter>(), Counter(0));
+        world.run_system(count_to_ten);
+        assert_eq!(*world.resource::<Counter>(), Counter(10));
+    }
 }