KernelAPI reference
Class HeadlessPlatform
Namespace: MicroEngine.Core
Assembly: MicroEngine.dll
Guide: Testing your game
A windowless platform: no devices, and a renderer that counts calls (or, with Rasterize, also records them and draws them with the CPU reference rasterizer). Used by automated tests and CI to play whole games through scripts. Its surface has the canvas’s size; tests drive its events by hand (Resize, Focus, Suspend, Resume, RequestQuit), which the next event pump delivers in order. Its run preset (Preset) is deterministic time: a stated default of this testing composition that a run or a game overrides. Nothing the platform does depends on the time mode.
public sealed class HeadlessPlatform : IPlatform, IPlatformHost, IDisposable, IScreenView, IViewCaptureInheritance
Implements
IPlatform, IPlatformHost, IDisposable, IScreenView, IViewCapture
Constructors
HeadlessPlatform(int, int)
Creates a headless platform whose renderer reports a width × height canvas.
public HeadlessPlatform(int width = 320, int height = 180)Parameters
width int
height int
Properties
Audio
The device the request supplied (Audio), otherwise SilentAudio.
public IAudioDevice Audio { get; }Property Value
CanBlock
True: tests and CI may block.
public bool CanBlock { get; }Property Value
Clipboard
The clipboard (the IClipboard capability): tests put text on it or read what was copied.
public MemoryClipboard Clipboard { get; }Property Value
Clock
A monotonic clock in seconds since the platform was created. The loop owns time: in deterministic time it never reads this clock to decide how many steps a frame runs.
public IMonotonicClock Clock { get; }Property Value
CloseRequested
Set it to true to ask the game to quit at the next event pump, as if the window’s close button was pressed; the request is delivered once while it stays true. Setting it back to false allows a later request.
public bool CloseRequested { get; set; }Property Value
Devices
The platform’s input backend (also its IInputBackend, IKeyLabels, IGamepadRumble and ITextInputControl capabilities): tests send device events with it, which the next frame routes like a real backend’s.
public HeadlessInputBackend Devices { get; }Property Value
FullscreenToggles
How many times the game asked to switch between a window and full screen (there is no window to switch).
public int FullscreenToggles { get; }Property Value
Graphics
A HeadlessGraphicsDevice: textures have a size but no pixels, unless Rasterize is on.
public IGraphicsDevice Graphics { get; }Property Value
Input
Keys, read together with the request’s extra sources (ExtraInput) when there are any.
public IInputSource Input { get; }Property Value
Keys
The input tests set by hand (keys, gamepad, pointer), read every update as one polled device.
public HeadlessInput Keys { get; }Property Value
Letterbox
The colour around the world in a capture of a frame that drew a UI (CaptureScreen); there is no window to paint.
public Color Letterbox { get; set; }Property Value
MainSurface
The surface, of the canvas’s size until Resize changes it; it has no native window.
public ISurface MainSurface { get; }Property Value
PixelDensity
Pixels per logical unit of the surface (PixelDensity): 1 by default, as a headless run has no screen. Set it when creating the platform to stand for a high-density screen: with the presentation’s UiScale unset, the UI scale follows it.
public float PixelDensity { get; init; }Property Value
Exceptions
The value is not a positive finite number.
Presentation
How the canvas is placed in the surface for the UI view’s mapping (WorldFrame): the game’s presentation when the platform was made for its settings, else PixelArt.
public Presentation Presentation { get; init; }Property Value
Preset
The run defaults this testing composition states (RunPreset, offered as a capability):
Testing by default, so a game run on it through GameRunner,
GameLoop, GameSession or InitializeForTest advances one fixed step
per frame with no option. The run’s TimeMode and the game’s Configure
win over it; Preset = new RunPreset() when creating the platform makes runs that choose nothing real-time.
The platform behaves the same either way.
public RunPreset Preset { get; init; }Property Value
Profile
The headless platform as a catalog entry (–platform headless, –headless).
public static PlatformProfile Profile { get; }Property Value
Rasterize
When true, textures keep their pixels and the renderer records each frame’s draws (Commands) and draws them on Frame with the CPU reference rasterizer, following the engine’s rendering rules; SaveScreenshot then writes that frame as a PNG (at scale 1). False by default: the renderer only counts. Set it when creating the platform.
public bool Rasterize { get; init; }Property Value
Renderer
The renderer, typed so tests can read its counters.
public HeadlessRenderer Renderer { get; }Property Value
Screenshots
Paths of the screenshots requested, in order; a file is written only when Rasterize is on.
public List<string> Screenshots { get; }Property Value
SilentAudio
The silent audio device, typed so tests can read Played.
public SilentAudioDevice SilentAudio { get; }Property Value
Suspended
Whether Suspend sent the platform to the background (until Resume).
public bool Suspended { get; }Property Value
Touch
The same screen as TouchScreen.
public ITouchScreen Touch { get; }Property Value
TouchScreen
A touch screen tests can touch; by default 4× the canvas, not touch-first, no safe-area insets. Also the host’s ITouchScreen capability.
public HeadlessTouchScreen TouchScreen { get; }Property Value
UiRenderer
The UI view’s renderer of the current frame (IScreenView): the surface’s size in UI units (pixels divided by the UI scale, UiScaleFor of PixelDensity). It counts draw calls; with Rasterize on it also draws them, and a frame that drew a UI is captured with it composited over the world (IViewCapture), each UI unit repeated over the window pixels it covers.
public HeadlessRenderer UiRenderer { get; }Property Value
Methods
BeginFrame()
Starts a frame and returns the renderer that draws into the virtual canvas.
public IRenderer BeginFrame()Returns
Dispose()
Disposes the audio device the request supplied, if any; nothing else holds resources.
public void Dispose()EndFrame()
Finishes the frame and presents it.
public void EndFrame()Focus(bool)
Gives (true) or takes (false) the input focus; the next pump delivers it when the focus changes.
public void Focus(bool focused)Parameters
focused bool
For(GameSettings)
A headless platform with the virtual size of settings.
public static HeadlessPlatform For(GameSettings settings)Parameters
settings GameSettings
Returns
For(GameSettings, bool)
A headless platform with the virtual size of settings, rasterizing when rasterize is true (see Rasterize).
public static HeadlessPlatform For(GameSettings settings, bool rasterize)Parameters
settings GameSettings
rasterize bool
Returns
For(PlatformRequest)
A headless platform for request: the virtual size of its settings, the audio device it supplies
(Audio) and its extra input sources read with Keys.
public static HeadlessPlatform For(PlatformRequest request)Parameters
request PlatformRequest
Returns
PumpEvents(IEngineEventSink)
Delivers the events the test hooks queued, in order; false while suspended.
public bool PumpEvents(IEngineEventSink sink)Parameters
sink IEngineEventSink
Returns
RequestQuit()
Asks the game to quit, as a window’s close button does; the next pump delivers the request.
public void RequestQuit()Resize(int, int)
Changes the surface’s size; the next pump delivers the resize (once, when the size changed).
public void Resize(int width, int height)Parameters
width int
height int
Resume()
Brings the platform back; the next pump delivers Resumed after a Suspending.
public void Resume()SaveScreenshot(string)
Records path in Screenshots; with Rasterize on, also writes what the
player would see there as an opaque PNG at scale 1 (CaptureScreen): the canvas, or, for
a frame that drew a UI, the surface with the UI over the world.
public void SaveScreenshot(string path)Parameters
path string
Suspend()
Sends the platform to the background, as a phone does; the next pump delivers Suspending.
public void Suspend()ToggleFullscreen()
Counts the request in FullscreenToggles: there is no window to switch.
public void ToggleFullscreen()TryGetCapability<T>(out T?)
The optional feature of type T this host offers, if it offers one.
public bool TryGetCapability<T>(out T? capability) where T : classParameters
capability T?
Returns
Type Parameters
T