UnheardCity/docs/building.md

Building Unheard City

The build is a PyInstaller one-folder bundle: Python, Qt (incl. Qt Multimedia), libsndfile (libvorbis, FLAC, opus, mpg123), soxr and pedalboard (the effects) 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 (~86 MB zip, ~205 MB unpacked, catalogs included). 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

First built with version 3.4.0 (Debian 13 in a container, Python 3.14.8 built from source because Debian has no 3.14 package): ~124 MB tar.gz, ~330 MB unpacked; the smoke test passes with PATH=/usr/bin:/bin and the GUI starts. 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.