CLI リファレンス

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

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

このページは、OmsiLaunch 0.1.0-beta3 のコマンドラインに関する完全かつ規範的なリファレンスです。3 つの実行ファイル、引数の文法、ディスパッチ順序、すべてのコマンドワード、すべての階層ルート、すべてのフラグ、出力エンベロープ、および各コマンドのエラー時の動作を扱います。本ページは tools\OmsiLaunch.Cli\Program.cs（CliProgram.RunAsync、OwnerSession.RunAsync、CliInput.Parse、CliInput.KnownFlags、CliInput.AcceptedNoEffectFlags、CliInput.CommandWordsAccepted、CliInput.HierarchicalRoutes、CliInput.BuildSpecAsync、CliEventWatch）、tools\OmsiLaunch.Cli\LaunchSpecJson.cs、および tools\OmsiLaunch.Bootstrapper 配下の 2 つのネイティブシムから生成されています。プロセスの結果は終了コードに、エラーコードはエラーに、実際の呼び出し例は CLI の使用例に記載しています。

実行ファイル#

nethost.dll はシムと同じ場所に置く必要があります。シム自身は引数を読み取りません。すべての引数は変更されずに CliInput.Parse に届くため、OmsiLaunch.exe と OmsiLaunchW.exe はまったく同じ構文を受け付けます。

呼び出しモデル#

引数の文法（CliInput.Parse）#

結果として、階層ルート（time get）の後ろにインストール引数を置いて組み合わせることはできません（time get D:\OMSI は未知のルート time get d:\omsi となり、終了コード 2）。D:\OMSI time get は受け付けられますが、これは オーナーモード です（新しいセッションが開始され、その中で操作が 1 回実行されます）。解析エラー（ArgumentException、FormatException、InvalidDataException、OverflowException）とセッションプロファイルのエラー（SessionProfileException）は、何かが実行される前に報告され、終了コードは常に 2 です。

インストールルート#

• 明示的な裸の単語によるインストール引数は、/spec ファイル内の RootPath より優先されます（CliInput.BuildSpecAsync）。
• . は実行ファイルを含むディレクトリ（AppContext.BaseDirectory）を意味し、呼び出し元の作業ディレクトリを意味することはありません（CliInput.ResolveInstallationRoot）。ポータブルパッケージはこの動作に依存しています。
• 引数が省略された場合、オーナーモードの操作（/new、/saved、/spec、/list、/recovery-status、/recover）も実行ファイルのディレクトリを使用します。パスは Path.GetFullPath で正規化されます。
• クライアントモードのコマンドはインストール引数を取りません。実行ファイルが置かれているインストール環境（AppContext.BaseDirectory）のローカル制御エンドポイントを対象とします。ローカル制御を参照してください。

オーナーとクライアント#

• オーナー: セッションのプランを作成し、開始し、監視し、復元するプロセスです（OwnerSession.RunAsync）。インストールリース（Local\OmsiLaunch.Installation.<sha256(root)>）と設定トランザクションを保持し、セッションが生きている間はローカル制御エンドポイントを公開し、トレイアイコンを表示します。オーナーはインストール環境ごとに厳密に 1 つです。制御エンドポイントで既にオーナーが session.status に応答している場合、2 回目の起動は OL_E_SESSION_ALREADY_ACTIVE（終了コード 7）で失敗します。
• クライアント: インストール引数なしで session status、session stop、events read、events watch、またはランタイム操作を送信する呼び出しです。ローカル制御パイプ経由で転送されます。オーナーが存在しない場合は OL_E_NO_ACTIVE_SESSION（終了コード 4）で失敗します。

ディスパッチ順序（CliProgram.RunAsync）#

