# LaunchSpec リファレンス > このページは OmsiLaunch 0.1.0-beta3 の[英語版の原文ページ](https://github.com/lmonteirotech/OmsiLaunch/blob/v0.1.0-beta.3/docs/reference/launchspec.md)の翻訳です。規範となるのは英語版です。内容が異なる場合は、英語版のページとコードが優先されます。 このページは、1 つの OmsiLaunch セッションを記述する要求レコードである `LaunchSpec` の規範的なリファレンスです。対象は、C# での形（`OmsiLaunch.Api`）、CLI が読み込む JSON ファイル形式（`/spec:`、`tools/OmsiLaunch.Cli/LaunchSpecJson.cs`）、各プロパティの型・既定値・検証ルール・現在の効果、プランを実行不可にする検証ルール、そして CLI フラグ、spec ファイル、セッションプロファイルの間の優先順位です。記載しているのは現在のコードが実際に行うことだけです。 関連ページ: [公開 API](https://omsilaunch.omsimods.com.br/ja/docs/reference/public-api/index.md)、[CLI リファレンス](https://omsilaunch.omsimods.com.br/ja/docs/reference/cli/index.md)、[セッションプロファイル](https://omsilaunch.omsimods.com.br/ja/docs/reference/session-profiles/index.md)、[エラーコード](https://omsilaunch.omsimods.com.br/ja/docs/reference/errors/index.md)、[セッションのライフサイクル](https://omsilaunch.omsimods.com.br/ja/docs/concepts/session-lifecycle/index.md)、[ケイパビリティ](https://omsilaunch.omsimods.com.br/ja/docs/reference/capabilities/index.md)。 ## LaunchSpec の出どころ | 出どころ | `LaunchSpec` になるまで | | --- | --- | | API | インテグレーターがレコードを構築し、`PlanSessionAsync` に渡します。 | | CLI フラグ | `CliInput.BuildSpecAsync` が組み込みの既定値（NEW_MAP、すべて未設定、`Behavior` は既定値）から開始し、フラグを適用します。 | | `/spec:` JSON ファイル | `LaunchSpecJson.LoadAsync` で読み込まれ、CLI フラグが上書きする基点（シード）として使われます（[優先順位](#precedence-cli-flags-vs-spec-file-vs-session-profile)を参照）。 | | セッションプロファイル（`/predefined-profile: /predefined-profile-index:`） | `SessionProfileCompiler.Apply` がプロファイルの world、settings、presentation、internet-textures、behaviour をシードに書き込み、`SessionProfile` メタデータを記録します。 | 以下の[完全な例](#complete-example)はレコードの形に照らして検証済みです。最小構成の例のコピーが `examples/release-session.example.json`（リリースパッケージでは `.omsilaunch\examples\release-session.example.json`）として同梱されています。 ## JSON 形式 | ルール | 詳細 | | --- | --- | | シリアライザー | `System.Text.Json` を `PropertyNameCaseInsensitive = true`、`ReadCommentHandling = Skip`、`AllowTrailingCommas = true` で使用します。コンバーターは登録されていません。 | | プロパティ名 | C# のプロパティ名（`Installation`、`RootPath`、...）です。読み込み時の照合は大文字と小文字を区別しません。CLI は PascalCase で書き出します。 | | 列挙型 | 整数です（文字列列挙型のコンバーターはありません）。`"Mode": 0` は有効で、`"Mode": "NewMap"` は不正な JSON として拒否されます。値は[列挙型](#enumerations)に記載しています。 | | `OptionalValue` | オブジェクト `{ "Presence": 0 | 1, "Value": }` です。`Presence` 0 = `Unset`（値は無視されます）、1 = `Set`（値が存在し、null でない必要があります。値が null の `Set` は検証されず、無効な値として振る舞います）。省略された `OptionalValue` メンバーは `Unset` です。読み取り専用の `IsSet` メンバーは CLI が書き出す出力に含まれ、読み込み時には受け付けられて無視されます。 | | 任意のレコード | `Year`、`Weather`、`Input`、`Diagnostics`、`Presentation`、`InternetTextures`、`SessionProfile` は `null` にするか省略できます。`Effective*` アクセサーが既定値で補います。 | | 必須のレコード | `Installation`、`World`、`Date`、`Time`、`Environment`（8 つの辞書すべてを含む。空なら `{}` を使用）、`Behavior` はオブジェクトとして存在する必要があります。これらは検証されません。`null` または欠落している場合は後で null 参照により失敗し、CLI はそれを `OL_E_INTERNAL`（終了コード 10）または `OL_E_INVALID_ARGUMENT`（終了コード 2）として報告します。 | | 未知のプロパティ | バインドの前に拒否されます: `OL_E_SPEC_UNKNOWN_PROPERTY: $.Path.Name`（パスにはファイルに書かれたとおりのメンバー名が使われます）。辞書の内容（`Environment.*`）はプロパティとしては検査されません。 | | ルート | JSON オブジェクトである必要があります: `OL_E_SPEC_INVALID`。最大ネスト深さは 32 です。 | | ファイルサイズ | 最大 1 MiB（1 048 576 バイト）: `OL_E_SPEC_TOO_LARGE`。ファイルが存在しない場合: `OL_E_SPEC_NOT_FOUND`。 | | コメントと末尾のカンマ | `//` および `/* */` のコメントと末尾のカンマは受け付けられます。 | | 不正な JSON | パーサーの例外は変換されません。CLI は `OL_E_INTERNAL` を終了コード 10 で報告します。 | | エンコーディング | UTF-8（リーダーは BOM を許容します）。識別子内のバックスラッシュはエスケープする必要があります（`"maps\\Grundorf\\global.cfg"`）。マップ、シチュエーション、車両、HOF の識別子ではスラッシュも受け付けられます。 | ## 完全な例 ```jsonc { // 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 ページ](https://omsilaunch.omsimods.com.br/ja/docs/reference/public-api/index.md#stability-vocabulary)の用語に従います。 ### `LaunchSpec`（ルート） | プロパティ | JSON 型 | 必須 | 省略時の既定値 | 使用 | 安定性 | | --- | --- | --- | --- | --- | --- | | `Installation` | `InstallationSpec` オブジェクト | はい | なし | はい | `STABLE_BETA` | | `World` | `WorldSpec` オブジェクト | はい | なし | はい | `STABLE_BETA` | | `Date` | `DateSpec` オブジェクト | はい | なし | 検証されます。`Unset` 以外のモードは実行不可 | `PARTIAL` | | `Time` | `TimeSpec` オブジェクト | はい | なし | 検証されます。`Unset` 以外のモードは実行不可 | `PARTIAL` | | `PlayerVehicle` | `OptionalValue` | いいえ | `Unset` | 診断のために解決されます。いずれかのフィールドが設定されていると実行不可 | `PARTIAL` | | `Environment` | `EnvironmentSpec` オブジェクト | はい | なし | はい（セマンティックな `options.cfg` オーバーレイ） | `STABLE_BETA` | | `Behavior` | `LaunchBehaviorSpec` オブジェクト | はい | なし | 一部（レコードを参照） | `STABLE_BETA` / `PARTIAL` | | `Year` | `YearSpec` オブジェクトまたは null | いいえ | `null` → `EffectiveYear` = モード `Unset` | `Unset` 以外のモードは実行不可 | `PARTIAL` | | `Weather` | `WeatherSpec` オブジェクトまたは null | いいえ | `null` → `EffectiveWeather` = モード `Unset` | `Unset` 以外のモードは実行不可 | `PARTIAL` | | `Input` | `InputSpec` オブジェクトまたは null | いいえ | `null` → `EffectiveInput` = 両方とも未設定 | ドキュメントが 1 つでも設定されていると実行不可 | `PARTIAL` | | `Diagnostics` | `DiagnosticsSpec` オブジェクトまたは null | いいえ | `null` → `EffectiveDiagnostics` = 既定値 | 保持されるのみ | `PARTIAL` | | `Presentation` | `SessionPresentationSpec` オブジェクトまたは null | いいえ | `null` → `EffectivePresentation` = 管理されたスプラッシュ、言語なし、カスタムディレクトリなし、トレイ表示 | はい | `STABLE_BETA` | | `InternetTextures` | `InternetTexturesSpec` オブジェクトまたは null | いいえ | `null` → `EffectiveInternetTextures` = `Native` | はい | `STABLE_BETA` / `EXPERIMENTAL` | | `SessionProfile` | `SessionProfileMetadata` オブジェクトまたは null | いいえ | `null` | 出自の記録のみ（`session_profile.selected` プラン診断） | `STABLE_BETA` | 読み取り専用アクセサー（CLI の JSON 出力に含まれ、読み込み時には無視されます）: `EffectiveYear`、`EffectiveWeather`、`EffectiveInput`、`EffectiveDiagnostics`、`EffectivePresentation`、`EffectiveInternetTextures`。 ### `InstallationSpec` | プロパティ | 型 | 既定値 | 有効な値 | 使用 | 安定性 | | --- | --- | --- | --- | --- | --- | | `RootPath` | string | 必須 | `Omsi.exe` と `plugins\` を含むディレクトリ。[パスのルール](#path-rules)を参照してください。空または空白のみ → `OL_E_INSTALLATION_NOT_FOUND`。 | はい | `STABLE_BETA` | | `ExpectedExecutableSha256` | string または null | `null` | 任意の文字列。 | 現在のコードには使用箇所がありません。ホストは常に `Omsi.exe` のハッシュを計算してビルドプロファイルと比較し、この値とは比較しません。 | `PARTIAL`（保持されるが、現在は効果なし） | ### `WorldSpec` | プロパティ | 型 | 既定値 | 有効な値 | 使用 | 安定性 | | --- | --- | --- | --- | --- | --- | | `Mode` | `WorldMode` int | 必須 | `0` `NewMap`、`1` `SavedSituation`、`2` `LastMapState`（`LastSituation` は同じ値 2 を持つ廃止済みの別名）。 | はい。`LastMapState` → `OL_E_CAPABILITY_UNAVAILABLE` | `NewMap`、`SavedSituation`: `STABLE_BETA`、`LastMapState`: `UNAVAILABLE` | | `MapIdentity` | `OptionalValue` | `Unset` | `NewMap` の場合は必須で、`maps\\global.cfg` の形式（大文字と小文字を区別しない、`/` 可、`..` 不可）であり、インストールされている必要があります。`SavedSituation` では無視されます（マップは `.osn` が提供します）。 | はい（ハンドオフ） | `STABLE_BETA` | | `SituationIdentity` | `OptionalValue` | `Unset` | `SavedSituation` の場合は必須で、インストール済みの `situations\...\.osn` 識別子（`DiscoverAsync(Situations)` / `/list:situations` が返すもの）です。 | はい（ハンドオフ） | `STABLE_BETA` | | `PresentedEntrypointIndex` | `OptionalValue` | `Unset` | `EntrypointIdentity` のない `NewMap` の場合は必須で、`>= 0` であり、そのマップについて OMSI が提示するエントリポイント一覧へのインデックスです。未設定の場合はプラグインに `-1` として送られます。 | はい（ハンドオフ） | `STABLE_BETA` | | `EntrypointIdentity` | `OptionalValue` | `Unset` | 生のエントリポイントラベルまたはディスカバリ識別子。設定するとプランが実行不可になります（`world.entrypoint-identity`、`RUNTIME_PARTIAL`、`OL_E_CAPABILITY_UNAVAILABLE`）。 | 保持される | `PARTIAL` | | `Entrypoint` | `EntrypointSpec`（読み取り専用） | 算出 | `EntrypointIdentity` が設定されていれば `Mode` = `Identity`、そうでなくインデックスが設定されていれば `PresentedIndex`、それ以外は `Unset`。`PresentedIndex`、`Identity` は入力をそのまま反映します。 | 派生 | `STABLE_BETA` | ### `DateSpec`、`TimeSpec`、`YearSpec` | プロパティ | 型 | 既定値 | 有効な値 | 使用 | 安定性 | | --- | --- | --- | --- | --- | --- | | `Mode` | `DateTimeMode` int | 必須（`Year`: レコードが null の場合は `0`） | `0` `Unset`、`1` `Explicit`、`2` `System`。 | `Explicit`/`System` → `unsupported` エントリ（`world.explicit-date`、`world.explicit-time`、`world.explicit-year`、`STATICALLY_PARTIAL`）と `OL_E_CAPABILITY_UNAVAILABLE`。モードは起動ハンドオフにもコピーされ、`Unset` でない場合はプラグインが拒否します（プランが実行不可であるため、実際にそこへ到達することはありません）。 | `PARTIAL` | | `Value` | `OptionalValue` / `OptionalValue` / `OptionalValue` | `Unset` | `SemanticDate`: `Year`、`Month` 1..12、`Day` 1..31。`SemanticTime`: `Hour` 0..23、`Minute` 0..59、`Second` 0..59。`Mode` が `Explicit` のときは設定されている必要があり（そうでなければ `OL_E_DATE_TIME_APPLY_FAILED`）、`Mode` が `Explicit` でないときは未設定である必要があります（`OL_E_INVALID_ARGUMENT`）。`YearSpec.Value` は検証されません。 | 検証のみ | `PARTIAL` | ### `WeatherSpec` | プロパティ | 型 | 既定値 | 有効な値 | 使用 | 安定性 | | --- | --- | --- | --- | --- | --- | | `Mode` | `WeatherMode` int | レコードが null の場合は `0` | `0` `Unset`、`1` `Preset`、`2` `Icao`、`3` `RealCurrent`。 | `Unset` 以外のモード → `weather` の unsupported エントリと `OL_E_CAPABILITY_UNAVAILABLE`。 | `PARTIAL` | | `Preset` | `OptionalValue` | `Unset` | プリセット名（検証されません）。 | 保持される | `PARTIAL` | | `Icao` | `OptionalValue` | `Unset` | ICAO コード（検証されません）。 | 保持される | `PARTIAL` | ### `PlayerVehicleSpec`（`PlayerVehicle` の内部） | プロパティ | 型 | 既定値 | 有効な値 | 使用 | 安定性 | | --- | --- | --- | --- | --- | --- | | `Model` | `OptionalValue` | `Unset` | インストール済みの `Vehicles\...\.bus` 識別子。そうでなければ `OL_E_VEHICLE_NOT_FOUND`。 | `ResolvedContent` に解決され、その後 `player-vehicle.model` が unsupported → `OL_E_CAPABILITY_UNAVAILABLE` | `PARTIAL` | | `Repaint` | `OptionalValue` | `Unset` | `Model` のリペイント識別子（`#item:`）。そうでなければ `OL_E_REPAINT_NOT_FOUND`。`Model` が設定されている場合にのみ検査されます。 | 同上 | `PARTIAL` | | `Hof` | `OptionalValue` | `Unset` | インストール済みの `Vehicles\...\.hof`。そうでなければ `OL_E_HOF_NOT_FOUND`。 | 同上 | `PARTIAL` | | `FleetNumber` | `OptionalValue` | `Unset` | 任意の文字列。 | `OL_E_CAPABILITY_UNAVAILABLE` | `PARTIAL` | | `Registration` | `OptionalValue` | `Unset` | 任意の文字列。 | `OL_E_CAPABILITY_UNAVAILABLE` | `PARTIAL` | | `Enabled` | bool（読み取り専用） | 算出 | `Model` が設定されていれば `true`。ハンドオフが `PlayerVehicleEnabled` として運ぶのは `PlayerVehicle.IsSet` です。 | 派生 | `PARTIAL` | `Presence` が 1 で、すべてのフィールドが未設定の `PlayerVehicle` は受け付けられ、効果はありません。このビルドでは、いずれかのフィールドが設定されているとプランは実行不可になります（`STATICALLY_PARTIAL`）。 ### `EnvironmentSpec` | プロパティ | 型 | 既定値 | 使用 | 安定性 | | --- | --- | --- | --- | --- | | `General`、`Advanced`、`Graphics`、`AdvancedGraphics`、`Sound`、`AiPassengers`、`Keyboard`、`Controllers` | それぞれ `IReadOnlyDictionary>`、必須（空の場合は `{}`） | なし | はい | `STABLE_BETA` | 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:=` フラグは `General` に書き込みます。セッションプロファイルの `settings` も `General` にマージされます。 | キー | 値 | 備考 | | --- | --- | --- | | `general.language` | string | `[language]` トークン | | `general.radio` | string | | | `general.alternateView`、`general.showOwnDriver`、`general.showErrorMessages`、`general.autoSave`、`general.currentTime`、`general.currentDate`、`general.currentYear` | `true` / `false` | 存在トークン（`autoSave` は `noAutoSave` の逆） | | `graphics.screenRatio` | string | | | `graphics.maxFPS` | 整数 10..200 | | | `graphics.tileDistance` | 整数 1..20 | | | `graphics.maxObjectDistanceMeters` | 数値 20..5000 | | | `graphics.minObjectScreenPercent` | 数値 0..10 | 100 で割って格納 | | `graphics.minReflectionObjectScreenPercent` | 数値 0..50 | 100 で割って格納 | | `graphics.maxObjectComplexity` | 整数 0..3 | | | `graphics.maxMapComplexity` | 整数 0..2 | | | `graphics.sunGlow`、`graphics.loadAllTiles`、`graphics.stencilBuffer`、`graphics.rainReflections`、`graphics.humansInRainReflections` | `true` / `false` | 存在トークン | | `graphics.stencilShadows` | `true` / `false` | `on` / `off` として書き込み | | `graphics.realTimeReflections` | `economy` / `full` | `STATICALLY_PARTIAL` | | `graphics.particles` | `enabled,maxPerEmitter,playerVehicleOnly,inReflections`（bool,int>=0,bool,bool） | `smokesystems` ブロック 1 つ | | `simulation.collision`、`simulation.collisionTerrain`、`simulation.collisionVehicles`、`simulation.collisionPedestrians`、`simulation.disableAutomaticScheduleAnalysisPopup`、`simulation.ticketInfo`、`simulation.automaticClutch` | `true` / `false` | 存在トークン | | `simulation.ticketSelling` | 整数 0..2 | | | `simulation.maintenance` | 整数 0..4 | | | `advanced.reducedMultithreading` | `true` / `false` | 2 つの OMSI トークンを同時に操作（`RUNTIME_PROVEN`） | | `view.driverSmooth`、`view.driverMoving`、`controls.autoCenter`、`controls.reducedSteeringSpeed` | `true` / `false` | 存在トークン | | `traffic.randomVehicles` | 整数 0..1000 | 複数行の `AIMaxCountRandom` ブロックの成分 0（ランタイム検証済み、マトリクス RV-005） | | `traffic.humans` | 整数 0..1000 | `AIMaxCountRandom` の成分 1 | | `traffic.factorPercent` | 数値 1..300 | | | `traffic.parkedVehiclesPercent` | 数値 0..100 | | | `traffic.scheduledVehicles` | 数値 0..1000 | | | `traffic.scheduledLinePriority` | 数値 1..4 | | | `traffic.passengerFactorPercent` | 数値 0..200 | | | `sound.stereo` | 数値 0..100 | | | `sound.maxSimultaneousSounds` | 数値 5..1000 | | | `sound.masterVolume` | 数値 0..1 | | | `advanced.multithreadingCalculate`、`advanced.multithreadingTextureLoad`、`graphics.texture`、`graphics.textureFilter` | 拒否 | 既知だが書き込み不可 → `OL_E_SETTING_NOT_WRITABLE` | パッチが適用されたファイルは、エンコーディング（Windows-1252 のバイトはそのまま保持し、BOM 付きの UTF-8/UTF-16 は尊重します）と改行コードを維持します。 ### `LaunchBehaviorSpec` | プロパティ | 型 | 既定値 | 有効な値 | 使用 | 安定性 | | --- | --- | --- | --- | --- | --- | | `RestoreConfiguration` | bool | `true` | 任意 | 使用箇所なし: セッションが所有するファイルは常に正確に復元されます。 | `PARTIAL`（保持されるが、現在は効果なし） | | `SuppressStaleClosecheckWarning` | bool | `true` | 任意 | `true`: セッション前から存在する `closecheck` ファイルは開始時に完全に削除されます（SHA-256 を伴う診断 `closecheck.stale-removed`、失敗時は `OL_E_CLOSECHECK_REMOVE_FAILED`）。`false`: 既存の `closecheck` はそのまま残され、セッションによる削除対象にはなりません。セッション中に OMSI が書き込む `closecheck` は、復元時に常に削除されます。 | `STABLE_BETA` | | `StartupTimeoutSeconds` | int | `180` | 1..600（範囲外の場合は `StartSessionAsync` から `ArgumentOutOfRangeException`。CLI の `/startup-timeout` は 1..600 を強制し、プロファイルでは > 0 が必要）。スーパーバイザーの開始から `Running` までの時間枠です。期限を過ぎると、セッションは `OL_E_STARTUP_TIMEOUT`（プラグインが開始済みの場合）または `OL_E_PLUGIN_NOT_LOADED` で失敗します。 | はい | `STABLE_BETA` | | `ShutdownTimeoutSeconds` | int | `30` | 任意の int（CLI の `/shutdown-timeout` は 1..600） | 使用箇所なし: スーパーバイザーは `TerminateProcess` で OMSI を即座に終了させます。協調的なシャットダウンの待機はありません。 | `PARTIAL`（保持されるが、現在は効果なし） | ### `InputSpec` | プロパティ | 型 | 既定値 | 使用 | 安定性 | | --- | --- | --- | --- | --- | | `KeyboardDocument` | `OptionalValue` | `Unset` | 設定 → `input.keyboard` が unsupported（`STATICALLY_PARTIAL`）となり `OL_E_CAPABILITY_UNAVAILABLE`。キーボードの PATCH/REPLACE の実行は未実装です。 | `PARTIAL` | | `ControllerDocument` | `OptionalValue` | `Unset` | 設定 → `input.controller` が unsupported となり `OL_E_CAPABILITY_UNAVAILABLE`。 | `PARTIAL` | ### `DiagnosticsSpec` | プロパティ | 型 | 既定値 | 使用 | 安定性 | | --- | --- | --- | --- | --- | | `Log` | bool | `true` | `src/` に使用箇所はありません。ホストトレース `\.omsilaunch\diagnostics\-host.log` は常に書き込まれます。 | `PARTIAL`（保持されるが、現在は効果なし） | | `Verbose` | bool | `false` | 使用箇所なし。 | `PARTIAL` | | `OmsiLogAll` | bool | `false` | 使用箇所なし。 | `PARTIAL` | | `ProcessTrace` | bool | `false` | 使用箇所なし。 | `PARTIAL` | | `PluginTrace` | bool | `false` | 使用箇所なし。 | `PARTIAL` | | `NativeTrace` | bool | `false` | 使用箇所なし。 | `PARTIAL` | CLI フラグ `/log`、`/logall`、`/omsi-logall`、`/verbose`、`/trace`、`/trace-process`、`/trace-plugin`、`/trace-native` がこれらのブール値を設定します（`/logall` は `Verbose`、`ProcessTrace`、`PluginTrace`、`NativeTrace` を設定します）。これらは spec の値と OR で結合されます。 ### `SessionPresentationSpec` | プロパティ | 型 | 既定値 | 有効な値 | 使用 | 安定性 | | --- | --- | --- | --- | --- | --- | | `Splash` | `SplashMode` int | `1`（`Managed`） | `0` `Unset`（別名 `Native`）: OMSI 自身のスプラッシュファイルには手を加えません。`1` `Managed`: OmsiLaunch がセッションの間 `GUI\NewSplashscreen_ENG.bmp` と `GUI\NewSplashscreen_.bmp` をオーバーレイします（終了後に正確に復元されます）。 | はい | `STABLE_BETA`（マトリクス RV-006） | | `Language` | `OptionalValue` | `Unset` | `PTB`/`PT-BR`、`ENG`/`EN`、`DEU`/`DE`、`FRA`/`FR`（大文字と小文字を区別しない）。それ以外の値はすべて `ENG` に正規化されます。未設定の場合は、`options.cfg` の `[language]` の値を読み取り、同じ方法で正規化します。 | はい（管理されたスプラッシュの場合のみ） | `STABLE_BETA` | | `CustomAssetDirectory` | `OptionalValue` | `Unset` | `ENG.bmp` と `.bmp`（640×480、24 ビット BMP）を含むディレクトリ。[パスのルール](#path-rules)を参照してください。ディレクトリがない場合: `OL_E_SPLASH_ASSET_DIRECTORY_MISSING`。ファイルがない場合: `OL_E_SPLASH_ASSET_MISSING`。形式が不正な場合: `OL_E_SPLASH_FORMAT_UNSUPPORTED`。未設定の場合は `\.omsilaunch\assets\splash`（パッケージから一度だけ初期配置されます）が使われ、それがなければパッケージ同梱の `assets\splash` が使われます。 | はい（管理されたスプラッシュの場合のみ） | `STABLE_BETA` | | `SuppressTrayIcon` | bool | `false` | `true` の場合、CLI オーナーの単独の Windows トレイ表示を抑止します。 | CLI オーナーのみ。API にはトレイがありません。CLI フラグはなく、spec ファイルからのみ指定できます。 | `STABLE_BETA` | ### `InternetTexturesSpec` | プロパティ | 型 | 既定値 | 有効な値 | 使用 | 安定性 | | --- | --- | --- | --- | --- | --- | | `Mode` | `InternetTexturesMode` int | `0`（`Native`） | `0` `Native`: 何も変更しません。`1` `Disabled`: プラグインが OMSI のプロセス内ダウンローダーを抑止します（テレメトリ `internet-textures.suppressed` / `internet-textures.suppression.failed`）。`2` `Override`: `.itx` プロファイルが `Texture\standard.itx` としてオーバーレイされ、そのターゲットファイルと `Texture\standard.ipr` はセッションによる削除対象になります。 | はい | `Native`: `STABLE_BETA`、`Disabled`、`Override`: `EXPERIMENTAL` | | `OverrideProfilePath` | `OptionalValue` | `Unset` | `Override` の場合は必須です（`OL_E_ITX_PROFILE_REQUIRED`）。2 行 1 組で構成されるテキストファイルで、1 行目は絶対 `http`/`https` URL、2 行目はインストールルートからの相対ターゲットパスです。ターゲットパスは `Texture\` コンポーネントを含み、ルート付きでなく、`..` を含まず、`\` で始まらず、ジャンクション/シンボリックリンクを経由しない必要があります（`OL_E_ITX_PROFILE_INVALID`、`OL_E_ITX_TARGET_OUTSIDE_TEXTURE_PATH`）。[パスのルール](#path-rules)を参照してください。 | はい | `EXPERIMENTAL` | ### `SessionProfileMetadata` | プロパティ | 型 | 使用 | 安定性 | | --- | --- | --- | --- | | `Id`、`Name`、`Version`、`Author`、`PresetId`、`PresetIndex`、`PresetName`、`PackagePath` | 文字列 / int | プラン診断 `session_profile.selected`（`Data["session_profile.*"]`）に記録されます。それ以外では使用されません。通常は手作業ではなくセッションプロファイルコンパイラーが設定します。 | `STABLE_BETA` | ## 列挙型 | 列挙型 | 値（JSON 整数） | | --- | --- | | `WorldMode` | `NewMap` = 0、`SavedSituation` = 1、`LastMapState` = 2、`LastSituation` = 2（廃止済みの別名。OMSI ネイティブの「前回のマップ状態」分岐であり、最新の `.osn` を意味することはありません） | | `DateTimeMode` | `Unset` = 0、`Explicit` = 1、`System` = 2 | | `WeatherMode` | `Unset` = 0、`Preset` = 1、`Icao` = 2、`RealCurrent` = 3 | | `SplashMode` | `Unset` = 0、`Native` = 0（別名）、`Managed` = 1 | | `InternetTexturesMode` | `Native` = 0、`Disabled` = 1、`Override` = 2 | | `Presence` | `Unset` = 0、`Set` = 1 | | `EntrypointMode`（読み取り専用の `Entrypoint.Mode`） | `Unset` = 0、`PresentedIndex` = 1、`Identity` = 2 | 宣言された範囲外の整数はシリアライザーによってそのまま格納され、未知の値として振る舞います（たとえば未知の `WorldMode` は NEW_MAP でも SAVED_SITUATION でもなく、world ケイパビリティを持たないプランになります。プラグインはこれを拒否しますが、CLI はいずれにせよモードを置き換えます。優先順位を参照してください）。 ## 検証ルールと実行不可の診断 `PlanSessionAsync` は `LaunchValidation.Validate` を実行し、続いて `SessionPlanner.PlanAsync` を実行します。プランが実行可能であるのは、`OL_E_` で始まる診断コードが 1 つもない場合に限ります。完全な一覧は次のとおりです。 | 診断 | 条件 | 発生元 | | --- | --- | --- | | `OL_E_INSTALLATION_NOT_FOUND` | `Installation.RootPath` が空または空白のみ | `LaunchValidation` | | `OL_E_DATE_TIME_APPLY_FAILED` | `Date.Mode` = `Explicit` で値が設定されていない、または月/日が範囲外。`Time.Mode` = `Explicit` で値が設定されていない、または時/分/秒が範囲外 | `LaunchValidation` | | `OL_E_INVALID_ARGUMENT` | モードが `Explicit` でないのに `Date.Value` または `Time.Value` が設定されている | `LaunchValidation` | | `OL_E_MAP_NOT_FOUND` | `NewMap` で `MapIdentity` が未設定、または `maps\...\global.cfg` の形式でない（検証）。`NewMap` で識別子がインストールされていない（プランナー） | 両方 | | `OL_E_ENTRYPOINT_NOT_FOUND` | `NewMap` で `EntrypointIdentity` がなく、`PresentedEntrypointIndex` が未設定または負 | `LaunchValidation` | | `OL_E_ENTRYPOINT_REQUIRED` | `NewMap`、マップはインストール済み、`EntrypointIdentity` なし、`PresentedEntrypointIndex` 未設定（`world.presented-entrypoint` が利用不可） | `SessionPlanner` | | `OL_E_SITUATION_NOT_FOUND` | `SavedSituation` で `SituationIdentity` がない（検証）、または識別子がインストールされていない（プランナー） | 両方 | | `OL_E_SITUATION_MAP_NOT_FOUND` | `SavedSituation`: `.osn` 内で指定されたマップがインストールされていない | `SessionPlanner` | | `OL_E_UNSUPPORTED_OPERATING_SYSTEM` | 「x64 OS 上の Windows 10 以降で、x64 のホストプロセスとして動作している」という条件を満たさない（`runtime.current-windows-x64`） | `SessionPlanner` | | `OL_E_INSTALLATION_NOT_WRITABLE` | ルートディレクトリが存在しない、読み取り専用属性が設定されている、または `plugins\` サブディレクトリがない（`transaction.exact-restore`） | `SessionPlanner` | | `OL_E_UNSUPPORTED_BUILD` | `Omsi.exe` が存在しない、またはそのサイズ/SHA-256 がプロファイルのフィンガープリント（`692EBFBF...`、8 503 440 バイト）とも許可リストのハッシュ（`omsi.profile.OMSI23004`）とも一致しない | `SessionPlanner` | | `OL_E_CAPABILITY_UNAVAILABLE` | `World.Mode` = `LastMapState`。`EntrypointIdentity` が設定されている。`Date`/`Time`/`Year` のモードが `Unset` でない。`Weather` のモードが `Unset` でない。`PlayerVehicle` のいずれかのフィールドが設定されている。`Input.KeyboardDocument` または `Input.ControllerDocument` が設定されている | `SessionPlanner` | | `OL_E_VEHICLE_NOT_FOUND`、`OL_E_REPAINT_NOT_FOUND`、`OL_E_HOF_NOT_FOUND` | `PlayerVehicle.Model` / `Repaint` / `Hof` がインストールされていない（`OL_E_CAPABILITY_UNAVAILABLE` に加えて） | `SessionPlanner` | | `OL_E_UNKNOWN_SETTING`、`OL_E_SETTING_NOT_WRITABLE` | カタログにない / 書き込み不可の `Environment` キー | `SessionPlanner` | | `OL_E_SESSION_PRESENTATION_INVALID` | スプラッシュ/ITX プランの構築中に例外が発生した。メッセージには `OL_E_SPLASH_ASSET_DIRECTORY_MISSING`、`OL_E_SPLASH_ASSET_MISSING`、`OL_E_SPLASH_FORMAT_UNSUPPORTED`、`OL_E_ITX_PROFILE_REQUIRED`、`OL_E_ITX_PROFILE_MISSING`、`OL_E_ITX_PROFILE_INVALID`、`OL_E_ITX_TARGET_OUTSIDE_TEXTURE_PATH` のいずれかが含まれる | `SessionPlanner` | | `OL_E_RUNTIME_ARTIFACT_MISSING` | プラグインクロージャーの参照（`OmsiLaunchRuntimePaths`）またはリリースマニフェストを読み込めない（メッセージに `OL_E_RELEASE_MANIFEST_INVALID` が含まれる場合がある） | `OmsiLaunchService.PlanSessionAsync` | プラン時には検証されないもの（開始時に `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:`、`/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:=` のエントリは `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 フラグは、上書きではなくエラーになります。 ## パスのルール | パス | API での動作 | CLI での動作 | | --- | --- | --- | | `Installation.RootPath` | 指定されたとおりに使われます。相対パスはファイル操作においてプロセスの作業ディレクトリを基準に解決されます。絶対パスを渡してください。リース、ジャーナル、コンテンツカタログは `Path.GetFullPath` で正規化します。 | `.` または空 = `OmsiLaunch.exe` を含むディレクトリであり、呼び出し元の作業フォルダーになることはありません。明示的なインストール引数は spec より優先されます。結果は絶対パスに変換されます。 | | `Presentation.CustomAssetDirectory` | 絶対パス、または `Installation.RootPath` からの相対パス。存在している必要があります。 | 同じです（`/splash-assets`）。セッションプロファイルの `assets` パスはプロファイルパッケージ内に制限され、絶対パスとして格納されます。 | | `InternetTextures.OverrideProfilePath` | `Path.GetFullPath` で解決されます。つまり、インストールルートではなくプロセスの作業ディレクトリが基準です。存在している必要があります。 | 同じです（`/internet-textures-profile`）。セッションプロファイルの `profile` パスはパッケージ内に制限され、絶対パスとして格納されます。 | | ITX のターゲット行 | インストールルートからの相対パス。`Texture\` コンポーネントを含む必要があります。ルートなし、`..` なし、先頭の `\` なし、ジャンクション/シンボリックリンクのコンポーネントなし。 | 同じです。 | | コンテンツ識別子（`MapIdentity`、`SituationIdentity`、`PlayerVehicle.*`） | インストール環境からの相対パスで、大文字と小文字を区別せず、`/` を受け付けます。絶対パスにはなりません。 | 同じです。 | ## 保持されるが適用されないもの | フィールド | 現在の効果 | 安定性 | | --- | --- | --- | | `Installation.ExpectedExecutableSha256` | なし（ホストは `Omsi.exe` のハッシュをビルドプロファイルと照合します） | `PARTIAL` | | `Behavior.RestoreConfiguration` | なし（復元は常に実行されます） | `PARTIAL` | | `Behavior.ShutdownTimeoutSeconds` | なし（強制終了。`ACCEPTED_FOR_COMPATIBILITY / CURRENTLY_NO_EFFECT`） | `PARTIAL` | | `Diagnostics.*` | なし（ホストトレースは常に書き込まれます） | `PARTIAL` | | `Input.KeyboardDocument`、`Input.ControllerDocument` | 設定されているとプランが実行不可 | `PARTIAL` | | `Date`、`Time`、`Year`（`Unset` 以外のモード） | プランが実行不可（`STATICALLY_PARTIAL`） | `PARTIAL` | | `Weather`（`Unset` 以外のモード） | プランが実行不可（`STATICALLY_PARTIAL`） | `PARTIAL` | | `PlayerVehicle.*`（いずれかのフィールドが設定） | 診断のためにコンテンツは解決されるが、プランは実行不可（`STATICALLY_PARTIAL`） | `PARTIAL` | | `World.EntrypointIdentity` | プランが実行不可（`RUNTIME_PARTIAL`） | `PARTIAL` | | `World.Mode` = `LastMapState` / `LastSituation` | プランが実行不可（`UNSUPPORTED_FOR_CURRENT_PROFILE`） | `UNAVAILABLE` | | `SessionProfile` | 出自の診断のみ | `STABLE_BETA` |