Public API reference (OmsiLaunch.Api)

Documentation for version v0.1.0-beta.3View source on GitHub

This page is the normative reference for the managed public API of OmsiLaunch 0.1.0-beta3: the OmsiLaunch.Api assembly (contracts) and the integrator entry point OmsiLaunchService in OmsiLaunch.Core. It documents only what the current code does. Everything an integrator can call, receive, or observe is listed here with its stability level; anything not listed is not an integration surface.

The generated public API inventory lists every public type and member of OmsiLaunch.Api, OmsiLaunch.Core and OmsiLaunch.Process with its signature and stability; a documentation gate fails when the inventory and the assemblies differ. This page explains the semantics.

Related pages: LaunchSpec reference, error codes, session lifecycle, transactions and recovery, runtime control, capabilities, local control plane, exit codes, runtime validation status.

Stability vocabulary#

Assembly overview#

Entry point: OmsiLaunchService and OmsiLaunchRuntimePaths#

public sealed record OmsiLaunchRuntimePaths(string PluginBuildDirectory, string NativeBridgePath, string? ReleaseManifestPath = null);
public sealed class OmsiLaunchService : IOmsiLaunch
{
    public OmsiLaunchService(IRuntimePlatform platform, OmsiLaunchRuntimePaths runtimePaths);
}

The service reads these paths on every PlanSessionAsync and StartSessionAsync; it never copies, stages or removes plugin files (see permanent plugin). The CLI constructs the service exactly like this (tools/OmsiLaunch.Cli/Program.cs):

using OmsiLaunch.Api;
using OmsiLaunch.Core;
using OmsiLaunch.Process;

var package = AppContext.BaseDirectory;                       // directory that contains OmsiLaunch.exe
var plugins = Path.Combine(package, "plugins");
var manifest = Path.Combine(package, "release-manifest.json");
IOmsiLaunch launch = new OmsiLaunchService(
    new CurrentWindowsX64Platform(),
    new OmsiLaunchRuntimePaths(plugins, Path.Combine(plugins, "OmsiLaunch.Native.x86.dll"), File.Exists(manifest) ? manifest : null));

Create one service per process and share it. Stability: STABLE_BETA.

Session ownership rules#

IOmsiLaunch#

public interface IOmsiLaunch
{
    Task<SessionPlan> PlanSessionAsync(LaunchSpec spec, CancellationToken cancellationToken = default);
    Task<SessionHandle> StartSessionAsync(SessionPlan plan, CancellationToken cancellationToken = default);
    Task<SessionStatus> GetStatusAsync(SessionHandle session, CancellationToken cancellationToken = default);
    Task<SessionStatus> WaitForAsync(SessionHandle session, SessionState state, TimeSpan timeout, CancellationToken cancellationToken = default);
    Task StopAsync(SessionHandle session, CancellationToken cancellationToken = default);
    Task CloseAsync(SessionHandle session, CancellationToken cancellationToken = default);
    Task<RuntimeCommandResult> ExecuteRuntimeAsync(SessionHandle session, RuntimeCommand command, TimeSpan timeout, CancellationToken cancellationToken = default);
    Task<IReadOnlyList<Capability>> GetCapabilitiesAsync(InstallationSpec installation, CancellationToken cancellationToken = default);
    Task<IReadOnlyList<ContentIdentity>> DiscoverAsync(InstallationSpec installation, ContentQueryKind query, OptionalValue<string> scope = default, CancellationToken cancellationToken = default);
    Task<RecoveryStatus> RecoverPendingAsync(InstallationSpec installation, bool restore, CancellationToken cancellationToken = default);
}

Common facts for every method:

• Unknown or already closed handles throw KeyNotFoundException ("Unknown OmsiLaunch session.").
• No method requires a Running session except ExecuteRuntimeAsync.
• Exceptions that carry an OmsiLaunch code put the code at the start of Exception.Message ("OL_E_PLAN_NOT_RUNNABLE: ..."). The CLI extracts codes from messages the same way (CliProgram.Classify).
• Supported build: only Omsi23004_692EBFBF (plus the Steam LAA allow-list hash, accepted; gameplay not validated, it needs a genuine Steam installation). See compatibility.

Complete minimal example#

var none = new Dictionary<string, OptionalValue<string>>();
var spec = new LaunchSpec(
    Installation: new InstallationSpec(@"C:\OMSI 2"),
    World: new WorldSpec(WorldMode.NewMap, OptionalValue<string>.Set(@"maps\Grundorf\global.cfg"), OptionalValue<string>.Unset, OptionalValue<int>.Set(1)),
    Date: new DateSpec(DateTimeMode.Unset, OptionalValue<SemanticDate>.Unset),
    Time: new TimeSpec(DateTimeMode.Unset, OptionalValue<SemanticTime>.Unset),
    PlayerVehicle: OptionalValue<PlayerVehicleSpec>.Unset,
    Environment: new EnvironmentSpec(none, none, none, none, none, none, none, none),
    Behavior: new LaunchBehaviorSpec());

