Plan UMU Proton backend implementation

2026-05-05 02:14:45 -04:00
parent b58681964c
commit 53d8c10645
1 changed files with 525 additions and 0 deletions
@@ -0,0 +1,525 @@
+# 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.