Schedules
The schedules that make up a frame, Startup, Update, FixedUpdate and the rest, which one to put a system in, and how to add and run your own.
On this page
A schedule is a set of systems that runs together, with their order and run conditions. When you call add_systems(Update, my_system), Update is the schedule. Each frame the app runs one schedule, Main, which runs the others in a fixed order.
The frame#
The first time Main runs, it runs the startup schedules once:
| Order | Schedule | Use it for |
|---|---|---|
| 1 | StateTransition | Entering the initial state, so OnEnter of a starting state runs before PreStartup. |
| 2 | PreStartup | Setup other startup systems depend on. |
| 3 | Startup | Your setup: spawning the camera, the level, the player. |
| 4 | PostStartup | Work that needs what Startup spawned. |
Then, every frame:
| Order | Schedule | What runs there |
|---|---|---|
| 1 | First | Frame bookkeeping: time is updated, message buffers swap. |
| 2 | PreUpdate | Engine preparation: input from the window and devices is collected. |
| 3 | StateTransition | Pending state changes apply, with their OnExit, OnTransition and OnEnter schedules. |
| 4 | RunFixedMainLoop | Runs the fixed-timestep schedules zero or more times (below). |
| 5 | Update | Most of your game logic that runs once per frame. |
| 6 | SpawnScene | Scenes queued for spawning are spawned. |
| 7 | PostUpdate | Engine responses to Update: transform propagation, animation, UI layout, visibility. |
| 8 | Last | End-of-frame work. |
Rendering isn't in this list. It runs in a separate render world that copies what it needs from the main world after Main, and on the desktop draws the frame while the next one is being simulated.
The fixed-timestep schedules#
RunFixedMainLoop runs FixedMain as many times as fixed steps fit into the time that passed: none on some frames, several on others. FixedMain runs these in order:
| Schedule | Use it for |
|---|---|
FixedFirst | Fixed-step bookkeeping. |
FixedPreUpdate | Preparation before gameplay. |
FixedUpdate | Gameplay that should run at a steady rate: movement, physics, AI, game rules, networking. |
FixedPostUpdate | Responses to FixedUpdate, such as resolving physics. |
FixedLast | End of the fixed step. |
The fixed step is 64 Hz by default. Inside these schedules, Res<Time> gives the fixed step's time. See Fixed timestep for changing the rate and smoothing motion between steps.
Which schedule to use#
| Put it in | When the system |
|---|---|
Startup | sets things up once. |
Update | runs once per rendered frame: input handling, UI, camera, audio, visual effects. |
FixedUpdate | needs the same result whatever the frame rate: movement, physics, timers that affect gameplay, networking. |
PostUpdate | must run after the engine's own Update work, for example reading final GlobalTransforms. Order it against the engine's system sets. |
OnEnter(state), OnExit(state) | sets up or tears down a state. |
Ordering inside a schedule#
A schedule decides the order of its systems from the constraints you give it (before, after, chain, sets) and otherwise runs them in parallel where it can. See System ordering and sets. Between schedules the order is always the table above: every PreUpdate system finishes before any Update system starts.
Custom schedules#
Define a label, add the schedule, and place it in the frame with MainScheduleOrder:
use neo::{app::MainScheduleOrder, ecs::schedule::ScheduleLabel, prelude::*};
#[derive(ScheduleLabel, Debug, Hash, PartialEq, Eq, Clone)]
struct AfterUpdate;
fn main() {
let mut app = App::new();
app.add_plugins(DefaultPlugins);
app.add_schedule(Schedule::new(AfterUpdate));
app.world_mut()
.resource_mut::<MainScheduleOrder>()
.insert_after(Update, AfterUpdate);
app.add_systems(AfterUpdate, || info!("after Update"));
app.run();
}Method on MainScheduleOrder | Places the schedule |
|---|---|
insert_after(existing, new), insert_before(existing, new) | In the per-frame list. |
insert_startup_after(existing, new), insert_startup_before(existing, new) | In the startup list. |
Change MainScheduleOrder while building the app, not from a system: it can't change while Main is running.
A schedule doesn't have to be in the frame at all. You can run one yourself from an exclusive system or a command:
fn run_cleanup(world: &mut World) {
world.run_schedule(AfterUpdate);
}
fn queue_cleanup(mut commands: Commands) {
commands.run_schedule(AfterUpdate);
}Schedule settings#
app.edit_schedule(label, |schedule| ..) changes how a schedule is built:
use neo::ecs::schedule::{LogLevel, ScheduleBuildSettings, SingleThreadedExecutor};
app.edit_schedule(Update, |schedule| {
// warn about systems that conflict but have no order between them
schedule.set_build_settings(ScheduleBuildSettings {
ambiguity_detection: LogLevel::Warn,
..default()
});
});
let mut schedule = Schedule::new(AfterUpdate);
schedule.set_executor(SingleThreadedExecutor::new()); // never run its systems in parallel
app.add_schedule(schedule);Examples#
Run these from the engine core's workspace:
| Example | What it shows |
|---|---|
cargo run --example custom_schedule | Custom per-frame and startup schedules, and a single-threaded executor. |
cargo run --example fixed_timestep | Systems in FixedUpdate and changing the step. |
cargo run --example nondeterministic_system_order | Finding and fixing systems whose order is ambiguous. |