Document haveged entropy fix and in-game-quit workaround

[bl2-split] / README.md

# Borderlands 2 — 2-player split-screen / dual-monitor co-op on Linux

Runs **two local instances** of Borderlands 2 that connect to each other over
Goldberg's emulated Steam LAN, so two people can play co-op on one PC — each with
their own controller, save, and screen. Tested on **Arch + KDE Plasma 6 (Wayland)**.

- **Two monitors:** one instance fullscreen on each (auto-detected).
- **One monitor:** side-by-side split.
- Each Xbox controller drives only its own instance.

> BL2 has no native PC split-screen; this launches two copies networked over LAN.
> Only legitimate because you own the game. No game files or saves are committed here.

![Two Borderlands 2 instances running co-op across two monitors, each on its own main menu in the shared LAN lobby with per-player Xbox controller prompts](sxs.jpg)

## Requirements

- **Borderlands 2 installed via Steam, forced to the Windows build under Proton**
  (see setup step 1). The native Linux (Aspyr) build is supported as a fallback but
  is crash-prone with two instances — Proton is the recommended path.
- Packages: `umu-launcher`, `gamescope` *(optional)*, `qt6-tools` (for `qdbus6`),
  `bubblewrap`, `libarchive` (`bsdtar`), `curl`, `binutils` (`strings`).
  ```
  sudo pacman -S umu-launcher qt6-tools bubblewrap libarchive curl binutils
  ```
- **Recommended:** an entropy daemon so the second instance doesn't stall on
  startup waiting for randomness (see Troubleshooting):
  ```
  sudo pacman -S haveged && sudo systemctl enable --now haveged
  ```
- Two Xbox controllers (any two distinguishable pads).

## Setup

1. **Point Steam at the Windows build.** Steam → *Borderlands 2 → Properties →
   Compatibility →* tick **"Force the use of a specific Steam Play compatibility
   tool"** → pick **Proton Experimental** (or a stable Proton). Steam re-downloads
   the Windows depot. (To use the native Linux build instead, skip this — the script
   auto-detects which is installed.)

2. **Build the two copies:**
   ```
   cd bl2-split
   ./bl2-splitscreen.sh check     # verifies prerequisites; shows detected mode
   ./bl2-splitscreen.sh setup     # downloads Goldberg + builds p1/ and p2/
   ```
   `setup` auto-downloads the Goldberg emulator (it is **not** committed to this
   repo) and builds two symlink-mirror copies of the game with per-player Steam
   identities. First `run` also makes umu download Proton + build each prefix (slow,
   one time).

3. **Play** (turn on both controllers first):
   ```
   ./bl2-splitscreen.sh run
   ```
   With two monitors each game opens fullscreen on its own display; with one, they
   tile side-by-side. In-game: **Player 1** *Play → host over LAN*; **Player 2**
   *Play → Join → pick the LAN game*. `Ctrl-C` kills both.

## Commands

| Command | Does |
|---|---|
| `./bl2-splitscreen.sh fetch` | download the Goldberg emulator into `goldberg/` |
| `./bl2-splitscreen.sh check` | verify prerequisites; print the detected mode |
| `./bl2-splitscreen.sh setup` | fetch Goldberg + build `p1/`, `p2/` |
| `./bl2-splitscreen.sh run`   | launch both instances + place windows |
| `./bl2-splitscreen.sh tile`  | re-place the two windows |
| `./bl2-splitscreen.sh kill`  | terminate all running Borderlands 2 instances |
| `./bl2-splitscreen.sh clean` | kill instances, then remove `p1/`, `p2/` (copies + saves + prefixes) |

Useful env overrides: `MODE=native|proton`, `DISPLAY_MODE=dual|split`,
`ISOLATION=bwrap|sdl`, `SPLASH_WAIT=<secs>`, `STAGGER=<secs>`.

## How it works

