Referenz der öffentlichen API (OmsiLaunch.Api)

Dokumentation für Version v0.1.0-beta.3Quelle auf GitHub ansehen

Übersetzung der englischen Originalseite für OmsiLaunch 0.1.0-beta3. Maßgeblich ist die englische Seite: Bei Abweichungen gelten die englische Seite und der Code.

Diese Seite ist die normative Referenz für die verwaltete öffentliche API von OmsiLaunch 0.1.0-beta3: die Assembly OmsiLaunch.Api (Verträge) und der Einstiegspunkt für Integratoren OmsiLaunchService in OmsiLaunch.Core. Sie dokumentiert ausschließlich, was der aktuelle Code tut. Alles, was ein Integrator aufrufen, empfangen oder beobachten kann, ist hier mit seiner Stabilitätsstufe aufgeführt; alles, was hier nicht aufgeführt ist, ist keine Integrationsschnittstelle.

Das generierte Inventar der öffentlichen API listet jeden öffentlichen Typ und jedes öffentliche Mitglied von OmsiLaunch.Api, OmsiLaunch.Core und OmsiLaunch.Process mit Signatur und Stabilität auf; ein Dokumentations-Gate schlägt fehl, wenn Inventar und Assemblies voneinander abweichen. Diese Seite erläutert die Semantik.

Verwandte Seiten: LaunchSpec-Referenz, Fehlercodes, Sitzungslebenszyklus, Transaktionen und Recovery, Runtime-Steuerung, Capabilities, lokale Steuerungsebene, Exitcodes, Status der Runtime-Validierung.

Stabilitätsvokabular#

Überblick über die Assemblies#

Einstiegspunkt: OmsiLaunchService und OmsiLaunchRuntimePaths#

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

Der Service liest diese Pfade bei jedem PlanSessionAsync und StartSessionAsync; er kopiert, stellt bereit oder entfernt niemals Plugin-Dateien (siehe permanentes Plugin). Die CLI erzeugt den Service genau so (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));

Erzeugen Sie einen Service pro Prozess und verwenden Sie ihn gemeinsam. Stabilität: STABLE_BETA.

Regeln zur Sitzungseigentümerschaft#

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);
}

Gemeinsame Fakten für jede Methode:

• Unbekannte oder bereits geschlossene Handles lösen KeyNotFoundException aus („Unknown OmsiLaunch session.“).
• Keine Methode außer ExecuteRuntimeAsync setzt eine laufende Sitzung (Running) voraus.
• Ausnahmen, die einen OmsiLaunch-Code tragen, stellen den Code an den Anfang von Exception.Message ("OL_E_PLAN_NOT_RUNNABLE: ..."). Die CLI extrahiert Codes auf dieselbe Weise aus Meldungen (CliProgram.Classify).
• Unterstützter Build: nur Omsi23004_692EBFBF (zusätzlich der Hash der Steam-LAA-Positivliste, akzeptiert; Gameplay nicht validiert, dafür ist eine echte Steam-Installation erforderlich). Siehe Kompatibilität.

Vollständiges Minimalbeispiel#

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#

Werte von ContentQueryKind und Ergebnisse:

Identitäten von Einstiegspunkten dienen nur der Erkennung: Der Startpfad verwendet PresentedEntrypointIndex; die Übergabe einer EntrypointIdentity macht den Plan auf diesem Build nicht ausführbar (world.entrypoint-identity, RUNTIME_PARTIAL).

RecoverPendingAsync#

Vertragstypen#

Optionale Werte und semantische Grundtypen#

LaunchSpec-Familie#

Alle folgenden Records sind in der LaunchSpec-Referenz Eigenschaft für Eigenschaft dokumentiert; diese Tabelle legt das Typinventar fest.

Plan- und Statustypen#

SessionState#

Byte-Enum in Deklarationsreihenfolge: Created, ValidatingPlatform, Planning, AcquiringInstallationLock, RecoveringPreviousTransaction, Snapshotting, ApplyingConfiguration, DeployingRuntime, CreatingStartupHandoff, StartingProcess, WaitingForPlugin, PluginBootstrap, StartingWorld, EnteringGameplay, Running, ProcessExited, Restoring, CleaningRuntime, Completed, Failed. ValidatingPlatform, Planning und EnteringGameplay werden vom aktuellen Service nie gesetzt; Snapshotting ist ein Übergangszustand und praktisch nicht beobachtbar. Endzustände: Completed, Failed. Vollständige Semantik: Sitzungslebenszyklus.

Typen der Runtime-Steuerung#

Das Plugin lehnt eine Übergabe ab (plugin.request.unsupported → OL_E_CAPABILITY_UNAVAILABLE), sofern nicht WorldMode NewMap oder SavedSituation ist, HeadlessStart true ist, PlayerVehicleEnabled false ist, beide Datums-/Zeitmodi Unset sind und eine gespeicherte Situation eine nicht leere Identität hat. Der Planer erzwingt dieselben Bedingungen früher, sodass ein ausführbarer Plan dies nie auslöst.

Typen der Capability-Registry#

Vollständiger Katalog: Capabilities.

Erweiterungsmethoden von D3DRuntimeApi#

Typisierte Wrapper um ExecuteRuntimeAsync für die d3d.*-Operationen (EXPERIMENTAL, PublicExperimental-Capability d3d.texture). Sie vergeben Anforderungs-IDs aus einem prozessweiten Zähler, der bei 30 000 beginnt, und verwenden standardmäßig ein Timeout von 5 s (außer GetD3DStatusAsync, das eines verlangt).

