audiogame-manager/docs/superpowers/specs/2026-05-05-umu-proton-backend-design.md

UMU Proton Backend Design

Goal

Add a general UMU/Proton backend to audiogame-manager so selected games can install and launch through umu-run with AGM-managed Proton prefixes. Shadow Line is the first supported game and should be installable, launchable, translated to English, and speech-capable without changing the existing Wine backend for other games.

Scope

This change introduces generic UMU helpers and wires Shadow Line to use them. It does not migrate existing Wine games, add proton-voices, or reimplement umu-launcher. AGM depends on umu-run for Proton/runtime management because UMU handles Proton selection, Steam Runtime setup, prefix creation, protonfixes, and Proton winetricks routing.

Architecture

Launcher entries gain a new backend value in the first games.conf field:

umu|c:\Program Files (x86)\GalaxyLaboratory\ShadowRine_FullVoice\play_sr.exe|Shadow Line|...

The existing Wine values (win64, win32) continue to behave as they do now. When the backend is umu, launch setup uses a dedicated Proton prefix under:

${XDG_DATA_HOME:-$HOME/.local/share}/audiogame-manager/protonBottles/<game-id>

The game id is supplied by the installer and stored in launcher flags, for example export umuGameId=shadow-line. Helpers will centralize backend behavior:

• install_proton_bottle <game-id> [winetricks verbs...]: create and select a UMU prefix, initialize it with umu-run "", and install optional Proton winetricks verbs with umu-run winetricks.
• get_umu_bottle <game-id>: export WINEPREFIX, GAMEID, STORE, and DISPLAY.
• run_umu_game <windows-path>: convert the Windows path to a Unix executable path in the UMU prefix and run it through umu-run.
• add_umu_launcher <game-id> <windows-path> [flags...]: append a umu|... launcher line.

Shadow Line

Shadow Line uses the generic UMU backend with umuGameId=shadow-line. Its installer will:

1. Require umu-run.
2. Download shadowrine_fullvoice3.171.exe and language_en.dat.
3. Create/select the Shadow Line UMU prefix.
4. Apply bcryptprimitives=native,builtin.
5. Apply per-app win8 for play_sr.exe.
6. Run the installer silently with UMU.
7. Stop any leftover Wine/Proton processes for the prefix.
8. Copy language_en.dat into SystemData.
9. Copy AGM's nvdaControllerClient32.dll and/or nvdaControllerClient64.dll over any matching game DLLs found in the Shadow Line install.
10. Register the UMU launcher and show the first-run instructions for switching the game language to English.

Clipboard translation will not be used for Shadow Line in this implementation.

Dependency Checks

check_requirements remains focused on core AGM dependencies, but UMU installers call a targeted require_umu helper so the error is clear at install time. The -c checkup report will also list umu-run: missing UMU is reported as required for Proton-backed games, not as a blocker for every Wine game.

Error Handling

UMU helper functions fail fast with clear messages when umu-run is missing, prefix initialization fails, the installer does not produce the expected executable, or the translation file cannot be copied. Shadow Line should not be added to games.conf unless the expected executable exists.

Verification

Verification will include:

• bash -n on changed shell scripts.
• shellcheck on changed Bash files.
• A focused install-path dry run where possible without launching the interactive game.
• Confirmation that Shadow Line creates a umu|...|Shadow Line launcher entry and that the UMU prefix contains play_sr.exe, language_en.dat, registry settings, and replacement NVDA DLLs when matching DLLs exist.