Справочник по LaunchSpec

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

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

Эта страница — нормативный справочник по LaunchSpec, записи запроса, которая описывает один сеанс OmsiLaunch. Здесь описаны её форма в C# (OmsiLaunch.Api), её форма в виде JSON-файла, который загружает CLI (/spec:<path>, tools/OmsiLaunch.Cli/LaunchSpecJson.cs), каждое свойство с типом, значением по умолчанию, правилом проверки и текущим действием, правила проверки, делающие план неисполнимым, а также приоритет между флагами CLI, файлами спецификации и профилями сеанса. Документируется только то, что делает текущий код.

Связанные страницы: публичный API, справочник по CLI, профили сеанса, коды ошибок, жизненный цикл сеанса, возможности.

Откуда берётся LaunchSpec#

Приведённый ниже полный пример сверен с формой записи. Копия минимального примера поставляется как examples/release-session.example.json (и .omsilaunch\examples\release-session.example.json в релизном пакете).

Форма JSON#

Полный пример#

{
  // 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
}

Явная дата, если сборка её поддерживает, записывается как "Date": { "Mode": 1, "Value": { "Presence": 1, "Value": { "Year": 2024, "Month": 5, "Day": 1 } } }, а время — как { "Mode": 1, "Value": { "Presence": 1, "Value": { "Hour": 7, "Minute": 30, "Second": 0 } } }. В этой сборке и то и другое делает план неисполнимым (см. ниже).

Справочник по свойствам#

Столбец «Использование» указывает, что текущий код делает со значением. Для стабильности используется терминология со страницы публичного API.

LaunchSpec (корень)#

Методы доступа только для чтения (присутствуют в JSON-выводе CLI, при загрузке игнорируются): EffectiveYear, EffectiveWeather, EffectiveInput, EffectiveDiagnostics, EffectivePresentation, EffectiveInternetTextures.

InstallationSpec#

WorldSpec#

DateSpec, TimeSpec, YearSpec#

WeatherSpec#

PlayerVehicleSpec (внутри PlayerVehicle)#

PlayerVehicle с Presence 1 и всеми незаданными полями принимается и ни на что не влияет. Любое заданное поле в этой сборке делает план неисполнимым (STATICALLY_PARTIAL).

EnvironmentSpec#

Восемь групп объединяются; то, в какую группу помещён ключ, ни на что не влияет. Каждая запись с Presence 1 — это семантический параметр из ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs); ключ определяет целевой файл (options.cfg для всех текущих ключей) и токен. При планировании проверяется, что ключ существует (OL_E_UNKNOWN_SETTING) и доступен для записи (OL_E_SETTING_NOT_WRITABLE); значение проверяется только при запуске (OL_E_INVALID_SETTING_VALUE, сообщается как сеанс в состоянии Failed с OL_E_START_SESSION). Ключи не зависят от регистра. Незаданные записи игнорируются. Флаг CLI /set:<key>=<value> записывает в General; параметры settings профиля сеанса также объединяются в General.

Изменяемые файлы сохраняют свою кодировку (байты Windows-1252 сохраняются; UTF-8/UTF-16 с меткой BOM учитываются) и окончания строк.

LaunchBehaviorSpec#

InputSpec#

DiagnosticsSpec#

Флаги CLI /log, /logall, /omsi-logall, /verbose, /trace, /trace-process, /trace-plugin, /trace-native заполняют эти логические значения (/logall устанавливает Verbose, ProcessTrace, PluginTrace, NativeTrace); они объединяются со значениями спецификации через логическое ИЛИ.

SessionPresentationSpec#

InternetTexturesSpec#

SessionProfileMetadata#

Перечисления#

Целые числа вне объявленного диапазона сохраняются сериализатором как есть и ведут себя как неизвестные значения (например, неизвестный WorldMode не является ни NEW_MAP, ни SAVED_SITUATION и даёт план без возможности мира; плагин бы его отклонил, но CLI в любом случае заменяет режим, см. раздел о приоритете).

