Run conditions
Run systems, sets and observers only when a condition holds, with the built-in conditions, your own condition functions and combinators like and, or and not.
On this page
A run condition is a check the engine makes before running a system. If it returns false, the system is skipped this time. Use run conditions to keep systems from doing work they don't need to: menu systems while playing, saving when nothing changed, an AI tick when there are no enemies.
use neo::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.init_resource::<Paused>()
.add_systems(Update, move_enemies.run_if(not_paused))
.run();
}
#[derive(Resource, Default)]
struct Paused(bool);
// a condition: a system that returns bool and only reads
fn not_paused(paused: Res<Paused>) -> bool {
!paused.0
}
fn move_enemies() {}A condition is any system that returns bool and only reads data: Res, Query, Single and so on. The one exception is Local, which conditions may change.
Built-in conditions#
These are in the prelude.
| Condition | True when |
|---|---|
run_once | The first time it's checked, never again. |
resource_exists::<T> | Resource T exists. |
resource_added::<T> | T was added since the system last ran. |
resource_changed::<T> | T changed since the system last ran. T must exist. |
resource_exists_and_changed::<T> | T exists and changed. |
resource_changed_or_removed::<T>, resource_removed::<T> | T changed or was removed, or was removed. |
resource_equals(value), resource_exists_and_equals(value) | T equals value (T: PartialEq). |
on_message::<M> | There are messages of type M this condition hasn't seen yet. |
any_with_component::<T> | At least one entity has T. |
any_match_filter::<F> | At least one entity passes the filter F. |
any_component_removed::<T> | Some entity lost a T recently. |
in_state(state) | The state S is currently state. |
state_exists::<S>, state_changed::<S> | State S exists, or changed this frame. |
condition_changed(c), condition_changed_to(value, c) | The result of condition c flipped, or flipped to value. |
Time-based conditions live in neo::time::common_conditions:
use neo::time::common_conditions::on_timer;
use std::time::Duration;
app.add_systems(Update, autosave.run_if(on_timer(Duration::from_secs(60))));Input conditions such as input_just_pressed(KeyCode::Escape) live in neo::input::common_conditions:
use neo::input::common_conditions::input_just_pressed;
app.add_systems(Update, toggle_pause.run_if(input_just_pressed(KeyCode::Escape)));Combine conditions#
| Combinator | Runs the system when |
|---|---|
.run_if(a).run_if(b) | Both are true (each is checked). |
not(a) | a is false. |
a.and_then(b) | Both are true; b is only checked if a was true. |
a.or_else(b) | Either is true; b is only checked if a was false. |
a.and_eager(b), a.or_eager(b) | The same, but both are always checked. |
a.nand_then(b), a.nor_else(b), a.xor(b), a.xnor(b) | The other logical combinations. |
app.add_systems(
Update,
print_counter.run_if(resource_exists::<Counter>.and_then(|c: Res<Counter>| c.is_changed())),
);and_then protects the second condition: here it never reads Counter when it doesn't exist.
Conditions that take arguments#
Write a function that returns a closure:
fn time_passed(seconds: f32) -> impl FnMut(Local<f32>, Res<Time>) -> bool {
move |mut elapsed: Local<f32>, time: Res<Time>| {
*elapsed += time.delta_secs();
*elapsed >= seconds
}
}
app.add_systems(Update, show_hint.run_if(time_passed(10.0)));On sets, tuples and observers#
| Where | Effect |
|---|---|
system.run_if(c) | Gates one system. |
(a, b).run_if(c) | Checks c once and runs both or neither. |
(a, b).distributive_run_if(c) | Checks c separately before each system. |
configure_sets(Update, MySet.run_if(c)) | Gates every system in the set. |
app.add_observer(observer.run_if(c)) | Gates an observer. |
A skipped system doesn't count as having run, so its change detection and message readers pick up where they left off when it next runs.
Run conditions or early return?#
Both work. A run condition is checked before the system's parameters are fetched and can be shared between systems. An early return inside the system is fine for checks that need the system's own data.
Example: cargo run --example run_conditions, from the engine core's workspace.