パブリック API リファレンス（OmsiLaunch.Api）

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

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

このページは、OmsiLaunch 0.1.0-beta3 のマネージドパブリック API に関する規範的なリファレンスです。対象は OmsiLaunch.Api アセンブリ（コントラクト）と、OmsiLaunch.Core に含まれるインテグレーター向けエントリポイント OmsiLaunchService です。記載しているのは現在のコードの動作のみです。インテグレーターが呼び出し、受け取り、観測できるものはすべて安定性レベルとともにここに列挙しています。ここに記載されていないものは統合用のサーフェスではありません。

自動生成される パブリック API インベントリ には、OmsiLaunch.Api、OmsiLaunch.Core、OmsiLaunch.Process のすべてのパブリック型とメンバーが、シグネチャと安定性とともに列挙されています。インベントリとアセンブリが一致しない場合はドキュメントゲートが失敗します。このページではそのセマンティクスを説明します。

関連ページ: LaunchSpec リファレンス、エラーコード、セッションライフサイクル、トランザクションとリカバリ、ランタイム制御、ケイパビリティ、ローカルコントロールプレーン、終了コード、ランタイム検証ステータス。

安定性の用語#

アセンブリの概要#

エントリポイント: OmsiLaunchService と OmsiLaunchRuntimePaths#

public sealed record OmsiLaunchRuntimePaths(string PluginBuildDirectory, string NativeBridgePath, string? ReleaseManifestPath = null);
public sealed class OmsiLaunchService : IOmsiLaunch
{
    public OmsiLaunchService(IRuntimePlatform platform, OmsiLaunchRuntimePaths runtimePaths);
}

サービスはこれらのパスを PlanSessionAsync と StartSessionAsync のたびに読み取ります。プラグインファイルをコピー、ステージング、削除することは一切ありません（常駐プラグイン を参照）。CLI はまさにこのとおりにサービスを構築します（tools/OmsiLaunch.Cli/Program.cs）。

using OmsiLaunch.Api;
using OmsiLaunch.Core;
using OmsiLaunch.Process;

var package = AppContext.BaseDirectory;                       // directory that contains OmsiLaunch.exe
var plugins = Path.Combine(package, "plugins");
var manifest = Path.Combine(package, "release-manifest.json");
IOmsiLaunch launch = new OmsiLaunchService(
    new CurrentWindowsX64Platform(),
    new OmsiLaunchRuntimePaths(plugins, Path.Combine(plugins, "OmsiLaunch.Native.x86.dll"), File.Exists(manifest) ? manifest : null));

サービスはプロセスごとに 1 つ作成し、共有してください。安定性: STABLE_BETA。

セッションの所有に関するルール#

IOmsiLaunch#

public interface IOmsiLaunch
{
    Task<SessionPlan> PlanSessionAsync(LaunchSpec spec, CancellationToken cancellationToken = default);
    Task<SessionHandle> StartSessionAsync(SessionPlan plan, CancellationToken cancellationToken = default);
    Task<SessionStatus> GetStatusAsync(SessionHandle session, CancellationToken cancellationToken = default);
    Task<SessionStatus> WaitForAsync(SessionHandle session, SessionState state, TimeSpan timeout, CancellationToken cancellationToken = default);
    Task StopAsync(SessionHandle session, CancellationToken cancellationToken = default);
    Task CloseAsync(SessionHandle session, CancellationToken cancellationToken = default);
    Task<RuntimeCommandResult> ExecuteRuntimeAsync(SessionHandle session, RuntimeCommand command, TimeSpan timeout, CancellationToken cancellationToken = default);
    Task<IReadOnlyList<Capability>> GetCapabilitiesAsync(InstallationSpec installation, CancellationToken cancellationToken = default);
    Task<IReadOnlyList<ContentIdentity>> DiscoverAsync(InstallationSpec installation, ContentQueryKind query, OptionalValue<string> scope = default, CancellationToken cancellationToken = default);
    Task<RecoveryStatus> RecoverPendingAsync(InstallationSpec installation, bool restore, CancellationToken cancellationToken = default);
}

