Battlenet_UMU/README.md

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

---

## 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://git.aleshym.co/funman300/Battlenet_UMU/raw/branch/main/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:

```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.

**For umu-launcher (Methods 1–4):** Proton-GE runs inside the Steam Runtime container, which bundles most libraries. Only the things the container cannot provide need to be on the host — Vulkan ICDs, audio, and TLS:

```bash
sudo pacman -S --needed \
  gnutls lib32-gnutls \
  mpg123 lib32-mpg123 \
  openal lib32-openal \
  libpulse lib32-libpulse \
  alsa-plugins lib32-alsa-plugins \
  alsa-lib lib32-alsa-lib \
  vulkan-icd-loader lib32-vulkan-icd-loader
```

**For plain wine-staging (Method 5 only):** Wine runs directly on the host, so it needs the full set of libraries:

```bash
sudo pacman -S --needed \
  wine-staging winetricks \
  gnutls lib32-gnutls \
  mpg123 lib32-mpg123 \
  openal lib32-openal \
  libpulse lib32-libpulse \
  alsa-plugins lib32-alsa-plugins \
  alsa-lib lib32-alsa-lib \
  giflib lib32-giflib \
  libpng lib32-libpng \
  libldap lib32-libldap \
  libjpeg-turbo lib32-libjpeg-turbo \
  libxcomposite lib32-libxcomposite \
  libxinerama lib32-libxinerama \
  gtk3 lib32-gtk3 \
  gst-plugins-base-libs \
  vulkan-icd-loader lib32-vulkan-icd-loader
```

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

---

## ⚠️ 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 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
```

### 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`. 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/.local/bin/battlenet
Icon=battlenet
Type=Application
Categories=Game;
StartupWMClass=battle.net.exe
```

### 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/`. With the setup script, use `--proton-version=GE-Proton9-20`.

---

## 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. Get 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:

   ```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.

### 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
```

---

## 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"

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. 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
```

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

---

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