Referência da API pública (OmsiLaunch.Api)

Documentação da versão v0.1.0-beta.3Ver código-fonte no GitHub

Tradução da página original em inglês do OmsiLaunch 0.1.0-beta3. A página em inglês é a referência normativa: em caso de divergência, prevalecem a página em inglês e o código.

Esta página é a referência normativa da API pública gerida do OmsiLaunch 0.1.0-beta3: o assembly OmsiLaunch.Api (contratos) e o ponto de entrada para integradores OmsiLaunchService em OmsiLaunch.Core. Documenta apenas o que o código atual faz. Tudo o que um integrador pode chamar, receber ou observar está aqui listado com o respetivo nível de estabilidade; o que não estiver listado não é uma superfície de integração.

O inventário da API pública gerado lista todos os tipos e membros públicos de OmsiLaunch.Api, OmsiLaunch.Core e OmsiLaunch.Process com a respetiva assinatura e estabilidade; um gate de documentação (verificação obrigatória) falha quando o inventário e os assemblies divergem. Esta página explica a semântica.

Páginas relacionadas: referência do LaunchSpec, códigos de erro, ciclo de vida da sessão, transações e recuperação, controlo de runtime, capacidades, plano de controlo local, códigos de saída, estado da validação em runtime.

Vocabulário de estabilidade#

Visão geral dos assemblies#

Ponto de entrada: 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);
}

O serviço lê estes caminhos em cada PlanSessionAsync e StartSessionAsync; nunca copia, prepara nem remove ficheiros do plugin (ver plugin permanente). A CLI constrói o serviço exatamente assim (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));

Deve criar-se um serviço por processo e partilhá-lo. Estabilidade: STABLE_BETA.

Regras de propriedade da sessão#

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

Factos comuns a todos os métodos:

• Handles desconhecidos ou já fechados lançam KeyNotFoundException ("Unknown OmsiLaunch session.").
• Nenhum método exige uma sessão em execução (Running), exceto ExecuteRuntimeAsync.
• As exceções que transportam um código OmsiLaunch colocam o código no início de Exception.Message ("OL_E_PLAN_NOT_RUNNABLE: ..."). A CLI extrai os códigos das mensagens da mesma forma (CliProgram.Classify).
• Build suportada: apenas Omsi23004_692EBFBF (mais o hash da lista de permissões Steam LAA, aceite; jogabilidade não validada, pois requer uma instalação Steam genuína). Ver compatibilidade.

Exemplo 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 e resultados de ContentQueryKind:

As identidades de ponto de entrada servem apenas para descoberta: o caminho de lançamento usa PresentedEntrypointIndex; passar um EntrypointIdentity torna o plano não executável nesta build (world.entrypoint-identity, RUNTIME_PARTIAL).

RecoverPendingAsync#

Tipos de contrato#

Valores opcionais e primitivas semânticas#

Família LaunchSpec#

Todos os records abaixo estão documentados propriedade a propriedade na referência do LaunchSpec; esta tabela fixa o inventário de tipos.

Tipos de plano e de estado#

SessionState#

Enum de byte, pela ordem de declaração: Created, ValidatingPlatform, Planning, AcquiringInstallationLock, RecoveringPreviousTransaction, Snapshotting, ApplyingConfiguration, DeployingRuntime, CreatingStartupHandoff, StartingProcess, WaitingForPlugin, PluginBootstrap, StartingWorld, EnteringGameplay, Running, ProcessExited, Restoring, CleaningRuntime, Completed, Failed. ValidatingPlatform, Planning e EnteringGameplay nunca são definidos pelo serviço atual; Snapshotting é transitório e praticamente inobservável. Estados terminais: Completed, Failed. Semântica completa: ciclo de vida da sessão.

Tipos de controlo de runtime#

O plugin rejeita um handoff (plugin.request.unsupported → OL_E_CAPABILITY_UNAVAILABLE), a menos que WorldMode seja NewMap ou SavedSituation, HeadlessStart seja verdadeiro, PlayerVehicleEnabled seja falso, ambos os modos de data/hora sejam Unset e uma situação guardada tenha uma identidade não vazia. O planeador impõe as mesmas restrições mais cedo, pelo que um plano executável nunca desencadeia esta rejeição.

Tipos do registo de capacidades#

Catálogo completo: capacidades.

Métodos de extensão D3DRuntimeApi#

Wrappers tipados sobre ExecuteRuntimeAsync para as operações d3d.* (EXPERIMENTAL, capacidade PublicExperimental d3d.texture). Atribuem ids de pedido a partir de um contador global do processo que começa em 30 000 e usam por predefinição um timeout de 5 s (exceto GetD3DStatusAsync, que exige um).

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

