Referencia de LaunchSpec

Documentación de la versión v0.1.0-beta.3Ver 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 difieren, prevalecen la página en inglés y el código.

Esta página es la referencia normativa de LaunchSpec, el registro 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 especificación 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 procede un LaunchSpec#

El ejemplo completo que aparece más abajo está verificado frente a la forma del registro. Una copia del ejemplo mínimo se distribuye como examples/release-session.example.json (y como .omsilaunch\examples\release-session.example.json en el paquete de la versión).

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 la build lo 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 esta build ambas hacen que el plan no sea ejecutable (consulta más abajo).

Referencia de propiedades#

La columna «Consumido» 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)#

Descriptores de acceso 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 esta 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 existe (OL_E_UNKNOWN_SETTING) y que se puede escribir (OL_E_SETTING_NOT_WRITABLE); el valor solo se valida en el inicio (OL_E_INVALID_SETTING_VALUE, notificado 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 los perfiles 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 de la especificación.

SessionPresentationSpec#

InternetTexturesSpec#

SessionProfileMetadata#

Enumeraciones#

Los enteros fuera del intervalo declarado se almacenan tal cual por 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 sustituye el modo en cualquier caso; consulta la precedencia).

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

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

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

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

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

CliInput.BuildSpecAsync (tools/OmsiLaunch.Cli/Program.cs) construye la especificación efectiva 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; después, ./vacío → directorio del ejecutable, Path.GetFullPath. Un argumento de instalación explícito siempre prevalece sobre el RootPath de la especificación.
3. Perfil de sesión (/predefined-profile + /predefined-profile-index): los argumentos explícitos de la CLI que afectan a un campo propiedad del 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 sustituye por uno nuevo (solo se conserva el modo de mundo de la CLI) y, a continuación, 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 impone para NEW_MAP y SAVED_SITUATION.
4. Mundo: el modo de mundo de la CLI siempre prevalece (/new predeterminado, /saved:<osn>, /last); el World.Mode del archivo de especificación se sustituye. Para ejecutar una situación guardada desde una especificación, pasa /saved:. /map y /entrypoint//entrypoint-index sobrescriben la semilla; una identidad /entrypoint de la CLI borra el índice; /saved junto con /map o con 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; los flags individuales /vehicle, /repaint, /hof, /fleet, /registration sobrescriben campos individuales del vehículo del jugador de la semilla.
7. Las entradas /set:<key>=<value> se añaden a Environment.General (se comprueba la clave, no el valor); los otros siete grupos proceden de la semilla sin cambios.
8. /startup-timeout y /shutdown-timeout sobrescriben la semilla solo cuando se indican; en caso contrario se aplican la especificación, después el perfil y después 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 procede 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 especificación > valor predeterminado integrado, salvo que un flag de la CLI que entra en conflicto con un campo propiedad del perfil es un error en lugar de una sobrescritura.

Reglas de rutas#

Transportado pero no aplicado#