Files
audiogame-manager/docs/superpowers/plans/2026-05-05-umu-proton-backend.md

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 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:

#!/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:

#!/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.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:

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.