Typen: D3DDeviceStatus(Available, State, Generation, LiveTextureCount, ResetHookInstalled, ExecutionThreadId, LastResetThreadId, QueryInterfaceHResult, CooperativeLevelHResult, OwnedDeviceReferences); D3DDeviceState: NotReady, Ready, Lost, Resetting, Stopping, Stopped; D3DTextureHandle(Value) mit 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.

Fehler: Ein fehlgeschlagenes Ergebnis wird als OmsiRuntimeException(Code, detail) erneut ausgelöst, wobei Code der ErrorCode des Ergebnisses ist (oder OL_E_RUNTIME_OPERATION_FAILED, wenn dieser fehlt) und die Meldung "<code>: <Values["detail"]>" lautet; ein erfolgreiches Ergebnis ohne Werte oder ein unbekannter Gerätezustands-String löst OmsiRuntimeException("OL_E_RUNTIME_PROTOCOL_MISMATCH", ...) aus. Alles, was ExecuteRuntimeAsync auslöst, wird unverändert weitergegeben. Die Behandlung des Geräte-Resets ist zur Laufzeit validiert: Ein Reset führt das Gerät über Resetting zurück zu Ready und macht jede aktive Textur ungültig (OL_E_D3D_STALE_RESOURCE_HANDLE, Runtime-Abschluss D01); GetCapabilitiesAsync meldet runtime.d3d.lifecycle.reset weiterhin als IMPLEMENTED_NOT_RUNTIME_VALIDATED (Verzögerung der Selbstauskunft). Der Übergang Lost lässt sich von außerhalb des Produkts nicht herbeiführen und ist nur offline abgedeckt.

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);
}

Typen des Prozessvertrags#

InstallationPaths (Installationsidentität und Pfadeingrenzung)#

Stabilität: STABLE_BETA (reine Funktionen, keine E/A, kein OMSI-Zustand, keine Änderung des Dateisystems, keine Beteiligung an Transaktionen, keine laufende Sitzung erforderlich). Dies ist die einzige Definition, die von der Installations-Lease, dem Namen der lokalen Steuerungs-Pipe, der Eingrenzung der Sitzungsprofil-Assets, der Validierung von Internettexturen-Zielen und dem Modellpfad für den Runtime-Spawn verwendet wird.

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"

Sitzungsprofile (OmsiLaunch.Core)#

Stabilität: EXPERIMENTAL. Diese Typen kompilieren ein YAML-Sitzungsprofil (<root>\.omsilaunch\session-profiles\<id>\profile.yaml, Schema omsilaunch.session-profile/v1) zu einer LaunchSpec. Die CLI-Option /predefined-profile:<id> /predefined-profile-index:<n> verwendet genau diese Aufrufe; ein Integrator kann sie verwenden, um ein Profil über die API zu starten.

Die CLI lehnt zusätzlich Befehlszeilen-Flags ab, die mit dem Profil in Konflikt stehen (OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT); diese Prüfung ist nicht Teil des Compilers. Die vollständige Zusammenführungsreihenfolge finden Sie unter Sitzungsprofile.

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
}

Plattformtypen (OmsiLaunch.Process)#

Threadsicherheit#

• OmsiLaunchService ist für gleichzeitige Aufrufe auf verschiedenen Sitzungen sicher: Sitzungen liegen in einem ConcurrentDictionary, und jede sitzungsbezogene Änderung erfolgt unter der privaten Sperre der Sitzung.
• Gleichzeitige Aufrufe auf derselben Sitzung sind sicher, werden aber dort serialisiert, wo es darauf ankommt: ExecuteRuntimeAsync nimmt ein Gate pro Sitzung, sodass ein zweiter Befehl auf den ersten wartet (sein Timeout beginnt, wenn er bereitgestellt wird).
• Der Supervisor läuft als Thread-Pool-Task (Task.Run) ab dem Moment, in dem StartSessionAsync zurückkehrt, bis sich die Sitzung im Endzustand befindet; er fragt Telemetrie und Prozess alle 100 ms ab. Aufrufer führen niemals Supervisor-Code aus.
• StopAsync und GetStatusAsync werden synchron abgeschlossen und dürfen von jedem Thread aufgerufen werden, auch innerhalb eines ProcessExit-Handlers (die CLI tut dies mit einem Budget von 4 s).
• Kein API-Aufruf ist an einen Thread gebunden; keiner benötigt einen Synchronisierungskontext.

Was nicht Teil der API ist#

• Kein IntPtr, kein nint, keine Win32-Handles, keine nativen Adressen, keine VMT-Zeiger und keine Prozessobjekte. Ergebniswerte, deren Schlüssel mit internal_ beginnen oder mit _address, _pointer, _vmt enden, werden entfernt, bevor ein Ergebnis ExecuteRuntimeAsync verlässt.
• Keine internal.*-Runtime-Operationen: internal.road-vehicles.make-basic ist in der Registry InternalOnly und liefert über API und CLI OL_E_RUNTIME_OPERATION_UNKNOWN.
• Keine direkten Lese- oder Schreibzugriffe auf den OMSI-Speicher, kein Dateizugriff auf die Installation über das hinaus, was eine LaunchSpec deklariert.
• Keine prozessübergreifenden Handles: Die lokale Steuerungsebene ist der einzige prozessübergreifende Weg, und sie akzeptiert ausschließlich session.status, session.events, session.stop und runtime.execute.
• Kein kooperatives Herunterfahren von OMSI, kein LAST_MAP_STATE, keine Anwendung von Datum/Zeit/Wetter/Spielerfahrzeug, keine Overlays für Tastatur-/Controller-Dokumente auf diesem Build.

Stabilitätsübersicht#