Referência do LaunchSpec

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 do LaunchSpec, o registo de pedido que descreve uma sessão do OmsiLaunch: a sua forma em C# (OmsiLaunch.Api), a sua forma de ficheiro JSON tal como é carregada pela CLI (/spec:<path>, tools/OmsiLaunch.Cli/LaunchSpecJson.cs), cada propriedade com o respetivo tipo, valor predefinido, regra de validação e efeito atual, as regras de validação que tornam um plano não executável e a precedência entre flags da CLI, ficheiros de especificação e perfis de sessão. Só se documenta o que o código atual faz.

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 a forma do registo. 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 lançamento).

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, escreve-se 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 executável (ver abaixo).

Referência das 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 só de 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 por definir é aceite e não tem efeito. Qualquer campo definido torna o plano não executável 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 definição semântica de ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs); a chave seleciona o ficheiro de destino (options.cfg para todas as chaves atuais) e o token. O planeamento verifica se a chave existe (OL_E_UNKNOWN_SETTING) e se é gravável (OL_E_SETTING_NOT_WRITABLE); o valor só é validado no arranque (OL_E_INVALID_SETTING_VALUE, reportado como uma sessão Failed com OL_E_START_SESSION). As chaves não distinguem maiúsculas de minúsculas. As entradas por definir são ignoradas. A flag da CLI /set:<key>=<value> escreve em General; as settings de perfis de sessão são também fundidas em General.

Os ficheiros modificados mantêm a sua codificação (bytes Windows-1252 preservados; UTF-8/UTF-16 marcados com BOM respeitados) e as terminações de linha.

LaunchBehaviorSpec#

InputSpec#

DiagnosticsSpec#

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

SessionPresentationSpec#

InternetTexturesSpec#

SessionProfileMetadata#

Enumerações#

Os inteiros fora do intervalo declarado são guardados tal como estão pelo serializador e comportam-se como valores desconhecidos (por exemplo, um WorldMode desconhecido não é nem NEW_MAP nem SAVED_SITUATION e produz um plano sem capacidade de mundo; o plugin rejeitá-lo-ia, mas a CLI substitui o modo de qualquer forma, ver a precedência).

Regras de validação e diagnósticos de não executável#

PlanSessionAsync executa LaunchValidation.Validate e depois SessionPlanner.PlanAsync. Um plano é executável exatamente quando nenhum código de diagnóstico começa por OL_E_. O conjunto completo:

Não validado no momento do planeamento (falha no arranque como uma sessão Failed com OL_E_START_SESSION): valores das definições (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 informativos do plano: plugin.integrity.reference (mensagem manifest ou self), session_profile.selected.

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

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

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

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

Regras de caminhos#

Transportado mas não aplicado#