Referentie van de openbare API (OmsiLaunch.Api)

Documentatie voor versie v0.1.0-beta.3Bron bekijken op GitHub

Vertaling van de oorspronkelijke Engelse pagina voor OmsiLaunch 0.1.0-beta3. De Engelse pagina is normatief: bij verschillen gelden de Engelse pagina en de code.

Deze pagina is de normatieve referentie voor de beheerde openbare API van OmsiLaunch 0.1.0-beta3: de assembly OmsiLaunch.Api (contracten) en het instappunt voor integrators OmsiLaunchService in OmsiLaunch.Core. Ze documenteert alleen wat de huidige code doet. Alles wat een integrator kan aanroepen, ontvangen of waarnemen, staat hier vermeld met het bijbehorende stabiliteitsniveau; wat hier niet staat, is geen integratieoppervlak.

De gegenereerde inventaris van de openbare API vermeldt elk openbaar type en elk openbaar lid van OmsiLaunch.Api, OmsiLaunch.Core en OmsiLaunch.Process met signatuur en stabiliteit; een documentatiegate faalt wanneer de inventaris en de assembly's van elkaar verschillen. Deze pagina legt de semantiek uit.

Gerelateerde pagina's: LaunchSpec-referentie, foutcodes, levenscyclus van de sessie, transacties en recovery, runtimebesturing, capabilities, lokaal control plane, exitcodes, status van de runtimevalidatie.

Stabiliteitsbegrippen#

Overzicht van de assembly's#

Instappunt: OmsiLaunchService en OmsiLaunchRuntimePaths#

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

De service leest deze paden bij elke PlanSessionAsync en StartSessionAsync; ze kopieert, plaatst of verwijdert nooit pluginbestanden (zie permanente plugin). De CLI construeert de service precies zo (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));

Maak één service per proces aan en deel die. Stabiliteit: STABLE_BETA.

Regels voor sessie-eigendom#

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

Gemeenschappelijke feiten voor elke methode:

• Onbekende of al gesloten handles werpen KeyNotFoundException ("Unknown OmsiLaunch session.").
• Geen enkele methode vereist een actieve sessie (Running), behalve ExecuteRuntimeAsync.
• Uitzonderingen die een OmsiLaunch-code dragen, plaatsen die code aan het begin van Exception.Message ("OL_E_PLAN_NOT_RUNNABLE: ..."). De CLI haalt codes op dezelfde manier uit berichten (CliProgram.Classify).
• Ondersteunde build: alleen Omsi23004_692EBFBF (plus de hash van de Steam-LAA-toestaanlijst, geaccepteerd; gameplay niet gevalideerd, daarvoor is een echte Steam-installatie nodig). Zie compatibiliteit.

Volledig minimaal voorbeeld#

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#

Waarden van ContentQueryKind en resultaten:

Identiteiten van instappunten zijn alleen bedoeld voor detectie: het startpad gebruikt PresentedEntrypointIndex; het doorgeven van een EntrypointIdentity maakt het plan op deze build niet uitvoerbaar (world.entrypoint-identity, RUNTIME_PARTIAL).

RecoverPendingAsync#

Contracttypen#

Optionele waarden en semantische primitieven#

LaunchSpec-familie#

Alle onderstaande records worden eigenschap voor eigenschap gedocumenteerd in de LaunchSpec-referentie; deze tabel legt de inventaris van typen vast.

Plan- en statustypen#

SessionState#

Byte-enum in declaratievolgorde: Created, ValidatingPlatform, Planning, AcquiringInstallationLock, RecoveringPreviousTransaction, Snapshotting, ApplyingConfiguration, DeployingRuntime, CreatingStartupHandoff, StartingProcess, WaitingForPlugin, PluginBootstrap, StartingWorld, EnteringGameplay, Running, ProcessExited, Restoring, CleaningRuntime, Completed, Failed. ValidatingPlatform, Planning en EnteringGameplay worden door de huidige service nooit ingesteld; Snapshotting is kortstondig en in de praktijk niet waarneembaar. Eindtoestanden: Completed, Failed. Volledige semantiek: levenscyclus van de sessie.

Typen voor runtimebesturing#

De plugin weigert een handoff (plugin.request.unsupported → OL_E_CAPABILITY_UNAVAILABLE), tenzij WorldMode gelijk is aan NewMap of SavedSituation, HeadlessStart true is, PlayerVehicleEnabled false is, beide datum-/tijdmodi Unset zijn en een opgeslagen situatie een niet-lege identiteit heeft. De planner dwingt dezelfde voorwaarden eerder af, zodat een uitvoerbaar plan dit nooit veroorzaakt.

Typen van het capabilityregister#

Volledige catalogus: capabilities.

Extensiemethoden van D3DRuntimeApi#