1. /silent（OmsiLaunchW.exe の下で既に実行中でない場合）: 実行ファイルのディレクトリから ShellExecute を通じて（ハンドル継承なしで）OmsiLaunchW.exe を開始し、/silent/--silent を除いた同じ引数を渡し、silent エンベロープ（delegated、host_process_id）を書き込んで 0 を返します。コンソールプロセスはセッションを待機しません。OmsiLaunchW.exe を参照してください。OL_E_WINDOWS_HOST_MISSING / OL_E_WINDOWS_HOST_START_FAILED は 7 を返します。
2. /version: product、version（アセンブリの informational version。OmsiLaunch.Version.props から刻印され、0.1.0-beta3）、protocol_version（0.1）、supported_family（OMSI_2_3_004_COMMON）を含むエンベロープ version。終了コード 0。
3. capabilities: PublicCapabilityRegistry のすべての PublicStableBeta または PublicExperimental 記述子を含むエンベロープ。終了コード 0。
4. help [family]: usage、product_version、protocol_version、family、および公開 commands（CliRoute、Description、Classification、RuntimeValidation）を含むエンベロープ help。family で絞り込むこともできます。終了コード 0。
5. profiles: family と、supported の実行ファイルバリアント（ALTERNATE_LAA 692EBFBF...、runtime_validated=true、および validation_status=pending_beta_field_validation の Steam LAA ハッシュ 7DAB063D...）を含むエンベロープ。終了コード 0。
6. クライアントのランタイム操作（インストール引数がなく、ルートまたは /runtime: がある場合）: 引数は PublicCapabilityRegistry.ValidateRuntimeArguments に照らして検証され（OL_E_RUNTIME_OPERATION_UNKNOWN、OL_E_RUNTIME_ARGUMENT_REQUIRED、終了コード 2）、その後 runtime.execute が 8 s のタイムアウト（road-vehicles.spawn では 30 s）で転送されます。
7. クライアントの session status（750 ms）、session stop（アクティブなセッション id に束縛、750 ms）、events read（750 ms）、events watch（Ctrl+C まで 250 ms ごとにポーリング）。
8. detect、または 引数がまったくない場合（インストール、コマンド、/?、/spec、起動フラグ、リカバリフラグ、/list のいずれもない）: Omsi プロセスを列挙し、制御エンドポイントを調べます（250 ms）。エンベロープ detect。終了コード 0。
9. /? または /help: 使用方法のテキストを出力し、終了コード 0。コマンドワードはあるがディスパッチ可能なルートがないその他の呼び出し（例: d3d 単独や session status D:\OMSI）は、使用方法のテキストを出力して終了コード 2 で終了します。
10. オーナーモード。前提条件: 実行ファイルと同じ場所に plugins\OmsiLaunch.Plugin.opl と plugins\OmsiLaunch.Native.x86.dll が存在する必要があります（OL_E_RUNTIME_INSTALLATION_INCOMPLETE、終了コード 7）。実行ファイルと同じ場所に release-manifest.json がある場合は、それが期待されるプラグインハッシュを提供します。
11. /recovery-status / /recover: RecoverPendingAsync。pending、recovered、diagnostics を含むエンベロープ recover。復元が要求されたのに完了しなかった場合にのみ終了コード 8、それ以外は 0。
12. /list:<category>: DiscoverAsync。エンベロープ content.list。終了コード 0。
13. LaunchSpec を構築し（BuildSpecAsync）、プランを作成し（PlanSessionAsync）、プランを出力します。/plan または /validate: IsRunnable なら終了コード 0、そうでなければ 1。実行不可のプランが OMSI を起動することはありません（終了コード 1）。OmsiLaunchW.exe の下では、実行不可のプランでの起動は、その最後の OL_E_ 診断をメッセージボックスで表示します（ドキュメント監査 BUG-06）。プランニングでは、インストール済みの常駐プラグイン一式を release-manifest.json と照合する検証も行うため、プラグインが欠落または改変されているとプランは実行不可になります（OL_E_PERMANENT_PLUGIN_*）。
14. 既存のオーナーの有無を調べ（OL_E_SESSION_ALREADY_ACTIVE、終了コード 7）、その後 OwnerSession.RunAsync を実行します。

オーナーのライフサイクル（OwnerSession.RunAsync）#

