KernelAPI reference

Class GameHost

Namespace: MicroEngine.Core
Assembly: MicroEngine.dll
Guide: Composing a game for every platform

The one launch path of every host: desktop (GameLauncher), browser pages, Android and iOS apps and tests compose the same way and decide a run the same way. A host states its defaults (its platforms, where content files are), the game’s Configure entry point composes the rest (HostBuilder), and the LaunchRequest decides the run: a script means deterministic time and seed 1 on every host; a run in deterministic time asks the platform not to wait for the display and for no sound device unless the launch asks for one; a real-time run whose game shows a start screen starts gamepads after the first frame.

public sealed class GameHost

Inheritance

object ← GameHost

Examples

A test that runs a game headless through the same path as the desktop launcher:

var host = GameHost.Create(new HostEnvironment(HostKind.Test), new LaunchRequest { Frames = 60 },
    h => h.UseGame(() => new MyGame()), h => h.UsePlatforms(new PlatformCatalog().Add(HeadlessPlatform.Profile)));
var result = host.Play();

Properties

Arguments

The typed launch options (LaunchArguments), with the seed resolved by the launch’s rule.

public LaunchArguments Arguments { get; }

Property Value

LaunchArguments

Builder

The composition: the host’s defaults, then the game’s Configure.

public HostBuilder Builder { get; }

Property Value

HostBuilder

Platforms

The platforms this host offers, in order of preference.

public PlatformCatalog Platforms { get; }

Property Value

PlatformCatalog

Request

What this launch asked for.

public LaunchRequest Request { get; }

Property Value

LaunchRequest

Methods

Candidates(GraphicsSettings)

The platforms the run tries, in order (Choose``1); notes about the choice go to the host’s error output.

public IReadOnlyList<PlatformProfile> Candidates(GraphicsSettings graphics)

The launch named a platform that is unknown or cannot run here, or none can.

Create(HostEnvironment, LaunchRequest, Action<HostBuilder>, Action<HostBuilder>?)

Composes a host: defaults (the host’s own platforms, content and storage) first, then configure (the game’s Configure entry point), which may replace any of them.

public static GameHost Create(HostEnvironment environment, LaunchRequest request, Action<HostBuilder> configure, Action<HostBuilder>? defaults = null)

Parameters

environment HostEnvironment

request LaunchRequest

configure Action<HostBuilder>

defaults Action<HostBuilder>?

Returns

GameHost

Exceptions

InvalidOperationException

The composition chose no game (UseGame).

CreateGame()

A new game, built by the composition’s UseGame.

public Game CreateGame()

Returns

Game

CreateLoop(Game, IPlatform, RunOptions)

A loop for one run of game on platform, with the composition applied to its engine.

public GameLoop CreateLoop(Game game, IPlatform platform, RunOptions options)

Parameters

game Game

platform IPlatform

options RunOptions

Returns

GameLoop

CreatePlatform(PlatformRequest)

Builds the platform for request: the first candidate that starts, reporting each one that could not (a missing native library, no display) before trying the next.

public (IPlatform Platform, PlatformProfile Profile) CreatePlatform(PlatformRequest request)

Parameters

request PlatformRequest

Returns

(IPlatform Platform, PlatformProfile Profile)

Exceptions

PlatformConfigurationException

No candidate could start; the message is the last one’s reason.

CreateRequest(Game, RunOptions)

What the run asks of its platform: the launch’s window options, no wait for the display and no sound device in deterministic time (unless the launch asks for a device), gamepads after the first frame for a real-time run with a start screen, the game’s identity; then the composition’s request changes (ConfigureRequest), in order.

public PlatformRequest CreateRequest(Game game, RunOptions options)

Parameters

game Game

options RunOptions

Returns

PlatformRequest

CreateRunOptions(Game, FrameProfiler?, InputScript?)

The run’s options for game: the graphics options with the launch’s overrides, the script, its captures, the frame limit, the seed, mute, pacing and the time mode (EffectiveTime).

public RunOptions CreateRunOptions(Game game, FrameProfiler? profiler = null, InputScript? script = null)

Parameters

game Game

profiler FrameProfiler?

script InputScript?

Returns

RunOptions

Exceptions

FormatException

The script is invalid.

CreateSession(Func<LaunchRequest, GameHost>)

A session for hosts that drive frames themselves and outlive a run (a browser page): each Start composes again with compose for that launch.

public static GameSession CreateSession(Func<LaunchRequest, GameHost> compose)

Parameters

compose Func<LaunchRequest, GameHost>

Returns

GameSession

Play(Action<RunOptions>?)

Runs a new game of the composition to completion on the platform the launch chooses, for hosts that own their thread and tests; the platform is disposed after the run. Never throws for errors raised by the game or a platform that could not start: they are in Error.

public RunResult Play(Action<RunOptions>? inspect = null)

Parameters

inspect Action<RunOptions>?

Returns

RunResult

Exceptions

FormatException

The launch’s script is invalid.

ReadScript()

The launch’s input script, parsed: ScriptText, else the file ScriptPath; null without one.

public InputScript? ReadScript()

Returns

InputScript?

Exceptions

FormatException

The script is invalid.

Run(Game, IPlatform, RunOptions)

Runs game on platform to completion with the composition applied; the platform is not disposed.

public RunResult Run(Game game, IPlatform platform, RunOptions options)

Parameters

game Game

platform IPlatform

options RunOptions

Returns

RunResult

Run()

Runs the launch as a desktop process does (GameLauncher): lists the platforms, or builds the game and its platform, reports and profiles as asked, runs it, writes the audio capture and prints the outcome.

public int Run()

Returns

int

The process exit code: 0 on success, 1 on a game or platform error, 2 on an invalid script.