HOF 管理

ドキュメントのバージョン main@63ccaf8GitHub でソースを見る

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

OMSI は、各車両のフォルダーから HOF ファイル（*.hof: 車両の IBIS／行先表示器に表示される行先、系統番号、停留所リスト）を読み込みます。HOF 管理は、HOF ファイルを 1 つのセッションの期間中だけ 車両フォルダーにコピーします。これにより、マップやアドオンはその路線に必要な HOF を同梱でき、ユーザーはある車両の HOF を他の車両で再利用できます。どの車両も恒久的には変更されません。このページは規範的なリファレンスであり、src/OmsiLaunch.Core/HofPlanner.cs の HofPlanner、LaunchSpec の HofManagement フィールド、CLI の /hof-source、/hof-target、/hof-file、/hof-mode フラグ、およびセッションプロファイルの hofs ブロックによる実装に対応しています。

安定性: プランニング、競合ルール、閉じ込め（confinement）、およびトランザクションによる復元は STABLE_BETA です（オフラインゲート hof.plan-sources-and-modes、hof.plan-rejects-unsafe-input、hof.transaction-exact-restore、hof.recovery-after-crash、session-profiles.hofs）。ランタイム検証済み: ミラーセッションの正確な復元と、/recover によるクラッシュ後のリカバリ（ランタイム検証の状況を参照してください）。

HOF 管理は PlayerVehicle.Hof / /hof:<id> とは別のものです。後者は開始時にプレイヤー車両の HOF を選択するもので、このビルドでは UNAVAILABLE です。

モデル#

リクエストは操作のリスト（HofManagementSpec.Operations）です。各 HofOperationSpec は次の項目を持ちます。

使用されるのはソースディレクトリ直下のファイルのみです（再帰はしません）。シンボリックリンクとジャンクションはたどりません（閉じ込めを参照してください）。

セッションで行われること#

1. プランニング（PlanSessionAsync、/plan）。すべての操作が解決されます。ソースが読み込まれ、ターゲットが確認され、競合が検出されます。変更される各ファイルは SessionPlan.PlannedMutations に、SemanticKey が hof.add または hof.mirror、RequestedValue がソースの識別子、Operation が exact-file-overlay（書き込み）または session-deletion（ミラーによる削除）として現れます。それらのパスは TouchedFiles に含まれます。問題がある場合、プランは下記のコードで実行不可になります。
2. 開始。失効したジャーナルがリカバリされた後、操作は実際のファイルから改めて解決され、セッショントランザクションに渡されます。書き込まれるファイルはオーバーレイ、ミラーによって取り除かれるファイルはセッション削除になります。バイト内容がすでにソースと等しいターゲットファイルは変更されず、トランザクションのエントリにもなりません。
3. セッションの終了、失敗、クラッシュ。 トランザクションはすべてのターゲットフォルダーを正確に復元します。既存だったファイルは元のバイト内容、タイムスタンプ、属性に戻り、セッションが作成したファイルは削除され、ミラーによって取り除かれたファイルは元に戻ります。オーナーがクラッシュした場合も、次回の開始時または /recover によって同じ復元が実行されます（トランザクションとリカバリを参照してください）。

ターゲットフォルダーの外には何も書き込まれません。ソースファイルは読み込まれるだけです。.omsilaunch\hof\ がセッションによって変更されることはありません。

競合ルール#

操作は順番に適用され、互いに矛盾してはなりません。

• 同じターゲットファイルに同じバイト内容を書き込む 2 つの操作はマージされます。バイト内容が異なる場合: OL_E_HOF_CONFLICT。
• 先行する操作が書き込むファイルを削除するミラー、または先行するミラーが削除するファイルに書き込む操作: OL_E_HOF_CONFLICT。
• ミラーはフォルダーのセッション HOF セット、つまり既存のファイルに先行する操作がそこに書き込むファイルを加えたものを対象とします。
• セッションのプレゼンテーション（スプラッシュ画面または Internet Textures）によっても書き込まれる HOF ターゲット: OL_E_HOF_CONFLICT（現在のプレゼンテーションのパスは Vehicles\ の外にあるため、実際には発生しません）。
• ターゲットに大文字と小文字だけが異なる同名のファイルがすでにある場合は、既存の表記が維持されます。

閉じ込め#

すべてのソースとターゲットはインストール環境の内部にとどまる必要があります。ルート付きパス、.. セグメント、およびルートの外に出るパスは OL_E_HOF_PATH_ESCAPE です。Vehicles\ の外にあるターゲット（および Vehicle ソース）、単純なディレクトリ名ではないコレクション名、ジャンクションまたはシンボリックリンクを経由して到達するソースまたはターゲットのフォルダーも同様です。それ自体がリパースポイントである .hof ファイルは無視されます。

上限#

エラーコード#

使い方#

コマンドライン（1 つの操作。複数の操作には /spec またはセッションプロファイルが必要です）:

OmsiLaunch.exe /new /map:maps\Grundorf\global.cfg /entrypoint-index:1 /hof-source:collection:berlin /hof-target:Vehicles\MAN_SD200\MAN_SD77.bus /plan
OmsiLaunch.exe /new /map:maps\Grundorf\global.cfg /entrypoint-index:1 /hof-source:vehicle:Vehicles\MAN_SD200\MAN_SD77.bus /hof-target:Vehicles\MAN_SD202 /hof-mode:mirror

LaunchSpec（/spec の JSON、列挙型は整数）:

{
  "HofManagement": {
    "Operations": [
      { "SourceKind": 1, "Source": "maps\\Grundorf\\hof", "TargetVehicles": [ "Vehicles\\MAN_SD200\\MAN_SD77.bus" ], "Mode": 0 },
      { "SourceKind": 0, "Source": "berlin", "TargetVehicles": [ "Vehicles\\MAN_SD202" ], "Mode": 1, "Files": [ "Linie5.hof" ] }
    ]
  }
}

セッションプロファイルのプリセット（package ソースはプロファイルパッケージ内のディレクトリです）:

hofs:
  - package: hof
    targets:
      - Vehicles\MAN_SD200\MAN_SD77.bus
    mode: mirror

API: LaunchSpec.HofManagement を設定し、通常どおり PlanSessionAsync / StartSessionAsync を呼び出します。/list:Hofs（ContentQueryKind.Hofs）はインストール済みの HOF ファイルを一覧表示します。

関連項目: LaunchSpec、セッションプロファイル、CLI、エラー、トランザクションとリカバリ。