Профили сеанса

Документация версии v0.1.0-beta.3Исходник на GitHub

Перевод исходной страницы на английском языке для OmsiLaunch 0.1.0-beta3. Нормативной является английская страница: при расхождениях приоритет имеют английская страница и код.

Профиль сеанса — это декларативный YAML-пакет, который автор контента поставляет вместе с картой или дополнением, чтобы конечные пользователи могли одной командой запустить воспроизводимый сеанс OmsiLaunch (OmsiLaunch.exe /predefined-profile:<id> /predefined-profile-index:<1..5> /new). Эта страница — нормативный справочник по формату omsilaunch.session-profile/v1 в том виде, в каком его реализует SessionProfileCompiler в src/OmsiLaunch.Core/SessionProfiles.cs, по правилам приоритета, которые применяет CLI (CliInput.BuildSpecAsync и RejectProfileConflicts в tools/OmsiLaunch.Cli/Program.cs), а также по каталогу параметров, которые может записывать профиль (ConfigurationCatalog). Всё, что умеет профиль, умеют и флаги CLI, и LaunchSpec; профиль лишь упаковывает этот выбор.

Стабильность: STABLE_BETA для разбора, проверки, обнаружения конфликтов и блоков settings / presentation / internet-textures / behavior (офлайн-тест session-profiles.strict-compiler; путь overlay (временная замена файла на время сеанса) и восстановления проверен в runtime в рамках RV-005 и RV-006, см. статус проверки в runtime). Ключи new.date, new.time, new.year и new.weather в этой сборке имеют статус UNAVAILABLE (см. Блок new).

Расположение и именование пакета#

Профиль устанавливает и удаляет пользователь или автор контента. OmsiLaunch никогда не пишет в пакет, никогда его не копирует и никогда не удаляет. Каталог пакета не входит ни в одну транзакцию.

Правила разбора#

Обратные косые черты в простых (не заключённых в кавычки) скалярах являются обычными символами. Пути Windows записываются с одинарной обратной косой чертой (maps\Grundorf\global.cfg). Удвоенная обратная косая черта в простом скаляре остаётся в значении удвоенной; см. Пример из релизного пакета.

Справочник по ключам#

Контексты названы точно так же, как их называет компилятор. Каждый перечисленный здесь ключ принимается; ничего другого не принимается.

profile (корневое отображение)#

compatibility#

new#

Блок читается и проверяется всякий раз, когда он присутствует, но применяется к спецификации только тогда, когда выбранный режим мира — NEW_MAP (/new, значение CLI по умолчанию). При /saved:<file.osn> блок игнорируется.

date, time, year и weather компилируются в DateSpec, TimeSpec, YearSpec и WeatherSpec с DateTimeMode.Explicit / выбранным WeatherMode. Затем планировщик сеанса (src/OmsiLaunch.Core/SessionPlanner.cs) сообщает возможности world.explicit-date, world.explicit-time, world.explicit-year и weather как STATICALLY_PARTIAL, добавляет OL_E_CAPABILITY_UNAVAILABLE в диагностику плана и помечает план как неисполнимый. Кроме того, плагин отклоняет данные передачи при запуске, если режим даты или времени не Unset (plugin.request.unsupported). Следствие для этой сборки: профиль, задающий любой из этих четырёх ключей, можно проверить с помощью /plan, но нельзя запустить сеанс (код выхода 1, OL_E_PLAN_NOT_RUNNABLE). В профилях, предназначенных для запуска, эти ключи следует опускать.

new.date#

new.time#

new.weather#

preset (каждая запись presets)#

Применяется только выбранный пресет. Тем не менее разбираются и проверяются все пресеты, поэтому ошибка в пресете 3 приводит к отказу запроса на пресет 1.

presentation#

presentation.splash#

Профиль не может задать SessionPresentationSpec.SuppressTrayIcon; значение остаётся false, если его не задаёт /spec.

internet-textures#

behavior#

