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

Documentação da versão v0.1.0-beta.3Ver 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: se as duas divergirem, valem a página em inglês e o código.

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

O inventário da API pública gerado lista todo tipo e membro público de OmsiLaunch.Api, OmsiLaunch.Core e OmsiLaunch.Process com sua assinatura e estabilidade; um gate de documentação 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, controle de runtime, capacidades, plano de controle local, códigos de saída, status 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ê esses caminhos em toda chamada de PlanSessionAsync e StartSessionAsync; ele nunca copia, prepara nem remove arquivos do plugin (consulte 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));

Crie um serviço por processo e compartilhe-o. 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);
}

Fatos 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.
• Exceções que carregam um código do OmsiLaunch colocam o código no início de Exception.Message ("OL_E_PLAN_NOT_RUNNABLE: ..."). A CLI extrai códigos das mensagens da mesma forma (CliProgram.Classify).
• Build suportada: somente Omsi23004_692EBFBF (além do hash da lista de permissões Steam LAA, aceito; gameplay não validado, pois exige uma instalação Steam genuína). Consulte 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 somente para descoberta: o caminho de inicialização usa PresentedEntrypointIndex; passar um EntrypointIdentity torna o plano não apto para execução nesta build (world.entrypoint-identity, RUNTIME_PARTIAL).

RecoverPendingAsync#

Tipos de contrato#

Valores opcionais e primitivos semânticos#

Família LaunchSpec#

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

Tipos de plano e de status#

SessionState#

Enum de byte na 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, na prática, não observável. Estados terminais: Completed, Failed. Semântica completa: ciclo de vida da sessão.

Tipos de controle de runtime#

O plugin rejeita um handoff (plugin.request.unsupported → OL_E_CAPABILITY_UNAVAILABLE), a menos que WorldMode seja NewMap ou SavedSituation, HeadlessStart seja true, PlayerVehicleEnabled seja false, ambos os modos de data/hora sejam Unset e uma situação salva tenha uma identidade não vazia. O planejador aplica as mesmas restrições antes, portanto um plano apto para execução nunca provoca essa rejeição.

Tipos do registro 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). Eles alocam ids de requisição a partir de um contador global do processo que começa em 30 000 e usam 5 s como timeout padrão (exceto GetD3DStatusAsync, que exige um timeout).

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 com falha é 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 string de estado do dispositivo desconhecida, lança OmsiRuntimeException("OL_E_RUNTIME_PROTOCOL_MISMATCH", ...). Tudo o que ExecuteRuntimeAsync lança se propaga sem alteração. O tratamento do reset do dispositivo está validado em runtime: um reset leva o dispositivo por Resetting de volta a Ready e invalida toda textura ativa (OL_E_D3D_STALE_RESOURCE_HANDLE, fechamento de runtime D01); GetCapabilitiesAsync ainda relata runtime.d3d.lifecycle.reset como IMPLEMENTED_NOT_RUNTIME_VALIDATED (defasagem do autorrelato). A transição para Lost não pode ser produzida de fora do produto e é coberta somente 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 de processo#

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

Estabilidade: STABLE_BETA (funções puras, sem E/S, sem estado do OMSI, sem alteração do sistema de arquivos, sem participação em transação, sem exigir sessão em execução). É a definição única usada pelo lease da instalação, pelo nome do pipe de controle local, pelo confinamento de assets do perfil de sessão, pela validação de destinos das texturas da internet e pelo caminho do modelo para 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, schema omsilaunch.session-profile/v1) em um LaunchSpec. O comando da CLI /predefined-profile:<id> /predefined-profile-index:<n> usa exatamente estas chamadas; um integrador pode usá-las para iniciar um perfil pela API.

A CLI também rejeita flags de linha de comando que conflitam com o perfil (OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT); essa verificação não faz parte do compilador. Consulte perfis de sessão para a ordem completa de mesclagem.

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 simultâneas em sessões diferentes: as sessões ficam em um ConcurrentDictionary e toda alteração por sessão acontece sob o lock privado da sessão.
• Chamadas simultâneas na mesma sessão são seguras, mas serializadas onde isso importa: ExecuteRuntimeAsync adquire um gate por sessão, de modo que um segundo comando aguarda o primeiro (seu timeout começa quando ele é colocado no mailbox).
• O supervisor é executado em uma tarefa do pool de threads (Task.Run) desde o momento em que StartSessionAsync retorna até que a sessão seja terminal; ele consulta a telemetria e o processo a cada 100 ms. Os chamadores nunca executam código do supervisor.
• StopAsync e GetStatusAsync são concluídos de forma síncrona e podem ser chamados de qualquer thread, inclusive dentro de um handler de ProcessExit (a CLI faz isso com um orçamento de 4 s).
• Nenhuma chamada da API tem afinidade de thread; nenhuma exige um contexto de sincronização.

O que não está na API#

• Nenhum IntPtr, nint, handle Win32, endereço nativo, ponteiro de VMT ou objeto de processo. Valores de resultado cujas chaves começam com internal_ ou terminam com _address, _pointer, _vmt são removidos antes que um resultado saia de ExecuteRuntimeAsync.
• Nenhuma operação de runtime internal.*: internal.road-vehicles.make-basic é InternalOnly no registro e retorna OL_E_RUNTIME_OPERATION_UNKNOWN pela API e pela CLI.
• Nenhuma leitura ou escrita bruta da memória do OMSI, nenhum acesso em nível de arquivo à instalação além do que um LaunchSpec declara.
• Nenhum handle entre processos: o plano de controle local é a única rota entre processos, e ele aceita somente session.status, session.events, session.stop e runtime.execute.
• Nenhum desligamento cooperativo do OMSI, nenhum LAST_MAP_STATE, nenhuma aplicação de data/hora/clima/veículo do jogador, nenhum overlay de documento de teclado/controle nesta build.

Resumo de estabilidade#