Getypeerde wrappers rond ExecuteRuntimeAsync voor de d3d.*-operaties (EXPERIMENTAL, PublicExperimental-capability d3d.texture). Ze wijzen verzoek-id's toe uit een procesbrede teller die bij 30 000 begint en gebruiken standaard een timeout van 5 s (behalve GetD3DStatusAsync, dat er een vereist).

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

Fouten: een mislukt resultaat wordt opnieuw geworpen als OmsiRuntimeException(Code, detail), waarbij Code de ErrorCode van het resultaat is (of OL_E_RUNTIME_OPERATION_FAILED als die ontbreekt) en het bericht "<code>: <Values["detail"]>" is; een geslaagd resultaat zonder waarden, of een onbekende tekenreeks voor de apparaattoestand, werpt OmsiRuntimeException("OL_E_RUNTIME_PROTOCOL_MISMATCH", ...). Alles wat ExecuteRuntimeAsync werpt, wordt ongewijzigd doorgegeven. De afhandeling van een apparaatreset is runtime-gevalideerd: een reset brengt het apparaat via Resetting terug naar Ready en maakt elke levende texture ongeldig (OL_E_D3D_STALE_RESOURCE_HANDLE, runtime-afsluitronde D01); GetCapabilitiesAsync meldt runtime.d3d.lifecycle.reset nog steeds als IMPLEMENTED_NOT_RUNTIME_VALIDATED (achterstand in de zelfrapportage). De overgang Lost kan niet van buiten het product worden veroorzaakt en is alleen offline gedekt.

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 van het procescontract#

InstallationPaths (installatie-identiteit en padinsluiting)#

Stabiliteit: STABLE_BETA (zuivere functies, geen I/O, geen OMSI-toestand, geen wijziging van het bestandssysteem, geen deelname aan transacties, geen actieve sessie vereist). Het is de enige definitie die wordt gebruikt door de installatielease, de pipenaam van local control, de insluiting van assets van sessieprofielen, de validatie van doelen van internettextures en het modelpad voor spawnen tijdens runtime.

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"

Sessieprofielen (OmsiLaunch.Core)#

Stabiliteit: EXPERIMENTAL. Deze typen compileren een YAML-sessieprofiel (<root>\.omsilaunch\session-profiles\<id>\profile.yaml, schema omsilaunch.session-profile/v1) tot een LaunchSpec. De CLI /predefined-profile:<id> /predefined-profile-index:<n> gebruikt precies deze aanroepen; een integrator kan ze gebruiken om een profiel via de API te starten.

De CLI weigert daarnaast opdrachtregelvlaggen die met het profiel conflicteren (OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT); die controle maakt geen deel uit van de compiler. Zie sessieprofielen voor de volledige samenvoegvolgorde.

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
}

Platformtypen (OmsiLaunch.Process)#

Threadveiligheid#

• OmsiLaunchService is veilig voor gelijktijdige aanroepen op verschillende sessies: sessies staan in een ConcurrentDictionary en elke wijziging per sessie gebeurt onder de eigen lock van de sessie.
• Gelijktijdige aanroepen op dezelfde sessie zijn veilig, maar worden geserialiseerd waar dat van belang is: ExecuteRuntimeAsync neemt een gate per sessie, zodat een tweede opdracht op de eerste wacht (de timeout ervan begint wanneer de opdracht wordt klaargezet).
• De supervisor draait als taak in de threadpool (Task.Run) vanaf het moment dat StartSessionAsync terugkeert totdat de sessie een eindtoestand bereikt; hij pollt de telemetrie en het proces elke 100 ms. Aanroepers voeren nooit supervisorcode uit.
• StopAsync en GetStatusAsync worden synchroon voltooid en kunnen vanuit elke thread worden aangeroepen, ook binnen een ProcessExit-handler (de CLI doet dit met een budget van 4 s).
• Geen enkele API-aanroep is aan een thread gebonden; geen enkele vereist een synchronisatiecontext.

Wat niet in de API zit#

• Geen IntPtr, nint, Win32-handles, native adressen, VMT-pointers of procesobjecten. Resultaatwaarden waarvan de sleutels met internal_ beginnen of op _address, _pointer, _vmt eindigen, worden verwijderd voordat een resultaat ExecuteRuntimeAsync verlaat.
• Geen internal.*-runtime-operaties: internal.road-vehicles.make-basic is InternalOnly in het register en retourneert OL_E_RUNTIME_OPERATION_UNKNOWN vanuit de API en de CLI.
• Geen directe lees- of schrijfacties in het OMSI-geheugen, geen toegang op bestandsniveau tot de installatie buiten wat een LaunchSpec declareert.
• Geen handles over procesgrenzen heen: het lokale control plane is de enige route tussen processen en accepteert alleen session.status, session.events, session.stop en runtime.execute.
• Geen coöperatief afsluiten van OMSI, geen LAST_MAP_STATE, geen toepassing van datum/tijd/weer/spelersvoertuig, geen overlays van toetsenbord-/controllerdocumenten op deze build.

Samenvatting van de stabiliteit#