systems/phases_and_order

Goal

Understand how SystemPipeline sorts systems by (phase, order, name) and see the execution order visualized on screen.

Why this tutorial exists

The system pipeline is the backbone of per-frame simulation. Each system declares a SystemPhase and an order integer. The pipeline auto-sorts them so that:

  • INPUT systems run first

  • CONTROL systems run second

  • SIMULATION systems run third

  • PRESENTATION systems run fourth

  • RENDERING systems run last

Within a phase, lower order values run first. Ties are broken by name.

This example creates 10 randomly shuffled systems spanning all five phases and renders a timeline showing their actual execution order.

Source map

  • Settings profile: examples/settings/systems/phases_and_order.yml

  • Example builder: examples/catalog/systems/phases_and_order/main.py

  • Scene: examples/catalog/systems/phases_and_order/scenes/scene.py

  • Shared runner: examples/_shared/runner.py

What to verify

You should see:

  1. a vertical list of 10 systems with phase labels and order numbers

  2. each system lights up briefly when it runs during the frame

  3. the order is always sorted: INPUT → CONTROL → SIMULATION → PRESENTATION → RENDERING

Behavior checks:

  • reloading the scene keeps the same sorted order (deterministic)

  • the phase colors match the legend at the top

  • systems within the same phase appear in ascending order

Run

mini-arcade run --example systems/phases_and_order
mini-arcade run --example systems/phases_and_order --pass-through --backend pygame
mini-arcade run --example systems/phases_and_order --pass-through --backend native

Common mistakes

  • Assuming systems run in registration order — they don’t, the pipeline sorts them.

  • Setting order to the same value for two systems and being surprised by alphabetical tiebreaking.

  • Putting rendering logic in a SIMULATION-phase system — it will run before the render phase.

Next step