diff --git a/README.md b/README.md index e69de29..a742e19 100644 --- a/README.md +++ b/README.md @@ -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 . + +### 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//pfx/` +- **Flatpak Steam:** `~/.var/app/com.valvesoftware.Steam/.local/share/Steam/steamapps/compatdata//pfx/` + +The `` 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//pfx/drive_c/Program Files (x86)/Battle.net/Battle.net Launcher.exe"` +- **Start In:** `"…/compatdata//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//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`. \ No newline at end of file diff --git a/battlenet-umu-setup.sh b/battlenet-umu-setup.sh new file mode 100644 index 0000000..871bcf7 --- /dev/null +++ b/battlenet-umu-setup.sh @@ -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" < "$KILL_SCRIPT" </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" </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" \ No newline at end of file