Dokumentacja publicznego API (OmsiLaunch.Api)

Dokumentacja wersji v0.1.0-beta.3Zobacz źródło na GitHubie

Tłumaczenie oryginalnej strony w języku angielskim dla OmsiLaunch 0.1.0-beta3. Wiążąca jest strona angielska: w razie rozbieżności obowiązują strona angielska i kod.

Ta strona jest normatywną dokumentacją zarządzanego publicznego API OmsiLaunch 0.1.0-beta3: zestawu OmsiLaunch.Api (kontrakty) oraz punktu wejścia dla integratorów OmsiLaunchService w OmsiLaunch.Core. Opisuje wyłącznie to, co robi bieżący kod. Wszystko, co integrator może wywołać, otrzymać lub zaobserwować, jest tu wymienione wraz z poziomem stabilności; to, czego tu nie wymieniono, nie jest powierzchnią integracji.

Generowany spis publicznego API wymienia każdy publiczny typ i składową OmsiLaunch.Api, OmsiLaunch.Core i OmsiLaunch.Process wraz z sygnaturą i stabilnością; bramka dokumentacji kończy się niepowodzeniem, gdy spis i zestawy się różnią. Ta strona objaśnia semantykę.

Powiązane strony: dokumentacja LaunchSpec, kody błędów, cykl życia sesji, transakcje i odzyskiwanie, sterowanie runtime, możliwości, lokalna płaszczyzna sterowania, kody wyjścia, stan weryfikacji w runtime.

Słownik stabilności#

Przegląd zestawów#

Punkt wejścia: OmsiLaunchService i OmsiLaunchRuntimePaths#

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

Usługa odczytuje te ścieżki przy każdym wywołaniu PlanSessionAsync i StartSessionAsync; nigdy nie kopiuje, nie przygotowuje ani nie usuwa plików wtyczki (zob. stała wtyczka). CLI tworzy usługę dokładnie w ten sposób (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));

Należy utworzyć jedną usługę na proces i ją współdzielić. Stabilność: STABLE_BETA.

Zasady własności sesji#

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

Wspólne zasady dla każdej metody:

• Nieznane lub już zamknięte uchwyty zgłaszają KeyNotFoundException („Unknown OmsiLaunch session.”).
• Żadna metoda poza ExecuteRuntimeAsync nie wymaga sesji w stanie Running.
• Wyjątki niosące kod OmsiLaunch umieszczają ten kod na początku Exception.Message ("OL_E_PLAN_NOT_RUNNABLE: ..."). CLI wyodrębnia kody z komunikatów w ten sam sposób (CliProgram.Classify).
• Obsługiwany build: tylko Omsi23004_692EBFBF (oraz skrót z listy dozwolonych Steam LAA – akceptowany; rozgrywka niezweryfikowana, wymaga prawdziwej instalacji Steam). Zob. zgodność.

Kompletny minimalny przykład#

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#

Wartości ContentQueryKind i wyniki:

Tożsamości punktów wejścia służą wyłącznie do wykrywania: ścieżka uruchamiania używa PresentedEntrypointIndex; przekazanie EntrypointIdentity czyni plan w tym buildzie niemożliwym do uruchomienia (world.entrypoint-identity, RUNTIME_PARTIAL).

RecoverPendingAsync#

Typy kontraktu#

Wartości opcjonalne i prymitywy semantyczne#

Rodzina LaunchSpec#

Wszystkie poniższe rekordy są opisane właściwość po właściwości w dokumentacji LaunchSpec; ta tabela ustala spis typów.

Typy planu i stanu#

SessionState#

Typ wyliczeniowy oparty na bajcie, w kolejności deklaracji: Created, ValidatingPlatform, Planning, AcquiringInstallationLock, RecoveringPreviousTransaction, Snapshotting, ApplyingConfiguration, DeployingRuntime, CreatingStartupHandoff, StartingProcess, WaitingForPlugin, PluginBootstrap, StartingWorld, EnteringGameplay, Running, ProcessExited, Restoring, CleaningRuntime, Completed, Failed. ValidatingPlatform, Planning i EnteringGameplay nigdy nie są ustawiane przez bieżącą usługę; Snapshotting jest stanem przejściowym i praktycznie niemożliwym do zaobserwowania. Stany końcowe: Completed, Failed. Pełna semantyka: cykl życia sesji.

Typy sterowania runtime#

Wtyczka odrzuca przekazanie (plugin.request.unsupported → OL_E_CAPABILITY_UNAVAILABLE), chyba że WorldMode to NewMap lub SavedSituation, HeadlessStart ma wartość true, PlayerVehicleEnabled ma wartość false, oba tryby daty/czasu to Unset, a zapisana sytuacja ma niepustą tożsamość. Planista egzekwuje te same ograniczenia wcześniej, więc plan możliwy do uruchomienia nigdy tego nie wyzwala.

Typy rejestru możliwości#

Pełny katalog: możliwości.

Metody rozszerzające D3DRuntimeApi#

