runi-dist/docs/launch-providers.md

<!-- Generated from the Runi source repository at v0.4.0. -->
<!-- Edit the original there, not this copy. -->

# 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:

```text
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:

```text
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](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.