Trait bevy_ecs::system::RunSystemOnce
source · pub trait RunSystemOnce: Sized {
// Required method
fn run_system_once_with<T: IntoSystem<In, Out, Marker>, In, Out, Marker>(
self,
input: In,
system: T
) -> Out;
// Provided method
fn run_system_once<T: IntoSystem<(), Out, Marker>, Out, Marker>(
self,
system: T
) -> Out { ... }
}
Expand description
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 the World::run_system
and run the system by their SystemId
.
§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()
});
§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()
});
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);
Required Methods§
sourcefn run_system_once_with<T: IntoSystem<In, Out, Marker>, In, Out, Marker>(
self,
input: In,
system: T
) -> Out
fn run_system_once_with<T: IntoSystem<In, Out, Marker>, In, Out, Marker>( self, input: In, system: T ) -> Out
Runs a system with given input and applies its deferred parameters.
Provided Methods§
sourcefn run_system_once<T: IntoSystem<(), Out, Marker>, Out, Marker>(
self,
system: T
) -> Out
fn run_system_once<T: IntoSystem<(), Out, Marker>, Out, Marker>( self, system: T ) -> Out
Runs a system and applies its deferred parameters.