# 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//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.