第一個工作階段

文件版本 v0.1.0-beta.3在 GitHub 上檢視原始檔

本頁為 OmsiLaunch 0.1.0-beta3 英文原始頁面 的翻譯。英文頁面為規範版本：若有出入，以英文頁面與程式碼為準。

本頁逐步說明如何以 OmsiLaunch 0.1.0-beta3 執行第一個受管理的 OMSI 工作階段：在不啟動 OMSI 的情況下規劃、以明確旗標啟動、以預先定義的工作階段設定檔啟動、控制與停止工作階段，以及事後查找診斷資訊。本頁假設套件已依安裝的說明完成安裝。每個旗標的規範都在 CLI 參考中；更多呼叫範例請參閱 CLI 範例。

工作階段會做什麼#

工作階段是圍繞單一 OMSI 處理程序的交易：OmsiLaunch 會為它將變更的檔案建立快照（預設為 GUI\ 下的兩個啟動畫面點陣圖，要求 /set overlay（暫時覆蓋）時再加上 options.cfg），在 .omsilaunch\ 下寫入持久的日誌，套用 overlay，帶著永久外掛程式啟動 Omsi.exe，等待進入遊戲（Running），在期間保持工作階段可受控制，最後終止 OMSI 並逐位元組還原每個變更過的檔案。/new 絕不會默默自行選擇地圖或進入點：兩者都必須明確指定，或來自 /spec 檔或工作階段設定檔。

1. 規劃（不會啟動任何東西）#

請在 OMSI 根目錄下執行；安裝預設為包含 OmsiLaunch.exe 的目錄。

OmsiLaunch.exe /list:Maps
OmsiLaunch.exe /list:Entrypoints /map:maps\Grundorf\global.cfg
OmsiLaunch.exe /new /map:maps\Grundorf\global.cfg /entrypoint-index:1 /plan --json

計畫必須顯示 "IsRunnable": true（結束代碼 0）。它會列出 TouchedFiles 與 PlannedMutations，讓您確切看到工作階段將覆蓋哪些內容。繼續之前請先修正任何 OL_E_ 診斷訊息；此時尚未寫入任何內容。

套件隨附的範例 spec 以檔案形式執行相同的操作：

OmsiLaunch.exe /spec:.omsilaunch\examples\release-session.example.json /plan

2. 以明確旗標啟動#

OmsiLaunch.exe /new /map:maps\Grundorf\global.cfg /entrypoint-index:1

依序會發生下列事情：

  1. 印出計畫（Plan: READY profile=Omsi23004_692EBFBF）。
  2. 復原任何較舊的待處理日誌、取得租用、建立快照、寫入日誌、套用 overlay、檢查外掛程式完整性、啟動 Omsi.exe。
  3. 出現系統匣圖示（OmsiLaunch is running）；請參閱 Windows 系統匣。
  4. 進入遊戲後，會以 JSON 印出 Running 狀態（"State": 14）。預設的啟動逾時為 180 s（可用 /startup-timeout:<1..600> 變更）。
  5. 主控台會保持連結，直到工作階段結束。請勿以關閉主控台視窗的方式停止：請使用下方的其中一種停止方法。

首次執行時可選擇加入：

  • /set:graphics.maxFPS=60（options.cfg overlay，結束時會還原）；
  • /splash:Unset 保持 OMSI 啟動畫面不變，或 /splash-language:DEU 選擇在地化的受管理啟動畫面；
  • /observe-seconds:30 在 Running 之後 30 s 自動停止（適合冒煙測試）；
  • --json 取得結構化輸出。

要求日期、時間、年份、天氣或玩家車輛的旗標（/date、/time、/year、/weather*、/vehicle……）會被接受，但此組建無法套用：計畫會變成 NOT RUNNABLE 並帶有 OL_E_CAPABILITY_UNAVAILABLE。請勿使用這些旗標。

3. 以預先定義的工作階段設定檔啟動#

工作階段設定檔是位於 <root>\.omsilaunch\session-profiles\<id>\profile.yaml 的 YAML 檔，用來固定地圖、進入點，以及最多五組設定的預設組合（preset）（結構描述 omsilaunch.session-profile/v1；完整參考請見工作階段設定檔）。建立 D:\OMSI 2\.omsilaunch\session-profiles\grundorf-quick\profile.yaml：

schema: omsilaunch.session-profile/v1
id: grundorf-quick
name: Grundorf quick start
author: You
version: "1.0"
compatibility:
  maps:
    - maps\Grundorf\global.cfg