1. StartSessionAsync(plan)。ここから先は、すべての終了経路が finally ブロック内の CloseAsync に到達します。例外、Ctrl+C（Console.CancelKeyPress）、コンソールのクローズ / ログオフ（停止 + 復元に 4 s の猶予を持つ AppDomain.ProcessExit。残ったものは次回の開始時にジャーナルによってリカバリされます）、トレイの "End session"、パイプの session.stop、および /observe-seconds がこれに含まれます。
2. spec で Presentation.SuppressTrayIcon が設定されていない限り、トレイアイコンが作成されます。
3. StartupTimeoutSeconds + 5 秒間 Running を待機します。ステータスが出力されます。状態が Running でない場合は終了コード 1 です（OmsiLaunchW.exe は、最後の OL_E_ 診断または OL_E_SESSION_START_FAILED とともに The OMSI session did not reach gameplay. を表示します）。
4. 検証バッチ（/runtime-batch、/runtime-write-batch、/d3d-batch）が実行され、成果物を書き込みます。
5. ローカル制御エンドポイントが開始されます。
6. /runtime:<operation> が 1 回実行されます（5 s、road-vehicles.spawn では 15 s）。結果は <root>\.omsilaunch\diagnostics\<sessionId>-runtime-operation.json に書き込まれ、出力されます。ランタイムコマンドが失敗してもセッションが終了することはありません（代わりに runtime_error が出力されます）。
7. 待機: /observe-seconds:n を指定した場合、セッションは n 秒後に停止されます。または、それより前にトレイ/パイプからの停止要求があった場合、あるいは OMSI が終了した場合に停止されます。指定しない場合、オーナーは OMSI が終了するか停止が要求されるまで待機します。
8. 完了時のステータスが出力されます。Completed なら終了コード 0、それ以外は 1 です。

session.stop、トレイの "End session"、Ctrl+C、および CloseAsync はすべて正規の停止を要求します。OMSI は TerminateProcess で終了させられ（OMSI 自身のシャットダウン処理は実行されず、options.cfg が OMSI によって書き換えられることはありません）、その後セッションが所有するすべてのファイルが復元されます。セッションのライフサイクルとトランザクションとリカバリを参照してください。

コマンドワード#

先頭の位置で受け付けられるすべての単語（CliInput.CommandWordsAccepted）:

階層ルート#

CliInput.HierarchicalRoutes は、小文字化されたルートをランタイム操作 id に対応付けます。すべてのルートは Running セッションを必要とし、ランタイムメールボックス（ExecuteRuntimeAsync）を通じて実行されます。ランタイムの書き込みは OMSI のメモリ上の状態のみを変更します。ファイルには一切触れず、設定トランザクションの一部でもなく、停止時に元に戻されることは ありません（OMSI は強制終了されます）。安定性は PublicCapabilityRegistry と検証マトリクスに従います。詳細と結果フィールドはランタイム制御にあります。

ルートのない操作#

以下の公開操作 id（PublicCapabilityRegistry.PublicRuntimeOperationIds）には階層ルートがなく、/runtime:<operation> に --key=value または /runtime-arg:key=value を付けて呼び出します: timetable.rv-files.list、timetable.track-entries.list、timetable.tour-entries.list、d3d.status、d3d.texture.create（width、height、format が必須、levels は任意）、d3d.texture.describe（handle、level は任意）、d3d.texture.update（handle、width、height、pixels_base64 が必須、level、x、y は任意）、d3d.texture.release（handle）。D3D 操作は EXPERIMENTAL です。テクスチャのライフサイクルとデバイスリセットによる無効化はランタイム検証済みです（ランタイムクロージャ H02、D01。ケイパビリティを参照）。timetable.track-entries.list と timetable.tour-entries.list は上限付きリストです。ランタイムスロットに収まらない結果は短縮されます（truncated=true）。internal.road-vehicles.make-basic は INTERNAL であり、CLI と API の両方で OL_E_RUNTIME_OPERATION_UNKNOWN により拒否されます。

フラグ#

CliInput.KnownFlags のすべてのフラグです。「フェーズ」は launch-time（新しいセッションの LaunchSpec/プランを形作る）、runtime（実行中のセッションに作用する）、control（CLI 自体の動作を変える）のいずれかです。互換性のためだけに解析されるフラグ（CliInput.AcceptedNoEffectFlags）は、その行に明記しています。

