Referência do LaunchSpec

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 de LaunchSpec, o registro de requisição que descreve uma sessão do OmsiLaunch: seu formato em C# (OmsiLaunch.Api), sua forma de arquivo JSON carregada pela CLI (/spec:<path>, tools/OmsiLaunch.Cli/LaunchSpecJson.cs), cada propriedade com seu tipo, valor padrão, regra de validação e efeito atual, as regras de validação que tornam um plano não apto para execução e a precedência entre flags da CLI, arquivos de especificação e perfis de sessão. Somente o que o código atual faz está documentado.

Páginas relacionadas: API pública, referência da CLI, perfis de sessão, códigos de erro, ciclo de vida da sessão, capacidades.

De onde vem um LaunchSpec#

O exemplo completo abaixo foi verificado contra o formato do registro. Uma cópia do exemplo mínimo é distribuída como examples/release-session.example.json (e .omsilaunch\examples\release-session.example.json no pacote de release).

Forma JSON#

Exemplo completo#

{
  // Comments and trailing commas are accepted. Enums are integers.
  "Installation": {
    "RootPath": ".",                          // "." = directory that contains OmsiLaunch.exe (CLI only)
    "ExpectedExecutableSha256": null          // carried, not consumed
  },
  "World": {
    "Mode": 0,                                // 0 NewMap, 1 SavedSituation, 2 LastMapState (unavailable)
    "MapIdentity": { "Presence": 1, "Value": "maps\\Grundorf\\global.cfg" },
    "SituationIdentity": { "Presence": 0, "Value": null },
    "PresentedEntrypointIndex": { "Presence": 1, "Value": 1 },
    "EntrypointIdentity": { "Presence": 0, "Value": null }
  },
  "Date": { "Mode": 0, "Value": { "Presence": 0, "Value": null } },
  "Time": { "Mode": 0, "Value": { "Presence": 0, "Value": null } },
  "Year": null,
  "Weather": null,
  "PlayerVehicle": { "Presence": 0, "Value": null },
  "Environment": {
    "General": {
      "traffic.randomVehicles": { "Presence": 1, "Value": "150" },
      "graphics.maxFPS": { "Presence": 1, "Value": "60" }
    },
    "Advanced": {}, "Graphics": {}, "AdvancedGraphics": {},
    "Sound": {}, "AiPassengers": {}, "Keyboard": {}, "Controllers": {}
  },
  "Behavior": {
    "RestoreConfiguration": true,             // carried, restore always happens
    "SuppressStaleClosecheckWarning": true,
    "StartupTimeoutSeconds": 180,             // 1..600
    "ShutdownTimeoutSeconds": 30              // carried, not consumed
  },
  "Input": null,
  "Diagnostics": null,
  "Presentation": {
    "Splash": 1,                              // 0 Unset/Native (keep OMSI files), 1 Managed
    "Language": { "Presence": 0, "Value": null },
    "CustomAssetDirectory": { "Presence": 0, "Value": null },
    "SuppressTrayIcon": false
  },
  "InternetTextures": {
    "Mode": 0,                                // 0 Native, 1 Disabled, 2 Override
    "OverrideProfilePath": { "Presence": 0, "Value": null }
  },
  "SessionProfile": null
}

Uma data explícita, quando o build a suporta, é escrita como "Date": { "Mode": 1, "Value": { "Presence": 1, "Value": { "Year": 2024, "Month": 5, "Day": 1 } } } e uma hora como { "Mode": 1, "Value": { "Presence": 1, "Value": { "Hour": 7, "Minute": 30, "Second": 0 } } }. Neste build, ambas tornam o plano não apto para execução (ver abaixo).

Referência de propriedades#

A coluna "Consumido" indica o que o código atual faz com o valor. A estabilidade usa o vocabulário da página da API pública.

LaunchSpec (raiz)#

Acessores somente leitura (presentes na saída JSON da CLI, ignorados no carregamento): EffectiveYear, EffectiveWeather, EffectiveInput, EffectiveDiagnostics, EffectivePresentation, EffectiveInternetTextures.

InstallationSpec#

WorldSpec#

DateSpec, TimeSpec, YearSpec#

WeatherSpec#

PlayerVehicleSpec (dentro de PlayerVehicle)#

Um PlayerVehicle com Presence 1 e todos os campos não definidos é aceito e não tem efeito. Qualquer campo definido torna o plano não apto para execução neste build (STATICALLY_PARTIAL).

EnvironmentSpec#

Os oito grupos são concatenados; o grupo em que uma chave é colocada não tem efeito. Cada entrada com Presence 1 é uma configuração semântica de ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs); a chave seleciona o arquivo de destino (options.cfg para todas as chaves atuais) e o token. O planejamento verifica se a chave existe (OL_E_UNKNOWN_SETTING) e é gravável (OL_E_SETTING_NOT_WRITABLE); o valor é validado apenas no início (OL_E_INVALID_SETTING_VALUE, reportado como uma sessão Failed com OL_E_START_SESSION). As chaves não diferenciam maiúsculas de minúsculas. Entradas não definidas são ignoradas. A flag da CLI /set:<key>=<value> grava em General; as settings do perfil de sessão também são mescladas em General.

