13 · Scheduler¶
What it is¶
The scheduler decides when each system runs: in which phase of the frame, in which order inside the phase, how many times (fixed timestep), and whether it runs at all (run conditions and game states).
Why we need it¶
- R1: with the ECS owning the loop, the scheduler is the frame: poll the window, run gameplay, send network packets, draw.
- R3: the simulation must advance in fixed ticks (60 per second), independent of the frame rate, so server and clients count ticks the same way.
- R4: games add systems from many plugins; explicit ordering keeps that predictable.
How others do it¶
| ECS | Scheduling |
|---|---|
| Bevy | Schedules (Startup, PreUpdate, FixedUpdate, Update, PostUpdate), system sets, before / after, run conditions, States with OnEnter / OnExit, automatic parallelism |
| flecs | Pipelines of phases (OnLoad, PreUpdate, OnUpdate, PostUpdate, OnStore), multithreading |
| Unity DOTS | System groups with UpdateBefore / UpdateAfter, fixed-step group |
| Unreal Mass | Processing phases and execution groups with ordering |
Our choice¶
Bevy's model, in two steps: phases + ordering + fixed timestep in v1, run conditions + States in v2. Sequential execution first; access sets are recorded from the start so a parallel version can come later.
How it works¶
Phases¶
flowchart LR
startup(["Startup<br/>(once)"]) --> pre
pre["PreUpdate<br/>poll window, input,<br/>network receive"] -- "flush" --> fixed
fixed[["FixedUpdate × N<br/>gameplay, Luau systems,<br/>physics, network send (server)"]] -- "flush" --> update
update["Update<br/>animation, camera, UI"] -- "flush" --> post
post["PostUpdate<br/>transform propagation,<br/>input send (client)"] -- "flush" --> render
render["Render<br/>extract + draw"] --> pre
Commands are flushed after each phase. The dedicated server runs only PreUpdate,
FixedUpdate and PostUpdate.
Fixed timestep¶
flowchart TD
frame["New frame"] --> add["accumulator += frame delta"]
add --> count["ticks = accumulator / fixedDelta"]
count --> cap{"ticks ≥ cap (5)?"}
cap -- "yes" --> drop["ticks = cap<br/>drop the time beyond it"]
cap -- "no" --> keep["accumulator -= ticks × fixedDelta"]
drop --> run
keep --> run["Run FixedUpdate ticks times<br/>after each: its event queues move forward, tick + 1"]
run --> alpha["alpha = accumulator / fixedDelta<br/>(for render interpolation)"]
alpha --> rest["Update, PostUpdate, Render<br/>then every other event queue moves forward"]
A slow frame runs FixedUpdate several times; a fast one may run it zero times. A cap on ticks per frame
avoids the "spiral of death" when the machine cannot keep up: the time beyond it is dropped, so the game
slows down instead of spending ever longer catching up.
rtype::ecs::FixedTimestep (time/FixedTimestep.hpp) is the accumulator. It belongs to the time plugin
(time/TimePlugin.hpp), which every App has: if none was added, the App adds one with the defaults before its
first frame (App and plugins). Adding one yourself configures it:
app.addPlugin(rtype::ecs::TimePlugin{rtype::ecs::FixedTimestep{30, 5}}); // 30 ticks per second, at most 5 per frame
app.addPlugin(rtype::ecs::TimePlugin::manual(std::chrono::milliseconds{16})); // tests: every frame lasts 16 ms
The default is 60 ticks per second, at most 5 per frame. The accumulator counts in integers (nanoseconds × ticks per second, so one tick is exactly 10^9 units at any rate): every machine counts the same ticks for the same frame times, and 60 Hz gives exactly 60 ticks per second, with no float drift and no rounding of 1/60 s. With the defaults, 5 ms frames run a tick every 3 or 4 frames, 16 ms frames almost one per frame, and 50 ms frames 3 per frame.
The time plugin inserts the Time resource (time/Time.hpp, "rtype.Time"), and its clock keeps it up to
date:
| Field | Meaning | Set |
|---|---|---|
delta |
the last frame's duration, in seconds (a negative frame counts as 0) | before PreUpdate (and Startup on the first frame) |
fixedDelta |
one fixed tick, in seconds (1/60 by default): what FixedUpdate systems multiply by |
before PreUpdate |
tick |
fixed ticks completed since the start; while FixedUpdate runs, the current tick (0, 1, 2...) |
after each FixedUpdate |
alpha |
how far the frame is into the next tick, in [0, 1): to interpolate what is drawn | before Update |
void movement(rtype::ecs::Query<Position, const Velocity> query, rtype::ecs::Res<rtype::ecs::Time> time) {
for (auto [entity, position, velocity] : query) {
position->x += velocity.x * time->fixedDelta;
}
}
Event queues move forward with the phase that writes them (Events). When a schedule
is built, it lists the events written (EventWriter) by its systems that run in this mode. The queues of
those written in FixedUpdate move forward after each fixed tick, so their events are readable for two fixed
ticks. Every other queue (written in another phase, or from outside the systems: platform, network, Luau)
moves forward at the end of the frame, so its events are readable for two frames.
The frame and its clock¶
The schedules run the frame; a frame clock (schedule/FrameClock.hpp) decides how many fixed ticks it
has. The schedules know nothing about time: the time plugin installs its clock (time/TimeClock.hpp), and
tests install one that returns the ticks they want.
class FrameClock {
public:
virtual std::uint32_t startFrame(World& world) = 0; // first thing of a frame: measure it, return the ticks
virtual void finishFixedTick(World& world) = 0; // after each FixedUpdate (and its event queues)
virtual void startUpdate(World& world) = 0; // after the fixed ticks, before Update
};
Schedules::runFrame(), called once per frame by the App:
flowchart TD
build["Build the schedules that changed<br/>(a bad schedule throws before the frame starts)"] --> start
start["ticks = clock.startFrame()"] --> startup["Startup (first frame only)"]
startup --> pre["PreUpdate"]
pre --> fixed{"ticks left?"}
fixed -- "yes" --> tick["FixedUpdate<br/>its event queues move forward<br/>clock.finishFixedTick()"]
tick --> fixed
fixed -- "no" --> update["clock.startUpdate()<br/>Update, PostUpdate, Render"]
update --> events["every other event queue moves forward"]
TimeClock measures std::chrono::steady_clock (the first frame counts 0) or uses the fixed duration of a
manual plugin, runs the fixed timestep on it and writes Time. Without a clock, FixedUpdate never runs.
Pausing. A tool (the editor, docs/Editor.md) freezes the gameplay with Schedules::setPaused(true): a paused frame
runs Startup, PreUpdate, PostUpdate and Render, but neither FixedUpdate nor Update, so the events still come in, what
follows the gameplay (global transforms, animations, particles) and the drawing still run, and the gameplay does not
move. The clock still measures the frame (Time::delta keeps its value) and the ticks it counted are dropped, so
resuming does not catch up. Schedules::step() makes the next paused frame run whole, with exactly one fixed tick. A
game's own pause menu is gameplay, not this.
Ordering inside a phase¶
app.addSystem(rtype::ecs::Phase::kFixedUpdate, "rtype.movement", &movement);
app.addSystem(rtype::ecs::Phase::kFixedUpdate, "rtype.collision", &detectCollisions).after("rtype.movement");
app.addSystem(rtype::ecs::Phase::kFixedUpdate, "rtype.damage", &applyDamage).after("rtype.collision");
Systems live in one Schedule per phase (schedule/Schedule.hpp): a schedule orders, checks and runs
the systems of its phase. A world's six schedules, the frame and its clock are held by Schedules
(schedule/Schedules.hpp), which the App owns: one App has one world, one Schedules and one run mode.
Systems are added through Schedules (the App forwards app.addSystem to it), which checks that a name is
used in no other phase before handing the system to the phase's schedule. Without an App, tests use them
directly:
rtype::ecs::Schedules schedules{world, rtype::ecs::RunMode::kStandalone};
schedules.addSystem(rtype::ecs::Phase::kFixedUpdate, "rtype.movement", &movement);
schedules.addSystem(rtype::ecs::Phase::kFixedUpdate, "rtype.collision", &detect).after("rtype.movement");
schedules.addSystem(rtype::ecs::Phase::kUpdate, "rtype.camera", &follow).setSide(rtype::ecs::Side::kClient);
schedules.build(); // checks and sorts every schedule
schedules.run(rtype::ecs::Phase::kFixedUpdate); // one phase: its systems, then their commands
schedules.runFrame(); // a whole frame (above)
schedules.getOrder(rtype::ecs::Phase::kFixedUpdate);
The schedules are keyed by Phase for now; named schedules (States' OnEnter / OnExit) come with v2.
When a schedule is built (by build(), or before it runs after a change), the before / after
constraints of its systems become a graph (detail::DependencyGraph) that is sorted topologically. Systems with no order between them run by name, so the order depends only on names and
constraints, never on the order plugins added the systems.
Adding a system whose name is already used, in any phase, throws a ScheduleException naming it and both
phases; the system is not added. Building throws one naming the systems involved for:
| Problem | Message names |
|---|---|
before / after naming a system that is not in the same phase (unknown, or in another phase) |
the system, the target and the phase: only systems of one phase can be ordered |
| A cycle of constraints | the systems of the cycle, 'a' -> 'b' -> 'c' -> 'a' |
| Two systems with conflicting access and no order (direct or through other systems) | every such pair, in name order, and the component, resource or event they share |
Access conflicts: one system writes a type the other reads or writes (two readers never conflict). Every system is checked whatever the run mode, so a schedule that builds on the server also builds on clients (standalone runs both kinds together).
In a kStandalone schedule, a server-side system and a client-side system that conflict are not an error: the one world
is the server's and the client's, so the scheduler orders the server's system first, as a client sees what the server did
over the network (unless the game ordered them itself). Pairs on the same side, or on both, still need an order.
Running a phase¶
Schedule::run() (or Schedules::run(phase)) runs the phase's systems in order, skipping those whose side
does not run in the process's RunMode (kServer: server and both; kClient: client and both;
kStandalone: everything). Then it flushes the commands of those systems, in the same order: a system's
structural changes are visible from the next phase, never to the other systems of its own phase.
Run conditions (v2)¶
app.addSystem(rtype::ecs::Phase::kFixedUpdate, "game.spawnWaves", &spawnWaves)
.runIf(&rtype::ecs::inState<GamePhase::kPlaying>);
A run condition is a small read-only function evaluated before the system; if it returns false the
system is skipped (its lastRun does not move).
States (v2)¶
A State<T> resource holds the current value of a game-flow enum; changing it runs the OnExit systems
of the old value and the OnEnter systems of the new one, at a defined point of the frame.
stateDiagram-v2
[*] --> Menu
Menu --> Lobby: host or join
Lobby --> Playing: all players ready
Playing --> GameOver: all ships destroyed
GameOver --> Lobby: retry
app:state("game.Phase", { "Menu", "Lobby", "Playing", "GameOver" })
local SpawnFirstWave = ecs.system("game.SpawnFirstWave", { onEnter = { "game.Phase", "Playing" } })
On the server, each room's world has its own state, which is how lobby → game → game over is handled per room.
Parallelism (later)¶
Each system's access set (reads/writes per component and resource, main-thread flag) is known. A parallel scheduler can run systems of the same phase concurrently when their access sets do not conflict and no ordering constraint links them. Nothing in the systems changes.
Connections¶
- Uses: Systems (access sets, sides), Commands (flushes),
Resources (
Time,State<T>, main-thread flags). - Used by: App and plugins (owns the
Schedulesand runs a frame untilAppExit; the time plugin installs the frame clock).
Appending to a resource¶
Two systems writing the same resource must be ordered, as their result could depend on who runs first. A queue that
several plugins fill is the exception: the order of the additions does not matter, and ordering each plugin against the
others would make them require each other. A system takes such a resource as a ResAppend<T>:
void drawTexts(rtype::ecs::ResAppend<rtype::plugins::graphics::SpriteQueue> queue) { queue->push(layer, text); }
Two systems appending to it need no order. A system that reads it or writes it any other way still does, so the system
that empties the queue stays ordered against every system that fills it, and forgetting that order is refused when the
schedule is built. The scheduler cannot check what -> is used for: a ResAppend must only add, and the result must
not depend on the order of the additions.
Pitfalls¶
- Gameplay in
Update. Anything that affects the simulation belongs inFixedUpdate;Updateruns at the frame rate, which differs per machine. - Implicit order. Relying on registration order works until a plugin is added. Declare
after. - Too many phases. Prefer ordering inside a phase over inventing new phases.
- Reading
FixedUpdateevents inUpdate. Their queues move forward once per fixed tick, so a frame that runs 3 ticks or more drops the events of its first tick beforeUpdateruns. Read them inFixedUpdate. - Frame time in gameplay.
deltachanges with the frame rate: gameplay usesfixedDelta.
Open questions¶
- Fixed tick rate for R-Type: 60 Hz, or 30 Hz to halve network traffic? (Team) The default is 60 Hz;
setFixedTimestep()changes it.