runi-dist/docs/launch-providers.md

Launch providers, emulated games and auxiliary actions

Status

This describes the implemented provider model for Windows executables, wrapper bundles, emulated games and shared storefront clients.

Architecture

Launch construction has three independent dimensions:

Launch target -> provider -> execution engine -> optional wrappers -> process

• A target is Play, Settings, Open Emulator or another explicit action.
• A provider builds the program invocation: direct executable, Xenia, RPCS3 or Ubisoft Connect.
• An engine runs that invocation: Proton/UMU, direct Proton or the Linux host. host is deliberately distinct from the legacy runtime backend named native, which means direct Proton.
• Gamescope, MangoHud and CPU affinity wrap Play by default. Utility actions do not inherit graphical wrappers.

Examples:

Use case	Provider	Engine
Existing Windows game/wrapper	executable	Proton/UMU or direct Proton
Xenia with an ISO	xenia	Proton
RPCS3 with a PS3 game directory	rpcs3	host
Windows Settings tool	executable	inherited Proton engine
Open emulator UI	executable/emulator UI	provider's engine
Ubisoft game deeplink	ubisoft	shared Proton prefix

Persistence and compatibility

Schema v3 added game.platform, game.install_root, [launch] and repeated [[actions]]. Schema v5 adds [store_binding] and store-specific identity aliases. Schema v7 separates a port's original platform from its target OS and stores optional Lossless Scaling frame-generation settings. Schema v8 adds explicit OptiScaler provider and migration state. Schema v9 adds managed native HDR state and migrates the legacy Lossless Scaling HDR option. Schema-v2 files remain readable and map to Windows, direct executable provider and Proton engine. Merely reading/listing does not rewrite them; the first later save creates a .toml.v2.bak and writes v9.

Every existing v2 game must produce the same argv, environment and working directory after loading through the new model. Recipes, prefix bundles, Doctor, saves, artwork, notes and configuration edits remain compatible.

Library hierarchy

The primary navigation is platform, followed by a scoped store filter:

All | PC | Windows Ports | Linux Ports | Xbox 360 | PlayStation 3
      All stores | Steam | GOG | Epic | Ubisoft | Local

Only populated platform/store values appear. Search and sort apply after both filters. Store and platform remain independent; emulator is neither. An Xbox 360 ISO imported from disk is initially platform = "xbox360", store = "local". Disc/digital format may become a separate future field.

Port collections are derived from port_target_os, while platform retains the original/content platform. A Windows port keeps Proton, Windows Technology Scan, recipes and OptiScaler. The first curated example is Gears of War 2 - Hollow (xbox360 -> windows); see its investigation (source repository). Linux Ports is structural in this phase: ELF/AppImage import and host launch remain future work.

Add/import experience

Selecting a file or folder runs conservative local detection and shows the platform, evidence, confidence and additional actions before registration. Recognized Xenia bundles use the included wrapper by default and offer direct Xenia as an alternative; an existing wrapper is never silently replaced. Settings.exe and the Xenia UI become Settings and Open Emulator actions using the same prefix.

RPCS3 imports read PS3_GAME/PARAM.SFO, resolve title/Title ID and build a host launch without Proton. A later library importer can batch-select games from an RPCS3 installation. Runi detects existing emulators or accepts a custom path; the first phase does not install/update them.

Process and safety rules

• Process tracking keys auxiliary work by (game_id, action_id); Play/Stop remains tied only to the primary target.
• Settings and Open Emulator are unavailable while Play owns the same prefix.
• Relative target paths resolve below the explicit install root. Importers do not create arbitrary command strings.
• Providers own argument ordering and validation.
• Adapter-suggested save paths require user confirmation; no backup starts automatically.
• Multi-disc metadata may be retained, but interactive disc switching is a later phase; existing wrappers continue owning it.

Shared storefront sessions

Ubisoft games reference a versioned store installation instead of owning a Wine prefix. The shared installation owns the prefix, launcher path and Proton runner; changing its runner updates every linked game. Play sends uplay://launch/<id>/0 to upc.exe and monitors the detected game executable, not merely the short-lived deeplink process. After that executable exits, Runi allows 30 seconds for cloud sync before closing the managed session; Keep Open cancels automatic closure. Concurrent games in the same store prefix are refused, removal of one game never removes the shared prefix, and a per-game prefix bundle cannot include it. See ubisoft-connect.md.

Delivery and acceptance

1. Schema-v3 compatibility and golden launch-plan regression tests.
2. Provider/engine boundary with executable and host execution.
3. Auxiliary action model, CLI and GUI process tracking.
4. Xenia and RPCS3 providers plus conservative detection.
5. Platform -> Store library filters and reviewed Add flow.
6. Real acceptance: existing registered Windows titles, Lost Odyssey wrapper, direct Xenia and one RPCS3-native title.

No phase is accepted while an existing game's launch plan changes unintentionally.