docs and example

Author: ecoskey

crates/bevy_ecs/macros/src/lib.rs

@@ -721,11 +721,83 @@ pub fn derive_from_world(input: TokenStream) -> TokenStream {
     })
 }
 
+/// Automatically compose systems together with function syntax.
+///
+/// This macro provides some nice syntax on top of the `SystemRunner` `SystemParam`
+/// to allow running systems inside other systems. Overall, the macro accepts normal
+/// closure syntax:
+///
+/// ```ignore
+/// let system_a = |world: &mut World| { 10 };
+/// let system_b = |a: In<u32>, world: &mut World| { println!("{}", *a + 12) };
+/// compose! {
+///     || -> Result<(), RunSystemError> {
+///         let a = run!(system-a)?;
+///         run!(system_b);
+///     }
+/// }
+/// ```
+///
+/// What's special is that the macro will expand any invocations of `run!()` into
+/// calls to `SystemRunner::run` or `SystemRunner::run_with`. The `run!()` accepts
+/// two parameters: first, a system identifier (or a path to one), and second, an
+/// optional input to invoke the system with.
+///
+/// Notes:
+/// 1. All system runners are passed through a `ParamSet`, so invoked systems will
+///    not conflict with each other. However, invoked systems may still conflict
+///    with system params in the outer closure.
+///
+/// 2. `run!` will not accept expressions that evaluate to systems, only direct
+///    identifiers or paths. So, if you want to call something like:
+///
+///    ```ignore
+///    run!(|query: Query<(&A, &B, &mut C)>| { ... })`
+///    ```
+///
+///    Assign the expression to a variable first.
 #[proc_macro]
 pub fn compose(input: TokenStream) -> TokenStream {
     system_composition::compose(input, false)
 }
 
+/// Automatically compose systems together with function syntax.
+///
+/// Unlike [`compose`], this macro allows generating systems that take input.
+///
+/// This macro provides some nice syntax on top of the `SystemRunner` `SystemParam`
+/// to allow running systems inside other systems. Overall, the macro accepts normal
+/// closure syntax:
+///
+/// ```ignore
+/// let system_a = |input: In<u32>, world: &mut World| { *input + 10 };
+/// let system_b = |a: In<u32>, world: &mut World| { println!("{}", *a + 12) };
+/// compose_with! {
+///     |input: In<u32>| -> Result<(), RunSystemError> {
+///         let a = run!(system_a, input)?;
+///         run!(system_b);
+///     }
+/// }
+/// ```
+///
+/// What's special is that the macro will expand any invocations of `run!()` into
+/// calls to `SystemRunner::run` or `SystemRunner::run_with`. The `run!()` accepts
+/// two parameters: first, a system identifier (or a path to one), and second, an
+/// optional input to invoke the system with.
+///
+/// Notes:
+/// 1. All system runners are passed through a `ParamSet`, so invoked systems will
+///    not conflict with each other. However, invoked systems may still conflict
+///    with system params in the outer closure.
+///
+/// 2. `run!` will not accept expressions that evaluate to systems, only direct
+///    identifiers or paths. So, if you want to call something like:
+///
+///    ```ignore
+///    run!(|query: Query<(&A, &B, &mut C)>| { ... })`
+///    ```
+///
+///    Assign the expression to a variable first.
 #[proc_macro]
 pub fn compose_with(input: TokenStream) -> TokenStream {
     system_composition::compose(input, true)

crates/bevy_ecs/src/system/system_param.rs

@@ -2765,6 +2765,47 @@ unsafe impl SystemParam for FilteredResourcesMut<'_, '_> {
     }
 }
 
+/// A [`SystemParam`] that allows running other systems.
+///
+/// To be useful, this must be configured using a [`SystemRunnerBuilder`](crate::system::SystemRunnerBuilder)
+/// to build the system using a [`SystemParamBuilder`](crate::prelude::SystemParamBuilder).
+///
+/// Also see the macros [`compose`](crate::system::compose) and [`compose_with`](crate::system::compose_with)
+/// for some nice syntax on top of this API.
+///
+/// # Examples
+///
+/// ```
+/// # use bevy_ecs::{prelude::*, system::*};
+/// #
+/// # #[derive(Component)]
+/// # struct A;
+/// #
+/// # #[derive(Component)]
+/// # struct B;
+/// # let mut world = World::new();
+/// #
+/// fn count_a(a: Query<&A>) -> u32 {
+///     a.len()
+/// }
+///
+/// fn count_b(b: Query<&B>) -> u32 {
+///     b.len()
+/// }
+///
+/// let get_sum = (
+///     ParamBuilder::system(count_a),
+///     ParamBuilder::system(count_b)
+/// )
+/// .build_state(&mut world)
+/// .build_system(
+///     |mut run_a: SystemRunner<(), u32>, mut run_b: SystemRunner<(), u32>| -> Result<u32, RunSystemError> {
+///         let a = run_a.run()?;
+///         let b = run_b.run()?;
+///         Ok(a + b)
+///     }
+/// );
+/// ```
 pub struct SystemRunner<'w, 's, In = (), Out = (), Sys = dyn System<In = In, Out = Out>>
 where
     In: SystemInput,
