System ordering and sets
Order systems with before, after and chain, group them in system sets, order against the engine's sets, and find ambiguous orderings.
On this page
Inside a schedule, systems run in parallel where their data access allows it, and otherwise in an order the engine picks. That order is not guaranteed and can change from run to run. When one system must see what another did this frame, say so.
before, after and chain#
use neo::prelude::*;
fn read_input() {}
fn move_player() {}
fn move_camera() {}
fn check_win() {}
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(
Update,
(
read_input,
move_player.after(read_input),
move_camera.after(move_player),
check_win.before(move_camera),
),
)
.run();
}(a, b, c).chain() is shorthand for "a, then b, then c":
app.add_systems(Update, (read_input, move_player, move_camera).chain());Ordering only constrains when a system starts. Systems that aren't ordered relative to each other still run in parallel when they can.
| Method | Meaning |
|---|---|
a.before(b), a.after(b) | Order two systems, or a system and a set. Commands from the earlier one are applied first. |
(a, b, c).chain() | Each runs after the previous one. |
a.before_ignore_deferred(b), after_ignore_deferred, chain_ignore_deferred() | The same order, without applying commands in between. |
a.before_weak(b), after_weak, chain_weak() | Order only the systems whose data access actually conflicts; the rest stay free to run in any order. |
a.ambiguous_with(b), ambiguous_with_all() | Declare that the order doesn't matter, to silence ambiguity warnings. |
Commands and sync points#
When a system with commands is ordered before another system, the engine inserts an ApplyDeferred sync point between them, so the later system sees the spawned entities and inserted components. Sync points briefly stop parallelism, so the _ignore_deferred variants exist for edges where the later system doesn't need those changes yet.
System sets#
A system set is a label for a group of systems. Configure the set once, and every system in it follows:
#[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
enum GameplaySet {
Input,
Movement,
Combat,
}
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.configure_sets(
Update,
(GameplaySet::Input, GameplaySet::Movement, GameplaySet::Combat).chain(),
)
.add_systems(Update, read_input.in_set(GameplaySet::Input))
.add_systems(Update, (move_player, move_enemies).in_set(GameplaySet::Movement))
.add_systems(Update, (deal_damage, check_deaths).chain().in_set(GameplaySet::Combat))
.run();
}- A system can be in any number of sets, and sets can be in other sets.
- Sets can have ordering and run conditions:
configure_sets(Update, GameplaySet::Combat.run_if(in_state(GameState::Playing)))gates every system in the set. - Sets are per schedule: configure them in each schedule you use them in.
- Plugins expose their sets so you can order your systems against theirs without naming their private systems.
Ordering against the engine#
The engine's plugins put their systems in public sets. Order against those, not against individual engine systems:
| Set | Schedule | What's in it |
|---|---|---|
TransformSystems::Propagate | PostUpdate | Computing GlobalTransform from Transform down the hierarchy. |
neo::app::AnimationSystems | PostUpdate | Applying animations. |
neo::ui::UiSystems::Layout | PostUpdate | UI layout. |
RunFixedMainLoopSystems::BeforeFixedMainLoop, AfterFixedMainLoop | RunFixedMainLoop | Per-frame work just before or after the fixed steps. |
StateTransitionSystems | StateTransition | The phases of a state change. |
// read the final world positions after this frame's propagation
app.add_systems(PostUpdate, follow_target.after(TransformSystems::Propagate));Finding ordering bugs#
Two systems that touch the same data with no order between them are ambiguous: the result may change from run to run. Ambiguity detection is off by default. Turn it on for a schedule while you debug:
use neo::ecs::schedule::{LogLevel, ScheduleBuildSettings};
app.edit_schedule(Update, |schedule| {
schedule.set_build_settings(ScheduleBuildSettings {
ambiguity_detection: LogLevel::Warn,
..default()
});
});Each reported pair needs either an order (before, after, chain) or ambiguous_with if the order truly doesn't matter.
Run cargo run --example nondeterministic_system_order from the engine core's workspace to see this in action, and cargo run --example ecs_guide for chained sets in a small game.