flutter3d
Showcase Changelog 62 packages API reference

Systems and events

since 0.5.0 Simulation, audio and XR

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']),
  );
}