LaunchSpec 参考

文档版本 v0.1.0-beta.3在 GitHub 上查看源文件

本页是 OmsiLaunch 0.1.0-beta3 英文原始页面 的译文。英文页面为规范文本：如有出入，以英文页面和代码为准。

本页是 LaunchSpec 的规范性参考。LaunchSpec 是描述单个 OmsiLaunch 会话的请求记录。本页说明：它的 C# 结构（OmsiLaunch.Api）；CLI 加载的 JSON 文件形式（/spec:<path>，tools/OmsiLaunch.Cli/LaunchSpecJson.cs）；每个属性的类型、默认值、校验规则和当前效果；使计划不可运行的校验规则；以及 CLI 参数、spec 文件和会话配置档之间的优先级。本页只记录当前代码实际执行的行为。

相关页面：公共 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
}

在版本（build）支持的情况下，显式日期写作 "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 } } }。在当前版本（build）上，两者都会使计划不可运行（见下文）。

属性参考#

“使用情况”列说明当前代码如何处理该值。稳定性采用公共 API 页面的术语。

LaunchSpec（根）#

只读访问器（出现在 CLI 的 JSON 输出中，加载时被忽略）：EffectiveYear、EffectiveWeather、EffectiveInput、EffectiveDiagnostics、EffectivePresentation、EffectiveInternetTextures。

InstallationSpec#

WorldSpec#

DateSpec、TimeSpec、YearSpec#

WeatherSpec#

PlayerVehicleSpec（位于 PlayerVehicle 内）#

Presence 为 1 但所有字段均未设置的 PlayerVehicle 会被接受，且不产生任何效果。在当前版本（build）上，设置任何字段都会使计划不可运行（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，报告为带 OL_E_START_SESSION 的 Failed 会话）。键不区分大小写。未设置的条目被忽略。CLI 参数 /set:<key>=<value> 写入 General；会话配置档的 settings 也合并到 General 中。

被修补的文件保留其编码（保留 Windows-1252 字节；遵循带 BOM 的 UTF-8/UTF-16）和换行符。

LaunchBehaviorSpec#

InputSpec#

DiagnosticsSpec#

CLI 参数 /log、/logall、/omsi-logall、/verbose、/trace、/trace-process、/trace-plugin、/trace-native 会填充这些布尔值（/logall 设置 Verbose、ProcessTrace、PluginTrace、NativeTrace）；它们与 spec 中的值做逻辑或（OR）运算。

SessionPresentationSpec#

InternetTexturesSpec#

SessionProfileMetadata#

枚举#

超出声明范围的整数会被序列化器原样存储，并表现为未知值（例如，未知的 WorldMode 既不是 NEW_MAP 也不是 SAVED_SITUATION，得到的计划没有世界能力；插件会拒绝它，但 CLI 无论如何都会替换该模式，参见优先级）。

校验规则与不可运行诊断信息#

PlanSessionAsync 先运行 LaunchValidation.Validate，再运行 SessionPlanner.PlanAsync。当且仅当没有任何诊断代码以 OL_E_ 开头时，计划才可运行。完整列表：

规划时不校验（在启动时作为带 OL_E_START_SESSION 的 Failed 会话失败）：设置项的值（OL_E_INVALID_SETTING_VALUE）、永久插件完整性（OL_E_PERMANENT_PLUGIN_*）、租约可用性（OL_E_INSTALLATION_BUSY）、StartupTimeoutSeconds 范围（由 StartSessionAsync 抛出）。

信息性计划诊断信息：plugin.integrity.reference（消息为 manifest 或 self）、session_profile.selected。

优先级：CLI 参数、spec 文件与会话配置档#

CliInput.BuildSpecAsync（tools/OmsiLaunch.Cli/Program.cs）按以下顺序构建生效的 spec：

1. 种子 = 内置默认值；如果提供了 /spec 文件，则为该文件。
2. 安装根目录 = 若提供了显式安装参数则使用它，否则使用种子的 RootPath；然后 ./空值 → 可执行文件所在目录，再经 Path.GetFullPath 处理。显式安装参数总是优先于 spec 的 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）；spec 文件的 World.Mode 会被替换。要从 spec 运行已保存情景，请传入 /saved:。/map 和 /entrypoint//entrypoint-index 覆盖种子；CLI 的 /entrypoint 标识会清除索引；/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 仅在提供时覆盖种子；否则依次采用 spec、配置档，最后是默认值 180 s / 30 s。ShutdownTimeoutSeconds 对监管器而言是 ACCEPTED_FOR_COMPATIBILITY / CURRENTLY_NO_EFFECT。
9. 提供了 /splash、/splash-language、/splash-assets、/internet-textures、/internet-textures-profile 时，它们覆盖种子；SuppressTrayIcon 仅来自种子。
10. 诊断参数与种子做逻辑或（OR）运算。

结果：显式 CLI 参数 > 会话配置档 > spec 文件 > 内置默认值；例外是与配置档所拥有字段冲突的 CLI 参数会导致错误，而不是覆盖。

路径规则#

仅携带而不应用的字段#