Interface IGameEmulation

A single instance of emulation for a specific IGame, with a specific combination of configuration, input, and initial save game state.

A IGameEmulation implementation is specific to the IEmulatorOrchestrator that produces it, and is responsible for handling the entire lifecycle of an emulation instance.

Namespace: Snowflake.Orchestration.Extensibility

Assembly: Snowflake.Framework.Primitives.dll

Syntax

public interface IGameEmulation

Properties

ControllerPorts

A list of IEmulatedController that representes the input devices that will be used in this emulation instance.

Declaration

IEnumerable<IEmulatedController> ControllerPorts { get; }

Property Value

Type	Description
System.Collections.Generic.IEnumerable<IEmulatedController>

EmulationState

The current state of the game emulation. It is absolutely impervious that implementations update this accordingly, or the IGameEmulation will not function correctly.

Declaration

GameEmulationState EmulationState { get; }

Property Value

Type	Description
GameEmulationState

Game

The game that is being emulated in this instance.

Declaration

IGame Game { get; }

Property Value

Type	Description
IGame

SaveProfile

The initial save game that should be copied into the working directory for this emulation instance. If this is null, then the implementation is responsible for creating a blank initial save game state in RestoreSaveGame().

Declaration

ISaveProfile SaveProfile { get; }

Property Value

Type	Description
ISaveProfile

Methods

CompileConfiguration()

Compiles relevant configuration into the working directory of the emulation instance, ready for use.

Declaration

Task CompileConfiguration()

Returns

Type	Description
System.Threading.Tasks.Task	An asynchronous task that signals the completion of the compilation.

DisposeAsync()

Implements System.IAsyncDisposable. When disposed, immediately stop the currently running emulation instance, if any, persist the save, and then clean up the working directory if any.

This method must be idempotent. Repeated calls must be ignored.

Declaration

ValueTask DisposeAsync()

Returns

Type	Description
System.Threading.Tasks.ValueTask

PersistSaveGame()

Persists the current state of the game's save information into a new immutable ISaveGame using the current ISaveProfile.

This can only be run if the game is not currently running, to avoid race conditions causing data corruption.

Declaration

Task<ISaveGame> PersistSaveGame()

Returns

Type	Description
System.Threading.Tasks.Task<ISaveGame>	A new ISaveGame with the current contents of the working directory save folder.

RestoreSaveGame()

Restores the save into the working directory save folder, or otherwise prepares the folder for a new game if SaveProfile is null.

This method must be idempotent. If the save game restore succeeds, calling this method again must do nothing.

Declaration

Task RestoreSaveGame()

Returns

Type	Description
System.Threading.Tasks.Task	An asynchronous task that signals the completion of the restore.

SetupEnvironment()

Run any misceallenous tasks required to prepare the working directory, such as copying BIOS files to the working directory if necessary.

This method must be idempotent. If the environment setup succeeds, calling this method again must do nothing.

Declaration

Task SetupEnvironment()

Returns

Type	Description
System.Threading.Tasks.Task	An asynchronous task that signals the completion of the preparation.

StartEmulation()

Begin the emulation instance (run the game).

This method must be idempotent. Once an emulation has started, this method must return the same cancellation token for the same process instance in future calls. If the emulation has stopped, this method must do nothing.

Implementations of IGameEmulation may opt to refuse to start if setup is incomplete, and throw System.InvalidOperationException if this is the case. Implementations must keep track of the hooks themselves in a thread-safe manner if they opt to do so.

Declaration

CancellationToken StartEmulation()

Returns

Type	Description
System.Threading.CancellationToken	A cancellation token that indicates when the emulation is halted by the user, or programmatically.

Exceptions

Type	Condition
System.InvalidOperationException	If all hooks have not yet been called.

StopEmulation()

As safely as possible, halt the currently running emulation instance forever. Instead of calling this directly, consider calling DisposeAsync() to dispose of the IGameEmulation instance.

This method must be idempotent. Once an emulation has stopped, it can never be restarted, and calling this method again must do nothing. If the emulation has yet to be started, this method must do nothing.

Declaration

Task StopEmulation()

Returns

Type	Description
System.Threading.Tasks.Task	An asynchronous task that signals the completion of the instance halt.