Правила проверки и диагностика неисполнимого плана#

PlanSessionAsync выполняет LaunchValidation.Validate, а затем SessionPlanner.PlanAsync. План исполним ровно тогда, когда ни один код диагностики не начинается с OL_E_. Полный набор:

Не проверяется на этапе планирования (приводит к сбою при запуске: сеанс в состоянии Failed с OL_E_START_SESSION): значения параметров (OL_E_INVALID_SETTING_VALUE), целостность постоянного плагина (OL_E_PERMANENT_PLUGIN_*), доступность аренды установки (OL_E_INSTALLATION_BUSY), диапазон StartupTimeoutSeconds (исключение из StartSessionAsync).

Информационные диагностические сообщения плана: plugin.integrity.reference (сообщение manifest или self), session_profile.selected.

Приоритет: флаги CLI, файл спецификации и профиль сеанса#

CliInput.BuildSpecAsync (tools/OmsiLaunch.Cli/Program.cs) строит итоговую спецификацию в следующем порядке:

1. Основа = встроенные значения по умолчанию или файл /spec, если он указан.
2. Корневой каталог установки = явный аргумент установки, если он указан, иначе RootPath из основы; затем ./пустое значение → каталог исполняемого файла, Path.GetFullPath. Явный аргумент установки всегда имеет приоритет над RootPath из спецификации.
3. Профиль сеанса (/predefined-profile + /predefined-profile-index): явные аргументы CLI, затрагивающие поле, которым владеет профиль, отклоняются с OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (поля мира — только в режиме NEW_MAP; ключи /set, присутствующие в пресете; флаги заставки, если в пресете есть presentation; флаги интернет-текстур, если в нём есть internet-textures; тайм-ауты, если в нём есть behavior). World из основы заменяется новым (сохраняется только режим мира из CLI), затем применяются блок new: профиля (только NEW_MAP), settings (в General), presentation, internet-textures, behavior и метаданные SessionProfile. compatibility.maps применяется для NEW_MAP и SAVED_SITUATION.
4. Мир: режим мира из CLI всегда имеет приоритет (/new по умолчанию, /saved:<osn>, /last); World.Mode из файла спецификации заменяется. Чтобы запустить сохранённую ситуацию из спецификации, передайте /saved:. /map и /entrypoint//entrypoint-index переопределяют основу; идентификатор /entrypoint из CLI сбрасывает индекс; /saved вместе с /map или флагами точки входа даёт OL_E_INVALID_ARGUMENT.
5. /date, /time, /year, /weather* переопределяют основу, если указаны (system выбирает DateTimeMode.System).
6. /no-vehicle сбрасывает PlayerVehicle; отдельные флаги /vehicle, /repaint, /hof, /fleet, /registration переопределяют отдельные поля ТС игрока из основы.
7. Записи /set:<key>=<value> добавляются в Environment.General (ключ проверяется, значение — нет); остальные семь групп берутся из основы без изменений.
8. /startup-timeout и /shutdown-timeout переопределяют основу, только если указаны; иначе действуют значение из спецификации, затем из профиля, затем значения по умолчанию 180 s / 30 s. ShutdownTimeoutSeconds для супервизора имеет статус ACCEPTED_FOR_COMPATIBILITY / CURRENTLY_NO_EFFECT (принимается для совместимости, сейчас ни на что не влияет).
9. /splash, /splash-language, /splash-assets, /internet-textures, /internet-textures-profile переопределяют основу, если указаны; SuppressTrayIcon берётся только из основы.
10. Флаги диагностики объединяются с основой через логическое ИЛИ.

Итог: явный флаг CLI > профиль сеанса > файл спецификации > встроенное значение по умолчанию, за исключением того, что флаг CLI, конфликтующий с полем, которым владеет профиль, является ошибкой, а не переопределением.

Правила путей#

Передаётся, но не применяется#