Riferimento dell'API pubblica (OmsiLaunch.Api)

Documentazione della versione v0.1.0-beta.3Vedi il sorgente su GitHub

Traduzione della pagina originale in inglese di OmsiLaunch 0.1.0-beta3. La pagina inglese è normativa: in caso di differenze prevalgono la pagina inglese e il codice.

Questa pagina è il riferimento normativo per l'API pubblica gestita di OmsiLaunch 0.1.0-beta3: l'assembly OmsiLaunch.Api (contratti) e il punto di ingresso per gli integratori OmsiLaunchService in OmsiLaunch.Core. Documenta soltanto ciò che fa il codice attuale. Tutto ciò che un integratore può chiamare, ricevere oppure osservare è elencato qui con il relativo livello di stabilità; ciò che non è elencato non è una superficie di integrazione.

L'inventario dell'API pubblica, generato automaticamente, elenca ogni tipo e membro pubblico di OmsiLaunch.Api, OmsiLaunch.Core e OmsiLaunch.Process con la relativa firma e stabilità; un gate della documentazione fallisce quando l'inventario e gli assembly differiscono. Questa pagina ne spiega la semantica.

Pagine correlate: riferimento LaunchSpec, codici di errore, ciclo di vita della sessione, transazioni e recupero, controllo runtime, capability, piano di controllo locale, codici di uscita, stato della validazione a runtime.

Vocabolario della stabilità#

Panoramica degli assembly#

Punto di ingresso: OmsiLaunchService e OmsiLaunchRuntimePaths#

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

Il servizio legge questi percorsi a ogni PlanSessionAsync e StartSessionAsync; non copia, non prepara e non rimuove mai file del plugin (vedere plugin permanente). La CLI costruisce il servizio esattamente in questo modo (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));

Creare un solo servizio per processo e condividerlo. Stabilità: STABLE_BETA.

Regole di proprietà della sessione#

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

Fatti comuni a tutti i metodi:

• Gli handle sconosciuti o già chiusi generano KeyNotFoundException ("Unknown OmsiLaunch session.").
• Nessun metodo richiede una sessione in stato Running, tranne ExecuteRuntimeAsync.
• Le eccezioni che trasportano un codice OmsiLaunch collocano il codice all'inizio di Exception.Message ("OL_E_PLAN_NOT_RUNNABLE: ..."). La CLI estrae i codici dai messaggi nello stesso modo (CliProgram.Classify).
• Build supportato: solo Omsi23004_692EBFBF (più l'hash della allow-list Steam LAA, accettato; gameplay non validato, richiede un'installazione Steam autentica). Vedere compatibilità.

Esempio minimo completo#

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#

Valori di ContentQueryKind e risultati:

Le identità dei punti di ingresso servono solo per l'individuazione: il percorso di avvio usa PresentedEntrypointIndex; passare una EntrypointIdentity rende il piano non eseguibile su questo build (world.entrypoint-identity, RUNTIME_PARTIAL).

RecoverPendingAsync#

Tipi del contratto#

Valori facoltativi e primitive semantiche#

Famiglia LaunchSpec#

Tutti i record seguenti sono documentati proprietà per proprietà nel riferimento LaunchSpec; questa tabella fissa l'inventario dei tipi.

Tipi di piano e di stato#

SessionState#

Enum di tipo byte, nell'ordine di dichiarazione: Created, ValidatingPlatform, Planning, AcquiringInstallationLock, RecoveringPreviousTransaction, Snapshotting, ApplyingConfiguration, DeployingRuntime, CreatingStartupHandoff, StartingProcess, WaitingForPlugin, PluginBootstrap, StartingWorld, EnteringGameplay, Running, ProcessExited, Restoring, CleaningRuntime, Completed, Failed. ValidatingPlatform, Planning ed EnteringGameplay non vengono mai impostati dal servizio attuale; Snapshotting è transitorio e in pratica non osservabile. Stati terminali: Completed, Failed. Semantica completa: ciclo di vita della sessione.

Tipi del controllo runtime#

Il plugin rifiuta un handoff (plugin.request.unsupported → OL_E_CAPABILITY_UNAVAILABLE) a meno che WorldMode sia NewMap o SavedSituation, HeadlessStart sia true, PlayerVehicleEnabled sia false, entrambe le modalità di data e ora siano Unset e una situazione salvata abbia un'identità non vuota. Il pianificatore impone gli stessi vincoli in precedenza, quindi un piano eseguibile non attiva mai questo rifiuto.

Tipi del registro delle capability#

Catalogo completo: capability.

Metodi di estensione D3DRuntimeApi#

Wrapper tipizzati su ExecuteRuntimeAsync per le operazioni d3d.* (EXPERIMENTAL, capability PublicExperimental d3d.texture). Allocano gli id di richiesta da un contatore a livello di processo che parte da 30 000 e usano come timeout predefinito 5 s (tranne GetD3DStatusAsync, che ne richiede uno esplicito).

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

