Installation

Two routes - pre-built executable for end users, build-from-source for developers.

Option A - pre-built executable

Recommended for most users.

Go to the project's GitHub Releases page.
Download BlackSoulsModLoader.exe.
Run it. Windows may flag it as "unknown publisher" - click More info → Run anyway. The exe is unsigned because PyInstaller binaries don't ship with a signing certificate.
In the GUI, click Browse next to Game folder and pick your BLACK SOULS II folder - the one containing Game.exe and Game.rgss3a.
Click Install / Update. The status line should turn green and read archive XXX MB · LOADER INSTALLED · backup: yes.
Close the loader window. Launch the game. You should see a BS_ModLoader MessageBox briefly at startup confirming the loader is running.

What just happened

The loader made an automatic backup of Game.rgss3a at Game.rgss3a.original.bak, then patched the original to inject a tiny Ruby script that scans the new Mods/ folder at startup. Re-running the installer always re-derives from the backup, so it's safe to install over and over.

Option B - build from source

For developers, contributors, or anyone modifying the loader itself.

Requirements

Python 3.8 or newer on PATH
Two pip packages: PyInstaller and PyQt6

Install dependencies (one-time)

pip install PyInstaller PyQt6

Build the executable

cd "Mod Loader/src"
pyinstaller --noconfirm --clean --onefile --windowed \
            --name "BlackSoulsModLoader" \
            --icon "square-image.ico" \
            --add-data "loader.rb;." \
            --add-data "square-image.ico;." \
            mod_loader_gui.py

Output: src/dist/BlackSoulsModLoader.exe. Single-file executable, no install required. loader.rb and the icon are embedded in the exe via the --add-data flags.

A convenience build.bat runs the exact same command - on Windows you can double-click it instead of typing the PyInstaller invocation.

Run from source (no exe build)

If you only want to test changes without packaging:

pip install PyQt6
cd "Mod Loader/src"
python mod_loader_gui.py

Uninstalling

Two equivalent ways:

GUI: launch BlackSoulsModLoader.exe, pick the same game folder, click Uninstall.
CLI: cd "Mod Loader/src" && python uninstall.py

Both restore Game.rgss3a from Game.rgss3a.original.bak. Your BLACK SOULS II/Mods/ folder is preserved - uninstalling only reverts the patch, not your installed mods.

Troubleshooting

The status line says "NOT a valid game folder"

The folder you picked doesn't contain Game.rgss3a. Common cause: you picked the parent folder. Open the folder you selected - if you see Game.exe alongside, you're in the right place. If Game.exe is in a subfolder, pick that subfolder instead.

The game won't start after install

Run the uninstaller to restore the backup. If the game starts again from the backup, the patch was the cause - file a bug report with whatever error message the game showed.

I see no MessageBox at startup, mods don't load

Check %TEMP%/bs_modloader.log and BLACK SOULS II/Mods/_loader.log for entries. If both are empty, the patch may not have taken effect - re-run the installer and try again. If the log says No Mods/ directory found, create BLACK SOULS II/Mods/ manually.