Session Profiles

Documentation for version v0.1.0-beta.3View source on GitHub

A session profile is a declarative YAML package that a content author ships with a map or an add-on so that end users can start a reproducible OmsiLaunch session with one command (OmsiLaunch.exe /predefined-profile:<id> /predefined-profile-index:<1..5> /new). This page is the normative reference for the omsilaunch.session-profile/v1 format as implemented by SessionProfileCompiler in src/OmsiLaunch.Core/SessionProfiles.cs, for the precedence rules applied by the CLI (CliInput.BuildSpecAsync and RejectProfileConflicts in tools/OmsiLaunch.Cli/Program.cs), and for the settings catalogue a profile may write (ConfigurationCatalog). Everything a profile can do, the CLI flags and the LaunchSpec can also do; a profile only packages those choices.

Stability: STABLE_BETA for parsing, validation, conflict detection and the settings / presentation / internet-textures / behavior blocks (offline test session-profiles.strict-compiler; the overlay and restore path is runtime validated by RV-005 and RV-006, see runtime validation status). The new.date, new.time, new.year and new.weather keys are UNAVAILABLE in this build (see The new block).

Package location and naming#

A profile is installed and removed by the user or the content author. OmsiLaunch never writes into a package, never copies it, and never deletes it. The package directory is not part of any transaction.

Parsing rules#

Backslashes in plain (unquoted) scalars are literal characters. Write Windows paths with a single backslash (maps\Grundorf\global.cfg). A doubled backslash in a plain scalar stays doubled in the value; see The packaged example.

Key reference#

Contexts are named exactly as the compiler names them. Every key listed here is accepted; nothing else is.

profile (root mapping)#

compatibility#

new#

The block is read and validated whenever it is present, but it is applied to the spec only when the selected world mode is NEW_MAP (/new, the CLI default). Under /saved:<file.osn> the block is ignored.

date, time, year and weather are compiled into DateSpec, TimeSpec, YearSpec and WeatherSpec with DateTimeMode.Explicit / the selected WeatherMode. The session planner (src/OmsiLaunch.Core/SessionPlanner.cs) then reports the capabilities world.explicit-date, world.explicit-time, world.explicit-year and weather as STATICALLY_PARTIAL, adds OL_E_CAPABILITY_UNAVAILABLE to the plan diagnostics and marks the plan not runnable. The plugin additionally rejects a handoff whose date or time mode is not Unset (plugin.request.unsupported). Consequence for this build: a profile that sets any of these four keys can be validated with /plan but cannot start a session (exit code 1, OL_E_PLAN_NOT_RUNNABLE). Leave them out of profiles intended to run.

new.date#

new.time#

new.weather#

preset (each entry of presets)#

Only the selected preset is applied. Every preset is still parsed and validated, so an error in preset 3 fails a request for preset 1.

presentation#

presentation.splash#

A profile cannot set SessionPresentationSpec.SuppressTrayIcon; it stays false unless a /spec sets it.

internet-textures#

behavior#

When the behavior block is present, both timeouts are set (given value or default) and replace the baseline LaunchBehaviorSpec entirely, including RestoreConfiguration and SuppressStaleClosecheckWarning, which revert to their defaults (true, true).

Settings#

settings keys are the semantic names of ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs). The compiler accepts a key only if it exists (OL_E_SESSION_PROFILE_SETTING_UNKNOWN) and is writable (OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE). Values are stored as strings and converted into an options.cfg patch when the session builds its overlays; an invalid value is therefore detected at StartSessionAsync, not at profile load, and fails the session with OL_E_START_SESSION whose message carries OL_E_INVALID_SETTING_VALUE: <key>. Every setting below writes options.cfg; all of them are session-scoped and restored exactly after the session.

Value forms:

• bool is true or false (case-insensitive). For presence tokens the token is added or removed; for inverted tokens (no_*) true removes the negative token.
• int / decimal are validated against the range; values with a divisor are stored divided (for example graphics.minObjectScreenPercent: 5 writes 0.05).
• string is written verbatim.

Catalogue entries that exist but are not writable (rejected with OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE): advanced.multithreadingCalculate, advanced.multithreadingTextureLoad (superseded by advanced.reducedMultithreading), graphics.texture, graphics.textureFilter.

Path confinement#

presentation.splash.assets and internet-textures.profile are resolved by Confined(package root, value):

1. Rooted paths (C:\...), paths starting with \, and any path component equal to .. are rejected.
2. The full path is computed and must start with the package directory.
3. Every existing component below the package root, up to and including the final path, is inspected for the ReparsePoint attribute. A junction, directory symbolic link, or file symbolic link anywhere on that path is rejected, as is a component that cannot be inspected (IOException / UnauthorizedAccessException).