すべてのメソッドに共通する事項:

• 不明なハンドル、またはすでにクローズされたハンドルは KeyNotFoundException（"Unknown OmsiLaunch session."）をスローします。
• ExecuteRuntimeAsync 以外のメソッドは、Running 状態のセッションを必要としません。
• OmsiLaunch コードを伴う例外は、そのコードを Exception.Message の先頭に置きます（"OL_E_PLAN_NOT_RUNNABLE: ..."）。CLI も同じ方法でメッセージからコードを抽出します（CliProgram.Classify）。
• 対応ビルド: Omsi23004_692EBFBF のみです（加えて Steam LAA の許可リストハッシュは受け付けられますが、ゲームプレイは検証されていません。検証には正規の Steam インストール環境が必要です）。互換性 を参照してください。

最小限の完全な例#

var none = new Dictionary<string, OptionalValue<string>>();
var spec = new LaunchSpec(
    Installation: new InstallationSpec(@"C:\OMSI 2"),
    World: new WorldSpec(WorldMode.NewMap, OptionalValue<string>.Set(@"maps\Grundorf\global.cfg"), OptionalValue<string>.Unset, OptionalValue<int>.Set(1)),
    Date: new DateSpec(DateTimeMode.Unset, OptionalValue<SemanticDate>.Unset),
    Time: new TimeSpec(DateTimeMode.Unset, OptionalValue<SemanticTime>.Unset),
    PlayerVehicle: OptionalValue<PlayerVehicleSpec>.Unset,
    Environment: new EnvironmentSpec(none, none, none, none, none, none, none, none),
    Behavior: new LaunchBehaviorSpec());

var plan = await launch.PlanSessionAsync(spec);
if (!plan.IsRunnable) { foreach (var d in plan.Diagnostics) Console.WriteLine($"{d.Code}: {d.Message}"); return; }

var session = await launch.StartSessionAsync(plan);
try
{
    var status = await launch.WaitForAsync(session, SessionState.Running, TimeSpan.FromSeconds(plan.Spec.Behavior.StartupTimeoutSeconds + 5));
    if (status.State == SessionState.Running)
    {
        var time = await launch.ExecuteRuntimeAsync(session, new RuntimeCommand(session.SessionId, 1, "time.read"), TimeSpan.FromSeconds(5));
        Console.WriteLine(time.Succeeded ? $"{time.Values!["hour"]}:{time.Values["minute"]}" : time.ErrorCode);
        await launch.StopAsync(session);
    }
    var final = await launch.WaitForAsync(session, SessionState.Completed, Timeout.InfiniteTimeSpan);
    Console.WriteLine(final.State);                      // Completed, or Failed with diagnostics
}
finally
{
    await launch.CloseAsync(session);                    // always
}

PlanSessionAsync#

StartSessionAsync#

GetStatusAsync#

WaitForAsync#

StopAsync#

CloseAsync#

ExecuteRuntimeAsync#

GetCapabilitiesAsync#

DiscoverAsync#

ContentQueryKind の値と結果:

エントリポイント ID は探索専用です。起動経路は PresentedEntrypointIndex を使用します。EntrypointIdentity を渡すと、このビルドではプランが実行不可になります（world.entrypoint-identity、RUNTIME_PARTIAL）。

RecoverPendingAsync#

コントラクト型#

省略可能な値とセマンティックなプリミティブ#

LaunchSpec ファミリー#

以下のレコードはすべて、LaunchSpec リファレンス でプロパティごとに説明しています。この表は型の一覧を確定するものです。

プラン型とステータス型#

SessionState#

宣言順の byte 列挙型: Created、ValidatingPlatform、Planning、AcquiringInstallationLock、RecoveringPreviousTransaction、Snapshotting、ApplyingConfiguration、DeployingRuntime、CreatingStartupHandoff、StartingProcess、WaitingForPlugin、PluginBootstrap、StartingWorld、EnteringGameplay、Running、ProcessExited、Restoring、CleaningRuntime、Completed、Failed。ValidatingPlatform、Planning、EnteringGameplay は現在のサービスでは一度も設定されません。Snapshotting は一時的な状態で、実際にはほぼ観測できません。終了状態: Completed、Failed。セマンティクスの詳細: セッションライフサイクル。

