Riferimento di LaunchSpec

Documentazione della versione v0.1.0-beta.3Vedi il sorgente su GitHub

Traduzione della pagina originale in inglese di OmsiLaunch 0.1.0-beta3. La pagina inglese è normativa: in caso di differenze prevalgono la pagina inglese e il codice.

Questa pagina è il riferimento normativo per LaunchSpec, il record di richiesta che descrive una sessione OmsiLaunch: la sua forma C# (OmsiLaunch.Api), la sua forma di file JSON così come viene caricata dalla CLI (/spec:<path>, tools/OmsiLaunch.Cli/LaunchSpecJson.cs), ogni proprietà con tipo, valore predefinito, regola di validazione ed effetto attuale, le regole di validazione che rendono un piano non eseguibile e la precedenza tra flag della CLI, file di specifica e profili di sessione. Viene documentato solo ciò che fa il codice attuale.

Pagine correlate: API pubblica, riferimento CLI, profili di sessione, codici di errore, ciclo di vita della sessione, capability.

Da dove proviene un LaunchSpec#

L'esempio completo riportato sotto è verificato rispetto alla forma del record. Una copia dell'esempio minimo è distribuita come examples/release-session.example.json (e .omsilaunch\examples\release-session.example.json nel pacchetto di rilascio).

Forma JSON#

Esempio 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
}

Una data esplicita, quando il build la supporta, si scrive come "Date": { "Mode": 1, "Value": { "Presence": 1, "Value": { "Year": 2024, "Month": 5, "Day": 1 } } } e un orario come { "Mode": 1, "Value": { "Presence": 1, "Value": { "Hour": 7, "Minute": 30, "Second": 0 } } }. In questo build entrambi rendono il piano non eseguibile (vedere sotto).

Riferimento delle proprietà#

La colonna «Utilizzo» indica che cosa fa il codice attuale con il valore. La stabilità usa il vocabolario della pagina dell'API pubblica.

LaunchSpec (root)#

