# UMU Proton Backend Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Add a reusable UMU/Proton backend and migrate Shadow Line to it with English localization and NVDA controller DLL replacement. **Architecture:** Keep the existing Wine backend intact and add UMU as a new launcher backend value in `games.conf`. Put generic UMU behavior in a focused include file, keep Shadow Line-specific install work in `.install/Shadow Line.sh`, and route launch/removal/kill behavior through backend-aware branches. **Tech Stack:** Bash, `umu-run`, Wine/Proton prefixes, existing AGM dialog/progress helpers, `shellcheck`. --- ## File Structure - Create: `.includes/proton.sh` - Owns UMU dependency checks, prefix selection, UMU launch environment, Windows path conversion, UMU installer/launch helpers, and UMU launcher registration. - Create: `tests/umu_backend_tests.sh` - Self-contained shell tests with temporary HOME/config/cache paths and stubbed external commands. - Modify: `audiogame-manager.sh` - Source `.includes/proton.sh`, skip Wine-only DLL scanning for UMU prefixes, launch UMU entries through `run_umu_game`, and handle UMU kill/remove paths safely. - Modify: `.includes/checkup.sh` - Report `umu-run` as required for Proton-backed games and include `umu-launcher` in package output. - Modify: `.install/Shadow Line.sh` - Use `install_proton_bottle`, run installer via UMU, apply registry settings, copy English language file, replace NVDA controller DLLs, register with `add_umu_launcher`, and show first-run English instructions. ## Task 1: Add UMU Backend Tests **Files:** - Create: `tests/umu_backend_tests.sh` - [ ] **Step 1: Write failing shell tests** Create `tests/umu_backend_tests.sh`: ```bash #!/usr/bin/env bash set -euo pipefail repoRoot="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" testRoot="$(mktemp -d)" trap 'rm -rf "$testRoot"' EXIT export HOME="${testRoot}/home" export XDG_DATA_HOME="${HOME}/.local/share" export XDG_CONFIG_HOME="${HOME}/.config" export XDG_CACHE_HOME="${HOME}/.cache" export DISPLAY="" export cache="${XDG_CACHE_HOME}/audiogame-manager" export configFile="${XDG_CONFIG_HOME}/storm-games/audiogame-manager/games.conf" export scriptDir="$repoRoot" mkdir -p "$cache" "${configFile%/*}" "${testRoot}/bin" touch "$configFile" cat > "${testRoot}/bin/umu-run" <<'STUB' #!/usr/bin/env bash printf '%s|%s|%s|%s\n' "$WINEPREFIX" "$GAMEID" "${STORE:-}" "$*" >> "$UMU_STUB_LOG" if [[ "${1:-}" == "" ]]; then mkdir -p "$WINEPREFIX/drive_c" fi STUB chmod +x "${testRoot}/bin/umu-run" cat > "${testRoot}/bin/wine" <<'STUB' #!/usr/bin/env bash if [[ "${1:-}" == "winepath" || "${1:-}" == "winepath.exe" ]]; then shift fi if [[ "${1:-}" == "-u" ]]; then input="$2" path="${input#c:\\}" path="${path//\\//}" printf '%s/drive_c/%s\n' "$WINEPREFIX" "$path" exit 0 fi printf 'wine %s\n' "$*" >> "$WINE_STUB_LOG" STUB chmod +x "${testRoot}/bin/wine" cat > "${testRoot}/bin/wineserver" <<'STUB' #!/usr/bin/env bash printf 'wineserver %s\n' "$*" >> "$WINE_STUB_LOG" STUB chmod +x "${testRoot}/bin/wineserver" export PATH="${testRoot}/bin:$PATH" export UMU_STUB_LOG="${testRoot}/umu.log" export WINE_STUB_LOG="${testRoot}/wine.log" # shellcheck source=.includes/proton.sh source "${repoRoot}/.includes/proton.sh" assert_equals() { local expected="$1" local actual="$2" local message="$3" if [[ "$expected" != "$actual" ]]; then printf 'FAIL: %s\nexpected: %s\nactual: %s\n' "$message" "$expected" "$actual" >&2 exit 1 fi } assert_file_contains() { local file="$1" local pattern="$2" local message="$3" if ! grep -Fq "$pattern" "$file"; then printf 'FAIL: %s\nmissing pattern: %s\nfile contents:\n' "$message" "$pattern" >&2 cat "$file" >&2 exit 1 fi } test_get_umu_bottle_sets_environment() { get_umu_bottle "shadow-line" assert_equals "${XDG_DATA_HOME}/audiogame-manager/protonBottles/shadow-line" "$WINEPREFIX" "WINEPREFIX points at AGM proton bottle" assert_equals "shadow-line" "$GAMEID" "GAMEID is exported" assert_equals "none" "$STORE" "STORE defaults to none" assert_equals ":0" "$DISPLAY" "DISPLAY defaults to :0" } test_add_umu_launcher_records_backend_and_game_id() { get_umu_bottle "shadow-line" add_umu_launcher "shadow-line" 'c:\Program Files (x86)\GalaxyLaboratory\ShadowRine_FullVoice\play_sr.exe' assert_file_contains "$configFile" 'umu|c:\Program Files (x86)\GalaxyLaboratory\ShadowRine_FullVoice\play_sr.exe|Shadow Line|export umuGameId=shadow-line' "UMU launcher entry is recorded" } test_run_umu_game_uses_converted_path() { get_umu_bottle "shadow-line" mkdir -p "${WINEPREFIX}/drive_c/Program Files (x86)/GalaxyLaboratory/ShadowRine_FullVoice" touch "${WINEPREFIX}/drive_c/Program Files (x86)/GalaxyLaboratory/ShadowRine_FullVoice/play_sr.exe" run_umu_game 'c:\Program Files (x86)\GalaxyLaboratory\ShadowRine_FullVoice\play_sr.exe' assert_file_contains "$UMU_STUB_LOG" "${WINEPREFIX}|shadow-line|none|${WINEPREFIX}/drive_c/Program Files (x86)/GalaxyLaboratory/ShadowRine_FullVoice/play_sr.exe" "UMU launches converted exe path" } test_get_umu_bottle_sets_environment test_add_umu_launcher_records_backend_and_game_id test_run_umu_game_uses_converted_path printf 'UMU backend tests passed\n' ``` - [ ] **Step 2: Run tests and verify they fail because `.includes/proton.sh` is missing** Run: `bash tests/umu_backend_tests.sh` Expected: FAIL with a message that `.includes/proton.sh` cannot be sourced. ## Task 2: Implement Generic UMU Helpers **Files:** - Create: `.includes/proton.sh` - Test: `tests/umu_backend_tests.sh` - [ ] **Step 1: Implement `.includes/proton.sh`** Create `.includes/proton.sh`: ```bash #!/usr/bin/env bash # shellcheck disable=SC2034,SC2154 # sourced by audiogame-manager and installers with shared globals require_umu() { if command -v umu-run &> /dev/null; then return 0 fi local message="This game requires umu-launcher. Please install umu-launcher and try again." if declare -F agm_msgbox &> /dev/null; then agm_msgbox "Audio Game Manager" "Audio Game Manager" "$message" else echo "$message" >&2 fi return 1 } get_umu_bottle() { local gameId="$1" if [[ -z "$gameId" ]]; then echo "get_umu_bottle requires a game id." >&2 return 1 fi export umuGameId="$gameId" export WINEPREFIX="${XDG_DATA_HOME:-$HOME/.local/share}/audiogame-manager/protonBottles/${gameId}" export GAMEID="$gameId" export STORE="${umuStore:-none}" export DISPLAY="${DISPLAY:-:0}" export UMU_RUNTIME_UPDATE="${UMU_RUNTIME_UPDATE:-0}" mkdir -p "$WINEPREFIX" } install_proton_bottle() { local gameId="$1" shift || true require_umu || return 1 get_umu_bottle "$gameId" || return 1 if [[ ! -f "${WINEPREFIX}/system.reg" ]]; then umu-run "" fi if [[ $# -gt 0 ]]; then umu-run winetricks "$@" fi } umu_windows_path_to_unix() { local windowsPath="$1" wine winepath -u "$windowsPath" } run_umu_game() { local windowsPath="$1" local exePath="" require_umu || return 1 if [[ -z "${umuGameId:-}" ]]; then echo "UMU game id is not set for ${game[2]:-selected game}." >&2 return 1 fi get_umu_bottle "$umuGameId" || return 1 exePath="$(umu_windows_path_to_unix "$windowsPath")" if [[ ! -f "$exePath" ]]; then echo "UMU executable not found: $exePath" >&2 return 1 fi pushd "${exePath%/*}" > /dev/null || return 1 umu-run "$exePath" popd > /dev/null || return 1 } add_umu_launcher() { local gameId="$1" local windowsPath="$2" shift 2 local launchSettings="umu|${windowsPath}|${game}|export umuGameId=${gameId}" while [[ $# -gt 0 ]]; do launchSettings+="|$1" shift done if ! grep -F -q -x "$launchSettings" "$configFile" 2> /dev/null; then echo "$launchSettings" >> "$configFile" sort -t '|' -k3,3f -o "$configFile" "$configFile" fi } set_umu_reg_value() { local key="$1" local valueName="$2" local valueData="$3" wine reg add "$key" /v "$valueName" /t REG_SZ /d "$valueData" /f } set_umu_app_winver() { local exeName="$1" local winVersion="$2" set_umu_reg_value "HKCU\\Software\\Wine\\AppDefaults\\${exeName}" "Version" "$winVersion" } stop_umu_bottle() { if command -v wineserver &> /dev/null; then wineserver -k 2> /dev/null || true fi } ``` - [ ] **Step 2: Run UMU backend tests and verify they pass** Run: `bash tests/umu_backend_tests.sh` Expected: PASS with `UMU backend tests passed`. - [ ] **Step 3: Run shellcheck on new files** Run: `shellcheck .includes/proton.sh tests/umu_backend_tests.sh` Expected: no output and exit code 0. ## Task 3: Wire UMU Backend Into AGM Launch, Kill, and Removal **Files:** - Modify: `audiogame-manager.sh` - Test: `tests/umu_backend_tests.sh` - [ ] **Step 1: Source proton helpers** In `audiogame-manager.sh`, after sourcing `.includes/bottle.sh`, add: ```bash # shellcheck source=.includes/proton.sh source "${scriptDir}/.includes/proton.sh" ``` - [ ] **Step 2: Make removal backend-aware** In `remove_game`, after `create_game_array "$selectedGame"` and before Wine-only setup, branch on `game[0]`: ```bash if [[ "${game[0]}" == "umu" ]]; then process_launcher_flags get_umu_bottle "$umuGameId" else source "${scriptDir}/.includes/bottle.sh" get_bottle "${game[0]}" fi ``` For directory conversion, replace the Wine-only `winepath` call with: ```bash if [[ "${game[0]}" == "umu" ]]; then gameDir="$(umu_windows_path_to_unix "$winePath")" else gameDir="$(winepath "$winePath")" fi ``` For stopping processes, use: ```bash if [[ "${game[0]}" == "umu" ]]; then stop_umu_bottle else wineserver -k fi ``` - [ ] **Step 3: Make kill backend-aware** In `kill_game`, after `create_game_array` or parsing the selected line, ensure UMU entries process launcher flags and call `stop_umu_bottle`: ```bash if [[ "${game[0]}" == "umu" ]]; then process_launcher_flags get_umu_bottle "$umuGameId" stop_umu_bottle else get_bottle "${game%|*}" wineserver -k fi ``` - [ ] **Step 4: Launch UMU entries through `run_umu_game`** In `game_launcher`, after `process_launcher_flags` and before Wine-only qjoypad/path work is used, add: ```bash if [[ "${game[0]}" == "umu" ]]; then echo "launching with umu" start_nvda2speechd run_umu_game "${game[1]}" exit 0 fi ``` Keep Wine launch behavior unchanged for non-UMU entries. - [ ] **Step 5: Run syntax checks** Run: `bash -n audiogame-manager.sh` Expected: no output and exit code 0. - [ ] **Step 6: Run shellcheck on touched shell files** Run: `shellcheck audiogame-manager.sh .includes/proton.sh tests/umu_backend_tests.sh` Expected: no new actionable errors. Existing intentional warnings may be suppressed locally only if they are not real bugs. ## Task 4: Update Dependency Reporting **Files:** - Modify: `.includes/checkup.sh` - [ ] **Step 1: Add UMU check to `.includes/checkup.sh`** After the Wine check, add: ```bash if command -v umu-run &> /dev/null; then [[ $# -eq 0 ]] && echo "umu-launcher is installed." else errorList+=("Warning: umu-launcher is not installed. Games that require Proton/UMU will not install or launch.") fi packageList+=("umu-launcher") ``` - [ ] **Step 2: Run syntax and shellcheck** Run: `bash -n .includes/checkup.sh` Expected: no output and exit code 0. Run: `shellcheck .includes/checkup.sh` Expected: no output and exit code 0, or only pre-existing intentional warnings. ## Task 5: Migrate Shadow Line Installer to UMU **Files:** - Modify: `.install/Shadow Line.sh` - [ ] **Step 1: Replace installer body** Update `.install/Shadow Line.sh` to: ```bash # shellcheck shell=bash disable=SC2154 # cache, game, and helper functions are set by audiogame-manager download "https://www.mm-galabo.com/sr/Download_files_srfv/shadowrine_fullvoice3.171.exe" \ "https://raw.githubusercontent.com/LordLuceus/sr-english-localization/master/language_en.dat" \ "${nvdaControllerClient32Dll}" \ "${nvdaControllerClient64Dll}" export game="Shadow Line" shadowLineGameId="shadow-line" shadowLinePath='c:\Program Files (x86)\GalaxyLaboratory\ShadowRine_FullVoice\play_sr.exe' shadowLineInstallDir="${WINEPREFIX}/drive_c/Program Files (x86)/GalaxyLaboratory/ShadowRine_FullVoice" install_proton_bottle "$shadowLineGameId" fakejapanese shadowLineInstallDir="${WINEPREFIX}/drive_c/Program Files (x86)/GalaxyLaboratory/ShadowRine_FullVoice" set_umu_reg_value "HKCU\\Software\\Wine\\DllOverrides" "bcryptprimitives" "native,builtin" set_umu_app_winver "play_sr.exe" "win8" { echo "# Installing Shadow Line..." timeout 300 umu-run "${cache}/shadowrine_fullvoice3.171.exe" /sp- /VERYSILENT /SUPPRESSMSGBOXES 2>&1 || true echo "# Installation complete" } | agm_progressbox "Installing Game" "Installing Shadow Line with UMU/Proton (this may take a few minutes)..." stop_umu_bottle if [[ ! -f "${shadowLineInstallDir}/play_sr.exe" ]]; then agm_msgbox "Shadow Line" "Shadow Line" "Shadow Line did not install to the expected location: ${shadowLineInstallDir}" exit 1 fi install -m 0644 "${cache}/language_en.dat" "${shadowLineInstallDir}/SystemData/language_en.dat" find "$shadowLineInstallDir" -type f -iname 'nvdaControllerClient32.dll' -exec cp -v "${cache}/nvdaControllerClient32.dll" "{}" \; find "$shadowLineInstallDir" -type f -iname 'nvdaControllerClient64.dll' -exec cp -v "${cache}/nvdaControllerClient64.dll" "{}" \; find "$shadowLineInstallDir" -type f -iname 'nvdaControllerClient.dll' -exec cp -v "${cache}/nvdaControllerClient32.dll" "{}" \; add_umu_launcher "$shadowLineGameId" "$shadowLinePath" alert "Shadow Line" "Shadow Line" "Please set the language to English when the game opens.\nGo to options and press enter.\nPress down arrow 5 times and press enter.\nPress down arrow 1 time and press enter.\nPress up arrow 2 times and press enter.\nIf everything worked as expected you should be back on the game menu and speech should work." ``` - [ ] **Step 2: Run syntax check** Run: `bash -n ".install/Shadow Line.sh"` Expected: no output and exit code 0. - [ ] **Step 3: Run shellcheck on Shadow Line installer** Run: `shellcheck ".install/Shadow Line.sh"` Expected: no output and exit code 0, or only intentional sourced-global warnings suppressed by the file header. ## Task 6: End-to-End Verification **Files:** - Modify as needed based on verification findings. - [ ] **Step 1: Run focused unit tests** Run: `bash tests/umu_backend_tests.sh` Expected: PASS with `UMU backend tests passed`. - [ ] **Step 2: Run syntax checks for all touched scripts** Run: ```bash bash -n audiogame-manager.sh bash -n .includes/proton.sh bash -n .includes/checkup.sh bash -n ".install/Shadow Line.sh" bash -n tests/umu_backend_tests.sh ``` Expected: all commands exit 0. - [ ] **Step 3: Run shellcheck for all touched Bash files** Run: ```bash shellcheck audiogame-manager.sh .includes/proton.sh .includes/checkup.sh ".install/Shadow Line.sh" tests/umu_backend_tests.sh ``` Expected: no actionable warnings. - [ ] **Step 4: Optional live install verification** If the user approves running the live installer, run: ```bash DISPLAY=:0 ./audiogame-manager.sh -I "Shadow Line" ``` Expected: - Shadow Line installs into `${XDG_DATA_HOME:-$HOME/.local/share}/audiogame-manager/protonBottles/shadow-line`. - `games.conf` contains `umu|...|Shadow Line|export umuGameId=shadow-line`. - `play_sr.exe` exists under the Shadow Line Proton prefix. - `SystemData/language_en.dat` exists. - `user.reg` contains `bcryptprimitives` and `AppDefaults\\play_sr.exe` with `Version=win8`. - [ ] **Step 5: Commit implementation** Run: ```bash git add .includes/proton.sh .includes/checkup.sh ".install/Shadow Line.sh" audiogame-manager.sh tests/umu_backend_tests.sh docs/superpowers/plans/2026-05-05-umu-proton-backend.md git commit -m "Add UMU Proton backend for Shadow Line" ``` Expected: commit succeeds and unrelated pre-existing dirty files remain unstaged. ## Self-Review - Spec coverage: generic UMU helpers, Shadow Line migration, dependency checks, error handling, and verification are each covered by tasks. - Placeholder scan: no TODO/TBD placeholders remain. - Type consistency: helper names are consistent across tests, implementation, installer, and launcher tasks.