| Concern | Solution |
|---|---|
| Two instances at once | Each copy uses **Goldberg** (`steam_api.dll`) instead of real Steam; they connect over emulated LAN |
| Goldberg actually loads | The `.exe` is copied **real** (not symlinked) so Wine loads DLLs from our dir, not the real install's `steam_api.dll` |
| Two different LAN players | Per-copy `force_account_name.txt` + `force_steamid.txt` |
| No startup crash | `steam_interfaces.txt` extracted from the original Steam lib per copy |
| Separate saves | Each instance has its own Proton prefix (`p1/prefix`, `p2/prefix`) |
| Co-op finds each other | Goldberg `custom_broadcasts.txt` → `127.0.0.1` (broadcast doesn't cross the two Proton containers) |
| Skips slow "Creating online session" | Goldberg `configs.main.ini` → `offline=1` |
| Windowed at the right size | `-windowed -ResX -ResY`; **no gamescope** (it hides raw controllers from nested clients) |
| One controller per instance | **bwrap** masks the other pad's `/dev/input` nodes (the Xbox pads are evdev-only, no hidraw) |
| Window placement | KWin script via `qdbus6` — one monitor each (dual) or side-by-side (single) |
| No intro-logo wait | Intro movies disabled in each prefix's `WillowEngine.ini` |
| No 13 GB duplication | `cp -as` symlink-mirror; only `steam_api.dll` + the `.exe` are real copies |

## What's in git (and what isn't)

**Committed** (enough for anyone to reproduce):
```
bl2-splitscreen.sh     the launcher/setup script
README.md              this file
.gitignore
goldberg/.gitkeep      empty dir; setup downloads binaries into it
p1/.gitkeep p2/.gitkeep
```

**Never committed** (`.gitignore`):
- `goldberg/steam_api.dll`, `goldberg/libsteam_api.so` — the Goldberg emulator
  binaries. They implement Steam's proprietary API, so they aren't redistributed
  here; `setup` downloads them from the upstream releases (gbe_fork / Mr_Goldberg).
- `p1/`, `p2/` (except `.gitkeep`) — the game copies, **your save games**, and Wine
  prefixes. Machine-specific and large.
- `*.log`.

So another person clones the repo, forces Proton on their own BL2 in Steam, runs
`./bl2-splitscreen.sh setup`, and everything else is pulled/generated locally.

## Troubleshooting

- **Both pads control both screens / keyboard controls both:** the games read input
  globally. Controllers are isolated by `bwrap` device-masking (default). Keyboard &
  mouse are *not* isolated — use a controller per player; kb/mouse is only for menus.
- **A pad drives the wrong screen or none:** ensure `ISOLATION=bwrap` (default). If
  **Steam is running**, its Steam Input virtual pads can interfere — quit Steam.
- **Stuck on "Creating online session":** should be quick with `offline=1` (set by
  setup). If a co-op *join* ever breaks, remove the offline setting:
  `rm p{1,2}/game/Binaries/Win32/steam_settings/configs.main.ini`
- **They don't see each other on LAN:** Player 1 hosts first (the script staggers
  launches). Discovery uses `custom_broadcasts.txt` (localhost).
- **The 2nd instance takes ages to reach the menu — and speeds up when you jiggle
  the mouse:** classic **entropy starvation** — something in the Wine/Goldberg/crypto
  path blocks on `/dev/random` waiting for randomness, and mouse movement feeds the
  pool. Fix it with an entropy daemon (also in Requirements):
  `sudo pacman -S haveged && sudo systemctl enable --now haveged`.
  The two instances also share a DXVK shader cache (`dxvk-cache/`) so the 2nd reuses
  the 1st's shaders; if still slow, raise the launch gap: `STAGGER=45 ./bl2-splitscreen.sh run`.
- **In-game "Quit Borderlands 2 → Yes" does nothing / hangs:** the game's shutdown
  path stalls under Goldberg (Steam-networking cleanup, worse with offline mode).
  Don't use in-game Quit — close with **`./bl2-splitscreen.sh kill`** or **Ctrl-C**
  in the run terminal (safe: you're at the menu, nothing is saving).
- **Ctrl-C / kill left something running:** `./bl2-splitscreen.sh kill` tears down
  the whole game + Proton/Wine tree.
- **A window won't sit on its monitor:** re-run `./bl2-splitscreen.sh tile`; raise
  `SPLASH_WAIT` if it fires before the game settles.
- **Reset everything:** `./bl2-splitscreen.sh clean` (removes copies + saves; the
  real Steam install is untouched).

## Native (Aspyr Linux) fallback

If Steam has the native Linux build installed, the script auto-detects `native` mode:
it uses the **classic Mr_Goldberg** `.so` (gbe_fork crashes that old binary), runs
inside the Steam scout runtime, and isolates controllers the same way. It works, but
the second instance is prone to crashing — prefer the Proton path.