vilimpoc.org git repositories - bl2-split/blob - README.md

   1 # Borderlands 2 — 2-player split-screen / dual-monitor co-op on Linux
   2
   3 Runs **two local instances** of Borderlands 2 that connect to each other over
   4 Goldberg's emulated Steam LAN, so two people can play co-op on one PC — each with
   5 their own controller, save, and screen. Tested on **Arch + KDE Plasma 6 (Wayland)**.
   6
   7 - **Two monitors:** one instance fullscreen on each (auto-detected).
   8 - **One monitor:** side-by-side split.
   9 - Each Xbox controller drives only its own instance.
  10
  11 > BL2 has no native PC split-screen; this launches two copies networked over LAN.
  12 > Only legitimate because you own the game. No game files or saves are committed here.
  13
  14 ![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)
  15
  16 ## Requirements
  17
  18 - **Borderlands 2 installed via Steam, forced to the Windows build under Proton**
  19   (see setup step 1). The native Linux (Aspyr) build is supported as a fallback but
  20   is crash-prone with two instances — Proton is the recommended path.
  21 - Packages: `umu-launcher`, `gamescope` *(optional)*, `qt6-tools` (for `qdbus6`),
  22   `bubblewrap`, `libarchive` (`bsdtar`), `curl`, `binutils` (`strings`).
  23   ```
  24   sudo pacman -S umu-launcher qt6-tools bubblewrap libarchive curl binutils
  25   ```
  26 - Two Xbox controllers (any two distinguishable pads).
  27
  28 ## Setup
  29
  30 1. **Point Steam at the Windows build.** Steam → *Borderlands 2 → Properties →
  31    Compatibility →* tick **"Force the use of a specific Steam Play compatibility
  32    tool"** → pick **Proton Experimental** (or a stable Proton). Steam re-downloads
  33    the Windows depot. (To use the native Linux build instead, skip this — the script
  34    auto-detects which is installed.)
  35
  36 2. **Build the two copies:**
  37    ```
  38    cd bl2-split
  39    ./bl2-splitscreen.sh check     # verifies prerequisites; shows detected mode
  40    ./bl2-splitscreen.sh setup     # downloads Goldberg + builds p1/ and p2/
  41    ```
  42    `setup` auto-downloads the Goldberg emulator (it is **not** committed to this
  43    repo) and builds two symlink-mirror copies of the game with per-player Steam
  44    identities. First `run` also makes umu download Proton + build each prefix (slow,
  45    one time).
  46
  47 3. **Play** (turn on both controllers first):
  48    ```
  49    ./bl2-splitscreen.sh run
  50    ```
  51    With two monitors each game opens fullscreen on its own display; with one, they
  52    tile side-by-side. In-game: **Player 1** *Play → host over LAN*; **Player 2**
  53    *Play → Join → pick the LAN game*. `Ctrl-C` kills both.
  54
  55 ## Commands
  56
  57 | Command | Does |
  58 |---|---|
  59 | `./bl2-splitscreen.sh fetch` | download the Goldberg emulator into `goldberg/` |
  60 | `./bl2-splitscreen.sh check` | verify prerequisites; print the detected mode |
  61 | `./bl2-splitscreen.sh setup` | fetch Goldberg + build `p1/`, `p2/` |
  62 | `./bl2-splitscreen.sh run`   | launch both instances + place windows |
  63 | `./bl2-splitscreen.sh tile`  | re-place the two windows |
  64 | `./bl2-splitscreen.sh clean` | remove `p1/`, `p2/` (copies + saves + prefixes) |
  65
  66 Useful env overrides: `MODE=native|proton`, `DISPLAY_MODE=dual|split`,
  67 `ISOLATION=bwrap|sdl`, `SPLASH_WAIT=<secs>`, `STAGGER=<secs>`.
  68
  69 ## How it works
  70
  71 | Concern | Solution |
  72 |---|---|
  73 | Two instances at once | Each copy uses **Goldberg** (`steam_api.dll`) instead of real Steam; they connect over emulated LAN |
  74 | 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` |
  75 | Two different LAN players | Per-copy `force_account_name.txt` + `force_steamid.txt` |
  76 | No startup crash | `steam_interfaces.txt` extracted from the original Steam lib per copy |
  77 | Separate saves | Each instance has its own Proton prefix (`p1/prefix`, `p2/prefix`) |
  78 | Co-op finds each other | Goldberg `custom_broadcasts.txt` → `127.0.0.1` (broadcast doesn't cross the two Proton containers) |
  79 | Skips slow "Creating online session" | Goldberg `configs.main.ini` → `offline=1` |
  80 | Windowed at the right size | `-windowed -ResX -ResY`; **no gamescope** (it hides raw controllers from nested clients) |
  81 | One controller per instance | **bwrap** masks the other pad's `/dev/input` nodes (the Xbox pads are evdev-only, no hidraw) |
  82 | Window placement | KWin script via `qdbus6` — one monitor each (dual) or side-by-side (single) |
  83 | No intro-logo wait | Intro movies disabled in each prefix's `WillowEngine.ini` |
  84 | No 13 GB duplication | `cp -as` symlink-mirror; only `steam_api.dll` + the `.exe` are real copies |
  85
  86 ## What's in git (and what isn't)
  87
  88 **Committed** (enough for anyone to reproduce):
  89 ```
  90 bl2-splitscreen.sh     the launcher/setup script
  91 README.md              this file
  92 .gitignore
  93 goldberg/.gitkeep      empty dir; setup downloads binaries into it
  94 p1/.gitkeep p2/.gitkeep
  95 ```
  96
  97 **Never committed** (`.gitignore`):
  98 - `goldberg/steam_api.dll`, `goldberg/libsteam_api.so` — the Goldberg emulator
  99   binaries. They implement Steam's proprietary API, so they aren't redistributed
 100   here; `setup` downloads them from the upstream releases (gbe_fork / Mr_Goldberg).
 101 - `p1/`, `p2/` (except `.gitkeep`) — the game copies, **your save games**, and Wine
 102   prefixes. Machine-specific and large.
 103 - `*.log`.
 104
 105 So another person clones the repo, forces Proton on their own BL2 in Steam, runs
 106 `./bl2-splitscreen.sh setup`, and everything else is pulled/generated locally.
 107
 108 ## Troubleshooting
 109
 110 - **Both pads control both screens / keyboard controls both:** the games read input
 111   globally. Controllers are isolated by `bwrap` device-masking (default). Keyboard &
 112   mouse are *not* isolated — use a controller per player; kb/mouse is only for menus.
 113 - **A pad drives the wrong screen or none:** ensure `ISOLATION=bwrap` (default). If
 114   **Steam is running**, its Steam Input virtual pads can interfere — quit Steam.
 115 - **Stuck on "Creating online session":** should be quick with `offline=1` (set by
 116   setup). If a co-op *join* ever breaks, remove the offline setting:
 117   `rm p{1,2}/game/Binaries/Win32/steam_settings/configs.main.ini`
 118 - **They don't see each other on LAN:** Player 1 hosts first (the script staggers
 119   launches). Discovery uses `custom_broadcasts.txt` (localhost).
 120 - **A window won't sit on its monitor:** re-run `./bl2-splitscreen.sh tile`; raise
 121   `SPLASH_WAIT` if it fires before the game settles.
 122 - **Reset everything:** `./bl2-splitscreen.sh clean` (removes copies + saves; the
 123   real Steam install is untouched).
 124
 125 ## Native (Aspyr Linux) fallback
 126
 127 If Steam has the native Linux build installed, the script auto-detects `native` mode:
 128 it uses the **classic Mr_Goldberg** `.so` (gbe_fork crashes that old binary), runs
 129 inside the Steam scout runtime, and isolates controllers the same way. It works, but
 130 the second instance is prone to crashing — prefer the Proton path.