Perfiles de sesión

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.

Un perfil de sesión es un paquete YAML declarativo que un autor de contenido distribuye con un mapa o un complemento para que los usuarios finales puedan iniciar una sesión reproducible de OmsiLaunch con un solo comando (OmsiLaunch.exe /predefined-profile:<id> /predefined-profile-index:<1..5> /new). Esta página es la referencia normativa del formato omsilaunch.session-profile/v1 tal como lo implementa SessionProfileCompiler en src/OmsiLaunch.Core/SessionProfiles.cs, de las reglas de precedencia que aplica la CLI (CliInput.BuildSpecAsync y RejectProfileConflicts en tools/OmsiLaunch.Cli/Program.cs) y del catálogo de ajustes que un perfil puede escribir (ConfigurationCatalog). Todo lo que puede hacer un perfil también lo pueden hacer los flags de la CLI y el LaunchSpec; un perfil solo empaqueta esas elecciones.

Estabilidad: STABLE_BETA para el análisis, la validación, la detección de conflictos y los bloques settings / presentation / internet-textures / behavior (prueba offline session-profiles.strict-compiler; la ruta de overlay y restauración está validada en runtime por RV-005 y RV-006, consulte el estado de la validación en runtime). Las claves new.date, new.time, new.year y new.weather son UNAVAILABLE en este build (consulte El bloque new).

Ubicación y nombre del paquete#

Un perfil lo instala y lo elimina el usuario o el autor del contenido. OmsiLaunch nunca escribe en un paquete, nunca lo copia y nunca lo elimina. El directorio del paquete no forma parte de ninguna transacción.

Reglas de análisis#

Las barras invertidas en escalares simples (sin comillas) son caracteres literales. Escriba las rutas de Windows con una sola barra invertida (maps\Grundorf\global.cfg). Una barra invertida duplicada en un escalar simple permanece duplicada en el valor; consulte El ejemplo incluido en el paquete.

Referencia de claves#

Los contextos se nombran exactamente como los nombra el compilador. Se acepta cada clave indicada aquí; ninguna otra.

profile (mapeo raíz)#

compatibility#

new#

El bloque se lee y se valida siempre que está presente, pero solo se aplica al spec cuando el modo de mundo seleccionado es NEW_MAP (/new, el valor predeterminado de la CLI). Con /saved:<file.osn> el bloque se ignora.

date, time, year y weather se compilan en DateSpec, TimeSpec, YearSpec y WeatherSpec con DateTimeMode.Explicit / el WeatherMode seleccionado. El planificador de sesiones (src/OmsiLaunch.Core/SessionPlanner.cs) informa entonces las capacidades world.explicit-date, world.explicit-time, world.explicit-year y weather como STATICALLY_PARTIAL, agrega OL_E_CAPABILITY_UNAVAILABLE a los diagnósticos del plan y marca el plan como no ejecutable. Además, el plugin rechaza un handoff cuyo modo de fecha u hora no sea Unset (plugin.request.unsupported). Consecuencia para este build: un perfil que establece cualquiera de estas cuatro claves se puede validar con /plan, pero no puede iniciar una sesión (código de salida 1, OL_E_PLAN_NOT_RUNNABLE). Omítalas en los perfiles destinados a ejecutarse.

new.date#

new.time#

new.weather#

preset (cada entrada de presets)#

Solo se aplica el preset seleccionado. Aun así, todos los presets se analizan y se validan, por lo que un error en el preset 3 hace fallar una solicitud del preset 1.

presentation#

presentation.splash#

Un perfil no puede establecer SessionPresentationSpec.SuppressTrayIcon; permanece en false a menos que un /spec lo establezca.

internet-textures#

behavior#

Cuando el bloque behavior está presente, se establecen ambos timeouts (valor indicado o predeterminado) y reemplazan por completo el LaunchBehaviorSpec de base, incluidos RestoreConfiguration y SuppressStaleClosecheckWarning, que vuelven a sus valores predeterminados (true, true).

Ajustes#

Las claves de settings son los nombres semánticos de ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs). El compilador acepta una clave solo si existe (OL_E_SESSION_PROFILE_SETTING_UNKNOWN) y es escribible (OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE). Los valores se almacenan como cadenas y se convierten en un parche de options.cfg cuando la sesión construye sus overlays; por lo tanto, un valor no válido se detecta en StartSessionAsync, no al cargar el perfil, y hace fallar la sesión con OL_E_START_SESSION, cuyo mensaje incluye OL_E_INVALID_SETTING_VALUE: <key>. Todos los ajustes siguientes escriben options.cfg; todos están limitados a la sesión y se restauran de forma exacta después de ella.

Formas de los valores:

• bool es true o false (sin distinguir mayúsculas de minúsculas). Para los tokens de presencia, el token se agrega o se quita; para los tokens invertidos (no_*), true quita el token negativo.
• int / decimal se validan contra el rango; los valores con divisor se almacenan divididos (por ejemplo, graphics.minObjectScreenPercent: 5 escribe 0.05).
• string se escribe textualmente.

Entradas del catálogo que existen pero no son escribibles (se rechazan con OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE): advanced.multithreadingCalculate, advanced.multithreadingTextureLoad (reemplazadas por advanced.reducedMultithreading), graphics.texture, graphics.textureFilter.

Confinamiento de rutas#

presentation.splash.assets e internet-textures.profile se resuelven con Confined(package root, value):

1. Se rechazan las rutas con raíz (C:\...), las rutas que empiezan con \ y cualquier componente de ruta igual a ...
2. Se calcula la ruta completa, que debe empezar con el directorio del paquete.
3. Se inspecciona el atributo ReparsePoint de cada componente existente por debajo de la raíz del paquete, hasta la ruta final inclusive. Se rechaza una junction, un enlace simbólico de directorio o un enlace simbólico de archivo en cualquier punto de esa ruta, así como un componente que no se pueda inspeccionar (IOException / UnauthorizedAccessException).

Los tres errores son OL_E_SESSION_PROFILE_PATH_ESCAPE. La misma regla de puntos de reanálisis se aplica a los destinos .itx bajo Texture\ al construir la sesión.

Precedencia y conflictos de sobrescritura#

CliInput.BuildSpecAsync compone el spec en este orden:

1. Valores predeterminados (NEW_MAP, todo sin establecer, timeouts 180 s / 30 s).
2. /spec:<file.json>, si se indica, reemplaza por completo los valores predeterminados.
3. Raíz de la instalación: un argumento de instalación explícito prevalece sobre el RootPath del spec; . significa el directorio que contiene el archivo ejecutable.
4. Perfil (/predefined-profile + /predefined-profile-index): se carga el paquete y RejectProfileConflicts se ejecuta contra los argumentos sin procesar de la CLI antes de combinar nada. Luego, el bloque de mundo de la semilla se restablece a un WorldSpec vacío del modo seleccionado (el mundo de un /spec se descarta cuando se usa un perfil) y SessionProfileCompiler.Apply superpone el perfil sobre la semilla: new (solo NEW_MAP), settings (combinado sobre el Environment.General de la semilla; el perfil prevalece por clave) y presentation, internet-textures, behavior (cada uno reemplaza el bloque de la semilla solo cuando el preset lo define).
5. Los argumentos restantes de la CLI se superponen encima: /map, /entrypoint, /entrypoint-index, /date, /time, /year, flags de clima, flags de vehículo, /set, flags de splash, flags de texturas de Internet, /startup-timeout, /shutdown-timeout. Los timeouts de la CLI solo se aplican cuando se indican; de lo contrario, se mantiene el valor del spec, del perfil o el predeterminado.
6. Comprobación de compatibilidad para los modos distintos de NEW_MAP (ValidateCompatibility).

Un argumento de la CLI que apunta a un campo que pertenece al perfil seleccionado es un conflicto y se rechaza con OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (código de salida 2, categoría invalid_argument). La comprobación es por campo, no por valor: repetir el mismo valor del perfil sigue siendo un conflicto.

No son conflictos: las claves de /set que el preset no define (se agregan), los flags de vehículo (/vehicle, /repaint, /hof, /fleet, /registration, /no-vehicle; un perfil no puede definir un vehículo del jugador) y cualquier argumento de mundo con /saved (allí no se aplica el bloque new). /map, /entrypoint y /entrypoint-index no son válidos junto con /saved, independientemente de los perfiles (OL_E_INVALID_ARGUMENT).

Códigos de error#

Todos ellos se generan mientras se compila la línea de comandos, antes de la planificación. Son SessionProfileException (o ArgumentException en el caso del conflicto) y nunca inician una sesión. El catálogo completo está en errores; los códigos de salida, en códigos de salida.

Cómo aparece un perfil en la API#

Después de una carga correcta, el spec incluye un record SessionProfileMetadata en LaunchSpec.SessionProfile:

El planificador agrega un diagnóstico informativo session_profile.selected a cada SessionPlan construido a partir de un spec de este tipo, con las claves de datos session_profile.id, session_profile.name, session_profile.version, session_profile.author, session_profile.preset_id, session_profile.preset_index, session_profile.preset_name y session_profile.path. No afecta la ejecutabilidad del plan. Los integradores que usan directamente la API pública pueden llamar a SessionProfileCompiler.Load y SessionProfileCompiler.Apply desde OmsiLaunch.Core; la representación YAML nunca pasa a OmsiLaunch.Api.

