セッションプロファイル

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

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

セッションプロファイルは宣言的な YAML パッケージです。コンテンツ作成者がマップやアドオンと一緒に配布し、エンドユーザーが 1 つのコマンド（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。オーバーレイと復元の経路は RV-005 と RV-006 でランタイム検証済みです。ランタイム検証の状況を参照してください）。new.date、new.time、new.year、new.weather の各キーは、このビルドでは UNAVAILABLE です（new ブロックを参照）。

パッケージの場所と命名#

プロファイルのインストールと削除は、ユーザーまたはコンテンツ作成者が行います。OmsiLaunch がパッケージに書き込んだり、コピーしたり、削除したりすることはありません。パッケージディレクトリはどのトランザクションにも含まれません。

解析ルール#

プレーン（引用符なし）スカラー内のバックスラッシュは文字どおりの文字です。Windows のパスはバックスラッシュ 1 つで書いてください（maps\Grundorf\global.cfg）。プレーンスカラー内で二重にしたバックスラッシュは、値の中でも二重のまま残ります。同梱の例を参照してください。

キーリファレンス#

コンテキストはコンパイラーでの名前をそのまま使っています。ここに記載されたキーはすべて受け付けられ、それ以外は受け付けられません。

profile（ルートマッピング）#

compatibility#

new#

このブロックは存在する場合は常に読み取られて検証されますが、spec に適用されるのは、選択された world モードが NEW_MAP（/new、CLI の既定）の場合だけです。/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）。このビルドでの結果として、これら 4 つのキーのいずれかを設定したプロファイルは /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）場合にのみ受け付けます。値は文字列として格納され、セッションがオーバーレイを構築するときに options.cfg のパッチに変換されます。そのため、無効な値が検出されるのはプロファイル読み込み時ではなく StartSessionAsync の時点であり、メッセージに OL_E_INVALID_SETTING_VALUE: <key> を含む OL_E_START_SESSION でセッションが失敗します。以下の設定はすべて options.cfg に書き込みます。いずれもセッションスコープであり、セッション終了後に正確に復元されます。

値の形式:

• bool は true または false です（大文字と小文字を区別しません）。存在トークンの場合、トークンが追加または削除されます。反転トークン（no_*）の場合、true は否定トークンを削除します。
• 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 属性が検査されます。そのパス上のどこかにジャンクション、ディレクトリのシンボリックリンク、ファイルのシンボリックリンクがあると拒否されます。検査できないコンポーネント（IOException / UnauthorizedAccessException）も同様に拒否されます。

3 つの失敗はいずれも 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 が実行されます。次に、シードの world ブロックが、選択されたモードの空の WorldSpec にリセットされ（プロファイルを使う場合、/spec の world は破棄されます）、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 の下での world 引数（そこでは 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: 設定のみのプロファイル、プリセット 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: マップに紐づき、3 つのプリセットと同梱アセットを持つプロファイル#

<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（表示）が同梱されています。これは構文的に有効で、スキーマに適合し、エラーなく読み込まれます。ただし、次の 2 つの性質により、このビルドでは変更なしでセッションを開始することはできません。

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 のパス正規化が二重の区切り文字を 1 つにまとめるため、それでも解決されます。

このビルドで実行可能な形は次のとおりです。

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、および world フラグ
• LaunchSpec: プロファイルのコンパイル先となるレコード
• トランザクションとリカバリ: settings、スプラッシュ、.itx のオーバーレイがどのように適用・復元されるか
• ケイパビリティとランタイム検証の状況