Errori: un risultato fallito viene rilanciato come OmsiRuntimeException(Code, detail), dove Code è l'ErrorCode del risultato (oppure OL_E_RUNTIME_OPERATION_FAILED se assente) e il messaggio è "<code>: <Values["detail"]>"; un risultato riuscito senza valori, oppure una stringa di stato del dispositivo sconosciuta, genera OmsiRuntimeException("OL_E_RUNTIME_PROTOCOL_MISMATCH", ...). Tutto ciò che genera ExecuteRuntimeAsync si propaga invariato. La gestione del reset del dispositivo è validata a runtime: un reset porta il dispositivo attraverso Resetting di nuovo a Ready e invalida ogni texture attiva (OL_E_D3D_STALE_RESOURCE_HANDLE, chiusura di runtime D01); GetCapabilitiesAsync riporta ancora runtime.d3d.lifecycle.reset come IMPLEMENTED_NOT_RUNTIME_VALIDATED (ritardo dell'auto-dichiarazione). La transizione Lost non può essere prodotta dall'esterno del prodotto ed è coperta solo 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);
}

Tipi del contratto di processo#

InstallationPaths (identità dell'installazione e contenimento dei percorsi)#

Stabilità: STABLE_BETA (funzioni pure, nessun I/O, nessuno stato di OMSI, nessuna modifica del file system, nessuna partecipazione alla transazione, nessuna sessione in stato Running richiesta). È la definizione unica usata dal lease dell'installazione, dal nome della pipe del controllo locale, dal confinamento degli asset dei profili di sessione, dalla validazione delle destinazioni di Internet Textures (texture da Internet) e dal percorso del modello per lo spawn a 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"

Profili di sessione (OmsiLaunch.Core)#

Stabilità: EXPERIMENTAL. Questi tipi compilano un profilo di sessione YAML (<root>\.omsilaunch\session-profiles\<id>\profile.yaml, schema omsilaunch.session-profile/v1) in una LaunchSpec. L'opzione CLI /predefined-profile:<id> /predefined-profile-index:<n> usa esattamente queste chiamate; un integratore può usarle per avviare un profilo tramite l'API.

La CLI rifiuta inoltre i flag della riga di comando in conflitto con il profilo (OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT); questo controllo non fa parte del compilatore. Vedere profili di sessione per l'ordine di unione completo.

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
}

Tipi di piattaforma (OmsiLaunch.Process)#

Sicurezza rispetto ai thread#

• OmsiLaunchService è sicuro per chiamate concorrenti su sessioni diverse: le sessioni risiedono in un ConcurrentDictionary e ogni modifica relativa a una sessione avviene sotto il lock privato di quella sessione.
• Le chiamate concorrenti sulla stessa sessione sono sicure ma serializzate dove necessario: ExecuteRuntimeAsync acquisisce un gate per sessione, quindi un secondo comando attende il primo (il suo timeout parte quando viene depositato nella mailbox).
• Il supervisore viene eseguito su un task del thread pool (Task.Run) dal momento in cui StartSessionAsync ritorna finché la sessione non è terminale; interroga la telemetria e il processo ogni 100 ms. I chiamanti non eseguono mai codice del supervisore.
• StopAsync e GetStatusAsync si completano in modo sincrono e possono essere chiamati da qualsiasi thread, anche all'interno di un handler ProcessExit (la CLI lo fa con un margine di 4 s).
• Nessuna chiamata dell'API è legata a un thread specifico; nessuna richiede un contesto di sincronizzazione.

Ciò che non fa parte dell'API#

• Nessun IntPtr, nint, handle Win32, indirizzo nativo, puntatore VMT o oggetto processo. I valori dei risultati le cui chiavi iniziano con internal_ o terminano con _address, _pointer, _vmt vengono rimossi prima che un risultato esca da ExecuteRuntimeAsync.
• Nessuna operazione runtime internal.*: internal.road-vehicles.make-basic è InternalOnly nel registro e restituisce OL_E_RUNTIME_OPERATION_UNKNOWN dall'API e dalla CLI.
• Nessuna lettura o scrittura diretta della memoria di OMSI, nessun accesso a livello di file all'installazione al di fuori di quanto dichiarato da una LaunchSpec.
• Nessun handle tra processi: il piano di controllo locale è l'unica via tra processi e accetta solo session.status, session.events, session.stop e runtime.execute.
• Nessuna chiusura cooperativa di OMSI, nessun LAST_MAP_STATE, nessuna applicazione di data/ora/meteo/veicolo del giocatore, nessun overlay di documenti di tastiera/controller su questo build.

Riepilogo della stabilità#