modified: README.md

new file: battlenet-diagnose.sh modified: battlenet-umu-setup.sh new file: battlenet-update-proton.sh
2026-04-16 12:59:47 -07:00
parent 28b1f0f824
commit 6f36e503fd
4 changed files with 877 additions and 58 deletions
@@ -8,18 +8,55 @@ A guide for installing the Battle.net launcher on Arch Linux (2026).

 ## 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 |
+| 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.

 ---

+## Quick start — automated script
+
+The fastest path is the included setup script, which handles everything in Method 1 automatically:
+
+```bash
+# Download and run
+curl -LO https://raw.githubusercontent.com/your-repo/battlenet-umu-setup.sh
+chmod +x battlenet-umu-setup.sh
+./battlenet-umu-setup.sh
+```
+
+Or if you already have this repo cloned:
+
+```bash
+./battlenet-umu-setup.sh
+```
+
+The script is idempotent — safe to re-run. Common flags:
+
+```bash
+./battlenet-umu-setup.sh --yes                          # non-interactive / CI
+./battlenet-umu-setup.sh --reinstall                    # wipe prefix and start over
+./battlenet-umu-setup.sh --proton-version=GE-Proton9-20 # pin a specific Proton version
+./battlenet-umu-setup.sh --gpu=nvidia                   # override GPU auto-detection
+./battlenet-umu-setup.sh --prefix-dir=~/Games/bnet      # custom prefix location
+./battlenet-umu-setup.sh --skip-packages                # skip the package check
+```
+
+Companion scripts also included:
+
+| Script                        | Purpose                                                       |
+| ----------------------------- | ------------------------------------------------------------- |
+| `battlenet-update-proton.sh`  | Download a new GE-Proton release and update the launch script |
+| `battlenet-diagnose.sh`       | Check setup health and report anything broken                 |
+
+---
+
 ## Prerequisites

 Enable `[multilib]` in `/etc/pacman.conf` if you haven't already. Uncomment these two lines:
