System parameters
Local state, ParamSet, optional and skipping parameters, your own SystemParam types, exclusive systems with full world access, and one-shot systems.
On this page
The Systems page lists the everyday parameters. This page covers the rest: per-system state, parameters that would otherwise conflict, parameters that skip a system, your own parameter types, and systems that take the whole world.
Local#
Local<T> is a value owned by one system that keeps its value between runs. It starts as T::default() (or FromWorld). Two systems with Local<u32> each have their own.
use neo::prelude::*;
fn count_frames(mut frames: Local<u64>) {
*frames += 1;
if *frames % 600 == 0 {
info!("{} frames", *frames);
}
}ParamSet#
Two parameters that both write the same data can't be in one system: two Query<&mut Transform> could hand out two &mut to the same entity. When you need both, and can't make them disjoint with With and Without, put them in a ParamSet and use one at a time:
#[derive(Component)]
struct Player;
fn snap_followers(mut set: ParamSet<(Query<&Transform, With<Player>>, Query<&mut Transform>)>) {
let Ok(target) = set.p0().single().map(|t| t.translation) else { return };
for mut transform in set.p1().iter_mut() {
transform.translation.x = target.x;
}
}p0() to p7() give access to each member in turn; a set holds up to eight.
Parameters that skip the system#
Some parameters stop the system from running, quietly, when they can't be fetched. Use them to express "only run when this exists" in the signature.
| Parameter | The system is skipped when |
|---|---|
Single<D, F> | Not exactly one entity matches. |
Populated<D, F> | No entity matches. |
PopulatedMessageReader<M> | There are no new messages. |
If<P> | The wrapped parameter P (for example If<Res<T>>) can't be fetched. |
SkipIfAny<F> | Any entity passes the filter F. Name it with a leading underscore. |
Res<T> and ResMut<T> for a missing resource are different: that's an error, sent to the error handler.
Your own SystemParam#
Derive SystemParam to bundle parameters that are always used together, with methods on top:
use neo::ecs::system::SystemParam;
#[derive(Resource)]
struct PlayerCount(usize);
#[derive(SystemParam)]
struct PlayerCounter<'w, 's> {
players: Query<'w, 's, &'static Player>,
count: ResMut<'w, PlayerCount>,
}
impl PlayerCounter<'_, '_> {
fn update(&mut self) {
self.count.0 = self.players.iter().len();
}
}
fn count_players(mut counter: PlayerCounter) {
counter.update();
}The struct has two lifetimes, 'w for world data and 's for system state, and component references inside are &'static.
Exclusive systems#
A system whose first parameter is &mut World is exclusive: it has the whole world, applies changes immediately, and runs with no other system at the same time.
fn save_game(world: &mut World) {
let mut query = world.query::<(&Name, &Transform)>();
for (name, transform) in query.iter(world) {
info!("{name}: {:?}", transform.translation);
}
}Use them for work that needs everything at once or must apply changes right away, such as running a schedule, saving, or spawning a scene synchronously. Exclusive systems block parallelism, so keep them few and short. They can take a few other parameters after &mut World, such as Local<T> and &mut QueryState<D, F>.
A read-only system can take &World alongside other read-only parameters.
One-shot systems#
A one-shot system runs only when you ask it to, not every frame. Register it to get a SystemId, then run it from a command, a system or the world:
use neo::ecs::system::SystemId;
#[derive(Resource)]
struct Callbacks {
on_victory: SystemId,
}
fn setup(mut commands: Commands) {
let on_victory = commands.register_system(celebrate);
commands.insert_resource(Callbacks { on_victory });
}
fn check_victory(callbacks: Res<Callbacks>, mut commands: Commands) {
if victory_reached() {
commands.run_system(callbacks.on_victory);
}
}
fn celebrate(mut commands: Commands) {
commands.spawn(Name::new("Fireworks"));
}
fn victory_reached() -> bool { false }| Method | What it does |
|---|---|
commands.register_system(s), world.register_system(s) | Registers s and returns its SystemId. |
commands.run_system(id), world.run_system(id) | Runs it. |
commands.run_system_with(id, input) | Runs a system that takes In<T>. |
commands.run_system_cached(s) | Registers on first use, then reuses the registration. |
commands.unregister_system(id) | Removes it. |
world.run_system_once(s) | Runs s once without registering. Needs use neo::ecs::system::RunSystemOnce;. Handy in tests. |
A one-shot system keeps its Local state and change detection between runs, like any system. Storing SystemIds in components gives you per-entity callbacks.
Examples#
Run these from the engine core's workspace:
| Example | What it shows |
|---|---|
cargo run --example system_param | A custom SystemParam. |
cargo run --example one_shot_systems | Registering and running one-shot systems from components. |
cargo run --example callbacks | Arbitrary systems stored in components and run on demand. |
cargo run --example fallible_params | Single, Option<Single> and Populated. |
cargo run --example ecs_guide | An exclusive system next to normal ones, and Local. |