Perfiles de sesión

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.

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 de OmsiLaunch reproducible 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 pueden hacerlo 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; consulta el estado de la validación en runtime). Las claves new.date, new.time, new.year y new.weather son UNAVAILABLE en esta build (consulta El bloque new).

Ubicación y nombre del paquete#

Un perfil lo instala y lo quita 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 de los escalares simples (sin comillas) son caracteres literales. Escribe 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; consulta El ejemplo incluido en el paquete.

Referencia de claves#

Los contextos se nombran exactamente como los nombra el compilador. Se acepta toda clave que figure aquí; nada más.

profile (mapeo raíz)#

compatibility#

new#

El bloque se lee y se valida siempre que está presente, pero solo se aplica a la especificación cuando el modo de mundo seleccionado es NEW_MAP (/new, el 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. A continuación, el planificador de sesiones (src/OmsiLaunch.Core/SessionPlanner.cs) notifica las capacidades world.explicit-date, world.explicit-time, world.explicit-year y weather como STATICALLY_PARTIAL, añade 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 esta build: un perfil que establece cualquiera de estas cuatro claves puede validarse con /plan, pero no puede iniciar una sesión (código de salida 1, OL_E_PLAN_NOT_RUNNABLE). Omítelas 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, de modo 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 salvo que un /spec lo establezca.

internet-textures#

behavior#

Cuando el bloque behavior está presente, se establecen ambos timeouts (valor indicado o predeterminado) y sustituyen por completo el LaunchBehaviorSpec 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 se puede escribir (OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE). Los valores se almacenan como cadenas y se convierten en una modificación de options.cfg cuando la sesión construye sus overlays; por 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 en options.cfg; todos están limitados a la sesión y se restauran exactamente después de ella.

Formas de valor:

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

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

Confinamiento de rutas#

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

1. Se rechazan las rutas con raíz (C:\...), las rutas que empiezan por \ y cualquier componente de ruta igual a ...
2. Se calcula la ruta completa, que debe empezar por el directorio del paquete.
3. Cada componente existente por debajo de la raíz del paquete, hasta la ruta final incluida, se inspecciona en busca del atributo ReparsePoint. Se rechaza una unión, 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 fallos producen 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 la especificación en este orden:

1. Valores predeterminados (NEW_MAP, todo sin establecer, timeouts de 180 s / 30 s).
2. /spec:<file.json>, si se indica, sustituye por completo los valores predeterminados.
3. Raíz de la instalación: un argumento de instalación explícito prevalece sobre el RootPath de la especificación; . significa el directorio que contiene el ejecutable.
4. Perfil (/predefined-profile + /predefined-profile-index): se carga el paquete y se ejecuta RejectProfileConflicts sobre los argumentos sin procesar de la CLI antes de combinar nada. Después, 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 a 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 sustituye el bloque de la semilla solo cuando el preset lo define).
5. Argumentos restantes de la CLI: se superponen encima: /map, /entrypoint, /entrypoint-index, /date, /time, /year, flags meteorológicos, 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; en caso contrario se mantiene el valor de la especificación, del perfil o el predeterminado.
6. Comprobación de compatibilidad para los modos distintos de NEW_MAP (ValidateCompatibility).

Un argumento de la CLI que afecta a un campo propiedad del 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 añaden), 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, con independencia de los perfiles (OL_E_INVALID_ARGUMENT).

Códigos de error#

Todos ellos se producen mientras se compila la línea de comandos, antes de la planificación. Son SessionProfileException (o ArgumentException para el 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#

Tras una carga correcta, la especificación incluye un registro SessionProfileMetadata en LaunchSpec.SessionProfile:

El planificador añade un diagnóstico informativo session_profile.selected a cada SessionPlan construido a partir de una especificación así, 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 a si el plan es ejecutable. 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 llega 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 proceden de la línea de comandos porque el perfil no define ningún bloque new; añadir /set:graphics.maxFPS=60 está permitido, añadir /set:traffic.humans=10 es un conflicto.

Ejemplo 2: perfil vinculado a un mapa con tres presets y recursos 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 referenciar maps\Grundorf\global.cfg.

El ejemplo incluido en el paquete#

La versión 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 cambios en esta build:

1. Establece new.date, new.time y new.weather, que hacen que el plan no sea ejecutable (consulta 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 tras 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 reduce los separadores duplicados.

La forma ejecutable para esta 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 registro en el que se compila un perfil
• Transacciones y recuperación para saber cómo se aplican y restauran los overlays de settings, splash y .itx
• Capacidades y estado de la validación en runtime