16 KiB
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 throughrun_umu_game, and handle UMU kill/remove paths safely.
- Source
- Modify:
.includes/checkup.sh- Report
umu-runas required for Proton-backed games and includeumu-launcherin package output.
- Report
- 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 withadd_umu_launcher, and show first-run English instructions.
- Use
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:
#!/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.shis 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:
#!/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:
# 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]:
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:
if [[ "${game[0]}" == "umu" ]]; then
gameDir="$(umu_windows_path_to_unix "$winePath")"
else
gameDir="$(winepath "$winePath")"
fi
For stopping processes, use:
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:
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:
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:
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:
# 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 -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:
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:
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.confcontainsumu|...|Shadow Line|export umuGameId=shadow-line. -
play_sr.exeexists under the Shadow Line Proton prefix. -
SystemData/language_en.datexists. -
user.regcontainsbcryptprimitivesandAppDefaults\\play_sr.exewithVersion=win8. -
Step 5: Commit implementation
Run:
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.