From 53d8c10645f8aca108bf3ba9297b0bc85d364019 Mon Sep 17 00:00:00 2001 From: Storm Dragon Date: Tue, 5 May 2026 02:14:45 -0400 Subject: [PATCH] Plan UMU Proton backend implementation --- .../plans/2026-05-05-umu-proton-backend.md | 525 ++++++++++++++++++ 1 file changed, 525 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-05-umu-proton-backend.md diff --git a/docs/superpowers/plans/2026-05-05-umu-proton-backend.md b/docs/superpowers/plans/2026-05-05-umu-proton-backend.md new file mode 100644 index 0000000..036d4e9 --- /dev/null +++ b/docs/superpowers/plans/2026-05-05-umu-proton-backend.md @@ -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.