Referencia de la API pública (OmsiLaunch.Api)

Documentación de la versión v0.1.0-beta.3Ver código fuente en GitHub

Traducción de la página original en inglés de OmsiLaunch 0.1.0-beta3. La página en inglés es la referencia normativa: si hay diferencias, prevalecen la página en inglés y el código.

Esta página es la referencia normativa de la API pública administrada de OmsiLaunch 0.1.0-beta3: el ensamblado OmsiLaunch.Api (contratos) y el punto de entrada para integradores OmsiLaunchService en OmsiLaunch.Core. Documenta únicamente lo que hace el código actual. Todo lo que un integrador puede llamar, recibir u observar se enumera aquí con su nivel de estabilidad; todo lo que no aparece en esta página no es una superficie de integración.

El inventario de la API pública generado enumera cada tipo y miembro público de OmsiLaunch.Api, OmsiLaunch.Core y OmsiLaunch.Process con su firma y su estabilidad; un gate de documentación (control de calidad de la documentación) falla cuando el inventario y los ensamblados difieren. Esta página explica la semántica.

Páginas relacionadas: referencia de LaunchSpec, códigos de error, ciclo de vida de la sesión, transacciones y recuperación, control de runtime, capacidades, plano de control local, códigos de salida, estado de la validación en runtime.

Vocabulario de estabilidad#

Descripción general de los ensamblados#

Punto de entrada: OmsiLaunchService y OmsiLaunchRuntimePaths#

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

El servicio lee estas rutas en cada PlanSessionAsync y StartSessionAsync; nunca copia, prepara ni elimina archivos del plugin (consulte plugin permanente). La CLI construye el servicio exactamente así (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));

Cree un único servicio por proceso y compártalo. Estabilidad: STABLE_BETA.

Reglas de propiedad de la sesión#

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

Hechos comunes a todos los métodos:

• Los handles desconocidos o ya cerrados lanzan KeyNotFoundException ("Unknown OmsiLaunch session.").
• Ningún método requiere una sesión en estado Running, salvo ExecuteRuntimeAsync.
• Las excepciones que llevan un código de OmsiLaunch colocan el código al comienzo de Exception.Message ("OL_E_PLAN_NOT_RUNNABLE: ..."). La CLI extrae los códigos de los mensajes de la misma forma (CliProgram.Classify).
• Build compatible: solo Omsi23004_692EBFBF (más el hash de la lista de permitidos de Steam LAA, que se acepta; el gameplay no está validado, ya que requiere una instalación genuina de Steam). Consulte compatibilidad.

Ejemplo mínimo 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#

Valores de ContentQueryKind y resultados:

Las identidades de punto de entrada son solo para el descubrimiento: la ruta de inicio usa PresentedEntrypointIndex; pasar un EntrypointIdentity vuelve no ejecutable el plan en este build (world.entrypoint-identity, RUNTIME_PARTIAL).

RecoverPendingAsync#

Tipos del contrato#

Valores opcionales y primitivas semánticas#

Familia de LaunchSpec#

Todos los records siguientes están documentados propiedad por propiedad en la referencia de LaunchSpec; esta tabla fija el inventario de tipos.

Tipos de plan y de estado#

SessionState#

Enum de tipo byte en orden de declaración: Created, ValidatingPlatform, Planning, AcquiringInstallationLock, RecoveringPreviousTransaction, Snapshotting, ApplyingConfiguration, DeployingRuntime, CreatingStartupHandoff, StartingProcess, WaitingForPlugin, PluginBootstrap, StartingWorld, EnteringGameplay, Running, ProcessExited, Restoring, CleaningRuntime, Completed, Failed. El servicio actual nunca establece ValidatingPlatform, Planning ni EnteringGameplay; Snapshotting es transitorio y en la práctica no se puede observar. Estados terminales: Completed, Failed. Semántica completa: ciclo de vida de la sesión.

Tipos del control de runtime#

El plugin rechaza un handoff (plugin.request.unsupported → OL_E_CAPABILITY_UNAVAILABLE) salvo que WorldMode sea NewMap o SavedSituation, HeadlessStart sea true, PlayerVehicleEnabled sea false, ambos modos de fecha/hora sean Unset y, en el caso de una situación guardada, esta tenga una identidad no vacía. El planificador aplica las mismas restricciones antes, por lo que un plan ejecutable nunca provoca este rechazo.

Tipos del registro de capacidades#

Catálogo completo: capacidades.

Métodos de extensión de D3DRuntimeApi#

Wrappers tipados sobre ExecuteRuntimeAsync para las operaciones d3d.* (EXPERIMENTAL, capacidad PublicExperimental d3d.texture). Asignan los ids de solicitud a partir de un contador global del proceso que comienza en 30 000 y usan un timeout predeterminado de 5 s (excepto GetD3DStatusAsync, que requiere uno explícito).