Typowane opakowania ExecuteRuntimeAsync dla operacji d3d.* (EXPERIMENTAL, możliwość PublicExperimental d3d.texture). Przydzielają identyfikatory żądań z licznika wspólnego dla całego procesu, zaczynającego się od 30 000, i domyślnie ustawiają limit czasu na 5 s (z wyjątkiem GetD3DStatusAsync, która go wymaga).

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

Błędy: nieudany wynik jest ponownie zgłaszany jako OmsiRuntimeException(Code, detail), gdzie Code to ErrorCode wyniku (lub OL_E_RUNTIME_OPERATION_FAILED, gdy go brak), a komunikat ma postać "<code>: <Values["detail"]>"; udany wynik bez wartości albo nieznany ciąg stanu urządzenia powoduje zgłoszenie OmsiRuntimeException("OL_E_RUNTIME_PROTOCOL_MISMATCH", ...). Wszystko, co zgłasza ExecuteRuntimeAsync, propaguje się bez zmian. Obsługa resetu urządzenia jest zweryfikowana w runtime: reset przeprowadza urządzenie przez Resetting z powrotem do Ready i unieważnia każdą aktywną teksturę (OL_E_D3D_STALE_RESOURCE_HANDLE, domknięcie weryfikacji w runtime D01); GetCapabilitiesAsync nadal zgłasza runtime.d3d.lifecycle.reset jako IMPLEMENTED_NOT_RUNTIME_VALIDATED (opóźnienie samoraportu względem dowodów). Przejścia Lost nie da się wywołać spoza produktu i jest ono pokryte wyłącznie testami offline.

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

Typy kontraktu procesu#

InstallationPaths (tożsamość instalacji i zawieranie ścieżek)#

Stabilność: STABLE_BETA (funkcje czyste, bez operacji we/wy, bez stanu OMSI, bez modyfikacji systemu plików, bez udziału w transakcji, bez wymogu sesji w stanie Running). Jest to jedyna definicja używana przez dzierżawę instalacji, nazwę potoku lokalnego sterowania, ograniczanie zasobów profilu sesji do pakietu, walidację celów tekstur internetowych oraz ścieżkę modelu przy dodawaniu pojazdów w 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"

Profile sesji (OmsiLaunch.Core)#

Stabilność: EXPERIMENTAL. Te typy kompilują profil sesji w formacie YAML (<root>\.omsilaunch\session-profiles\<id>\profile.yaml, schemat omsilaunch.session-profile/v1) do LaunchSpec. Polecenie CLI /predefined-profile:<id> /predefined-profile-index:<n> używa dokładnie tych wywołań; integrator może ich użyć, aby uruchomić profil przez API.

CLI dodatkowo odrzuca flagi wiersza poleceń sprzeczne z profilem (OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT); to sprawdzenie nie jest częścią kompilatora. Pełna kolejność scalania: profile sesji.

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
}

Typy platformy (OmsiLaunch.Process)#

Bezpieczeństwo wątków#

• OmsiLaunchService jest bezpieczna dla współbieżnych wywołań dotyczących różnych sesji: sesje są przechowywane w ConcurrentDictionary, a każda modyfikacja dotycząca sesji odbywa się pod prywatną blokadą tej sesji.
• Współbieżne wywołania dotyczące tej samej sesji są bezpieczne, ale tam, gdzie ma to znaczenie, są serializowane: ExecuteRuntimeAsync pobiera bramkę sesji, więc drugie polecenie czeka na pierwsze (jego limit czasu zaczyna biec w chwili umieszczenia w skrzynce).
• Nadzorca działa jako zadanie puli wątków (Task.Run) od chwili powrotu z StartSessionAsync aż do osiągnięcia przez sesję stanu końcowego; co 100 ms odpytuje telemetrię i proces. Kod wywołujący nigdy nie wykonuje kodu nadzorcy.
• StopAsync i GetStatusAsync kończą się synchronicznie i mogą być wywoływane z dowolnego wątku, także wewnątrz procedury obsługi ProcessExit (CLI robi to z budżetem 4 s).
• Żadne wywołanie API nie jest powiązane z konkretnym wątkiem; żadne nie wymaga kontekstu synchronizacji.

Czego nie ma w API#

• Brak IntPtr, nint, uchwytów Win32, adresów natywnych, wskaźników VMT i obiektów procesów. Wartości wyniku, których klucze zaczynają się od internal_ lub kończą na _address, _pointer, _vmt, są usuwane, zanim wynik opuści ExecuteRuntimeAsync.
• Brak operacji runtime internal.*: internal.road-vehicles.make-basic ma w rejestrze klasyfikację InternalOnly i zwraca OL_E_RUNTIME_OPERATION_UNKNOWN zarówno z API, jak i z CLI.
• Brak surowych odczytów i zapisów pamięci OMSI oraz brak dostępu do plików instalacji innego niż zadeklarowany w LaunchSpec.
• Brak uchwytów międzyprocesowych: lokalna płaszczyzna sterowania jest jedyną drogą międzyprocesową i akceptuje wyłącznie session.status, session.events, session.stop i runtime.execute.
• W tym buildzie brak kooperacyjnego zamykania OMSI, brak LAST_MAP_STATE, brak stosowania daty/czasu/pogody/pojazdu gracza i brak nakładek dokumentów klawiatury/kontrolera.

Podsumowanie stabilności#