PlatformAPI reference
Class LaunchRequest
Namespace: MicroEngine.Hosting
Assembly: MicroEngine.Hosting.dll
Guide: Composing a game for every platform
What one launch of a game asks for, whichever host received it: a desktop command line (Parse), a browser page’s query string, a phone’s launch extras or a test. Every host turns its input into this record and hands it to the same launcher model, so the rules that follow from it are written once: a run with a script is in deterministic time unless Time says otherwise (EffectiveTime) and has seed 1 unless Seed says otherwise (ResolveSeed).
public sealed record LaunchRequest : IEquatable<LaunchRequest>Inheritance
Implements
Remarks
Options that name a value of a module the hosting layer does not know (the GPU, the window mode, where sound may go) are kept as the words of the command line, already checked against the words allowed; the engine maps them to its own types.
Constructors
LaunchRequest()
public LaunchRequest()Fields
HeadlessName
The name of the windowless platform –headless stands for.
public const string HeadlessName = "headless"Field Value
Usage
The one-line usage text desktop launchers print after an argument error.
public const string Usage = "Usage: [--script FILE] [--captures DIR] [--platform NAME] [--list-platforms] [--headless] [--hidden] [--time realtime|deterministic] [--frames N] [--seed N] [--scale N] [--mute] [--report] [--audio auto|device|silent] [--audio-capture FILE] [--gpu auto|high-performance|power-saving] [--renderer NAME[,NAME...]] [--graphics NAME] [--vsync on|off] [--fps-limit N] [--window windowed|fullscreen|exclusive] [--display N] [--pacing display|measured] [--profile FILE] [--state-trace FILE]"Field Value
Properties
Audio
–audio: where sound may go, one of AudioWords (“auto” by default).
public string Audio { get; init; }Property Value
AudioCapturePath
–audio-capture: the WAV file to write what would have been heard to, or null.
public string? AudioCapturePath { get; init; }Property Value
AudioWords
The words Audio accepts.
public static IReadOnlyList<string> AudioWords { get; }Property Value
CaptureDirectory
–captures: where script captures are written (“captures” by default).
public string CaptureDirectory { get; init; }Property Value
Display
–display: the display to open on, counted from 0, or null to keep the game’s choice.
public int? Display { get; init; }Property Value
int?
EffectiveTime
The time mode the run asks the loop for: Time when given, else Deterministic for a run with a script, else null (the game’s choice, then the composition’s preset, then real time). The rule is the same on every host: a scripted run in a browser or on a phone advances one fixed step per frame exactly as on desktop, so its captures are reproducible.
public TimeMode? EffectiveTime { get; }Property Value
FrameRateLimit
–fps-limit: the frame limit (0 for none), or null to keep the game’s choice.
public int? FrameRateLimit { get; init; }Property Value
int?
Frames
–frames: stop after this many updates; 0 (the default) runs until the game quits.
public long Frames { get; init; }Property Value
Gpu
–gpu: one of GpuWords, or null to keep the game’s choice.
public string? Gpu { get; init; }Property Value
GpuWords
The words Gpu accepts.
public static IReadOnlyList<string> GpuWords { get; }Property Value
Graphics
–graphics: the graphics device to draw with (“sdl-renderer”, “sdl-gpu”…), or null to keep the game’s choice.
public string? Graphics { get; init; }Property Value
HasScript
Whether the run plays an input script.
public bool HasScript { get; }Property Value
Headless
–headless: run without a window, the same as –platform headless.
public bool Headless { get; init; }Property Value
Hidden
–hidden: render into a hidden window; it implies nothing about time or sound.
public bool Hidden { get; init; }Property Value
IsDeterministic
Whether the run asks for deterministic time (EffectiveTime).
public bool IsDeterministic { get; }Property Value
ListPlatforms
–list-platforms: print the host’s platforms and exit.
public bool ListPlatforms { get; init; }Property Value
Mute
–mute: no sound.
public bool Mute { get; init; }Property Value
PaceToDisplay
–pacing: false for measured, true (the default) for display.
public bool PaceToDisplay { get; init; }Property Value
Platform
–platform: the platform profile to run on, or null to let the host choose.
public string? Platform { get; init; }Property Value
ProfilePath
–profile: the file to write frame measurements to, or null to measure nothing.
public string? ProfilePath { get; init; }Property Value
Renderers
–renderer: graphics APIs to try first, or null to keep the game’s choice.
public IReadOnlyList<string>? Renderers { get; init; }Property Value
Report
–report: print the platform that runs and whether it has audio before the game starts.
public bool Report { get; init; }Property Value
Scale
–scale: the window scale, or null for the game’s.
public int? Scale { get; init; }Property Value
int?
ScriptName
The script’s name for messages: the file name of ScriptPath, or the one the host gave with ScriptText.
public string? ScriptName { get; init; }Property Value
ScriptPath
–script: the input script file to read, or null. Hosts that hold the text itself use ScriptText.
public string? ScriptPath { get; init; }Property Value
ScriptText
The input script’s text, for hosts that receive it rather than a file (a browser page, a phone’s bundled script); wins over ScriptPath.
public string? ScriptText { get; init; }Property Value
Seed
–seed: the seed of the game’s randomness, or null for ResolveSeed’s rule.
public int? Seed { get; init; }Property Value
int?
StateTracePath
–state-trace: the file to write the run’s per-step state hashes to, one line per fixed step with the hash
of each section (the kernel’s StateTrace text format), or null to hash nothing.
public string? StateTracePath { get; init; }Property Value
Time
–time: how the loop advances time, or null to leave it to EffectiveTime’s rule.
public TimeMode? Time { get; init; }Property Value
VSync
–vsync: on or off, or null to keep the game’s choice.
public bool? VSync { get; init; }Property Value
bool?
Window
–window: one of WindowWords, or null to keep the game’s choice.
public string? Window { get; init; }Property Value
WindowWords
The words Window accepts.
public static IReadOnlyList<string> WindowWords { get; }Property Value
Methods
<Clone>$()
public LaunchRequest <Clone>$()Returns
Equals(object?)
public override bool Equals(object? obj)Parameters
obj object?
Returns
Equals(LaunchRequest?)
public bool Equals(LaunchRequest? other)Parameters
other LaunchRequest?
Returns
GetHashCode()
public override int GetHashCode()Returns
Parse(IReadOnlyList<string>, Func<string, bool>?)
Parses a desktop command line (the options of Usage). A script file must exist when
fileExists (by default Exists) says so.
public static LaunchRequest Parse(IReadOnlyList<string> args, Func<string, bool>? fileExists = null)Parameters
args IReadOnlyList<string>
fileExists Func<string, bool>?
Returns
Exceptions
An argument is unknown, misses its value or has an invalid one, –headless contradicts –platform, or the script file does not exist.
ResolveSeed(int)
The seed of the run: Seed when given, else 1 for a run with a script, else clockSeed.
public int ResolveSeed(int clockSeed)Parameters
clockSeed int
Returns
ToString()
public override string ToString()Returns
Operators
operator ==(LaunchRequest?, LaunchRequest?)
public static bool operator ==(LaunchRequest? left, LaunchRequest? right)Parameters
left LaunchRequest?
right LaunchRequest?
Returns
operator !=(LaunchRequest?, LaunchRequest?)
public static bool operator !=(LaunchRequest? left, LaunchRequest? right)Parameters
left LaunchRequest?
right LaunchRequest?