Если блок behavior присутствует, задаются оба тайм-аута (указанное значение или значение по умолчанию), и они полностью заменяют базовый LaunchBehaviorSpec, включая RestoreConfiguration и SuppressStaleClosecheckWarning, которые возвращаются к значениям по умолчанию (true, true).

Параметры#

Ключи settings — это семантические имена из ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs). Компилятор принимает ключ, только если он существует (OL_E_SESSION_PROFILE_SETTING_UNKNOWN) и доступен для записи (OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE). Значения хранятся как строки и преобразуются в изменения options.cfg, когда сеанс строит свои overlay; поэтому недопустимое значение обнаруживается в StartSessionAsync, а не при загрузке профиля, и приводит к сбою сеанса с OL_E_START_SESSION, сообщение которого содержит OL_E_INVALID_SETTING_VALUE: <key>. Каждый параметр ниже записывает в options.cfg; все они действуют только в пределах сеанса и после сеанса точно восстанавливаются.

Формы значений:

• bool — true или false (без учёта регистра). Для токенов присутствия токен добавляется или удаляется; для инвертированных токенов (no_*) true удаляет отрицательный токен.
• int / decimal проверяются по диапазону; значения с делителем сохраняются делёнными (например, graphics.minObjectScreenPercent: 5 записывает 0.05).
• string записывается дословно.

Записи каталога, которые существуют, но недоступны для записи (отклоняются с OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE): advanced.multithreadingCalculate, advanced.multithreadingTextureLoad (заменены на advanced.reducedMultithreading), graphics.texture, graphics.textureFilter.

Ограничение путей#

presentation.splash.assets и internet-textures.profile разрешаются с помощью Confined(package root, value):

1. Корневые пути (C:\...), пути, начинающиеся с \, и любые пути с компонентом, равным .., отклоняются.
2. Вычисляется полный путь, и он должен начинаться с каталога пакета.
3. Каждый существующий компонент ниже корня пакета вплоть до конечного пути включительно проверяется на наличие атрибута ReparsePoint. Junction, символическая ссылка на каталог или символическая ссылка на файл в любом месте этого пути отклоняются, как и компонент, который невозможно проверить (IOException / UnauthorizedAccessException).

Все три вида ошибок дают OL_E_SESSION_PROFILE_PATH_ESCAPE. То же правило для точек повторной обработки применяется к целям .itx внутри Texture\ при построении сеанса.

Приоритет и конфликты переопределения#

CliInput.BuildSpecAsync составляет спецификацию в следующем порядке:

1. Значения по умолчанию (NEW_MAP, ничего не задано, тайм-ауты 180 s / 30 s).
2. /spec:<file.json>, если указан, полностью заменяет значения по умолчанию.
3. Корневой каталог установки: явный аргумент установки имеет приоритет над RootPath из спецификации; . означает каталог, содержащий исполняемый файл.
4. Профиль (/predefined-profile + /predefined-profile-index): пакет загружается, и RejectProfileConflicts проверяет необработанные аргументы CLI до какого-либо объединения. Затем блок мира в основе сбрасывается в пустой WorldSpec выбранного режима (мир из /spec отбрасывается, если используется профиль), и SessionProfileCompiler.Apply накладывает профиль на основу: new (только NEW_MAP), settings (объединяются поверх Environment.General основы, по каждому ключу побеждает профиль), а также presentation, internet-textures, behavior (каждый заменяет блок основы, только если его определяет пресет).
5. Остальные аргументы CLI накладываются сверху: /map, /entrypoint, /entrypoint-index, /date, /time, /year, флаги погоды, флаги ТС, /set, флаги заставки, флаги интернет-текстур, /startup-timeout, /shutdown-timeout. Тайм-ауты из CLI применяются, только если указаны; иначе остаётся значение из спецификации/профиля/по умолчанию.
6. Проверка совместимости для режимов, отличных от NEW_MAP (ValidateCompatibility).