Tipos: 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.

Errores: un resultado fallido se vuelve a lanzar como OmsiRuntimeException(Code, detail), donde Code es el ErrorCode del resultado (o OL_E_RUNTIME_OPERATION_FAILED cuando falta) y el mensaje es "<code>: <Values["detail"]>"; un resultado exitoso sin valores, o una cadena de estado del dispositivo desconocida, lanza OmsiRuntimeException("OL_E_RUNTIME_PROTOCOL_MISMATCH", ...). Todo lo que lanza ExecuteRuntimeAsync se propaga sin cambios. El manejo del reinicio del dispositivo (D3D) está validado en runtime: un reinicio hace pasar el dispositivo por Resetting y lo devuelve a Ready, e invalida todas las texturas vivas (OL_E_D3D_STALE_RESOURCE_HANDLE, cierre de validación en runtime D01); GetCapabilitiesAsync todavía informa runtime.d3d.lifecycle.reset como IMPLEMENTED_NOT_RUNTIME_VALIDATED (desfase del autoinforme). La transición a Lost no puede producirse desde fuera del producto y solo está cubierta 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);
}

Tipos del contrato del proceso#

InstallationPaths (identidad de la instalación y contención de rutas)#

Estabilidad: STABLE_BETA (funciones puras, sin E/S, sin estado de OMSI, sin modificaciones del sistema de archivos, sin participación en transacciones, sin requerir una sesión en estado Running). Es la única definición que usan el lease de la instalación, el nombre del pipe de control local, el confinamiento de los assets de los perfiles de sesión, la validación de los destinos de Internet Textures y la ruta del modelo de generación (spawn) en 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"

Perfiles de sesión (OmsiLaunch.Core)#

Estabilidad: EXPERIMENTAL. Estos tipos compilan un perfil de sesión en YAML (<root>\.omsilaunch\session-profiles\<id>\profile.yaml, esquema omsilaunch.session-profile/v1) en un LaunchSpec. La CLI /predefined-profile:<id> /predefined-profile-index:<n> usa exactamente estas llamadas; un integrador puede usarlas para iniciar un perfil mediante la API.

La CLI además rechaza los flags de línea de comandos que entran en conflicto con el perfil (OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT); esa verificación no forma parte del compilador. Consulte perfiles de sesión para ver el orden de combinación 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
}

Tipos de plataforma (OmsiLaunch.Process)#

Seguridad de threads#

• OmsiLaunchService admite llamadas concurrentes sobre sesiones distintas: las sesiones residen en un ConcurrentDictionary y cada modificación por sesión ocurre bajo el bloqueo privado de esa sesión.
• Las llamadas concurrentes sobre la misma sesión son seguras, pero se serializan donde importa: ExecuteRuntimeAsync toma un gate por sesión, por lo que un segundo comando espera al primero (su timeout comienza cuando se deposita en el buzón).
• El supervisor se ejecuta en una tarea del grupo de threads (Task.Run) desde el momento en que StartSessionAsync retorna hasta que la sesión es terminal; consulta la telemetría y el proceso cada 100 ms. Los llamadores nunca ejecutan código del supervisor.
• StopAsync y GetStatusAsync se completan de forma sincrónica y se pueden llamar desde cualquier thread, incluso dentro de un manejador de ProcessExit (la CLI lo hace con un margen de 4 s).
• Ninguna llamada de la API tiene afinidad de thread; ninguna requiere un contexto de sincronización.

Lo que no está en la API#

• No hay IntPtr, nint, handles de Win32, direcciones nativas, punteros a VMT ni objetos de proceso. Los valores del resultado cuyas claves comienzan con internal_ o terminan en _address, _pointer, _vmt se eliminan antes de que un resultado salga de ExecuteRuntimeAsync.
• No hay operaciones de runtime internal.*: internal.road-vehicles.make-basic es InternalOnly en el registro y devuelve OL_E_RUNTIME_OPERATION_UNKNOWN desde la API y desde la CLI.
• No hay lecturas ni escrituras directas de la memoria de OMSI, ni acceso a nivel de archivo a la instalación más allá de lo que declara un LaunchSpec.
• No hay handles entre procesos: el plano de control local es la única ruta entre procesos, y solo acepta session.status, session.events, session.stop y runtime.execute.
• En este build no hay cierre cooperativo de OMSI, ni LAST_MAP_STATE, ni aplicación de fecha/hora/clima/vehículo del jugador, ni overlays de documentos de teclado/controlador.

Resumen de estabilidad#