ランタイム制御の型#

プラグインは、WorldMode が NewMap または SavedSituation であり、HeadlessStart が true、PlayerVehicleEnabled が false、日付/時刻の両モードが Unset で、保存済みシチュエーションの場合は ID が空でない、という条件をすべて満たさない限り、ハンドオフを拒否します（plugin.request.unsupported → OL_E_CAPABILITY_UNAVAILABLE）。プランナーが同じ制約をより早い段階で強制するため、実行可能なプランがこれを引き起こすことはありません。

ケイパビリティレジストリの型#

完全なカタログ: ケイパビリティ。

D3DRuntimeApi 拡張メソッド#

d3d.* 操作（EXPERIMENTAL、PublicExperimental ケイパビリティ d3d.texture）用に ExecuteRuntimeAsync をラップした型付きラッパーです。要求 ID は 30 000 から始まるプロセス全体のカウンターから割り当てられ、タイムアウトの既定値は 5 s です（ただし GetD3DStatusAsync はタイムアウトの指定が必須です）。

型: D3DDeviceStatus(Available, State, Generation, LiveTextureCount, ResetHookInstalled, ExecutionThreadId, LastResetThreadId, QueryInterfaceHResult, CooperativeLevelHResult, OwnedDeviceReferences)。D3DDeviceState: NotReady、Ready、Lost、Resetting、Stopping、Stopped。D3DTextureHandle(Value)（Value = "d3dtex-<session id N>-<16 hex>"）。D3DTextureDescription(Handle, State, DeviceState, Generation, Width, Height, Format, Levels, Level, LevelWidth, LevelHeight, HResult, ExecutionThreadId)。D3DTextureResourceState: Live、Released、Stale。D3DTextureFormat: A8R8G8B8、X8R8G8B8、R5G6B5、X1R5G5B5、A1R5G5B5、A4R4G4B4、A8、L8、A8L8。

エラー: 失敗した結果は OmsiRuntimeException(Code, detail) として再スローされます。Code は結果の ErrorCode（存在しない場合は OL_E_RUNTIME_OPERATION_FAILED）で、メッセージは "<code>: <Values["detail"]>" です。値を持たない成功結果、または不明なデバイス状態の文字列は OmsiRuntimeException("OL_E_RUNTIME_PROTOCOL_MISMATCH", ...) をスローします。ExecuteRuntimeAsync がスローする例外はすべてそのまま伝播します。デバイスリセットの処理はランタイム検証済みです。リセットによってデバイスは Resetting を経て Ready に戻り、有効なテクスチャはすべて無効化されます（OL_E_D3D_STALE_RESOURCE_HANDLE、ランタイムクロージャ D01）。一方で GetCapabilitiesAsync は、runtime.d3d.lifecycle.reset をまだ IMPLEMENTED_NOT_RUNTIME_VALIDATED と報告します（自己申告の遅れ）。Lost への遷移は製品の外部から発生させることができず、オフラインでのみカバーされています。

var status = await launch.GetD3DStatusAsync(session, TimeSpan.FromSeconds(5));
if (status.State == D3DDeviceState.Ready)
{
    var texture = await launch.CreateD3DTextureAsync(session, 8, 8, D3DTextureFormat.A8R8G8B8);
    var pixels = new byte[8 * 8 * 4];
    await launch.UpdateD3DTextureAsync(session, texture.Handle, new D3DTextureUpdate(0, 0, 0, 8, 8, pixels));
    await launch.ReleaseD3DTextureAsync(session, texture.Handle);
}

プロセスコントラクトの型#

InstallationPaths（インストール環境の ID とパスの包含判定）#

安定性: STABLE_BETA（純粋関数であり、I/O なし、OMSI の状態なし、ファイルシステムの変更なし、トランザクションへの関与なし、Running セッション不要）。インストールリース、ローカル制御のパイプ名、セッションプロファイルのアセットの閉じ込め、Internet Textures のターゲット検証、ランタイムのスポーン用モデルパスで使用される唯一の定義です。