Erros: um resultado falhado é relançado como OmsiRuntimeException(Code, detail), em que Code é o ErrorCode do resultado (ou OL_E_RUNTIME_OPERATION_FAILED quando ausente) e a mensagem é "<code>: <Values["detail"]>"; um resultado bem-sucedido sem valores, ou uma cadeia de estado do dispositivo desconhecida, lança OmsiRuntimeException("OL_E_RUNTIME_PROTOCOL_MISMATCH", ...). Tudo o que ExecuteRuntimeAsync lança propaga-se sem alterações. O tratamento da reposição do dispositivo (reset) está validado em runtime: uma reposição faz o dispositivo passar por Resetting de volta a Ready e invalida todas as texturas ativas (OL_E_D3D_STALE_RESOURCE_HANDLE, fecho de runtime D01); GetCapabilitiesAsync ainda comunica runtime.d3d.lifecycle.reset como IMPLEMENTED_NOT_RUNTIME_VALIDATED (atraso do autorrelato). A transição Lost não pode ser produzida a partir do exterior do produto e está coberta apenas 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 de contrato do processo#

InstallationPaths (identidade da instalação e contenção de caminhos)#

Estabilidade: STABLE_BETA (funções puras, sem I/O, sem estado do OMSI, sem alterações ao sistema de ficheiros, sem participação em transações, sem necessidade de sessão em execução). É a definição única usada pela concessão da instalação, pelo nome do pipe de controlo local, pelo confinamento de recursos dos perfis de sessão, pela validação dos alvos de Internet Textures e pelo caminho do modelo de criação (spawn) em 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"

Perfis de sessão (OmsiLaunch.Core)#

Estabilidade: EXPERIMENTAL. Estes tipos compilam um perfil de sessão YAML (<root>\.omsilaunch\session-profiles\<id>\profile.yaml, esquema omsilaunch.session-profile/v1) num LaunchSpec. A CLI /predefined-profile:<id> /predefined-profile-index:<n> usa exatamente estas chamadas; um integrador pode usá-las para iniciar um perfil através da API.

A CLI rejeita adicionalmente flags da linha de comandos que entrem em conflito com o perfil (OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT); essa verificação não faz parte do compilador. Ver perfis de sessão para a ordem de fusão completa.

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)#

Segurança de threads#

• OmsiLaunchService é seguro para chamadas concorrentes em sessões diferentes: as sessões vivem num ConcurrentDictionary e cada alteração por sessão ocorre sob o lock privado da sessão.
• As chamadas concorrentes na mesma sessão são seguras, mas serializadas onde é relevante: ExecuteRuntimeAsync obtém um gate por sessão, pelo que um segundo comando aguarda pelo primeiro (o seu timeout começa quando é colocado na mailbox).
• O supervisor é executado numa tarefa do thread pool (Task.Run) desde o momento em que StartSessionAsync retorna até a sessão ser terminal; consulta a telemetria e o processo a cada 100 ms. Os chamadores nunca executam código do supervisor.
• StopAsync e GetStatusAsync concluem-se de forma síncrona e podem ser chamados a partir de qualquer thread, incluindo dentro de um handler ProcessExit (a CLI faz isto com um orçamento de 4 s).
• Nenhuma chamada da API está vinculada a uma thread; nenhuma requer um contexto de sincronização.

O que não está na API#

• Nenhum IntPtr, nint, handles Win32, endereços nativos, ponteiros de VMT ou objetos de processo. Os valores do resultado cujas chaves começam por internal_ ou terminam em _address, _pointer, _vmt são removidos antes de um resultado sair de ExecuteRuntimeAsync.
• Nenhuma operação de runtime internal.*: internal.road-vehicles.make-basic é InternalOnly no registo e devolve OL_E_RUNTIME_OPERATION_UNKNOWN a partir da API e da CLI.
• Nenhuma leitura ou escrita direta na memória do OMSI, nenhum acesso ao nível de ficheiros à instalação para além do que um LaunchSpec declara.
• Nenhum handle entre processos: o plano de controlo local é a única via entre processos e aceita apenas session.status, session.events, session.stop e runtime.execute.
• Nenhum encerramento cooperativo do OMSI, nenhum LAST_MAP_STATE, nenhuma aplicação de data/hora/meteorologia/veículo do jogador, nenhum overlay de documentos de teclado/controlador nesta build.

Resumo da estabilidade#