Аргумент CLI, направленный на поле, которым владеет выбранный профиль, является конфликтом и отклоняется с OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (код выхода 2, категория invalid_argument). Проверка выполняется по полю, а не по значению: повтор собственного значения профиля тоже является конфликтом.

Не являются конфликтами: ключи /set, которые пресет не определяет (они добавляются), флаги ТС (/vehicle, /repaint, /hof, /fleet, /registration, /no-vehicle; профиль не может определить ТС игрока) и любой аргумент мира при /saved (блок new там не применяется). /map, /entrypoint и /entrypoint-index недопустимы вместе с /saved независимо от профилей (OL_E_INVALID_ARGUMENT).

Коды ошибок#

Все эти ошибки возникают во время компиляции командной строки, до планирования. Это SessionProfileException (или ArgumentException для конфликта), и они никогда не запускают сеанс. Полный каталог приведён в разделе ошибки; коды выхода — в разделе коды выхода.

Как профиль отображается в API#

После успешной загрузки спецификация содержит запись SessionProfileMetadata в LaunchSpec.SessionProfile:

Планировщик добавляет информационное диагностическое сообщение session_profile.selected в каждый SessionPlan, построенный из такой спецификации, с ключами данных session_profile.id, session_profile.name, session_profile.version, session_profile.author, session_profile.preset_id, session_profile.preset_index, session_profile.preset_name и session_profile.path. Оно не влияет на исполнимость. Интеграторы, напрямую использующие публичный API, могут вызывать SessionProfileCompiler.Load и SessionProfileCompiler.Apply из OmsiLaunch.Core; YAML-представление никогда не попадает в OmsiLaunch.Api.

Примеры#

Пример 1: профиль только с параметрами, один пресет#

<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

Запуск: OmsiLaunch.exe /predefined-profile:quiet-evening /predefined-profile-index:1 /new /map:maps\Grundorf\global.cfg /entrypoint-index:0. Карта и точка входа берутся из командной строки, потому что профиль не определяет блок new; добавить /set:graphics.maxFPS=60 можно, а добавление /set:traffic.humans=10 является конфликтом.

Пример 2: профиль, привязанный к карте, с тремя пресетами и ресурсами в пакете#

<root>\.omsilaunch\session-profiles\grundorf-tour\profile.yaml, с assets\splash\ENG.bmp, assets\splash\DEU.bmp и textures\offline.itx внутри пакета:

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

Запуск: OmsiLaunch.exe /predefined-profile:grundorf-tour /predefined-profile-index:2 /new. С /saved:situations\mytrip.osn блок new пропускается, и .osn должен ссылаться на maps\Grundorf\global.cfg.

Пример из релизного пакета#

Релиз содержит docs/examples/session-profiles/rmg-leste/profile.yaml (просмотр). Он синтаксически корректен, соответствует схеме и загрузился бы без ошибок. Две особенности не позволяют ему в неизменном виде запустить сеанс в этой сборке:

1. Он задаёт new.date, new.time и new.weather, из-за чего план становится неисполнимым (см. Блок new).
2. Его значения путей — простые скаляры с удвоенными обратными косыми чертами (maps\\RMG Leste\\global.cfg). YAML сохраняет их удвоенными, а идентификаторы карт сравниваются как текст (только после нормализации / в \), поэтому new.map и compatibility.maps не совпали бы с идентификатором из каталога maps\RMG Leste\global.cfg (OL_E_MAP_NOT_FOUND при планировании). Значение assets при этом разрешается, потому что нормализация путей Windows схлопывает удвоенные разделители.

Исполнимая форма для этой сборки:

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

Связанные страницы#

• Справочник по CLI — о /predefined-profile, /predefined-profile-index, /set и флагах мира
• LaunchSpec — о записи, в которую компилируется профиль
• Транзакции и восстановление после сбоя — о том, как применяются и восстанавливаются overlay для settings, заставки и .itx
• Возможности и статус проверки в runtime