@@ -2779,6 +2820,7 @@ where
     In: SystemInput,
     Sys: System<In = In, Out = Out> + ?Sized,
 {
+    /// Run the system with input.
     #[inline]
     pub fn run_with(&mut self, input: In::Inner<'_>) -> Result<Out, RunSystemError> {
         // SAFETY:
@@ -2798,6 +2840,7 @@ impl<'w, 's, Out, Sys> SystemRunner<'w, 's, (), Out, Sys>
 where
     Sys: System<In = (), Out = Out> + ?Sized,
 {
+    /// Run the system.
     #[inline]
     pub fn run(&mut self) -> Result<Out, RunSystemError> {
         self.run_with(())

examples/ecs/system_piping.rs

@@ -2,6 +2,7 @@
 //! passing the output of the first into the input of the next.
 
 use bevy::prelude::*;
+use bevy_ecs::system::{compose, RunSystemError};
 use std::num::ParseIntError;
 
 use bevy::log::{debug, error, info, Level, LogPlugin};
@@ -21,17 +22,29 @@ fn main() {
                 parse_message_system.pipe(handler_system),
                 data_pipe_system.map(|out| info!("{out}")),
                 parse_message_system.map(|out| debug!("{out:?}")),
-                warning_pipe_system.map(|out| {
-                    if let Err(err) = out {
-                        error!("{err}");
+                parse_message_system.map(drop),
+                // You can also use the `compose!` macro to pipe systems together!
+                // This is even more powerful, but might be harder to use with
+                // fully generic code. See the docs on `compose!` and `compose_with!`
+                // for more info.
+                compose! {
+                    || -> Result<(), RunSystemError> {
+                        let out = run!(warning_pipe_system)?;
+                        if let Err(err) = out {
+                            error!("{err}");
+                        }
+                        Ok(())
                     }
-                }),
-                parse_error_message_system.map(|out| {
-                    if let Err(err) = out {
-                        error!("{err}");
+                },
+                compose! {
+                    || -> Result<(), RunSystemError>  {
+                        let out = run!(parse_error_message_system)?;
+                        if let Err(err) = out {
+                            error!("{err}");
+                        }
+                        Ok(())
                     }
-                }),
-                parse_message_system.map(drop),
+                },
             ),
         )
         .run();

release-content/migration-guides/system_input_unwrap.md

@@ -0,0 +1,9 @@
+---
+title: "New required method on SystemInput"
+pull_requests: [todo]
+---
+
+Custom implementations of the `SystemInput` trait will need to implement a new
+required method: `unwrap`. Like `wrap`, it converts between the inner input item
+and the wrapper, but in the opposite direction. In most cases it should be
+trivial to add.

release-content/release-notes/system_composition.md

@@ -0,0 +1,49 @@
+---
+title: System Composition
+authors: ["@ecoskey"]
+pull_requests: [todo]
+---
+
+## `SystemRunner` SystemParam
+
+We've been working on some new tools to make composing multiple ECS systems together
+even easier. Bevy 0.18 introduces the `SystemRunner` `SystemParam`, allowing running
+systems inside other systems!
+
+```rust
+fn count_a(a: Query<&A>) -> u32 {
+    a.len()
+}
+
+fn count_b(b: Query<&B>) -> u32 {
+    b.len()
+}
+
+let get_sum = (
+    ParamBuilder::system(count_a),
+    ParamBuilder::system(count_b)
+)
+.build_system(
+    |mut run_a: SystemRunner<(), u32>, mut run_b: SystemRunner<(), u32>| -> Result<u32, RunSystemError> {
+        let a = run_a.run()?;
+        let b = run_b.run()?;
+        Ok(a + b)
+    }
+);
+```
+
+## `compose!` and `compose_with!`
+
+With this new API we've also added some nice macro syntax to go on top. The `compose!`
+and `compose_with!` macros will automatically transform a provided closure, making
+the new `SystemRunner` params almost seamless to use.
+
+```rust
+compose! {
+    || -> Result<u32, RunSystemError> {
+        let a = run!(count_a)?;
+        let b = run!(count_b)?;
+        Ok(a + b)
+    }
+}
+```