modified: README.md

new file: battlenet-umu-setup.sh
2026-04-16 12:39:48 -07:00
parent 8b1835a9fc
commit 28b1f0f824
2 changed files with 604 additions and 0 deletions
@@ -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`.