KernelAPI reference
Namespace MicroEngine.Kernel
The kernel: engine composition (builder, services, modules, capabilities), the frame schedule and its phases, loop-owned time, engine events, logging and generational handles.
Guide: Modules and the frame schedule
Classes
Optional features something in the engine offers (a display that can change its mode, a touch screen, platform diagnostics), declared by whoever provides them and queried by type. A feature that is absent is simply not declared: callers ask with TryGet``1 instead of casting a platform or device to find out.
The default ILog: each message at or above MinimumLevel becomes one line
category: message on Error (read when the message is written, so a redirected stream
receives it) or on the writer it was given.
Composes an Engine: modules are added in order, each registering services, frame systems and capabilities; settings records are edited; Build then fixes the schedule and the time policy. Nothing is discovered by reflection.
The engine’s IEngineLifecycle: subscribers read it through the interface; the loop and hosts raise
the events through the Raise methods.
A composed engine: its services, its fixed frame schedule, its clock, its events and its capabilities. A loop (the game runner, a host, a test) drives it frame by frame: it advances Clock and runs the phases in order.
The loop’s clock: turns the time each frame stands for into fixed steps, following TimeSettings. The platform only supplies a monotonic clock; how much simulated time a frame adds, how many steps it runs, how far a slow frame catches up and the interpolation blend are decided here, the same way on every backend.
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.
HandlePool<T>
Items reached through generational Handle`1s: slots are reused, and a handle to a removed item is detected (stale) instead of reaching the item that took its slot.
A request to quit that came from outside the game (the window’s close button, the system), passed to QuitRequested. A handler that must keep the game running (unsaved work, a confirmation dialog) calls Veto; the game can quit later on its own.
A Random that draws exactly what new Random(seed) draws, and whose state can take part in the
per-step state hash (IStateHashed): its seed, how many values it drew and a running hash of them. Two
runs that drew the same values from the same seed hash the same; one extra or different draw changes the hash.
The engine’s services, one instance per type, registered by modules and read by whoever needs them. Typed and explicit: a service is found by the exact type it was registered as (no base classes, no interfaces it also implements), nothing is created on demand and nothing is discovered by reflection, so the registry works the same under trimming, NativeAOT and WebAssembly.
Where two traces first differ (FirstDivergence).
Accumulates a 64-bit hash (FNV-1a) of simulation state in named sections. Values are encoded in a fixed binary form
(little-endian; floats by their bits, so -0 and NaN payloads count; strings length-prefixed), so the same
values in the same order give the same hash on every machine and run. Nothing is read by reflection: the engine and
the game add what they choose (IStateHashed).
A run’s per-step state hashes: the loop records one StepHash after every fixed step when a run is given
one (RunOptions.StateTrace). Two runs of the same build, script and seed must record the same trace;
FirstDivergence names the first update and section where two differ.
The state hash after one fixed step.
The loop’s time policy: the fixed simulation rate, how far a slow frame may catch up, and whether time follows the wall clock. Every value is explicit; nothing is derived from the platform or from other options.
Structs
What a frame system knows about time when it runs (FrameSchedule).
Handle<T>
A reference to an item of a HandlePool`1: a slot index and the generation of the item that held the
slot when the handle was made. When the item is removed its slot’s generation changes, so an old handle no longer
finds anything (instead of finding whatever reuses the slot). default is None.
The hash of one named part of the state of a step (Sections).
The new size of the drawing surface, in pixels (Resized).
Interfaces
Engine events: the things that happen to a running game from outside its simulation. Raised on the game’s thread, between frames (before the frame that follows them), in the order they happened; handlers run in the order they subscribed.
A part of the engine or of a game that registers itself: services, frame systems, capabilities, settings and lifecycle handlers, all from Configure. Rendering, input, audio, scenes and the game itself are modules.
Where the engine’s diagnostics go. The default (ConsoleLog) writes them to the standard error stream; a host that has its own (a phone’s system log, a browser console, an editor panel) registers another sink as the engine’s ILog service.
Something whose simulation state takes part in the per-step state hash (StateHasher): it adds the values that decide what the game does next, and leaves out what only drawing uses.
Enums
The phases of a frame, in the order they run. The four fixed phases (PreFixed, FixedUpdate, Physics, PostFixed) run once per fixed step, zero or more times a frame as time calls for (TimeSettings); every other phase runs once per frame.
How important a log message is.
How the loop advances time (Mode).