Referencia de LaunchSpec

Documentación de la versión v0.1.0-beta.3Ver código fuente en GitHub

Traducción de la página original en inglés de OmsiLaunch 0.1.0-beta3. La página en inglés es la referencia normativa: si hay diferencias, prevalecen la página en inglés y el código.

Esta página es la referencia normativa de LaunchSpec, el record de solicitud que describe una sesión de OmsiLaunch: su forma en C# (OmsiLaunch.Api), su forma de archivo JSON tal como la carga la CLI (/spec:<path>, tools/OmsiLaunch.Cli/LaunchSpecJson.cs), cada propiedad con su tipo, valor predeterminado, regla de validación y efecto actual, las reglas de validación que hacen que un plan no sea ejecutable y la precedencia entre los flags de la CLI, los archivos de spec y los perfiles de sesión. Solo se documenta lo que hace el código actual.

Páginas relacionadas: API pública, referencia de la CLI, perfiles de sesión, códigos de error, ciclo de vida de la sesión, capacidades.

De dónde proviene un LaunchSpec#

El ejemplo completo de abajo está verificado contra la forma del record. Una copia del ejemplo mínimo se distribuye como examples/release-session.example.json (y .omsilaunch\examples\release-session.example.json en el paquete de release).

Forma JSON#

Ejemplo 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 fecha explícita, cuando el build la admite, se escribe como "Date": { "Mode": 1, "Value": { "Presence": 1, "Value": { "Year": 2024, "Month": 5, "Day": 1 } } } y una hora como { "Mode": 1, "Value": { "Presence": 1, "Value": { "Hour": 7, "Minute": 30, "Second": 0 } } }. En este build, ambas hacen que el plan no sea ejecutable (vea más abajo).

Referencia de propiedades#

La columna "Consumida" indica qué hace el código actual con el valor. La estabilidad usa el vocabulario de la página de la API pública.

LaunchSpec (raíz)#

Accesores de solo lectura (presentes en la salida JSON de la CLI, ignorados al cargar): EffectiveYear, EffectiveWeather, EffectiveInput, EffectiveDiagnostics, EffectivePresentation, EffectiveInternetTextures.

InstallationSpec#

WorldSpec#

DateSpec, TimeSpec, YearSpec#

WeatherSpec#

PlayerVehicleSpec (dentro de PlayerVehicle)#

Un PlayerVehicle con Presence 1 y todos los campos sin establecer se acepta y no tiene efecto. Cualquier campo establecido hace que el plan no sea ejecutable en este build (STATICALLY_PARTIAL).

EnvironmentSpec#

Los ocho grupos se concatenan; el grupo en el que se coloca una clave no tiene efecto. Cada entrada con Presence 1 es un ajuste semántico de ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs); la clave selecciona el archivo de destino (options.cfg para todas las claves actuales) y el token. La planificación comprueba que la clave exista (OL_E_UNKNOWN_SETTING) y sea escribible (OL_E_SETTING_NOT_WRITABLE); el valor solo se valida al iniciar (OL_E_INVALID_SETTING_VALUE, informado como una sesión Failed con OL_E_START_SESSION). Las claves no distinguen mayúsculas de minúsculas. Las entradas sin establecer se ignoran. El flag /set:<key>=<value> de la CLI escribe en General; los settings de un perfil de sesión también se combinan en General.

Los archivos modificados conservan su codificación (se preservan los bytes Windows-1252; se respetan UTF-8/UTF-16 marcados con BOM) y sus finales de línea.

LaunchBehaviorSpec#

InputSpec#

DiagnosticsSpec#

Los flags de la CLI /log, /logall, /omsi-logall, /verbose, /trace, /trace-process, /trace-plugin, /trace-native rellenan estos booleanos (/logall establece Verbose, ProcessTrace, PluginTrace, NativeTrace); se combinan con OR con los valores del spec.

SessionPresentationSpec#

InternetTexturesSpec#

SessionProfileMetadata#

Enumeraciones#