new:
  map: maps\Grundorf\global.cfg
  entrypoint-index: 1
presets:
  - index: 1
    id: low
    name: Low detail
    settings:
      graphics.maxFPS: 30
      graphics.tileDistance: 3
  - index: 2
    id: high
    name: High detail
    settings:
      graphics.maxFPS: 60
      graphics.tileDistance: 8

接著執行：

OmsiLaunch.exe /predefined-profile:grundorf-quick /predefined-profile-index:2 /new /plan
OmsiLaunch.exe /predefined-profile:grundorf-quick /predefined-profile-index:2 /new

需要記住的規則：id 必須與目錄名稱相同；索引為 1..5；會覆寫設定檔所擁有欄位的明確旗標（/map、/entrypoint-index、預設組合所擁有的 /set 索引鍵、預設組合含有 presentation 時的啟動畫面旗標）會以 OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT 拒絕（結束代碼 2）；new: 區塊只在使用 /new 時套用；使用 /saved:<file.osn> 時，情境的地圖必須列在 compatibility.maps 下。套件隨附的 .omsilaunch\examples\session-profiles\rmg-leste\profile.yaml 示範了完整的結構描述，但其 new: 區塊設定了 date、time 與 weather，而此組建無法套用這些項目，因此請先移除這些索引鍵再複製使用。

4. 控制執行中的工作階段#

從同一目錄下的第二個主控台執行（不需安裝引數）：

OmsiLaunch.exe session status --json
OmsiLaunch.exe events watch
OmsiLaunch.exe time get
OmsiLaunch.exe vehicles list
OmsiLaunch.exe vehicles get --handle=rv-000001

這些命令會經由此安裝的本機控制管道傳送（本機控制）；結束代碼 4 表示此處沒有正在執行的擁有者。

5. 停止#

下列任一方式都會以相同流程結束工作階段（先終止 OMSI，接著還原每個變更過的檔案，再刪除日誌與備份）：

方法備註
系統匣圖示 → End session → 確認在 OmsiLaunch.exe 與 OmsiLaunchW.exe 工作階段中皆可使用。
OmsiLaunch.exe session stop從另一個主控台執行；會立即返回，由擁有者完成還原。
在擁有者主控台按 Ctrl+C要求停止；擁有者會等待還原完成後才結束。
/observe-seconds:<n>在 Running 之後 n 秒自動停止。
OMSI 自行結束擁有者偵測到 ProcessExited 後進行還原。

OMSI 本身的關閉程序不會執行，因此 OMSI 結束時不會改寫 options.cfg；這是刻意的設計，以確保還原精確。以 X 按鈕關閉擁有者主控台視窗時，還原只有 4 s 可完成；若未完成，下一次啟動（或 OmsiLaunch.exe /recover）會依據日誌將其完成。當工作階段以 Completed 結束時，擁有者的結束代碼為 0。

6. 事後查看的位置#

位置內容
主控台／--json 輸出計畫、Running 狀態、最終狀態（"State": 18 = Completed）。
<root>\.omsilaunch\diagnostics\<sessionId>-host.log工作階段的主機追蹤記錄（交易邊界、處理程序啟動、外掛程式交接、進入遊戲、還原）。
<root>\.omsilaunch\diagnostics\<sessionId>-runtime-operation.json由擁有者執行的 /runtime: 操作結果。
<root>\.omsilaunch\diagnostics\tray-host.log系統匣指示器事件。
OmsiLaunch.exe /recovery-status正常結束後為 "pending": false。true 表示仍留有日誌；請執行 OmsiLaunch.exe /recover。

若工作階段未能進入遊戲，最終狀態會帶有導致失敗的 OL_E_ 診斷訊息（例如 OL_E_STARTUP_TIMEOUT、OL_E_PLUGIN_NOT_LOADED、OL_E_PROCESS_EXITED_EARLY），結束代碼為 1，而檔案仍然已經還原。請參閱結束代碼、錯誤與已知限制。

在沒有主控台的情況下執行#

OmsiLaunch.exe /silent /new /map:maps\Grundorf\global.cfg /entrypoint-index:1

會委派給 OmsiLaunchW.exe 並立即回傳 0。此工作階段沒有主控台；失敗會以訊息方塊顯示，系統匣圖示是唯一可見的介面。請使用 session status、events watch 與診斷目錄追蹤其狀態。Windows 主機的完整行為請參閱 OmsiLaunchW.exe 參考。