Funzioni di accesso di sola lettura (presenti nell'output JSON della CLI, ignorate in caricamento): EffectiveYear, EffectiveWeather, EffectiveInput, EffectiveDiagnostics, EffectivePresentation, EffectiveInternetTextures.

InstallationSpec#

WorldSpec#

DateSpec, TimeSpec, YearSpec#

WeatherSpec#

PlayerVehicleSpec (all'interno di PlayerVehicle)#

Un PlayerVehicle con Presence 1 e tutti i campi non impostati viene accettato e non ha alcun effetto. Qualsiasi campo impostato rende il piano non eseguibile in questo build (STATICALLY_PARTIAL).

EnvironmentSpec#

Gli otto gruppi vengono concatenati; il gruppo in cui è collocata una chiave non ha alcun effetto. Ogni voce con Presence 1 è un'impostazione semantica di ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs); la chiave seleziona il file di destinazione (options.cfg per tutte le chiavi attuali) e il token. La pianificazione verifica che la chiave esista (OL_E_UNKNOWN_SETTING) e sia scrivibile (OL_E_SETTING_NOT_WRITABLE); il valore viene validato solo all'avvio (OL_E_INVALID_SETTING_VALUE, segnalato come sessione Failed con OL_E_START_SESSION). Le chiavi non distinguono maiuscole e minuscole. Le voci non impostate vengono ignorate. Il flag della CLI /set:<key>=<value> scrive in General; anche le settings dei profili di sessione vengono unite in General.

I file modificati mantengono la loro codifica (byte Windows-1252 preservati; UTF-8/UTF-16 con BOM rispettati) e i terminatori di riga.

LaunchBehaviorSpec#

InputSpec#

DiagnosticsSpec#

I flag della CLI /log, /logall, /omsi-logall, /verbose, /trace, /trace-process, /trace-plugin, /trace-native valorizzano questi booleani (/logall imposta Verbose, ProcessTrace, PluginTrace, NativeTrace); vengono combinati in OR con i valori della specifica.

SessionPresentationSpec#

InternetTexturesSpec#

SessionProfileMetadata#

Enumerazioni#

Gli interi al di fuori dell'intervallo dichiarato vengono memorizzati così come sono dal serializzatore e si comportano come valori sconosciuti (ad esempio un WorldMode sconosciuto non è né NEW_MAP né SAVED_SITUATION e produce un piano senza capability di mondo; il plugin lo rifiuterebbe, ma la CLI sostituisce comunque la modalità, vedere la precedenza).

Regole di validazione e diagnostica di non eseguibilità#

PlanSessionAsync esegue LaunchValidation.Validate e poi SessionPlanner.PlanAsync. Un piano è eseguibile esattamente quando nessun codice di diagnostica inizia con OL_E_. L'insieme completo:

Non validati in fase di pianificazione (falliscono all'avvio come sessione Failed con OL_E_START_SESSION): valori delle impostazioni (OL_E_INVALID_SETTING_VALUE), integrità del plugin permanente (OL_E_PERMANENT_PLUGIN_*), disponibilità del lease (OL_E_INSTALLATION_BUSY), intervallo di StartupTimeoutSeconds (eccezione generata da StartSessionAsync).

Diagnostica informativa del piano: plugin.integrity.reference (messaggio manifest o self), session_profile.selected.

Precedenza: flag della CLI, file di specifica e profilo di sessione#

CliInput.BuildSpecAsync (tools/OmsiLaunch.Cli/Program.cs) costruisce la specifica effettiva in questo ordine:

1. Base = valori predefiniti incorporati, oppure il file /spec quando indicato.
2. Radice dell'installazione = l'argomento di installazione esplicito se indicato, altrimenti il RootPath della base; poi ./vuoto → directory dell'eseguibile, Path.GetFullPath. Un argomento di installazione esplicito prevale sempre sul RootPath della specifica.
3. Profilo di sessione (/predefined-profile + /predefined-profile-index): gli argomenti espliciti della CLI che toccano un campo di proprietà del profilo vengono rifiutati con OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (campi del mondo solo in modalità NEW_MAP; chiavi /set presenti nel preset; flag della splash quando il preset ha presentation; flag delle internet-textures quando ha internet-textures; timeout quando ha behavior). Il World della base viene sostituito da uno nuovo (sopravvive solo la modalità del mondo della CLI), poi vengono applicati il blocco new: del profilo (solo NEW_MAP), settings (in General), presentation, internet-textures, behavior e i metadati SessionProfile. compatibility.maps viene imposto per NEW_MAP e SAVED_SITUATION.
4. Mondo: la modalità del mondo della CLI prevale sempre (/new predefinito, /saved:<osn>, /last); il World.Mode del file di specifica viene sostituito. Per eseguire una situazione salvata da una specifica, passare /saved:. /map e /entrypoint//entrypoint-index sovrascrivono la base; un'identità /entrypoint della CLI azzera l'indice; /saved con /map o con flag del punto di ingresso è OL_E_INVALID_ARGUMENT.
5. /date, /time, /year, /weather* sovrascrivono la base quando indicati (system seleziona DateTimeMode.System).
6. /no-vehicle azzera PlayerVehicle; i singoli /vehicle, /repaint, /hof, /fleet, /registration sovrascrivono i singoli campi del veicolo del giocatore della base.
7. Le voci /set:<key>=<value> vengono aggiunte a Environment.General (chiave controllata, valore no); gli altri sette gruppi provengono dalla base senza modifiche.
8. /startup-timeout e /shutdown-timeout sovrascrivono la base solo quando indicati; altrimenti si applicano la specifica, poi il profilo, poi i valori predefiniti 180 s / 30 s. ShutdownTimeoutSeconds è ACCEPTED_FOR_COMPATIBILITY / CURRENTLY_NO_EFFECT sul supervisore.
9. /splash, /splash-language, /splash-assets, /internet-textures, /internet-textures-profile sovrascrivono la base quando indicati; SuppressTrayIcon proviene solo dalla base.
10. I flag di diagnostica vengono combinati in OR con la base.

Risultato: flag esplicito della CLI > profilo di sessione > file di specifica > valore predefinito incorporato, con l'eccezione che un flag della CLI in conflitto con un campo di proprietà del profilo è un errore anziché una sovrascrittura.

Regole dei percorsi#

Trasportati ma non applicati#