Skip to content
MicroEngineDemosRoadmap

KernelAPI reference

Class GameLauncher

Namespace: MicroEngine.Core
Assembly: MicroEngine.dll
Guide: Configuration and launch options

The command line every desktop game accepts, on any backend: a thin caller of the launcher model every host shares (GameHost, LaunchRequest). Supported arguments:

  • --script FILE play scripted input (see [InputScript](/docs/api/microengine.core.inputscript/)); implies deterministic time unless --time says otherwise.
  • --captures DIR directory for script captures (default ./captures).
  • --platform NAME run on that platform of the catalog (default: MICROENGINE_PLATFORM, else the first one that can run here); --list-platforms prints them and exits.
  • --headless run without a window (no captures are written); the same as --platform headless. A headless run is in deterministic time unless --time says otherwise (the headless platform's [RunPreset](/docs/api/microengine.core.runpreset/)).
  • --hidden render in a hidden window (captures still work); it implies nothing about time or sound.
  • --time realtime|deterministic how the loop advances time ([TimeMode](/docs/api/microengine.kernel.timemode/)): with the wall clock, or one fixed step per frame; by default the game's choice, else the platform's [RunPreset](/docs/api/microengine.core.runpreset/) (headless: deterministic), else real time; a script means deterministic.
  • --frames N stop after N updates; --seed N; --scale N; --mute.
  • --report print the platform that runs and whether it has audio before the game starts (package checks).
  • --audio auto|device|silent where sound may go ([AudioOutput](/docs/api/microengine.core.audiooutput/)); auto (the default) asks for no physical device when the run is in deterministic time (scripts, --time deterministic), so checks are never heard, and for one otherwise (the headless platform has none).
  • --audio-capture FILE play nothing aloud and write what would have been heard as a WAV ([CaptureAudioDevice](/docs/api/microengine.audio.captureaudiodevice/)).
  • --gpu auto|high-performance|power-saving the GPU to ask for on a machine with two ([GpuPreference](/docs/api/microengine.core.gpupreference/)).
  • --renderer NAME[,NAME...] graphics APIs to try first ([Renderers](/docs/api/microengine.core.graphicssettings/#MicroEngine_Core_GraphicsSettings_Renderers)).
  • --graphics NAME the graphics device to draw with, on platforms that offer several: SDL's sdl-renderer or sdl-gpu ([Device](/docs/api/microengine.core.graphicssettings/#MicroEngine_Core_GraphicsSettings_Device)).
  • --vsync on|off wait for the display's refresh or not ([VSync](/docs/api/microengine.core.graphicssettings/#MicroEngine_Core_GraphicsSettings_VSync)).
  • --fps-limit N draw at most N frames per second; 0 removes the game's limit ([FrameRateLimit](/docs/api/microengine.core.graphicssettings/#MicroEngine_Core_GraphicsSettings_FrameRateLimit)).
  • --window windowed|fullscreen|exclusive the window mode ([WindowMode](/docs/api/microengine.core.graphicssettings/#MicroEngine_Core_GraphicsSettings_WindowMode)).
  • --display N open on display N, counted from 0 ([Display](/docs/api/microengine.core.graphicssettings/#MicroEngine_Core_GraphicsSettings_Display)).
  • --pacing display|measured count frame time in refresh periods of the display (the default) or as measured ([PaceToDisplay](/docs/api/microengine.core.runoptions/#MicroEngine_Core_RunOptions_PaceToDisplay)).
  • --profile FILE measure every frame and the start phases ([FrameProfiler](/docs/api/microengine.core.frameprofiler/)), print a summary and write the results as JSON, or CSV when FILE ends in .csv.
  • --state-trace FILE hash the simulation state after every fixed step ([StateTrace](/docs/api/microengine.core.runoptions/#MicroEngine_Core_RunOptions_StateTrace)) and write one line per step with each section's hash ([StateTrace](/docs/api/microengine.kernel.statetrace/)'s text format): two runs of the same build, script and seed write the same file, and [FirstDivergence](/docs/api/microengine.kernel.statetrace/#MicroEngine_Kernel_StateTrace_FirstDivergence_MicroEngine_Kernel_StateTrace_MicroEngine_Kernel_StateTrace_) names where two traces part.

A run in deterministic time also asks the platform, through explicit request options, not to wait for the display (WaitForDisplay) and for no sound device (–audio auto); a run in real time whose game shows a start screen asks it to start gamepads after the first frame (StartGamepadsAfterFirstFrame). The platform itself never knows the time mode. Browser pages, phone apps and tests apply the same rules through GameHost. Returns a process exit code: 0 on success, 1 on a game or platform error, 2 on bad arguments.

C#
public static class GameLauncher

Inheritance

object ← GameLauncher

Fields

ProfileWarmupFrames

Frames of a profiled run left out of its summary: the first second or so, while the JIT compiles and caches warm up.

C#
public const int ProfileWarmupFrames = 60

Field Value

int

Usage

The one-line usage text printed after an argument error.

C#
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

string

Methods

Fallbacks(PlatformCatalog)

The platforms tried, in order, when nobody named one: every platform of the catalog that can run here except the headless one (a player who sees no window would not know why), or the catalog’s default when that leaves none.

C#
public static IReadOnlyList<PlatformProfile> Fallbacks(PlatformCatalog catalog)

Parameters

catalog PlatformCatalog

Returns

IReadOnlyList<PlatformProfile>

Exceptions

PlatformConfigurationException

The catalog has no platform that can run here.

Preferred(PlatformCatalog, string?)

The platforms tried when the game prefers backend (Backend) and nobody named one: that platform first, then the Fallbacks. A preference this catalog lacks or that cannot run here is reported on standard error and skipped.

C#
public static IReadOnlyList<PlatformProfile> Preferred(PlatformCatalog catalog, string? backend)

Parameters

catalog PlatformCatalog

backend string?

Returns

IReadOnlyList<PlatformProfile>

Exceptions

PlatformConfigurationException

The catalog has no platform that can run here.

Report(PlatformProfile, IPlatform)

What –report prints: the profile that runs, with what the platform says about itself when it overrides ToString (SDL names its graphics API), and whether an audio device is open.

C#
public static IReadOnlyList<string> Report(PlatformProfile profile, IPlatform platform)

Parameters

profile PlatformProfile

platform IPlatform

Returns

IReadOnlyList<string>

Run(Game, string[], PlatformCatalog, Func<PlatformRequest, PlatformRequest>?)

Runs game with the command line args on the platforms of catalog.

C#
public static int Run(Game game, string[] args, PlatformCatalog catalog, Func<PlatformRequest, PlatformRequest>? configure = null)

Parameters

game Game

args string[]

catalog PlatformCatalog

configure Func<PlatformRequest, PlatformRequest>?

Changes the platform request before the platform is built: an audio device or input sources of the host’s own (see PlatformRequest).

Returns

int

Run(string[], Action<HostBuilder>, Action<HostBuilder>?)

Runs the game a composition chooses (a game’s Configure entry point, GameHost) with the command line args as a desktop process. defaults (the host’s own platforms and content) runs before configure, which may replace any of them.

C#
public static int Run(string[] args, Action<HostBuilder> configure, Action<HostBuilder>? defaults = null)

Parameters

args string[]

configure Action<HostBuilder>

defaults Action<HostBuilder>?

Returns

int

The process exit code: 0 on success, 1 on a game or platform error, 2 on bad arguments.