var plan = await launch.PlanSessionAsync(spec);
if (!plan.IsRunnable) { foreach (var d in plan.Diagnostics) Console.WriteLine($"{d.Code}: {d.Message}"); return; }

var session = await launch.StartSessionAsync(plan);
try
{
    var status = await launch.WaitForAsync(session, SessionState.Running, TimeSpan.FromSeconds(plan.Spec.Behavior.StartupTimeoutSeconds + 5));
    if (status.State == SessionState.Running)
    {
        var time = await launch.ExecuteRuntimeAsync(session, new RuntimeCommand(session.SessionId, 1, "time.read"), TimeSpan.FromSeconds(5));
        Console.WriteLine(time.Succeeded ? $"{time.Values!["hour"]}:{time.Values["minute"]}" : time.ErrorCode);
        await launch.StopAsync(session);
    }
    var final = await launch.WaitForAsync(session, SessionState.Completed, Timeout.InfiniteTimeSpan);
    Console.WriteLine(final.State);                      // Completed, or Failed with diagnostics
}
finally
{
    await launch.CloseAsync(session);                    // always
}

PlanSessionAsync#

StartSessionAsync#

GetStatusAsync#

WaitForAsync#

StopAsync#

CloseAsync#

ExecuteRuntimeAsync#

GetCapabilitiesAsync#

DiscoverAsync#

ContentQueryKind values and results:

Entrypoint identities are for discovery only: the launch path uses PresentedEntrypointIndex; passing an EntrypointIdentity makes the plan non-runnable on this build (world.entrypoint-identity, RUNTIME_PARTIAL).

RecoverPendingAsync#

Contract types#

Optional values and semantic primitives#

LaunchSpec family#

All records below are documented property by property in the LaunchSpec reference; this table fixes the type inventory.

Plan and status types#

SessionState#

Byte enum in declaration order: Created, ValidatingPlatform, Planning, AcquiringInstallationLock, RecoveringPreviousTransaction, Snapshotting, ApplyingConfiguration, DeployingRuntime, CreatingStartupHandoff, StartingProcess, WaitingForPlugin, PluginBootstrap, StartingWorld, EnteringGameplay, Running, ProcessExited, Restoring, CleaningRuntime, Completed, Failed. ValidatingPlatform, Planning and EnteringGameplay are never set by the current service; Snapshotting is transient and practically unobservable. Terminal states: Completed, Failed. Full semantics: session lifecycle.

Runtime control types#

The plugin rejects a handoff (plugin.request.unsupported → OL_E_CAPABILITY_UNAVAILABLE) unless WorldMode is NewMap or SavedSituation, HeadlessStart is true, PlayerVehicleEnabled is false, both date/time modes are Unset, and a saved situation has a non-empty identity. The planner enforces the same constraints earlier, so a runnable plan never triggers this.

Capability registry types#

Full catalog: capabilities.

D3DRuntimeApi extension methods#

Typed wrappers over ExecuteRuntimeAsync for the d3d.* operations (EXPERIMENTAL, PublicExperimental capability d3d.texture). They allocate request ids from a process-wide counter starting at 30 000 and default the timeout to 5 s (except GetD3DStatusAsync, which requires one).

Types: D3DDeviceStatus(Available, State, Generation, LiveTextureCount, ResetHookInstalled, ExecutionThreadId, LastResetThreadId, QueryInterfaceHResult, CooperativeLevelHResult, OwnedDeviceReferences); D3DDeviceState: NotReady, Ready, Lost, Resetting, Stopping, Stopped; D3DTextureHandle(Value) with Value = "d3dtex-<session id N>-<16 hex>"; D3DTextureDescription(Handle, State, DeviceState, Generation, Width, Height, Format, Levels, Level, LevelWidth, LevelHeight, HResult, ExecutionThreadId); D3DTextureResourceState: Live, Released, Stale; D3DTextureFormat: A8R8G8B8, X8R8G8B8, R5G6B5, X1R5G5B5, A1R5G5B5, A4R4G4B4, A8, L8, A8L8.

