funman300/Battlenet_UMU
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

modified: README.md

Browse Source 
new file:   battlenet-umu-setup.sh
This commit is contained in:
funman300
2026-04-16 12:39:48 -07:00
parent 8b1835a9fc
commit 28b1f0f824
2 changed files with 604 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+372
View File
@@ -0,0 +1,372 @@
# Battle.net Arch Linux Install Guide
A guide for installing the Battle.net launcher on Arch Linux (2026).
> **Note on this revision:** This guide has been substantially rewritten and scoped to Arch Linux. The original targeted Wine 5.x, DXVK 1.7.1, Ubuntu 20.04 "focal", and Debian 10, and relied on winetricks recipes (`dotnet48`, `vcrun*`, manual DXVK copy) that are no longer necessary or recommended. Modern Battle.net runs well out of the box with Proton-GE or a recent `wine-staging`, without `.NET`, manual DXVK, or DirectX redistributable hacks.
---
## TL;DR — Which method should I use?
| Method | Best for | Effort |
|---|---|---|
| **umu-launcher (standalone Proton, no Steam)** | Scripting, minimal installs, homelab. **Recommended.** | Low |
| **Steam + Proton-GE (non-Steam shortcut)** | People who already run Steam. | Low |
| **Lutris (official installer script)** | People who want a GUI game manager. | Low–Medium |
| **Bottles (Flatpak, Gaming environment)** | Flatpak-first setups. | Low |
| **Manual `wine-staging` prefix** | Pure-Wine purists, non-Proton setups. | High |
If you just want it to work: use **Method 1 (umu)**. It gives you Proton-grade compatibility without Steam, and the upstream protonfix for Battle.net automatically applies the workarounds you'd otherwise have to remember.
---
## Prerequisites
Enable `[multilib]` in `/etc/pacman.conf` if you haven't already. Uncomment these two lines:
```ini
[multilib]
Include = /etc/pacman.d/mirrorlist
```
Then:
```bash
sudo pacman -Syu
```
> You do **not** need `[testing]`, `[core-testing]`, or `[multilib-testing]` enabled. The old guide told you to enable those — don't. Testing repos are for people actively helping test Arch itself and will periodically break your system.
Install the common 32-bit graphics and audio libraries most Wine/Proton setups want:
```bash
sudo pacman -S --needed \
wine-staging winetricks \
giflib lib32-giflib \
libpng lib32-libpng \
libldap lib32-libldap \
gnutls lib32-gnutls \
mpg123 lib32-mpg123 \
openal lib32-openal \
v4l-utils lib32-v4l-utils \
libpulse lib32-libpulse \
alsa-plugins lib32-alsa-plugins \
alsa-lib lib32-alsa-lib \
libjpeg-turbo lib32-libjpeg-turbo \
sqlite lib32-sqlite \
libxcomposite lib32-libxcomposite \
libxinerama lib32-libxinerama \
ncurses lib32-ncurses \
opencl-icd-loader lib32-opencl-icd-loader \
libxslt lib32-libxslt \
libva lib32-libva \
gtk3 lib32-gtk3 \
gst-plugins-base-libs lib32-gst-plugins-base-libs \
vulkan-icd-loader lib32-vulkan-icd-loader \
cups samba
```
For an NVIDIA GPU, also install `lib32-nvidia-utils`. For AMD/Intel, `lib32-mesa` and `lib32-vulkan-radeon` or `lib32-vulkan-intel`.
---
## ⚠️ Before you start — things the old guide got wrong
- **Do not run Wine, winecfg, winetricks, or game launchers with `sudo`.** Wine prefixes are designed to live in your user's home directory. Running Wine as root corrupts ownership, creates a `/root` prefix, and is a real security risk since you're executing untrusted Windows binaries as root. Every command in this guide runs as your regular user.
- **You do not need `dotnet48`, `vcrun2003/2005/2008/2012/2013`, or `directplay`.** Modern Battle.net ships its own CEF runtime.
- **You do not need to manually install DXVK into `system32`.** Proton-GE bundles a current DXVK and VKD3D.
- **You do not need the 2010 DirectX End-User Runtime redist.** Battle.net doesn't need it, and games that do will install their own D3DX DLLs.
- **`win64` prefixes are now the default and correct choice.** No `WINEARCH=win32` needed.
- **Don't enable Arch testing repos** unless you're specifically helping test them.
---
## Method 1 — umu-launcher (recommended)
[`umu-launcher`](https://github.com/Open-Wine-Components/umu-launcher) is the Open Wine Components project (from the GE-Proton maintainers) that makes Proton usable outside Steam. It manages Proton versions, runs games inside the Steam Runtime container, and automatically applies **protonfixes** — including the upstream fix for Battle.net that handles the `WINE_SIMULATE_WRITECOPY=1` workaround for you.
### 1. Install umu-launcher
```bash
sudo pacman -S umu-launcher
```
Verify:
```bash
umu-run --help
```
### 2. Download the Battle.net installer
```bash
curl -L -o ~/Downloads/Battle.net-Setup.exe \
"https://downloader.battle.net/download/getInstaller?os=win&installer=Battle.net-Setup.exe"
```
### 3. Run the installer through umu
```bash
export WINEPREFIX="$HOME/Games/battlenet-umu"
export GAMEID="umu-battlenet"
export PROTONPATH="GE-Proton" # auto-downloads latest GE-Proton
umu-run ~/Downloads/Battle.net-Setup.exe
```
umu will:
- Download the latest GE-Proton into `~/.local/share/Steam/compatibilitytools.d/` if it isn't there.
- Create the prefix at `~/Games/battlenet-umu`.
- Look up `umu-battlenet` in the protonfixes database and pre-apply the needed env vars and tweaks.
Complete the installer at the default path.
### 4. Create a launch script
`~/.local/bin/battlenet`:
```bash
#!/bin/sh
export WINEPREFIX="$HOME/Games/battlenet-umu"
export GAMEID="umu-battlenet"
export PROTONPATH="GE-Proton"
exec umu-run "$WINEPREFIX/drive_c/Program Files (x86)/Battle.net/Battle.net Launcher.exe" "$@"
```
```bash
chmod +x ~/.local/bin/battlenet
```
Make sure `~/.local/bin` is on your `PATH` (it is by default on most Arch shells). Now `battlenet` in any terminal starts the launcher.
### 5. (Optional) Desktop entry
`~/.local/share/applications/battlenet.desktop`:
```ini
[Desktop Entry]
Name=Battle.net
Exec=/home/YOUR_USERNAME/.local/bin/battlenet
Icon=battlenet
Type=Application
Categories=Game;
```
### 6. (Optional) Pin a specific Proton version
If a GE-Proton release ever regresses Battle.net, pin a known-good one instead of tracking latest:
```bash
export PROTONPATH="GE-Proton9-20"
```
It needs to exist in `~/.local/share/Steam/compatibilitytools.d/`.
---
## Method 2 — Steam + Proton-GE (non-Steam shortcut)
Good if you already have Steam installed.
### 1. Install Steam and ProtonUp-Qt
```bash
sudo pacman -S steam
# ProtonUp-Qt is on the AUR:
yay -S protonup-qt # or use paru, or grab the Flatpak
```
Log into Steam at least once. Open ProtonUp-Qt, point it at your Steam install, and install the latest **GE-Proton**. Restart Steam.
### 2. Download the Battle.net installer
Get `Battle.net-Setup.exe` from <https://download.battle.net/?product=bnetdesk>.
### 3. Add it to Steam as a non-Steam game
1. In Steam: **Games → Add a Non-Steam Game to My Library → Browse** and select `Battle.net-Setup.exe`.
2. Right-click the new entry → **Properties → Compatibility** → tick **Force the use of a specific Steam Play compatibility tool** → select the latest **GE-Proton**.
3. Under **Launch Options**, paste:
```
WINE_SIMULATE_WRITECOPY=1 %command%
```
This works around a CEF/login-screen issue that Blizzard periodically reintroduces with launcher updates. Cheap insurance.
4. Launch it from Steam and complete the installer at the default path.
### 4. Point the shortcut at the installed launcher
After installation, the Battle.net launcher lives inside the prefix Steam created. Find the `compatdata` folder:
- **Native Steam:** `~/.local/share/Steam/steamapps/compatdata/<APPID>/pfx/`
- **Flatpak Steam:** `~/.var/app/com.valvesoftware.Steam/.local/share/Steam/steamapps/compatdata/<APPID>/pfx/`
The `<APPID>` is a numeric folder; sort by modification date to find the one you just created.
Right-click the Steam shortcut → **Properties** and change:
- **Target:** `"…/compatdata/<APPID>/pfx/drive_c/Program Files (x86)/Battle.net/Battle.net Launcher.exe"`
- **Start In:** `"…/compatdata/<APPID>/pfx/drive_c/Program Files (x86)/Battle.net/"`
Launch — you should now get the real launcher, not the installer.
---
## Method 3 — Lutris
Modern Lutris uses **umu-launcher** under the hood when you pick a Proton runner, so protonfixes apply automatically.
```bash
sudo pacman -S lutris
```
1. Open Lutris → **+ (Add game) → Search the Lutris website for installers**.
2. Search **Battle.net** and pick the current maintained installer.
3. Follow the prompts.
> **Known issue (early 2026):** the default Wine-GE runner bundled with some Lutris versions is too old for current Battle.net. If installation hangs or the launcher refuses to start, open Lutris → **Preferences → Runners → Wine** and install a newer **lutris-GE** or **wine-ge** runner, then set it on the Battle.net entry.
### Add the environment variable (belt-and-suspenders)
Right-click the Battle.net entry → **Configure → System options → Environment variables**:
| Key | Value |
|---|---|
| `WINE_SIMULATE_WRITECOPY` | `1` |
---
## Method 4 — Bottles (Flatpak)
```bash
flatpak install flathub com.usebottles.bottles
```
1. Open Bottles → **+** → choose the **Gaming** environment.
2. Under **Preferences → Runners**, install the latest **caffe** or **soda** runner (or GE-Proton if supported).
3. In the bottle → **Run Executable** → pick `Battle.net-Setup.exe`.
4. After install, in the bottle's **Settings → Environment Variables**, add:
- `WINE_SIMULATE_WRITECOPY=1`
- Optionally: `WINEDLLOVERRIDES=locationapi=d`
The launcher shows up in the bottle's **Programs** list.
---
## Method 5 — Manual wine-staging prefix (advanced, no Proton)
Use this only if you specifically want pure Wine without Proton.
### 1. Create a 64-bit prefix
```bash
# As your normal user — NOT root
export WINEPREFIX="$HOME/Games/battlenet-wine-prefix"
export WINEARCH=win64
mkdir -p "$WINEPREFIX"
winecfg
```
In `winecfg`, set the Windows version to **Windows 10** and close.
### 2. Install DXVK
```bash
WINEPREFIX="$HOME/Games/battlenet-wine-prefix" winetricks dxvk
```
That single command replaces what the old guide did by hand with `cp -r` into `system32`/`syswow64`. **Do not copy DLLs manually.**
### 3. Download and run the installer
```bash
curl -L -o ~/Downloads/Battle.net-Setup.exe \
"https://downloader.battle.net/download/getInstaller?os=win&installer=Battle.net-Setup.exe"
WINEPREFIX="$HOME/Games/battlenet-wine-prefix" \
WINE_SIMULATE_WRITECOPY=1 \
wine ~/Downloads/Battle.net-Setup.exe
```
### 4. Launch scripts
`~/.local/bin/battlenet`:
```bash
#!/bin/sh
export WINEPREFIX="$HOME/Games/battlenet-wine-prefix"
export WINE_SIMULATE_WRITECOPY=1
exec wine "$WINEPREFIX/drive_c/Program Files (x86)/Battle.net/Battle.net Launcher.exe" "$@"
```
`~/.local/bin/battlenetkill`:
```bash
#!/bin/sh
export WINEPREFIX="$HOME/Games/battlenet-wine-prefix"
wineserver -k
```
```bash
chmod +x ~/.local/bin/battlenet ~/.local/bin/battlenetkill
```
---
## Troubleshooting
### "Battle.net Update Agent went to sleep. Attempting to wake it up… BLZBNTBNA00000005"
The most common 2025–2026 failure mode. In order:
1. Confirm `WINE_SIMULATE_WRITECOPY=1` is set (or that you're using umu/Lutris-via-umu, which sets it).
2. Kill everything and wipe the agent cache:
```bash
pkill -9 Battle.net; pkill -9 Agent; pkill -9 Blizzard
rm -rf "$WINEPREFIX/drive_c/ProgramData/Battle.net/Agent"
rm -rf "$WINEPREFIX/drive_c/ProgramData/Blizzard Entertainment"
```
Restart the launcher; you'll have to log in again.
3. Update GE-Proton. Fixes for Battle.net regressions usually land in a new GE-Proton release within days.
### Blank login screen / missing login buttons
`WINE_SIMULATE_WRITECOPY=1`. Specifically the fix for this — Blizzard's CEF launcher depends on Windows write-copy memory semantics that Wine doesn't emulate by default.
### Blank window / broken input under Wayland
Wine's native Wayland driver is still rough for the Battle.net launcher in 2026. Either:
- Log into an X11 session (SDDM/GDM login screen → session picker), or
- Make sure you're going through XWayland — Steam/Proton does this automatically.
### "X Error of failed request: BadWindow" or X11 root-access errors
Caused by running Wine as root (what the old guide told you to do). **Don't.** If you're stuck with a root-owned prefix, remove it and start over as your normal user:
```bash
sudo rm -rf /home/<user>/Games/battlenet-wine-prefix
```
### Something else is broken
Delete the prefix and start over — this really does fix most weird states.
```bash
rm -rf "$HOME/Games/battlenet-umu" # or battlenet-wine-prefix
```
---
## A note on bans
Blizzard does not ban for running via Wine/Proton/Linux. Their Warden anti-cheat targets cheat software inside the game process, not the compatibility layer. This has been confirmed by Blizzard support as recently as 2025.
---
## Changelog for this revision
- **Scoped to Arch Linux.** Removed the Ubuntu `focal` and Debian 10 sections — both EOL, and the guide is cleaner focused on one distro.
- Removed `sudo` from all Wine/winetricks/wine-launch commands.
- Removed obsolete winetricks verbs (`dotnet48`, `vcrun*`, `directplay`).
- Removed manual DXVK 1.7.1 copy-into-system32 procedure.
- Removed manual DirectX June 2010 redist install step.
- Removed advice to enable Arch `[testing]` repos.
- Added **umu-launcher** as the recommended method — protonfixes handle the Battle.net workarounds automatically.
- Added Steam + Proton-GE, Lutris, and Bottles methods.
- Added `WINE_SIMULATE_WRITECOPY=1` workaround for the modern CEF login/agent issues.
- Replaced `/usr/bin/` install of user launch scripts with `~/.local/bin/`.
- Set default Wine Windows version to Windows 10 rather than Windows 7.
- Added Wayland/XWayland notes and the Agent-cache wipe fix for `BLZBNTBNA00000005`.
battlenet-umu-setup.sh
+232
View File
@@ -0,0 +1,232 @@
#!/usr/bin/env bash
#
# battlenet-umu-setup.sh
#
# Installs the Battle.net launcher on Arch Linux via umu-launcher.
# Idempotent: safe to re-run. Skips steps that are already done.
#
# Usage:
# ./battlenet-umu-setup.sh # interactive
# ./battlenet-umu-setup.sh --yes # non-interactive, assume yes
# ./battlenet-umu-setup.sh --reinstall # wipe prefix and reinstall
#
# Does NOT run itself as root. It will call sudo only for pacman.
set -euo pipefail
# ---------- config ----------
PREFIX_DIR="${BATTLENET_PREFIX:-$HOME/Games/battlenet-umu}"
GAMEID="umu-battlenet"
PROTONPATH="${PROTONPATH:-GE-Proton}"
INSTALLER_URL="https://downloader.battle.net/download/getInstaller?os=win&installer=Battle.net-Setup.exe"
INSTALLER_PATH="$HOME/Downloads/Battle.net-Setup.exe"
LAUNCHER_EXE_REL="drive_c/Program Files (x86)/Battle.net/Battle.net Launcher.exe"
BIN_DIR="$HOME/.local/bin"
DESKTOP_DIR="$HOME/.local/share/applications"
LAUNCH_SCRIPT="$BIN_DIR/battlenet"
KILL_SCRIPT="$BIN_DIR/battlenetkill"
DESKTOP_FILE="$DESKTOP_DIR/battlenet.desktop"
ASSUME_YES=0
REINSTALL=0
# ---------- helpers ----------
c_reset=$'\033[0m'; c_blue=$'\033[1;34m'; c_green=$'\033[1;32m'
c_yellow=$'\033[1;33m'; c_red=$'\033[1;31m'; c_dim=$'\033[2m'
log() { printf '%s==>%s %s\n' "$c_blue" "$c_reset" "$*"; }
ok() { printf '%s✓%s %s\n' "$c_green" "$c_reset" "$*"; }
warn() { printf '%s!%s %s\n' "$c_yellow" "$c_reset" "$*"; }
err() { printf '%s✗%s %s\n' "$c_red" "$c_reset" "$*" >&2; }
skip() { printf ' %s(skip) %s%s\n' "$c_dim" "$*" "$c_reset"; }
confirm() {
# confirm "Question?" -> returns 0 for yes, 1 for no
if [[ $ASSUME_YES -eq 1 ]]; then return 0; fi
local prompt="$1 [Y/n] "
local reply
read -r -p "$prompt" reply
[[ -z "$reply" || "$reply" =~ ^[Yy] ]]
}
die() { err "$*"; exit 1; }
# ---------- arg parsing ----------
for arg in "$@"; do
case "$arg" in
-y|--yes) ASSUME_YES=1 ;;
--reinstall) REINSTALL=1 ;;
-h|--help)
sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'
exit 0
;;
*) die "Unknown argument: $arg" ;;
esac
done
# ---------- preflight ----------
log "Preflight checks"
[[ $EUID -ne 0 ]] || die "Do not run this script as root. It will sudo when it needs to."
command -v pacman >/dev/null || die "pacman not found — this script is for Arch Linux."
command -v curl >/dev/null || die "curl not installed. sudo pacman -S curl"
# multilib check
if ! pacman -Sl multilib >/dev/null 2>&1; then
err "[multilib] repository is not enabled in /etc/pacman.conf."
err "Edit /etc/pacman.conf, uncomment the [multilib] section, then run:"
err " sudo pacman -Syu"
exit 1
fi
ok "[multilib] is enabled"
# ---------- install umu-launcher ----------
log "Installing umu-launcher"
if pacman -Qi umu-launcher >/dev/null 2>&1; then
skip "umu-launcher already installed"
else
confirm "Install umu-launcher via pacman?" || die "Aborted."
sudo pacman -S --needed --noconfirm umu-launcher
ok "umu-launcher installed"
fi
command -v umu-run >/dev/null || die "umu-run not on PATH after install — something went wrong."
# ---------- download installer ----------
log "Fetching Battle.net installer"
mkdir -p "$(dirname "$INSTALLER_PATH")"
if [[ -f "$INSTALLER_PATH" ]]; then
skip "Installer already at $INSTALLER_PATH"
if confirm "Re-download to get the latest?"; then
curl -L --fail -o "$INSTALLER_PATH" "$INSTALLER_URL"
ok "Installer re-downloaded"
fi
else
curl -L --fail -o "$INSTALLER_PATH" "$INSTALLER_URL"
ok "Installer saved to $INSTALLER_PATH"
fi
# ---------- prefix ----------
log "Preparing prefix at $PREFIX_DIR"
if [[ -d "$PREFIX_DIR" ]]; then
if [[ $REINSTALL -eq 1 ]]; then
warn "Reinstall requested — removing existing prefix"
if confirm "Really delete $PREFIX_DIR ?"; then
rm -rf "$PREFIX_DIR"
ok "Prefix removed"
else
die "Aborted."
fi
else
skip "Prefix already exists (use --reinstall to wipe)"
fi
fi
mkdir -p "$PREFIX_DIR"
# ---------- run installer ----------
LAUNCHER_PATH="$PREFIX_DIR/$LAUNCHER_EXE_REL"
if [[ -f "$LAUNCHER_PATH" ]]; then
skip "Battle.net Launcher.exe already present in prefix"
else
log "Running Battle.net installer through umu (this takes a few minutes)"
warn "The Battle.net installer window will appear. Accept the defaults"
warn "and let it finish. The installer may auto-close — that's fine."
confirm "Continue?" || die "Aborted."
WINEPREFIX="$PREFIX_DIR" \
GAMEID="$GAMEID" \
PROTONPATH="$PROTONPATH" \
umu-run "$INSTALLER_PATH" || {
warn "umu-run exited non-zero. That's often normal for the Battle.net installer."
}
# The installer sometimes drops the launcher even if it exits weirdly.
# Give it a moment, then check.
sleep 2
if [[ ! -f "$LAUNCHER_PATH" ]]; then
err "Battle.net Launcher.exe not found at expected path:"
err " $LAUNCHER_PATH"
err "The installer may not have completed. Re-run with --reinstall."
exit 1
fi
ok "Battle.net installed into prefix"
fi
# ---------- launch scripts ----------
log "Installing launch scripts to $BIN_DIR"
mkdir -p "$BIN_DIR"
cat > "$LAUNCH_SCRIPT" <<EOF
#!/bin/sh
# Auto-generated by battlenet-umu-setup.sh
export WINEPREFIX="$PREFIX_DIR"
export GAMEID="$GAMEID"
export PROTONPATH="$PROTONPATH"
exec umu-run "\$WINEPREFIX/$LAUNCHER_EXE_REL" "\$@"
EOF
chmod +x "$LAUNCH_SCRIPT"
ok "Wrote $LAUNCH_SCRIPT"
cat > "$KILL_SCRIPT" <<EOF
#!/bin/sh
# Auto-generated by battlenet-umu-setup.sh
# Kills the Battle.net launcher and all Wine/Proton processes for this prefix.
export WINEPREFIX="$PREFIX_DIR"
pkill -9 -f 'Battle\\.net' 2>/dev/null || true
pkill -9 -f 'Agent\\.exe' 2>/dev/null || true
pkill -9 -f 'Blizzard' 2>/dev/null || true
# wineserver may not be on PATH in umu environments; try both.
if command -v wineserver >/dev/null; then
wineserver -k 2>/dev/null || true
fi
EOF
chmod +x "$KILL_SCRIPT"
ok "Wrote $KILL_SCRIPT"
# PATH check
case ":$PATH:" in
*":$BIN_DIR:"*) ok "$BIN_DIR is on PATH" ;;
*) warn "$BIN_DIR is not on your PATH. Add this to your shell rc:"
warn " export PATH=\"\$HOME/.local/bin:\$PATH\"" ;;
esac
# ---------- desktop entry ----------
log "Installing desktop entry"
mkdir -p "$DESKTOP_DIR"
cat > "$DESKTOP_FILE" <<EOF
[Desktop Entry]
Name=Battle.net
Comment=Blizzard launcher (umu/Proton)
Exec=$LAUNCH_SCRIPT
Icon=battlenet
Type=Application
Categories=Game;
StartupWMClass=battle.net.exe
EOF
ok "Wrote $DESKTOP_FILE"
# Refresh the desktop database if the tool is around — best-effort only.
if command -v update-desktop-database >/dev/null; then
update-desktop-database "$DESKTOP_DIR" 2>/dev/null || true
fi
# ---------- done ----------
echo
ok "Setup complete."
echo
echo " Prefix: $PREFIX_DIR"
echo " Launcher: $LAUNCH_SCRIPT"
echo " Kill: $KILL_SCRIPT"
echo " Desktop: $DESKTOP_FILE"
echo
echo "Run 'battlenet' to start it, or launch from your app menu."
echo "If it hangs on 'Update Agent went to sleep', run: battlenetkill && battlenet"