GWGUI.Emulation.SDK
1.2.0
dotnet add package GWGUI.Emulation.SDK --version 1.2.0
NuGet\Install-Package GWGUI.Emulation.SDK -Version 1.2.0
<PackageReference Include="GWGUI.Emulation.SDK" Version="1.2.0" />
<PackageVersion Include="GWGUI.Emulation.SDK" Version="1.2.0" />
<PackageReference Include="GWGUI.Emulation.SDK" />
paket add GWGUI.Emulation.SDK --version 1.2.0
#r "nuget: GWGUI.Emulation.SDK, 1.2.0"
#:package GWGUI.Emulation.SDK@1.2.0
#addin nuget:?package=GWGUI.Emulation.SDK&version=1.2.0
#tool nuget:?package=GWGUI.Emulation.SDK&version=1.2.0
GWGUI.Emulation.SDK
GWGUI.Emulation.SDK provides the public contracts used to develop independent emulation modules
for GW GUI. A module can define machines, settings, runtimes, media, input, video, audio, saved
states and its own update source without referencing GWGUI.App.
Install
<PackageReference Include="GWGUI.Emulation.SDK" Version="1.2.0" />
The package targets .NET 10. The current host API is 1.2, and the current module.json schema is
2.
Start a module
- Copy the
sdk/module-templatedirectory into a new repository. - Replace the example project identity, namespace, assembly name and values in
module.json. - Implement
IEmulationModuleFactoryand return anIEmulationModulefromCreate. - Require host API
1.2when using the currentAudioChunkconstructor orIEmulationVideoSettingsManager. The workspace modules and template target the current development API directly; declare the tested maximum explicitly. - Set
updateCatalogUrlto the stable HTTPS JSON catalogue published by the module repository. - Package the result with this structure:
Modules/<module-id>/
module.json
gwgui.emulation.<module-id>.dll
<private dependencies>
GW GUI validates the manifest, API range, identity, archive paths and checksum before installation. Adding, updating or removing a module takes effect after restarting GW GUI.
Main contracts
IEmulationModuleFactoryis the module entry point.IEmulationModuledescribes machines, settings, configurations and runtime creation.IEmulatedMachineexposes lifecycle, input, media, video, audio and saved-state services.IEmulationEmulatorManager,IEmulationFirmwareManager,IEmulationInputSettingsManagerandIEmulationStorageSettingsManageradd optional capabilities.IEmulationVideoSettingsManagerapplies the host'sEmulationGraphicsApipreference to an opaque configuration without exposing native backend values to the application.AudioChunk.InterleavedSamplescarries PCM16 samples in ascendingEmulationAudioChannelLayoutspeaker order. ItsChannelCountis derived from that layout, andHasValidLengthchecks the complete interleaved frames. The default layout is stereo.IMultichannelAudioOutputaddsStart(sampleRate, channelLayout)to the audio output contract. A runtime must preserve the layout through buffering, transport, volume changes and output replacement, and reconfigure the output when either the sample rate or layout changes. A stereo-onlyIAudioOutputmust not receive surround samples as stereo.IEmulationModuleLocalizationsupplies translations embedded in the module. The application owns the localization display and lookup flow, while a module owns only the translated strings specific to its machines and emulators. This keeps the application independent from concrete modules: it requests a key through the interface without referencing Atari, Amiga, Amstrad or any emulator.
The complete contract, manifest rules, packaging format and publication workflow are documented in the module authoring guide. SDK compatibility and version changes are documented in the versioning policy.
Shared services (host API 1.2)
EmulationSdk exposes shared operations through public interfaces. A module routes its emulator
adapters through its own Common layer, which uses these contracts; the SDK implementations remain
internal. No registration of the module assembly as a friend of the SDK is required.
The services cover adapter discovery, core releases and diagnostics, configuration files, saved states, input processing, audio and video processing, runtime commands and media preparation. Media operations are relayed by the SDK to MediaEngine; a module only references the SDK.
Use ConfigurationFiles for configuration persistence and path storage/resolution, and StateFiles
for the common saved-state envelope. State restoration validates the core identity and the
configuration, content and state hashes. Adapting an older module may require changes to its state
format; compatibility with previous saved-state files is not guaranteed.
Objects returned by the resource factories belong to the caller and must be disposed after their work has stopped, including on failure. Services and resources borrowed from the host remain owned by the host.
Version compatibility
The NuGet package follows semantic versioning. Every module declares an inclusive host API range in
module.json; compatibility beyond that range is never assumed. A package revision can improve
documentation or internal implementation while retaining host API 1.0.
License
MIT
Optional controller feedback (host API 1.1)
A machine may implement IEmulationControllerFeedbackSource. Its complete snapshot contains only explicitly configured physical device/motor destinations and normalized strengths. An empty snapshot clears previous outputs. The host must also stop its outputs when inactive, paused, stopped, faulted or disposed, and must attempt every device even if one fails. It never takes ownership of a borrowed physical input service.
EmulationControllerChoice.VisualOutputDefinitions describes the commands supported by each visual peripheral; EmulationControllerPort.OutputBindings contains the user's explicit destinations. Missing bindings remain empty, including after restoring defaults. Core-specific effect codes belong to the backend adapter, not these contracts. A module using these types must require host API 1.1; an older host must reject its manifest before loading its assembly.
Shared video preference (host API 1.2)
Implement IEmulationVideoSettingsManager.ApplyVideoSettings to follow the application's existing presentation renderer. Return a configuration derived without mutating the input. The module chooses the supported native API and its fallback; native tokens stay inside its adapter. Preserve software rendering and special emulation modes as separate choices. Automatic also covers a host presentation path with no specific graphics API, such as WPF; it does not force software emulation.
GW GUI applies the preference while editing and saving settings and before runtime creation. Modules that omit this optional interface keep their existing behavior. Modules implementing it must declare host API minimum 1.2 so older hosts reject them before loading their assembly.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- LTRData.DiscUtils.ExFat (>= 1.0.88)
- LTRData.DiscUtils.Ext (>= 1.0.88)
- LTRData.DiscUtils.Fat (>= 1.0.88)
- LTRData.DiscUtils.HfsPlus (>= 1.0.88)
- LTRData.DiscUtils.Ntfs (>= 1.0.88)
- LTRData.DiscUtils.Vdi (>= 1.0.88)
- LTRData.DiscUtils.Vhd (>= 1.0.88)
- LTRData.DiscUtils.Vhdx (>= 1.0.88)
- LTRData.DiscUtils.Vmdk (>= 1.0.88)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.