Référence de l'API publique (OmsiLaunch.Api)

Documentation de la version v0.1.0-beta.3Voir la source sur GitHub

Traduction de la page originale en anglais d’OmsiLaunch 0.1.0-beta3. La page anglaise fait foi : en cas de divergence, la page anglaise et le code prévalent.

Cette page est la référence normative de l'API publique managée d'OmsiLaunch 0.1.0-beta3 : l'assembly OmsiLaunch.Api (contrats) et le point d'entrée pour les intégrateurs OmsiLaunchService dans OmsiLaunch.Core. Elle ne documente que ce que fait le code actuel. Tout ce qu'un intégrateur peut appeler, recevoir ou observer est listé ici avec son niveau de stabilité ; tout ce qui n'est pas listé n'est pas une surface d'intégration.

L'inventaire de l'API publique généré liste chaque type et membre public de OmsiLaunch.Api, OmsiLaunch.Core et OmsiLaunch.Process avec sa signature et sa stabilité ; un contrôle bloquant de documentation échoue lorsque l'inventaire et les assemblies divergent. Cette page en explique la sémantique.

Pages associées : référence LaunchSpec, codes d'erreur, cycle de vie de la session, transactions et récupération, contrôle runtime, capacités, plan de contrôle local, codes de sortie, état de la validation à l'exécution.

Vocabulaire de stabilité#

Vue d'ensemble des assemblies#

Point d'entrée : OmsiLaunchService et OmsiLaunchRuntimePaths#

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

Le service lit ces chemins à chaque PlanSessionAsync et StartSessionAsync ; il ne copie, ne prépare ni ne supprime jamais de fichiers du plugin (voir plugin permanent). La CLI construit le service exactement ainsi (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));

Créez un seul service par processus et partagez-le. Stabilité : STABLE_BETA.

Règles de propriété de la session#

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

Points communs à toutes les méthodes :

• Les handles inconnus ou déjà fermés lèvent KeyNotFoundException (« Unknown OmsiLaunch session. »).
• Aucune méthode n'exige une session Running, sauf ExecuteRuntimeAsync.
• Les exceptions qui portent un code OmsiLaunch placent le code au début de Exception.Message ("OL_E_PLAN_NOT_RUNNABLE: ..."). La CLI extrait les codes des messages de la même manière (CliProgram.Classify).
• Build pris en charge : uniquement Omsi23004_692EBFBF (plus le hash de la liste d'autorisation Steam LAA, accepté ; le gameplay n'est pas validé, il nécessite une véritable installation Steam). Voir compatibilité.

Exemple minimal complet#

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#

Valeurs et résultats de ContentQueryKind :

Les identités de point d'entrée servent uniquement à la découverte : le chemin de lancement utilise PresentedEntrypointIndex ; passer un EntrypointIdentity rend le plan non exécutable sur ce build (world.entrypoint-identity, RUNTIME_PARTIAL).

RecoverPendingAsync#

Types de contrat#

Valeurs optionnelles et primitives sémantiques#

Famille LaunchSpec#

Tous les records ci-dessous sont documentés propriété par propriété dans la référence LaunchSpec ; ce tableau fixe l'inventaire des types.

Types de plan et d'état#

SessionState#

Enum de type byte, dans l'ordre de déclaration : Created, ValidatingPlatform, Planning, AcquiringInstallationLock, RecoveringPreviousTransaction, Snapshotting, ApplyingConfiguration, DeployingRuntime, CreatingStartupHandoff, StartingProcess, WaitingForPlugin, PluginBootstrap, StartingWorld, EnteringGameplay, Running, ProcessExited, Restoring, CleaningRuntime, Completed, Failed. ValidatingPlatform, Planning et EnteringGameplay ne sont jamais définis par le service actuel ; Snapshotting est transitoire et pratiquement inobservable. États terminaux : Completed, Failed. Sémantique complète : cycle de vie de la session.

Types de contrôle runtime#

Le plugin rejette un handoff (plugin.request.unsupported → OL_E_CAPABILITY_UNAVAILABLE) sauf si WorldMode vaut NewMap ou SavedSituation, HeadlessStart vaut true, PlayerVehicleEnabled vaut false, les deux modes de date/heure valent Unset, et qu'une situation enregistrée a une identité non vide. Le planificateur applique les mêmes contraintes plus tôt, de sorte qu'un plan exécutable ne déclenche jamais ce rejet.

Types du registre des capacités#

Catalogue complet : capacités.

Méthodes d'extension D3DRuntimeApi#

