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
}

明確日期（在組建支援時）寫成 "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（根）#

唯讀存取子（出現在 CLI JSON 輸出中，載入時忽略）：EffectiveYear、EffectiveWeather、EffectiveInput、EffectiveDiagnostics、EffectivePresentation、EffectiveInternetTextures。

InstallationSpec#

WorldSpec#

DateSpec、TimeSpec、YearSpec#

WeatherSpec#

PlayerVehicleSpec（位於 PlayerVehicle 內）#

Presence 為 1 且所有欄位皆未設定的 PlayerVehicle 會被接受，且沒有任何效果。在此組建中，設定任何欄位都會使計畫不可執行（STATICALLY_PARTIAL）。

EnvironmentSpec#

這八個群組會被串接在一起；鍵放在哪個群組中並無影響。每個 Presence 為 1 的項目都是來自 ConfigurationCatalog（src/OmsiLaunch.Configuration/ConfigurationCatalog.cs）的語意設定；鍵決定目標檔案（目前所有鍵皆為 options.cfg）與 token。規劃時會檢查鍵是否存在（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 時的 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 旗標會被視為錯誤，而不是覆寫。

路徑規則#

會攜帶但不套用#