工作階段設定檔

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

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

工作階段設定檔是一種宣告式 YAML 套件，由內容作者隨地圖或附加元件一起發佈，讓終端使用者只需一個命令（OmsiLaunch.exe /predefined-profile:<id> /predefined-profile-index:<1..5> /new）就能啟動可重現的 OmsiLaunch 工作階段。本頁是下列內容的規範性參考：由 src/OmsiLaunch.Core/SessionProfiles.cs 中的 SessionProfileCompiler 所實作的 omsilaunch.session-profile/v1 格式、CLI 套用的優先順序規則（tools/OmsiLaunch.Cli/Program.cs 中的 CliInput.BuildSpecAsync 與 RejectProfileConflicts），以及設定檔可寫入的設定目錄（ConfigurationCatalog）。設定檔能做的一切，CLI 旗標與 LaunchSpec 也都能做；設定檔只是將這些選擇打包起來。

穩定性：剖析、驗證、衝突偵測以及 settings / presentation / internet-textures / behavior 區塊為 STABLE_BETA（離線測試 session-profiles.strict-compiler；overlay（暫時覆蓋）與還原路徑已由 RV-005 與 RV-006 於執行階段驗證，請見執行階段驗證狀態）。new.date、new.time、new.year 與 new.weather 鍵在此組建中為 UNAVAILABLE（請見 new 區塊）。

套件位置與命名#

設定檔由使用者或內容作者安裝與移除。OmsiLaunch 從不寫入套件、從不複製套件，也從不刪除套件。套件目錄不屬於任何交易。

剖析規則#

純量（未加引號）中的反斜線是字面字元。Windows 路徑請以單一反斜線書寫（maps\Grundorf\global.cfg）。純量中的雙反斜線在值中仍會維持雙反斜線；請見隨附的範例。

鍵參考#

情境名稱與編譯器所使用的名稱完全相同。此處列出的每個鍵都會被接受；除此之外一律不接受。

profile（根對應）#

compatibility#

new#

只要此區塊存在就會被讀取與驗證，但只有在所選世界模式為 NEW_MAP（/new，CLI 預設值）時才會套用到 spec。在 /saved:<file.osn> 下此區塊會被忽略。

date、time、year 與 weather 會以 DateTimeMode.Explicit／所選的 WeatherMode 編譯為 DateSpec、TimeSpec、YearSpec 與 WeatherSpec。接著工作階段規劃器（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；除非由 /spec 設定，否則它維持為 false。

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）的鍵。值以字串儲存，並在工作階段建立其 overlay 時轉換為 options.cfg 修補；因此無效值會在 StartSessionAsync 時才被偵測到，而非在載入設定檔時，並使工作階段以 OL_E_START_SESSION 失敗，其訊息帶有 OL_E_INVALID_SETTING_VALUE: <key>。下列每個設定都會寫入 options.cfg；它們全都限於工作階段範圍，並在工作階段結束後精確還原。

值的形式：

• bool 為 true 或 false（不區分大小寫）。對於存在型 token，會新增或移除該 token；對於反向 token（no_*），true 會移除否定 token。
• 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。建立工作階段時，同樣的重新分析點規則也會套用到 Texture\ 下的 .itx 目標。

優先順序與覆寫衝突#

CliInput.BuildSpecAsync 依下列順序組合 spec：

1. 預設值（NEW_MAP、所有項目皆未設定、逾時 180 s / 30 s）。
2. /spec:<file.json>：若有指定，會完全取代預設值。
3. 安裝根目錄：明確的安裝引數優先於 spec 的 RootPath；. 表示包含可執行檔的目錄。
4. 設定檔（/predefined-profile + /predefined-profile-index）：載入套件，並在合併任何內容之前，對原始 CLI 引數執行 RejectProfileConflicts。接著種子的世界區塊會重設為所選模式的空 WorldSpec（使用設定檔時，/spec 的世界會被捨棄），再由 SessionProfileCompiler.Apply 將設定檔疊加到種子上：new（僅 NEW_MAP）、settings（合併到種子的 Environment.General 之上，逐鍵以設定檔為準），以及 presentation、internet-textures、behavior（各自只在預設組合有定義時取代種子的對應區塊）。
5. 其餘 CLI 引數疊加在最上層：/map、/entrypoint、/entrypoint-index、/date、/time、/year、天氣旗標、車輛旗標、/set、啟動畫面旗標、Internet Textures 旗標、/startup-timeout、/shutdown-timeout。CLI 的逾時只在有指定時套用；否則維持 spec／設定檔／預設值。
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 中的呈現方式#

成功載入後，spec 會在 LaunchSpec.SessionProfile 中攜帶一筆 SessionProfileMetadata 記錄：

規劃器會在由此類 spec 建立的每個 SessionPlan 中加入資訊性診斷訊息 session_profile.selected，其資料鍵為 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 的整合者可以呼叫 OmsiLaunch.Core 中的 SessionProfileCompiler.Load 與 SessionProfileCompiler.Apply；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：設定檔所編譯成的記錄
• 交易與復原：settings、啟動畫面與 .itx overlay 如何套用與還原
• 功能與執行階段驗證狀態