All three failures are OL_E_SESSION_PROFILE_PATH_ESCAPE. The same reparse-point rule is applied to .itx targets under Texture\ at session build.

Precedence and override conflicts#

CliInput.BuildSpecAsync composes the spec in this order:

1. Defaults (NEW_MAP, everything unset, timeouts 180 s / 30 s).
2. /spec:<file.json>, if given, replaces the defaults entirely.
3. Installation root: an explicit installation argument wins over the spec's RootPath; . means the directory containing the executable.
4. Profile (/predefined-profile + /predefined-profile-index): the package is loaded and RejectProfileConflicts runs against the raw CLI arguments before anything is merged. The world block of the seed is then reset to an empty WorldSpec of the selected mode (a /spec world is discarded when a profile is used) and SessionProfileCompiler.Apply layers the profile onto the seed: new (NEW_MAP only), settings (merged over the seed's Environment.General, profile wins per key), and presentation, internet-textures, behavior (each replaces the seed block only when the preset defines it).
5. Remaining CLI arguments are layered on top: /map, /entrypoint, /entrypoint-index, /date, /time, /year, weather flags, vehicle flags, /set, splash flags, internet-textures flags, /startup-timeout, /shutdown-timeout. Timeouts from the CLI apply only when given; otherwise the spec/profile/default value stands.
6. Compatibility check for non-NEW_MAP modes (ValidateCompatibility).

A CLI argument that targets a field the selected profile owns is a conflict, rejected with OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (exit code 2, category invalid_argument). The check is per field, not per value: repeating the profile's own value is still a conflict.

Not conflicts: /set keys the preset does not define (they are added), vehicle flags (/vehicle, /repaint, /hof, /fleet, /registration, /no-vehicle; a profile cannot define a player vehicle), and any world argument under /saved (the new block is not applied there). /map, /entrypoint and /entrypoint-index are invalid together with /saved regardless of profiles (OL_E_INVALID_ARGUMENT).

Error codes#

All of these are raised while the command line is being compiled, before planning. They are SessionProfileException (or ArgumentException for the conflict) and never start a session. The full catalogue is in errors; exit codes in exit codes.

How a profile appears in the API#

After a successful load the spec carries a SessionProfileMetadata record in LaunchSpec.SessionProfile:

The planner adds an informational diagnostic session_profile.selected to every SessionPlan built from such a spec, with data keys session_profile.id, session_profile.name, session_profile.version, session_profile.author, session_profile.preset_id, session_profile.preset_index, session_profile.preset_name and session_profile.path. It does not affect runnability. Integrators using the public API directly may call SessionProfileCompiler.Load and SessionProfileCompiler.Apply from OmsiLaunch.Core; the YAML representation never crosses into OmsiLaunch.Api.

Examples#

Example 1: settings-only profile, one 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

Run: OmsiLaunch.exe /predefined-profile:quiet-evening /predefined-profile-index:1 /new /map:maps\Grundorf\global.cfg /entrypoint-index:0. The map and entrypoint come from the command line because the profile defines no new block; adding /set:graphics.maxFPS=60 is allowed, adding /set:traffic.humans=10 is a conflict.

Example 2: map-bound profile with three presets and packaged assets#

<root>\.omsilaunch\session-profiles\grundorf-tour\profile.yaml, with assets\splash\ENG.bmp, assets\splash\DEU.bmp and textures\offline.itx inside the package:

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

Run: OmsiLaunch.exe /predefined-profile:grundorf-tour /predefined-profile-index:2 /new. With /saved:situations\mytrip.osn the new block is skipped and the .osn must reference maps\Grundorf\global.cfg.

The packaged example#

The release ships docs/examples/session-profiles/rmg-leste/profile.yaml (view). It is syntactically valid, matches the schema and would load without error. Two properties keep it from starting a session unchanged in this build:

1. It sets new.date, new.time and new.weather, which make the plan not runnable (see The new block).
2. Its path values are plain scalars with doubled backslashes (maps\\RMG Leste\\global.cfg). YAML keeps them doubled, and map identities are compared textually (after / to \ normalisation only), so new.map and compatibility.maps would not match the catalogue identity maps\RMG Leste\global.cfg (OL_E_MAP_NOT_FOUND at planning). The assets value still resolves because Windows path normalisation collapses doubled separators.

The runnable form for this build is:

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

Related pages#

• CLI reference for /predefined-profile, /predefined-profile-index, /set and the world flags
• LaunchSpec for the record a profile compiles into
• Transactions and recovery for how settings, splash and .itx overlays are applied and restored
• Capabilities and runtime validation status