Wrappers typés au-dessus de ExecuteRuntimeAsync pour les opérations d3d.* (EXPERIMENTAL, capacité PublicExperimental d3d.texture). Ils allouent les identifiants de requête à partir d'un compteur global au processus commençant à 30 000 et utilisent un timeout par défaut de 5 s (sauf GetD3DStatusAsync, qui en exige un).

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

Erreurs : un résultat en échec est relevé sous la forme OmsiRuntimeException(Code, detail), où Code est le ErrorCode du résultat (ou OL_E_RUNTIME_OPERATION_FAILED s'il est absent) et le message est "<code>: <Values["detail"]>" ; un résultat réussi sans valeurs, ou une chaîne d'état de périphérique inconnue, lève OmsiRuntimeException("OL_E_RUNTIME_PROTOCOL_MISMATCH", ...). Tout ce que lève ExecuteRuntimeAsync se propage sans modification. La gestion de la réinitialisation du périphérique est validée à l'exécution : une réinitialisation fait passer le périphérique par Resetting avant de revenir à Ready et invalide chaque texture active (OL_E_D3D_STALE_RESOURCE_HANDLE, clôture d'exécution D01) ; GetCapabilitiesAsync signale encore runtime.d3d.lifecycle.reset comme IMPLEMENTED_NOT_RUNTIME_VALIDATED (retard de l'auto-déclaration). La transition Lost ne peut pas être produite depuis l'extérieur du produit et n'est couverte que hors ligne.

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

Types de contrat du processus#

InstallationPaths (identité de l'installation et confinement des chemins)#

Stabilité : STABLE_BETA (fonctions pures, aucune E/S, aucun état OMSI, aucune modification du système de fichiers, aucune participation à une transaction, aucune session Running requise). C'est la définition unique utilisée par le bail d'installation, le nom du pipe de contrôle local, le confinement des ressources des profils de session, la validation des cibles des textures Internet et le chemin du modèle d'apparition 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"

Profils de session (OmsiLaunch.Core)#

Stabilité : EXPERIMENTAL. Ces types compilent un profil de session YAML (<root>\.omsilaunch\session-profiles\<id>\profile.yaml, schéma omsilaunch.session-profile/v1) en LaunchSpec. L'option CLI /predefined-profile:<id> /predefined-profile-index:<n> utilise exactement ces appels ; un intégrateur peut les utiliser pour démarrer un profil via l'API.

La CLI rejette en outre les options de ligne de commande qui entrent en conflit avec le profil (OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT) ; cette vérification ne fait pas partie du compilateur. Voir profils de session pour l'ordre de fusion complet.

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
}

Types de plateforme (OmsiLaunch.Process)#

Sécurité des threads#

• OmsiLaunchService prend en charge les appels concurrents sur des sessions différentes : les sessions résident dans un ConcurrentDictionary et chaque modification propre à une session se produit sous le verrou privé de cette session.
• Les appels concurrents sur une même session sont sûrs mais sérialisés là où c'est nécessaire : ExecuteRuntimeAsync prend une barrière par session, de sorte qu'une seconde commande attend la première (son timeout commence lorsqu'elle est déposée).
• Le superviseur s'exécute sur une tâche du pool de threads (Task.Run) depuis le retour de StartSessionAsync jusqu'à ce que la session soit terminale ; il interroge la télémétrie et le processus toutes les 100 ms. Les appelants n'exécutent jamais de code du superviseur.
• StopAsync et GetStatusAsync se terminent de façon synchrone et peuvent être appelés depuis n'importe quel thread, y compris dans un gestionnaire ProcessExit (la CLI le fait avec un budget de 4 s).
• Aucun appel de l'API n'est lié à un thread ; aucun n'exige de contexte de synchronisation.

Ce qui ne fait pas partie de l'API#

• Aucun IntPtr, nint, handle Win32, adresse native, pointeur de VMT ni objet processus. Les valeurs de résultat dont les clés commencent par internal_ ou se terminent par _address, _pointer, _vmt sont supprimées avant qu'un résultat ne quitte ExecuteRuntimeAsync.
• Aucune opération runtime internal.* : internal.road-vehicles.make-basic est InternalOnly dans le registre et renvoie OL_E_RUNTIME_OPERATION_UNKNOWN depuis l'API et la CLI.
• Aucune lecture ni écriture brute de la mémoire d'OMSI, aucun accès au niveau fichier à l'installation au-delà de ce que déclare un LaunchSpec.
• Aucun handle inter-processus : le plan de contrôle local est la seule voie inter-processus, et il n'accepte que session.status, session.events, session.stop et runtime.execute.
• Pas d'arrêt coopératif d'OMSI, pas de LAST_MAP_STATE, pas d'application de date/heure/météo/véhicule du joueur, pas d'overlays de documents clavier/manette sur ce build.

Résumé de la stabilité#