Los enteros fuera del rango declarado se almacenan tal cual en el serializador y se comportan como valores desconocidos (por ejemplo, un WorldMode desconocido no es ni NEW_MAP ni SAVED_SITUATION y produce un plan sin capacidad de mundo; el plugin lo rechazaría, pero la CLI reemplaza el modo de todos modos; consulte la precedencia).

Reglas de validación y diagnósticos de plan no ejecutable#

PlanSessionAsync ejecuta LaunchValidation.Validate y luego SessionPlanner.PlanAsync. Un plan es ejecutable exactamente cuando ningún código de diagnóstico empieza con OL_E_. El conjunto completo:

No se valida en el momento de planificar (falla al iniciar como una sesión Failed con OL_E_START_SESSION): valores de los ajustes (OL_E_INVALID_SETTING_VALUE), integridad del plugin permanente (OL_E_PERMANENT_PLUGIN_*), disponibilidad del lease (OL_E_INSTALLATION_BUSY), rango de StartupTimeoutSeconds (lanzado por StartSessionAsync).

Diagnósticos de plan informativos: plugin.integrity.reference (mensaje manifest o self), session_profile.selected.

Precedencia: flags de la CLI frente a archivo de spec frente a perfil de sesión#

CliInput.BuildSpecAsync (tools/OmsiLaunch.Cli/Program.cs) construye el spec efectivo en este orden:

1. Semilla = valores predeterminados integrados, o el archivo /spec cuando se indica.
2. Raíz de la instalación = el argumento de instalación explícito si se indica; si no, el RootPath de la semilla; luego ./vacío → directorio del archivo ejecutable, Path.GetFullPath. Un argumento de instalación explícito siempre prevalece sobre el RootPath del spec.
3. Perfil de sesión (/predefined-profile + /predefined-profile-index): los argumentos explícitos de la CLI que afectan un campo que pertenece al perfil se rechazan con OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (campos de mundo solo en modo NEW_MAP; claves de /set presentes en el preset; flags de splash cuando el preset tiene presentation; flags de texturas de Internet cuando tiene internet-textures; timeouts cuando tiene behavior). El World de la semilla se reemplaza por uno nuevo (solo se conserva el modo de mundo de la CLI) y luego se aplican el bloque new: del perfil (solo NEW_MAP), settings (en General), presentation, internet-textures, behavior y los metadatos de SessionProfile. compatibility.maps se exige para NEW_MAP y SAVED_SITUATION.
4. Mundo: el modo de mundo de la CLI siempre prevalece (/new de forma predeterminada, /saved:<osn>, /last); el World.Mode del archivo de spec se reemplaza. Para ejecutar una situación guardada desde un spec, pase /saved:. /map y /entrypoint//entrypoint-index sobrescriben la semilla; una identidad /entrypoint de la CLI borra el índice; /saved con /map o flags de punto de entrada es OL_E_INVALID_ARGUMENT.
5. /date, /time, /year, /weather* sobrescriben la semilla cuando se indican (system selecciona DateTimeMode.System).
6. /no-vehicle borra PlayerVehicle; /vehicle, /repaint, /hof, /fleet, /registration individuales sobrescriben campos individuales del vehículo del jugador de la semilla.
7. Las entradas /set:<key>=<value> se agregan a Environment.General (se comprueba la clave, no el valor); los otros siete grupos provienen de la semilla sin cambios.
8. /startup-timeout y /shutdown-timeout sobrescriben la semilla solo cuando se indican; de lo contrario, se aplican el spec, luego el perfil y luego los valores predeterminados 180 s / 30 s. ShutdownTimeoutSeconds es ACCEPTED_FOR_COMPATIBILITY / CURRENTLY_NO_EFFECT en el supervisor.
9. /splash, /splash-language, /splash-assets, /internet-textures, /internet-textures-profile sobrescriben la semilla cuando se indican; SuppressTrayIcon proviene solo de la semilla.
10. Los flags de diagnóstico se combinan con OR con la semilla.

Resultado: flag explícito de la CLI > perfil de sesión > archivo de spec > valor predeterminado integrado, excepto que un flag de la CLI que entra en conflicto con un campo que pertenece al perfil es un error y no una sobrescritura.

Reglas de rutas#

Transportado pero no aplicado#