Os arquivos modificados mantêm sua codificação (bytes Windows-1252 preservados; UTF-8/UTF-16 marcados com BOM respeitados) e suas quebras de linha.

LaunchBehaviorSpec#

InputSpec#

DiagnosticsSpec#

As flags da CLI /log, /logall, /omsi-logall, /verbose, /trace, /trace-process, /trace-plugin, /trace-native preenchem esses booleanos (/logall define Verbose, ProcessTrace, PluginTrace, NativeTrace); eles são combinados por OR com os valores da especificação.

SessionPresentationSpec#

InternetTexturesSpec#

SessionProfileMetadata#

Enumerações#

Inteiros fora do intervalo declarado são armazenados como estão pelo serializador e se comportam como valores desconhecidos (por exemplo, um WorldMode desconhecido não é nem NEW_MAP nem SAVED_SITUATION e gera um plano sem capacidade de mundo; o plugin o rejeitaria, mas a CLI substitui o modo de qualquer forma, ver precedência).

Regras de validação e diagnósticos de não aptidão para execução#

PlanSessionAsync executa LaunchValidation.Validate e depois SessionPlanner.PlanAsync. Um plano é apto para execução exatamente quando nenhum código de diagnóstico começa com OL_E_. O conjunto completo:

Não validado no momento do planejamento (falha no início como uma sessão Failed com OL_E_START_SESSION): valores de configuração (OL_E_INVALID_SETTING_VALUE), integridade do plugin permanente (OL_E_PERMANENT_PLUGIN_*), disponibilidade do lease (OL_E_INSTALLATION_BUSY), intervalo de StartupTimeoutSeconds (lançado por StartSessionAsync).

Diagnósticos de plano informativos: plugin.integrity.reference (mensagem manifest ou self), session_profile.selected.

Precedência: flags da CLI vs arquivo de especificação vs perfil de sessão#

CliInput.BuildSpecAsync (tools/OmsiLaunch.Cli/Program.cs) constrói a especificação efetiva nesta ordem:

1. Base = padrões internos, ou o arquivo /spec quando informado.
2. Raiz da instalação = o argumento de instalação explícito, se informado, senão o RootPath da base; depois ./vazio → diretório do executável, Path.GetFullPath. Um argumento de instalação explícito sempre prevalece sobre o RootPath da especificação.
3. Perfil de sessão (/predefined-profile + /predefined-profile-index): argumentos explícitos da CLI que afetam um campo pertencente ao perfil são rejeitados com OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (campos de mundo apenas no modo NEW_MAP; chaves de /set presentes na predefinição; flags de splash quando a predefinição tem presentation; flags de texturas da internet quando tem internet-textures; timeouts quando tem behavior). O World da base é substituído por um novo (apenas o modo de mundo da CLI sobrevive); em seguida são aplicados o bloco new: do perfil (apenas NEW_MAP), settings (em General), presentation, internet-textures, behavior e os metadados de SessionProfile. compatibility.maps é imposto para NEW_MAP e SAVED_SITUATION.
4. Mundo: o modo de mundo da CLI sempre prevalece (/new padrão, /saved:<osn>, /last); o World.Mode do arquivo de especificação é substituído. Para executar uma situação salva a partir de uma especificação, passe /saved:. /map e /entrypoint//entrypoint-index sobrescrevem a base; uma identidade /entrypoint da CLI limpa o índice; /saved com /map ou flags de ponto de entrada gera OL_E_INVALID_ARGUMENT.
5. /date, /time, /year, /weather* sobrescrevem a base quando informados (system seleciona DateTimeMode.System).
6. /no-vehicle limpa PlayerVehicle; /vehicle, /repaint, /hof, /fleet, /registration individuais sobrescrevem campos individuais do veículo do jogador da base.
7. As entradas /set:<key>=<value> são adicionadas a Environment.General (chave verificada, valor não); os outros sete grupos vêm da base sem alteração.
8. /startup-timeout e /shutdown-timeout sobrescrevem a base apenas quando informados; caso contrário, aplicam-se a especificação, depois o perfil, depois os padrões 180 s / 30 s. ShutdownTimeoutSeconds é ACCEPTED_FOR_COMPATIBILITY / CURRENTLY_NO_EFFECT no supervisor.
9. /splash, /splash-language, /splash-assets, /internet-textures, /internet-textures-profile sobrescrevem a base quando informados; SuppressTrayIcon vem apenas da base.
10. As flags de diagnóstico são combinadas por OR com a base.

Resultado: flag explícita da CLI > perfil de sessão > arquivo de especificação > padrão interno, exceto que uma flag da CLI em conflito com um campo pertencente ao perfil é um erro, e não uma sobrescrita.

Regras de caminho#

Transportado, mas não aplicado#