Trait RunSystemOnce

pub trait RunSystemOnce: Sized {
    // Required method
    fn run_system_once_with<T, In, Out, Marker>(
        self,
        input: SystemIn<'_, T::System>,
        system: T,
    ) -> Result<Out, RunSystemError>
       where T: IntoSystem<In, Out, Marker>,
             In: SystemInput;

    // Provided method
    fn run_system_once<T, Out, Marker>(
        self,
        system: T,
    ) -> Result<Out, RunSystemError>
       where T: IntoSystem<(), Out, Marker> { ... }
}

Trait used to run a system immediately on a World.

Warning

This function is not an efficient method of running systems and it’s meant to be used as a utility for testing and/or diagnostics.

Systems called through run_system_once do not hold onto any state, as they are created and destroyed every time run_system_once is called. Practically, this means that Local variables are reset on every run and change detection does not work.

#[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_once(increment); // prints 1
world.run_system_once(increment); // still prints 1

If you do need systems to hold onto state between runs, use World::run_system_cached or World::run_system.

Usage

Typically, to test a system, or to extract specific diagnostics information from a world, you’d need a Schedule to run the system. This can create redundant boilerplate code when writing tests or trying to quickly iterate on debug specific systems.

For these situations, this function can be useful because it allows you to execute a system immediately with some custom input and retrieve its output without requiring the necessary boilerplate.

Examples

Immediate Command Execution

This usage is helpful when trying to test systems or functions that operate on Commands:

let mut world = World::default();
let entity = world.run_system_once(|mut commands: Commands| {
    commands.spawn_empty().id()
}).unwrap();

Immediate Queries

This usage is helpful when trying to run an arbitrary query on a world for testing or debugging purposes:

#[derive(Component)]
struct T(usize);

let mut world = World::default();
world.spawn(T(0));
world.spawn(T(1));
world.spawn(T(1));
let count = world.run_system_once(|query: Query<&T>| {
    query.iter().filter(|t| t.0 == 1).count()
}).unwrap();

Note that instead of closures you can also pass in regular functions as systems:

#[derive(Component)]
struct T(usize);

fn count(query: Query<&T>) -> usize {
    query.iter().filter(|t| t.0 == 1).count()
}

let mut world = World::default();
world.spawn(T(0));
world.spawn(T(1));
world.spawn(T(1));
let count = world.run_system_once(count).unwrap();

Required Methods

fn run_system_once_with<T, In, Out, Marker>( self, input: SystemIn<'_, T::System>, system: T, ) -> Result<Out, RunSystemError>

where T: IntoSystem<In, Out, Marker>, In: SystemInput,

Tries to run a system with given input and apply deferred parameters.

Provided Methods

fn run_system_once<T, Out, Marker>( self, system: T, ) -> Result<Out, RunSystemError>

where T: IntoSystem<(), Out, Marker>,

Tries to run a system and apply its deferred parameters.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl RunSystemOnce for &mut World