var same = InstallationPaths.IdentityKey(@"C:\OMSI") == InstallationPaths.IdentityKey(@"c:\foo\..\OMSI\"); // true
InstallationPaths.TryGetContainedRelativePath(@"C:\OMSI", @"Sceneryobjects\\x\texture\a.tga", out var relative); // true, "Sceneryobjects\x\texture\a.tga"

セッションプロファイル（OmsiLaunch.Core）#

安定性: EXPERIMENTAL。これらの型は、YAML の セッションプロファイル（<root>\.omsilaunch\session-profiles\<id>\profile.yaml、スキーマ omsilaunch.session-profile/v1）を LaunchSpec にコンパイルします。CLI の /predefined-profile:<id> /predefined-profile-index:<n> はまさにこれらの呼び出しを使用しています。インテグレーターはこれらを使って API 経由でプロファイルを開始できます。

CLI はさらに、プロファイルと矛盾するコマンドラインフラグを拒否します（OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT）。このチェックはコンパイラーには含まれていません。マージ順序の詳細は セッションプロファイル を参照してください。

static async Task<SessionPlan> PlanProfileAsync(IOmsiLaunch launch, LaunchSpec baseline, string installationRoot, string profileId)
{
    // baseline: a LaunchSpec for installationRoot with World.Mode = WorldMode.NewMap (see the complete example).
    var profile = SessionProfileCompiler.Load(installationRoot, profileId, presetIndex: 1);
    var spec = SessionProfileCompiler.Apply(profile, baseline, WorldMode.NewMap);
    return await launch.PlanSessionAsync(spec); // plan.Spec.SessionProfile carries the provenance
}

プラットフォームの型（OmsiLaunch.Process）#

スレッドセーフ#

• OmsiLaunchService は、異なるセッションに対する同時呼び出しに対して安全です。セッションは ConcurrentDictionary に格納され、セッションごとの変更はすべてそのセッション専用のロックの下で行われます。
• 同じセッションに対する同時呼び出しも安全ですが、必要な箇所では直列化されます。ExecuteRuntimeAsync はセッションごとのゲートを取得するため、2 つ目のコマンドは 1 つ目の完了を待ちます（そのタイムアウトはステージングされた時点から始まります）。
• スーパーバイザーは、StartSessionAsync が戻った時点からセッションが終了状態になるまで、スレッドプールのタスク（Task.Run）上で動作し、100 ms ごとにテレメトリとプロセスをポーリングします。呼び出し元がスーパーバイザーのコードを実行することはありません。
• StopAsync と GetStatusAsync は同期的に完了し、ProcessExit ハンドラーの内部を含め、任意のスレッドから呼び出せます（CLI は 4 s の猶予でこれを行っています）。
• スレッドアフィニティを持つ API 呼び出しはなく、同期コンテキストを必要とするものもありません。

API に含まれないもの#

• IntPtr、nint、Win32 ハンドル、ネイティブアドレス、VMT ポインター、プロセスオブジェクトは含まれません。キーが internal_ で始まる、または _address、_pointer、_vmt で終わる結果値は、結果が ExecuteRuntimeAsync から返される前に除去されます。
• internal.* ランタイム操作は含まれません。internal.road-vehicles.make-basic はレジストリ上 InternalOnly であり、API と CLI からは OL_E_RUNTIME_OPERATION_UNKNOWN を返します。
• OMSI メモリの生の読み書きはなく、LaunchSpec が宣言するもの以外にインストール環境へのファイルレベルのアクセスもありません。
• プロセス間ハンドルはありません。ローカルコントロールプレーン が唯一のプロセス間経路であり、受け付けるのは session.status、session.events、session.stop、runtime.execute のみです。
• このビルドには、OMSI の協調的なシャットダウン、LAST_MAP_STATE、日付/時刻/天候/プレイヤー車両の適用、キーボード/コントローラードキュメントのオーバーレイはありません。

安定性のまとめ#