Справочник публичного API (OmsiLaunch.Api)

Документация версии v0.1.0-beta.3Исходник на GitHub

Перевод исходной страницы на английском языке для OmsiLaunch 0.1.0-beta3. Нормативной является английская страница: при расхождениях приоритет имеют английская страница и код.

Эта страница — нормативный справочник по управляемому публичному API OmsiLaunch 0.1.0-beta3: сборке OmsiLaunch.Api (контракты) и точке входа для интеграторов OmsiLaunchService в OmsiLaunch.Core. Здесь описано только то, что делает текущий код. Всё, что интегратор может вызвать, получить или наблюдать, перечислено здесь с уровнем стабильности; всё, что не перечислено, не является поверхностью интеграции.

Сгенерированная инвентаризация публичного API перечисляет каждый публичный тип и член OmsiLaunch.Api, OmsiLaunch.Core и OmsiLaunch.Process с сигнатурой и стабильностью; гейт документации завершается ошибкой, если инвентаризация и сборки расходятся. Эта страница объясняет семантику.

Связанные страницы: справочник LaunchSpec, коды ошибок, жизненный цикл сеанса, транзакции и восстановление после сбоя, runtime-управление, возможности, локальная плоскость управления, коды выхода, статус проверки в runtime.

Словарь уровней стабильности#

Обзор сборок#

Точка входа: 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));

Создавайте один сервис на процесс и используйте его совместно. Стабильность: 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);
}

Общие факты для всех методов:

• Неизвестные или уже закрытые handles приводят к исключению 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 и результаты:

Идентичности точек входа предназначены только для обнаружения: путь запуска использует PresentedEntrypointIndex; передача EntrypointIdentity делает план неисполнимым на этом билде (world.entrypoint-identity, RUNTIME_PARTIAL).

RecoverPendingAsync#

Типы контракта#

Необязательные значения и семантические примитивы#

Семейство LaunchSpec#

Все перечисленные ниже records описаны свойство за свойством в справочнике 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. Полная семантика: жизненный цикл сеанса.

Типы runtime-управления#

Плагин отклоняет handoff (plugin.request.unsupported → OL_E_CAPABILITY_UNAVAILABLE), если не выполнены все условия: WorldMode равен NewMap или SavedSituation, HeadlessStart равен true, PlayerVehicleEnabled равен false, оба режима даты и времени — Unset, а у сохранённой ситуации непустая идентичность. Планировщик применяет те же ограничения раньше, поэтому исполнимый план никогда к этому не приводит.

Типы реестра возможностей#

Полный каталог: возможности.

Методы расширения D3DRuntimeApi#

Типизированные обёртки над ExecuteRuntimeAsync для операций d3d.* (EXPERIMENTAL, возможность d3d.texture с классификацией PublicExperimental). Они выделяют идентификаторы запросов из общего для процесса счётчика, начинающегося с 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, распространяется без изменений. Обработка сброса устройства (device reset) проверена в runtime: сброс переводит устройство через Resetting обратно в Ready и делает недействительными все живые текстуры (OL_E_D3D_STALE_RESOURCE_HANDLE, runtime closure 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 (идентичность установки и ограничение путей)#

Стабильность: STABLE_BETA (чистые функции: без ввода-вывода, без состояния OMSI, без изменения файловой системы, без участия в транзакции, сеанс в состоянии Running не требуется). Это единое определение, которое используют аренда установки, имя pipe локального управления, ограничение ресурсов профиля сеанса пределами пакета, проверка целей интернет-текстур (Internet Textures) и путь к модели при runtime-создании (spawn).

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 захватывает гейт сеанса, поэтому вторая команда ждёт первую (её тайм-аут начинается в момент размещения в почтовом ящике).
• Супервизор работает в задаче пула потоков (Task.Run) с момента возврата StartSessionAsync до перехода сеанса в терминальное состояние; он опрашивает телеметрию и процесс каждые 100 ms. Вызывающие стороны никогда не выполняют код супервизора.
• StopAsync и GetStatusAsync завершаются синхронно и могут вызываться из любого потока, в том числе внутри обработчика ProcessExit (CLI делает это с бюджетом 4 s).
• Ни один вызов API не привязан к потоку; ни один не требует контекста синхронизации.

Чего нет в API#

• Нет IntPtr, nint, дескрипторов Win32, нативных адресов, указателей VMT и объектов процессов. Значения результата, ключи которых начинаются с internal_ или заканчиваются на _address, _pointer, _vmt, удаляются до того, как результат покинет ExecuteRuntimeAsync.
• Нет runtime-операций internal.*: internal.road-vehicles.make-basic в реестре имеет классификацию InternalOnly и возвращает OL_E_RUNTIME_OPERATION_UNKNOWN из API и CLI.
• Нет прямого чтения или записи памяти OMSI и нет доступа к файлам установки, кроме того, что объявлено в LaunchSpec.
• Нет межпроцессных handles: локальная плоскость управления — единственный межпроцессный путь, и она принимает только session.status, session.events, session.stop и runtime.execute.
• На этом билде нет кооперативного завершения OMSI, нет LAST_MAP_STATE, нет применения даты, времени, погоды и транспортного средства игрока, нет overlays документов клавиатуры и контроллера.

Сводка стабильности#