Ejemplos#

Ejemplo 1: perfil solo con ajustes, un preset#

<root>\.omsilaunch\session-profiles\quiet-evening\profile.yaml

schema: omsilaunch.session-profile/v1
id: quiet-evening
name: Quiet evening
author: Example author
version: "1.0"
presets:
  - index: 1
    id: default
    name: Low traffic, no autosave
    settings:
      traffic.randomVehicles: 40
      traffic.humans: 60
      general.autoSave: false
      sound.masterVolume: 0.6

Ejecución: OmsiLaunch.exe /predefined-profile:quiet-evening /predefined-profile-index:1 /new /map:maps\Grundorf\global.cfg /entrypoint-index:0. El mapa y el punto de entrada provienen de la línea de comandos porque el perfil no define ningún bloque new; agregar /set:graphics.maxFPS=60 está permitido, agregar /set:traffic.humans=10 es un conflicto.

Ejemplo 2: perfil vinculado a un mapa con tres presets y assets incluidos en el paquete#

<root>\.omsilaunch\session-profiles\grundorf-tour\profile.yaml, con assets\splash\ENG.bmp, assets\splash\DEU.bmp y textures\offline.itx dentro del paquete:

schema: omsilaunch.session-profile/v1
id: grundorf-tour
name: Grundorf guided tour
author: Example team
version: "2.1"
compatibility:
  maps:
    - maps\Grundorf\global.cfg
new:
  map: maps\Grundorf\global.cfg
  entrypoint-index: 0
presets:
  - index: 1
    id: low
    name: Low-end PC
    settings:
      graphics.maxFPS: 30
      graphics.tileDistance: 3
      graphics.rainReflections: false
    presentation:
      splash:
        mode: managed
        language: DEU
        assets: assets\splash
    internet-textures:
      mode: disabled
    behavior:
      startup-timeout: 300
  - index: 2
    id: mid
    name: Mid-range PC
    settings:
      graphics.maxFPS: 60
      graphics.tileDistance: 6
    internet-textures:
      mode: override
      profile: textures\offline.itx
  - index: 3
    id: high
    name: High-end PC
    settings:
      graphics.maxFPS: 120
      graphics.tileDistance: 10
      advanced.reducedMultithreading: false
    presentation:
      splash:
        mode: native

Ejecución: OmsiLaunch.exe /predefined-profile:grundorf-tour /predefined-profile-index:2 /new. Con /saved:situations\mytrip.osn, el bloque new se omite y el .osn debe hacer referencia a maps\Grundorf\global.cfg.

El ejemplo incluido en el paquete#

La release incluye docs/examples/session-profiles/rmg-leste/profile.yaml (ver). Es sintácticamente válido, cumple el esquema y se cargaría sin errores. Dos propiedades impiden que inicie una sesión sin modificaciones en este build:

1. Establece new.date, new.time y new.weather, que hacen que el plan no sea ejecutable (consulte El bloque new).
2. Sus valores de ruta son escalares simples con barras invertidas duplicadas (maps\\RMG Leste\\global.cfg). YAML las mantiene duplicadas y las identidades de mapa se comparan textualmente (solo después de normalizar / a \), por lo que new.map y compatibility.maps no coincidirían con la identidad del catálogo maps\RMG Leste\global.cfg (OL_E_MAP_NOT_FOUND durante la planificación). El valor de assets sí se resuelve porque la normalización de rutas de Windows colapsa los separadores duplicados.

La forma ejecutable para este build es:

schema: omsilaunch.session-profile/v1
id: rmg-leste
name: RMG Leste
author: Equipe RMG
version: "1.0"
compatibility:
  maps:
    - maps\RMG Leste\global.cfg
new:
  map: maps\RMG Leste\global.cfg
  entrypoint-index: 3
presets:
  - index: 1
    id: weak
    name: PC fraco
    settings:
      graphics.maxFPS: 30
      graphics.tileDistance: 3
    presentation:
      splash:
        mode: managed
        language: PTB
        assets: assets\splash
    internet-textures:
      mode: disabled
  - index: 2
    id: medium
    name: PC medio
    settings:
      graphics.maxFPS: 40
      graphics.tileDistance: 5
  - index: 3
    id: strong
    name: PC forte
    settings:
      graphics.maxFPS: 60
      graphics.tileDistance: 8

Páginas relacionadas#

• Referencia de la CLI para /predefined-profile, /predefined-profile-index, /set y los flags de mundo
• LaunchSpec para el record en el que se compila un perfil
• Transacciones y recuperación para saber cómo se aplican y se restauran los overlays de settings, splash y .itx
• Capacidades y estado de la validación en runtime