# Building Unheard City

The build is a PyInstaller **one-folder** bundle: Python, Qt (incl. Qt Multimedia), libsndfile (libvorbis,
FLAC, opus, mpg123) and soxr are all inside; nothing else is installed or needed at runtime. Build on each
target OS (no cross-compiling).

## Windows (x86-64)
```
py -3.14 -m venv .venv            (Python 3.10-3.14)
.venv\Scripts\python -m pip install -e .[app,dev]
.venv\Scripts\python -m pytest -q
.venv\Scripts\python tools\build_app.py
```
That one command does everything, offline. If `app/assets/` (committed icon and wallpaper) is missing, it is
made from `bac_logo_full.png` and `wallpaper.jpg` in `Downloads\Arkham City` (or `--art FOLDER`); without those
images the build still works, with a plain icon and no wallpaper.
Output: `dist\UnheardCity\UnheardCity.exe` and `dist\UnheardCity-<ver>-windows-amd64.zip`
(~78 MB zip, ~190 MB unpacked). The build also writes `THIRD_PARTY_LICENSES.txt` (license texts come from the
wheels and from `tools/licenses/`).

**Installer.** On Windows the folder (and zip) also contains `Install.cmd`, `install.ps1` and `uninstall.ps1`
(sources in `tools/installer/`, version filled in by the build). It is a plain PowerShell installer, so no
installer tool is needed to build it: per-user install to `%LOCALAPPDATA%\Programs\UnheardCity`, Start menu and
optional desktop shortcut, an uninstall entry in Settings > Apps (`HKCU`), upgrade in place. User data in
`%APPDATA%\UnheardCity` is kept on uninstall unless the user chooses otherwise. Unattended:
`install.ps1 -Quiet -Desktop no [-Target DIR]`, `uninstall.ps1 -Quiet`.

Verify the bundle is self-contained (PATH stripped to Windows folders):
```
set PATH=C:\Windows\System32;C:\Windows
dist\UnheardCity\UnheardCity.exe --smoke-test --report smoke.txt    & type smoke.txt
dist\UnheardCity\UnheardCity.exe --quit-after 8 --screenshot shot.png
```

## Linux (x86-64)
Use the oldest distribution you want to support (glibc compatibility), e.g. Ubuntu 22.04:
```
sudo apt install python3 python3-venv libxcb-cursor0 libxkbcommon-x11-0 libegl1 libpulse0
python3 -m venv .venv && . .venv/bin/activate
pip install -e .[app,dev]
QT_QPA_PLATFORM=offscreen pytest -q
python tools/build_app.py          # -> dist/UnheardCity-<ver>-linux-x86_64.tar.gz
QT_QPA_PLATFORM=offscreen dist/UnheardCity/UnheardCity --smoke-test --game /path/to/game
```
Notes:
- The `soundfile` and `soxr` wheels for manylinux bundle libsndfile/libsoxr; the PySide6 wheels bundle Qt and
  Qt Multimedia's FFmpeg backend (PulseAudio/PipeWire output). The target desktop only needs the usual X11/
  Wayland and PulseAudio/PipeWire client libraries that every desktop distribution has.
- Game folders under Proton are found automatically in `~/.steam/steam`, `~/.local/share/Steam`, Flatpak
  (`~/.var/app/com.valvesoftware.Steam/...`) and Snap Steam libraries, including extra libraries from
  `libraryfolders.vdf`. The game language is read from the Proton prefix
  (`steamapps/compatdata/200260/pfx/drive_c/users/steamuser/Documents/WB Games/...`).
- The in-game test harness (`ackit verify --ingame`) is Windows-only; everything else is portable.