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_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::{RunSystemById, SystemId},
     world::{EntityWorldMut, FromWorld, World},
 };
 use bevy_ecs_macros::SystemParam;
@@ -519,11 +520,17 @@ impl<'w, 's> Commands<'w, 's> {
         self.queue.push(RemoveResource::<R>::new());
     }
 
+    /// Runs the system corresponding to the given [`SystemId`].
+    ///
+    /// Calls [`World::run_system_by_id`](crate::system::World::run_system_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_by_id(my_system)` using a [`World::run_system_by_id`](crate::system::World::run_system_by_id)
+/// 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 [`World::run_system_by_id`](crate::system::World::run_system_by_id).
+///
 /// # 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

@@ -165,6 +165,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 [`World::run_system_by_id`](crate::system::World::run_system_by_id)
+/// 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
@@ -261,6 +285,7 @@ impl RunSystem for &mut World {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate as bevy_ecs;
     use crate::prelude::*;
 
     #[test]
@@ -279,4 +304,51 @@ 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));
+    }
 }