制御と出力#

プランニング、検証、ハーネス#

ワールドの選択#

日付、時刻、天候#

これら 4 つはすべて受け付けられ、LaunchSpec に保持されますが、ネイティブの開始経路はこれらを適用しません。プランナーはこれらを STATICALLY_PARTIAL として記録し、さらに OL_E_CAPABILITY_UNAVAILABLE を追加するため、プランは NOT RUNNABLE（実行不可）になります（終了コード 1）。これらを設定する /spec ファイルやセッションプロファイルも同じ結果になります。

プレイヤー車両#

受け付けられ、インストール環境に照らして解決されますが、ランタイムでは適用されません。設定された各フィールドは STATICALLY_PARTIAL となり、OL_E_CAPABILITY_UNAVAILABLE を追加します（プランは NOT RUNNABLE、終了コード 1）。

設定オーバーレイ#

スプラッシュの表示#

Internet Textures#

セッションプロファイル#

LaunchSpec ファイル#

優先順位（CliInput.BuildSpecAsync）: デフォルト → /spec ファイル → /predefined-profile（Installation と World を置き換えてから、プロファイルを適用） → 明示的なフラグ。明示的なインストール引数は spec 内の RootPath より優先されます。/no-vehicle は spec のプレイヤー車両をクリアします。/vehicle とその関連フラグはフィールド単位で spec にマージされます。/set キーは Environment.General にマージされます。/splash、/splash-language、/splash-assets、/internet-textures、/internet-textures-profile は指定された場合にのみ上書きします。/startup-timeout と /shutdown-timeout は指定された場合にのみ上書きします。Presentation.SuppressTrayIcon は spec からのみ取得されます（フラグはありません）。診断フラグは spec の Diagnostics と OR で結合されます。

コンテンツの検出#

タイムアウトと観察#

リカバリ#

出力形式#

• 成功エンベロープ（CliInput.WriteEnvelope、--json 指定時）: {"ok": true, "command": "<name>", "protocol_version": "0.1", "result": <object>}（インデント付き）。転送された session status および events read の応答では、制御フレームに収めるために古いイベントが除外された場合、metadata メンバーが追加されます（events_dropped_count、ローカル制御を参照）。--json がない場合は <object> のみがインデント付き JSON として出力され、イベントが除外された場合はその後に Note: <n> older events were omitted to fit the control frame. が続きます。
• エラーエンベロープ（CliInput.WriteError、--json 指定時）: {"ok": false, "command": "<name>", "protocol_version": "0.1", "error": {"code": "OL_E_...", "category": "<category>", "message": "..."}}。--json がない場合: 1 行の OL_E_<CODE>: message。カテゴリ: invalid_argument、unsupported_profile、session、runtime、not_found、transaction、internal。OmsiLaunchW.exe の下では、同じコードとメッセージがメッセージボックスで表示されます。
• プランとステータス（CliInput.Write）: SessionPlan、SessionStatus、RuntimeCommandResult の各レコードは、エンベロープ なし でインデント付き JSON として出力されます。--json がない場合、プランは Plan: READY profile=Omsi23004_692EBFBF または Plan: NOT RUNNABLE profile=... と要約されます。その他のレコードは引き続き JSON として出力されます。列挙値は整数としてシリアル化されます（SessionState.Running は 14、Completed は 18、Failed は 19）。
• エンベロープで使用されるコマンド名: silent、version、capabilities、help、profiles、detect、recover、content.list、session、session.status、session.stop、events.read、events.watch、events watch、installation、cli、session profile、および転送されたランタイムコマンドのランタイム操作 id。
• OmsiLaunchW.exe（OMSILAUNCH_WINDOWS_HOST=1）の下では、--json が指定されない限りコンソールには何も書き込まれません。

コマンドごとのエラー#

環境#

関連項目#

CLI の使用例 · OmsiLaunchW.exe · 終了コード · エラー · ローカル制御 · Windows トレイ · ランタイム制御 · ケイパビリティ · LaunchSpec · セッションプロファイル · パッケージング · 互換性 · 既知の制限事項 · 公開 API