Systems and events
Open the live demo · Read the source · View on GitHub
The engine's loop owns the fixed step, and a game or a plugin adds work to
it by phase without forking anything: addSystem puts a function into one
of the loop's phases (input, movers, physics, fields, rules,
publish), and the loop runs it there every step. A genre's own step is one
such system, named <genre>.step, and a game orders its rules against it by
that name.
Step 1: Add systems to a phase #
Two systems are added to the rules phase here, one that only logs and one
that raises the score. A system names the ones it runs after or before, by
name; registration order decides whatever nothing names.
final loop = EngineLoop(input: InputState());
// The bus the step publishes onto. A game's is its `EngineLoop`'s, whose
// step channel is heard at the end of the step; this page wants each
// event as it is published, so a `DirectBus`.
final events = DirectBus();
final heard = <GameEvent>[];
events.onStep<GameEvent>('step_systems.heard', (d) => heard.add(d.event));
var score = 0;
final order = <String>[];
final logging = loop.addSystem(
'logging',
LoopPhase.rules,
(LoopContext step) => order.add('logging'),
settings: const SystemSettings(after: <String>['scoring']),
);
loop.addSystem('scoring', LoopPhase.rules, (LoopContext step) {
order.add('scoring');
score += 5;
events.publish(_ScoreChanged(score));
});
Step 2: Run a step and hear its events #
runSteps runs the step's phases in order, each system of a phase in its
place. A system publishes what it did onto a bus, and whoever cares
subscribes. In a game the bus is the loop's own (LoopContext.publish), and
a step's events reach the step subscribers at the end of that step, never
across a gap where something else could have changed the world in between.
This page wants each event as it is published, so its bus is a DirectBus.
// Registered "logging" first but named to run after "scoring": the
// constraint wins, and only what nothing names falls back on
// registration.
loop.runSteps(1);
final published = List<GameEvent>.of(heard);
final firstOrder = List<String>.of(order);
Logging names scoring as the system it runs after, so scoring runs first even though logging was added first. The event it published was heard by the subscriber as it was published.
Step 3: Remove a system #
addSystem returns a registration, and cancelling it takes the system back
out. A system removed this way does not run on the next step.
// The handle `addSystem` returned removes the system again; a step run
// after that no longer calls it.
logging.cancel();
order.clear();
loop.runSteps(1);
final afterRemoval = List<String>.of(order);
Step 4: Watch the order run #
Three systems, added in one order and given another: scoring is added
first and named to run after input, and logging after both. Every
0.6 s a step runs, and each of the three slots lights in the colour of
whichever system ran in that place: blue for input, yellow for scoring,
purple for logging. Turn "scoring before input" on and scoring drops its
constraint, so registration order puts it first; un-register logging and its
slot goes dark. The yellow tower is the score that scoring keeps adding to.
final loop = EngineLoop(input: InputState());
loop.addSystem(
'scoring',
LoopPhase.rules,
(LoopContext step) {
_ran.add('scoring');
_score += 5;
},
settings: SystemSettings(
after: scoringFirst ? const <String>[] : const <String>['input'],
),
);
loop.addSystem(
'input',
LoopPhase.rules,
(LoopContext step) => _ran.add('input'),
);
if (loggingOn) {
loop.addSystem(
'logging',
LoopPhase.rules,
(LoopContext step) => _ran.add('logging'),
settings: const SystemSettings(after: <String>['scoring', 'input']),
);
}