NEOLearn

System parameters

Local state, ParamSet, optional and skipping parameters, your own SystemParam types, exclusive systems with full world access, and one-shot systems.

Updated October 20, 2026

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.

Rust
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:

Rust
#[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.

ParameterThe 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:

Rust
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.

Rust
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:

Rust
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 }
MethodWhat 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:

ExampleWhat it shows
cargo run --example system_paramA custom SystemParam.
cargo run --example one_shot_systemsRegistering and running one-shot systems from components.
cargo run --example callbacksArbitrary systems stored in components and run on demand.
cargo run --example fallible_paramsSingle, Option<Single> and Populated.
cargo run --example ecs_guideAn exclusive system next to normal ones, and Local.

Next steps#