@@ -66,7 +103,17 @@ sudo pacman -S --needed \
  cups samba
 ```

-For an NVIDIA GPU, also install `lib32-nvidia-utils`. For AMD/Intel, `lib32-mesa` and `lib32-vulkan-radeon` or `lib32-vulkan-intel`.
+### GPU-specific packages
+
+Install the right set for your GPU — getting this wrong is the most common reason a successful install fails to render:
+
+| GPU          | Extra packages to install                                        |
+| ------------ | ---------------------------------------------------------------- |
+| **NVIDIA**   | `lib32-nvidia-utils nvidia-utils`                                |
+| **AMD**      | `lib32-mesa lib32-vulkan-radeon vulkan-radeon mesa`              |
+| **Intel**    | `lib32-mesa lib32-vulkan-intel vulkan-intel mesa`                |
+
+The `battlenet-umu-setup.sh` script auto-detects your GPU and installs the correct set. Override with `--gpu=nvidia|amd|intel` if detection is wrong.

 ---

@@ -85,13 +132,18 @@ For an NVIDIA GPU, also install `lib32-nvidia-utils`. For AMD/Intel, `lib32-mesa

 [`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
+### 1. Install prerequisites and umu-launcher
+
+Install the prerequisite packages from [Prerequisites](#prerequisites) above, then:

 ```bash
 sudo pacman -S umu-launcher
 ```

+Alternatively, `battlenet-umu-setup.sh` handles both in one step.
+
 Verify:
+
 ```bash
 umu-run --help
 ```
@@ -114,6 +166,7 @@ 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.
@@ -123,6 +176,7 @@ Complete the installer at the default path.
 ### 4. Create a launch script

 `~/.local/bin/battlenet`:
+
 ```bash
 #!/bin/sh
 export WINEPREFIX="$HOME/Games/battlenet-umu"
@@ -135,18 +189,20 @@ exec umu-run "$WINEPREFIX/drive_c/Program Files (x86)/Battle.net/Battle.net Laun
 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.
+Make sure `~/.local/bin` is on your `PATH`. See [Adding ~/.local/bin to PATH](#adding-localbin-to-path) below if it isn't. Once it is, `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
+Exec=$HOME/.local/bin/battlenet
 Icon=battlenet
 Type=Application
 Categories=Game;
+StartupWMClass=battle.net.exe
 ```

 ### 6. (Optional) Pin a specific Proton version
@@ -157,7 +213,7 @@ If a GE-Proton release ever regresses Battle.net, pin a known-good one instead o
 export PROTONPATH="GE-Proton9-20"
 ```

-It needs to exist in `~/.local/share/Steam/compatibilitytools.d/`.
+It needs to exist in `~/.local/share/Steam/compatibilitytools.d/`. With the setup script, use `--proton-version=GE-Proton9-20`.

 ---

@@ -175,7 +231,7 @@ 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
+### 2. Get the Battle.net installer

 Get `Battle.net-Setup.exe` from <https://download.battle.net/?product=bnetdesk>.

@@ -184,9 +240,11 @@ Get `Battle.net-Setup.exe` from <https://download.battle.net/?product=bnetdesk>.
 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:
-   ```
+
+   ```text
   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.

@@ -226,9 +284,9 @@ sudo pacman -S lutris

 Right-click the Battle.net entry → **Configure → System options → Environment variables**:

-| Key | Value |
-|---|---|
-| `WINE_SIMULATE_WRITECOPY` | `1` |
+| Key                        | Value |
+| -------------------------- | ----- |
+| `WINE_SIMULATE_WRITECOPY`  | `1`   |

 ---

@@ -288,6 +346,7 @@ WINE_SIMULATE_WRITECOPY=1 \
 ### 4. Launch scripts

 `~/.local/bin/battlenet`:
+
 ```bash
 #!/bin/sh
 export WINEPREFIX="$HOME/Games/battlenet-wine-prefix"
@@ -296,6 +355,7 @@ exec wine "$WINEPREFIX/drive_c/Program Files (x86)/Battle.net/Battle.net Launche
 ```

 `~/.local/bin/battlenetkill`:
+
 ```bash
 #!/bin/sh
 export WINEPREFIX="$HOME/Games/battlenet-wine-prefix"
@@ -308,6 +368,55 @@ chmod +x ~/.local/bin/battlenet ~/.local/bin/battlenetkill

 ---

+## Adding ~/.local/bin to PATH
+
+Most Arch shell setups include `~/.local/bin` automatically, but if yours doesn't:
+
+**bash** — add to `~/.bashrc` or `~/.bash_profile`:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+**zsh** — add to `~/.zshrc`:
+
+```zsh
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+**fish** — run once; it persists across sessions:
+
+```fish
+fish_add_path $HOME/.local/bin
+```
+
+---
+
+## Game-specific notes
+
+### World of Warcraft
+
+Runs well out of the box on GE-Proton. A few tuning points:
+
+- **D3D12 vs D3D11:** WoW defaults to D3D12 on recent clients. If you see crashes at launch, switch to D3D11 in the WoW graphics settings or add `PROTON_USE_WINED3D=0` and try D3D11 explicitly.
+- **High CPU usage at login screen:** Known issue with some GE-Proton builds. Pinning a slightly older release (e.g. `GE-Proton9-15`) often resolves it until the next fix lands.
+
+### Overwatch 2
+
+- Uses the **BattlEye** anti-cheat. BattlEye has official Linux support via the runtime bundled with Proton-GE; you do **not** need to disable it.
+- Add `PROTON_ENABLE_NVAPI=1` if you have NVIDIA and see the game refuse to launch with a GPU compatibility error.
+
+### Diablo IV
+
+- Runs well on GE-Proton. Uses **Warden** (no dedicated Linux anti-cheat binary) — no special config needed.
+- If you see corruption in cut-scenes, try `DXVK_ASYNC=1` in your launch script (async shader compilation).
+
+### Hearthstone
+
+Historically the most problematic title on Wine. With umu + protonfixes it works, but the login screen is particularly sensitive to `WINE_SIMULATE_WRITECOPY=1`. Make sure it's set (umu sets it automatically via protonfixes).
+
+---
+
 ## Troubleshooting

 ### "Battle.net Update Agent went to sleep. Attempting to wake it up… BLZBNTBNA00000005"
@@ -316,11 +425,13 @@ 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.

@@ -330,13 +441,33 @@ The most common 2025–2026 failure mode. In order:

 ### 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.
+Wine's native Wayland driver is still rough for the Battle.net launcher in 2026. The fix is to force XWayland explicitly:
+
+```bash
+DISPLAY=:0 SDL_VIDEODRIVER=x11 battlenet
+```
+
+Or add the overrides permanently to your launch script (`~/.local/bin/battlenet`):
+
+```sh
+export DISPLAY="${DISPLAY:-:0}"
+export SDL_VIDEODRIVER=x11
+```
+
+If `DISPLAY=:0` doesn't work, find the correct display number:
+
+```bash
+ls /tmp/.X11-unix/
+```
+
+Each `X<N>` file corresponds to `DISPLAY=:<N>`. Use whichever exists.
+
+As a fallback, log into a plain **X11 session** from your display manager's session picker (SDDM/GDM). Steam/Proton routes through XWayland automatically, which is why Method 2 works without this tweak.

 ### "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
 ```
@@ -344,12 +475,57 @@ 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
 ```

 ---

+## systemd user service (optional)
+
+If you want to start and stop Battle.net with `systemctl` rather than a terminal command, create a user service unit:
+
+`~/.config/systemd/user/battlenet.service`:
+
+```ini
+[Unit]
+Description=Battle.net launcher (umu/Proton)
+After=graphical-session.target
+
+[Service]
+Type=simple
+Environment=DISPLAY=:0
+ExecStart=%h/.local/bin/battlenet
+ExecStop=%h/.local/bin/battlenetkill
+Restart=no
+
+[Install]
+WantedBy=default.target
+```
+
+Enable and control it:
+
+```bash
+systemctl --user daemon-reload
+
+# Start
+systemctl --user start battlenet
+
+# Stop
+systemctl --user stop battlenet
+
+# Start automatically at login
+systemctl --user enable battlenet
+
+# View logs
+journalctl --user -u battlenet -f
+```
+
+> **Note:** The `DISPLAY=:0` line assumes a single-user X11 or XWayland session. If your display number differs (check `ls /tmp/.X11-unix/`), update it. Under a proper XDG session you can also use `%I` socket activation, but for a game launcher `Type=simple` with a fixed display is simpler and more reliable.
+
+---
+
 ## 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.
@@ -369,4 +545,13 @@ Blizzard does not ban for running via Wine/Proton/Linux. Their Warden anti-cheat
 - 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`.
+- Added Wayland/XWayland notes and the Agent-cache wipe fix for `BLZBNTBNA00000005`.
+- Added GPU-specific package table to Prerequisites.
+- Added shell-specific PATH setup instructions (bash/zsh/fish).
+- Fixed desktop entry to use `$HOME` instead of hardcoded username.
+- Added game-specific notes for WoW, Overwatch 2, Diablo IV, and Hearthstone.
+- Added Quick start section with script flags and companion script table.
+- Added explicit XWayland fix (`DISPLAY=:0 SDL_VIDEODRIVER=x11`) to Wayland troubleshooting.
+- Added systemd user service unit for start/stop via `systemctl`.
+- Added `battlenet-update-proton.sh` — GE-Proton version manager.
+- Added `battlenet-diagnose.sh` — setup health checker.