LaunchSpec リファレンス

ドキュメントのバージョン v0.1.0-beta.3GitHub でソースを見る

このページは OmsiLaunch 0.1.0-beta3 の英語版の原文ページの翻訳です。規範となるのは英語版です。内容が異なる場合は、英語版のページとコードが優先されます。

このページは、1 つの OmsiLaunch セッションを記述する要求レコードである LaunchSpec の規範的なリファレンスです。対象は、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#

8 つのグループは連結されます。キーをどのグループに置いても効果は変わりません。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 でもなく、world ケイパビリティを持たないプランになります。プラグインはこれを拒否しますが、CLI はいずれにせよモードを置き換えます。優先順位を参照してください）。

検証ルールと実行不可の診断#

PlanSessionAsync は LaunchValidation.Validate を実行し、続いて SessionPlanner.PlanAsync を実行します。プランが実行可能であるのは、OL_E_ で始まる診断コードが 1 つもない場合に限ります。完全な一覧は次のとおりです。

プラン時には検証されないもの（開始時に 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 で拒否されます（world フィールドは NEW_MAP モードの場合のみ、/set のキーはプリセットに存在する場合、スプラッシュのフラグはプリセットに presentation がある場合、internet-textures のフラグは internet-textures がある場合、タイムアウトは behavior がある場合）。シードの World は新しいものに置き換えられ（CLI の world モードだけが残ります）、その後、プロファイルの new: ブロック（NEW_MAP の場合のみ）、settings（General へ）、presentation、internet-textures、behavior、および SessionProfile メタデータが適用されます。compatibility.maps は NEW_MAP と SAVED_SITUATION に対して強制されます。
4. World: CLI の world モードが常に優先されます（既定の /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 に追加されます（キーは検査され、値は検査されません）。残りの 7 つのグループはシードから変更されずに引き継がれます。
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 フラグは、上書きではなくエラーになります。

パスのルール#

保持されるが適用されないもの#