KernelAPI reference
Class FrameSchedule
Namespace: MicroEngine.Kernel
Assembly: MicroEngine.Kernel.dll
Guide: Modules and the frame schedule
The systems that run each frame: named callbacks placed in a FramePhase, run in phase order. Within a phase, systems run in the order they were added unless a system asks to run after or before another one of the same phase; the order is resolved once, when the engine is built, and a cycle of such constraints is an error that names the systems in it.
public sealed class FrameScheduleInheritance
Remarks
Modules add systems while the engine is configured (EngineBuilder); once it is built the schedule is fixed and adding, replacing or removing a system throws. Running it allocates nothing.
Constructors
FrameSchedule()
public FrameSchedule()Properties
Count
The number of systems scheduled.
public int Count { get; }Property Value
IsFrozen
Whether the schedule is fixed (the engine was built): it can run but no longer change.
public bool IsFrozen { get; }Property Value
MeasureTime
Whether Run measures how long each system takes (Times). Off by default: a schedule that does not measure takes no timestamps. It may change once the schedule is frozen, since it changes no system.
public bool MeasureTime { get; set; }Property Value
Exceptions
Turning it on when the order cannot be resolved (see Order).
Methods
Add(FramePhase, string, Action<FrameContext>, string?, string?)
Schedules run in phase under name, optionally after or
before another system of the same phase.
public FrameSchedule Add(FramePhase phase, string name, Action<FrameContext> run, string? after = null, string? before = null)Parameters
phase FramePhase
The phase it runs in.
name string
A name unique in the whole schedule, such as “engine.scenes” or “mygame.camera”.
run Action<FrameContext>
The system; it receives the frame’s FrameContext.
after string?
The name of a system of the same phase this one must run after, or null.
before string?
The name of a system of the same phase this one must run before, or null.
Returns
This schedule, to chain calls.
Remarks
Constraints naming a system that does not exist, or one in another phase, are reported when the engine is built.
Exceptions
name is empty, or a system with that name is already scheduled.
run is null.
phase is not a FramePhase.
The schedule is frozen.
Contains(string)
Whether a system named name is scheduled.
public bool Contains(string name)Parameters
name string
Returns
Freeze()
Resolves the order and fixes the schedule; the engine does this when it is built.
public void Freeze()Exceptions
The order cannot be resolved (see Order).
IsFixed(FramePhase)
Whether phase runs once per fixed step (PreFixed to PostFixed) rather than once per frame.
public static bool IsFixed(FramePhase phase)Parameters
phase FramePhase
Returns
Order(FramePhase)
The names of the systems of phase in the order they run, resolving the order if needed.
public IReadOnlyList<string> Order(FramePhase phase)Parameters
phase FramePhase
Returns
Exceptions
A constraint names a missing system or one in another phase, or the constraints form a cycle.
PhaseOf(string)
The phase of the system name, or null when there is none.
public FramePhase? PhaseOf(string name)Parameters
name string
Returns
Remove(string)
Removes the system name; false when there was none. Constraints of other systems that name it then fail when the engine is built.
public bool Remove(string name)Parameters
name string
Returns
Exceptions
The schedule is frozen.
Replace(string, Action<FrameContext>)
Replaces what the system name runs, keeping its phase and order: the way to substitute a built-in system.
public FrameSchedule Replace(string name, Action<FrameContext> run)Parameters
name string
run Action<FrameContext>
Returns
Exceptions
No system is named name.
run is null.
The schedule is frozen.
ResetTimes()
Sets every measured time (Times) back to zero; the loop does it at the start of each frame.
public void ResetTimes()Run(FramePhase, in FrameContext)
Runs the systems of phase, in order, with context.
public void Run(FramePhase phase, in FrameContext context)Parameters
phase FramePhase
context FrameContext
Remarks
An exception thrown by a system stops the phase and reaches the caller.
Exceptions
The order cannot be resolved (see Order).
Times(FramePhase)
The milliseconds each system of phase took since the last ResetTimes, aligned with
Order: a fixed phase adds up every step it ran. All zero while MeasureTime was off.
public ReadOnlySpan<double> Times(FramePhase phase)Parameters
phase FramePhase
Returns
Exceptions
The order cannot be resolved (see Order).