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

Documentación de la versión v0.1.0-beta.3Ver 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 difieren, prevalecen la página en inglés y el código.

Esta página es la referencia normativa de la API pública gestionada 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 figura aquí con su nivel de estabilidad; lo que no aparece 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 control de 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#

Visió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 (consulta 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));

Crea un único servicio por proceso y compártelo. 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 ejecución (Running), salvo ExecuteRuntimeAsync.
• Las excepciones que llevan un código de OmsiLaunch colocan el código al principio de Exception.Message ("OL_E_PLAN_NOT_RUNNABLE: ..."). La CLI extrae los códigos de los mensajes de la misma manera (CliProgram.Classify).
• Build compatible: solo Omsi23004_692EBFBF (más el hash de la lista de permitidos de Steam LAA, aceptado; la fase de juego no está validada, requiere una instalación de Steam auténtica). Consulta 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 sirven solo para el descubrimiento: la ruta de lanzamiento usa PresentedEntrypointIndex; pasar un EntrypointIdentity hace que el plan no sea ejecutable en esta build (world.entrypoint-identity, RUNTIME_PARTIAL).

RecoverPendingAsync#

Tipos del contrato#

Valores opcionales y primitivas semánticas#

Familia LaunchSpec#

Todos los records siguientes se documentan 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 prácticamente inobservable. Estados terminales: Completed, Failed. Semántica completa: ciclo de vida de la sesión.

Tipos de 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 y hora sean Unset y una situación guardada tenga una identidad no vacía. El planificador aplica las mismas restricciones antes, así que un plan ejecutable nunca provoca este rechazo.

Tipos del registro de capacidades#

Catálogo completo: capacidades.

Métodos de extensión de D3DRuntimeApi#

Envoltorios tipados sobre ExecuteRuntimeAsync para las operaciones d3d.* (EXPERIMENTAL, capacidad PublicExperimental d3d.texture). Asignan los ids de solicitud a partir de un contador de ámbito de proceso que empieza en 30 000 y usan un timeout predeterminado de 5 s (salvo GetD3DStatusAsync, que exige uno).

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 (u OL_E_RUNTIME_OPERATION_FAILED si no lo hay) y el mensaje es "<code>: <Values["detail"]>"; un resultado correcto 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. La gestión del reset del dispositivo está validada en runtime: un reset hace pasar el dispositivo por Resetting de vuelta a Ready e invalida todas las texturas activas (OL_E_D3D_STALE_RESOURCE_HANDLE, cierre de validación en runtime D01); GetCapabilitiesAsync sigue notificando runtime.d3d.lifecycle.reset como IMPLEMENTED_NOT_RUNTIME_VALIDATED (retraso del autoinforme). La transición Lost no se puede producir 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 de 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 necesidad de una sesión en ejecución). Es la definición única que usan el lease de la instalación, el nombre de la canalización de control local, el confinamiento de los recursos de los perfiles de sesión, la validación de destinos de las texturas de Internet y la ruta del modelo para la generación 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 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 a través de la API.

Además, la CLI rechaza los flags de línea de comandos que entran en conflicto con el perfil (OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT); esa comprobación no forma parte del compilador. Consulta perfiles de sesión para ver el orden completo de combinación.

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 para subprocesos#

• OmsiLaunchService admite llamadas concurrentes sobre sesiones distintas: las sesiones residen en un ConcurrentDictionary y toda modificación de una sesión se hace 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 una barrera por sesión, de modo que un segundo comando espera al primero (su timeout empieza cuando se deposita).
• 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; sondea la telemetría y el proceso cada 100 ms. Los llamadores nunca ejecutan código del supervisor.
• StopAsync y GetStatusAsync se completan de forma síncrona y se pueden llamar desde cualquier thread, incluso dentro de un controlador ProcessExit (la CLI lo hace con un margen de 4 s).
• Ninguna llamada de la API está ligada a un thread; ninguna requiere un contexto de sincronización.

Lo que no está en la API#

• Ningún IntPtr, nint, handle de Win32, dirección nativa, puntero de VMT ni objeto de proceso. Los valores del resultado cuyas claves empiezan por internal_ o terminan en _address, _pointer, _vmt se eliminan antes de que un resultado salga de ExecuteRuntimeAsync.
• Ninguna operación 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.
• Ninguna lectura ni escritura directa de la memoria de OMSI, ningún acceso a nivel de archivo a la instalación más allá de lo que declara un LaunchSpec.
• Ningún handle entre procesos: el plano de control local es la única vía entre procesos y solo acepta session.status, session.events, session.stop y runtime.execute.
• Ningún cierre cooperativo de OMSI, ningún LAST_MAP_STATE, ninguna aplicación de fecha/hora/meteorología/vehículo del jugador y ningún overlay de documentos de teclado/mando en esta build.

Resumen de estabilidad#