Errors: a failed result is rethrown as OmsiRuntimeException(Code, detail) where Code is the result's ErrorCode (or OL_E_RUNTIME_OPERATION_FAILED when absent) and the message is "<code>: <Values["detail"]>"; a successful result without values, or an unknown device-state string, throws OmsiRuntimeException("OL_E_RUNTIME_PROTOCOL_MISMATCH", ...). Everything ExecuteRuntimeAsync throws propagates unchanged. Device reset handling is runtime-validated: a reset moves the device through Resetting back to Ready and invalidates every live texture (OL_E_D3D_STALE_RESOURCE_HANDLE, runtime closure D01); GetCapabilitiesAsync still reports runtime.d3d.lifecycle.reset as IMPLEMENTED_NOT_RUNTIME_VALIDATED (self-report lag). The Lost transition cannot be produced from outside the product and is covered offline only.

var status = await launch.GetD3DStatusAsync(session, TimeSpan.FromSeconds(5));
if (status.State == D3DDeviceState.Ready)
{
    var texture = await launch.CreateD3DTextureAsync(session, 8, 8, D3DTextureFormat.A8R8G8B8);
    var pixels = new byte[8 * 8 * 4];
    await launch.UpdateD3DTextureAsync(session, texture.Handle, new D3DTextureUpdate(0, 0, 0, 8, 8, pixels));
    await launch.ReleaseD3DTextureAsync(session, texture.Handle);
}

Process contract types#

InstallationPaths (installation identity and path containment)#

Stability: STABLE_BETA (pure functions, no I/O, no OMSI state, no filesystem mutation, no transaction participation, no Running session required). It is the single definition used by the installation lease, the local control pipe name, session-profile asset confinement, Internet Textures target validation and the runtime spawn model path.

var same = InstallationPaths.IdentityKey(@"C:\OMSI") == InstallationPaths.IdentityKey(@"c:\foo\..\OMSI\"); // true
InstallationPaths.TryGetContainedRelativePath(@"C:\OMSI", @"Sceneryobjects\\x\texture\a.tga", out var relative); // true, "Sceneryobjects\x\texture\a.tga"

Session profiles (OmsiLaunch.Core)#

Stability: EXPERIMENTAL. These types compile a YAML session profile (<root>\.omsilaunch\session-profiles\<id>\profile.yaml, schema omsilaunch.session-profile/v1) into a LaunchSpec. The CLI /predefined-profile:<id> /predefined-profile-index:<n> uses exactly these calls; an integrator can use them to start a profile through the API.

The CLI additionally rejects command-line flags that conflict with the profile (OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT); that check is not part of the compiler. See session profiles for the full merge order.

static async Task<SessionPlan> PlanProfileAsync(IOmsiLaunch launch, LaunchSpec baseline, string installationRoot, string profileId)
{
    // baseline: a LaunchSpec for installationRoot with World.Mode = WorldMode.NewMap (see the complete example).
    var profile = SessionProfileCompiler.Load(installationRoot, profileId, presetIndex: 1);
    var spec = SessionProfileCompiler.Apply(profile, baseline, WorldMode.NewMap);
    return await launch.PlanSessionAsync(spec); // plan.Spec.SessionProfile carries the provenance
}

Platform types (OmsiLaunch.Process)#

Thread safety#

• OmsiLaunchService is safe for concurrent calls on different sessions: sessions live in a ConcurrentDictionary and every per-session mutation happens under the session's private lock.
• Concurrent calls on the same session are safe but serialized where it matters: ExecuteRuntimeAsync takes a per-session gate, so a second command waits for the first (its timeout starts when it is staged).
• The supervisor runs on a thread-pool task (Task.Run) from the moment StartSessionAsync returns until the session is terminal; it polls telemetry and the process every 100 ms. Callers never run supervisor code.
• StopAsync and GetStatusAsync complete synchronously and may be called from any thread, including inside a ProcessExit handler (the CLI does this with a 4 s budget).
• No API call is thread-affine; none requires a synchronization context.

What is not in the API#

• No IntPtr, nint, Win32 handles, native addresses, VMT pointers or process objects. Result values whose keys start with internal_ or end with _address, _pointer, _vmt are removed before a result leaves ExecuteRuntimeAsync.
• No internal.* runtime operations: internal.road-vehicles.make-basic is InternalOnly in the registry and returns OL_E_RUNTIME_OPERATION_UNKNOWN from the API and the CLI.
• No raw OMSI memory reads or writes, no file-level access to the installation other than what a LaunchSpec declares.
• No cross-process handles: the local control plane is the only cross-process route, and it accepts session.status, session.events, session.stop and runtime.execute only.
• No cooperative OMSI shutdown, no LAST_MAP_STATE, no date/time/weather/player-vehicle application, no keyboard/controller document overlays on this build.

Stability summary#