Asset Extractor

A standalone GUI for unpacking and re-packing Game.rgss3a.

The Asset Extractor ships as BlackSoulsAssetExtractor.exe, an independent tool from the Mod Loader. You can use either without the other.

When to use this tool

Browsing original assets - extract the archive once, then browse the output to find the exact filename of any graphic / data file.
Translating - extract .rvdata2 files, edit them with rvpacker or RPG Maker VX Ace, then repack.
Permanent asset replacement - for cases where the Mod Loader's runtime asset overrides aren't enough, or where you want to ship a single replacement archive instead of a mod folder.

For most asset mods, the Mod Loader's runtime overrides are simpler. Drop a PNG into Mods/<your_mod>/assets/Graphics/Faces/ and you're done - no extraction or repacking required. See the Asset overrides page.

Extract

Click Browse next to Game folder and pick your BLACK SOULS II folder.
Click Browse next to Output folder and pick where to dump everything (an empty folder is best - the extractor doesn't clean up between runs).
Click EXTRACT ALL. Wait a few seconds - there are ~2,500 files in the archive.

Output is sorted by the archive's own layout:

<output>/
├── Data/
│   ├── Items.rvdata2
│   ├── Weapons.rvdata2
│   ├── MapInfos.rvdata2
│   ├── Map001.rvdata2
│   ├── Map002.rvdata2
│   └── ...                       (~425 files)
└── Graphics/
    ├── Faces/                    character portraits
    ├── Characters/               sprite sheets
    ├── Pictures/                 CGs, event pictures
    ├── System/                   UI elements (window skin, etc.)
    ├── Battlebacks1/, Battlebacks2/
    ├── Animations/
    ├── Parallaxes/
    ├── Tilesets/
    ├── Titles1/, Titles2/
    └── ...                       (~2166 files total)

The extractor never touches the original archive - it reads, decrypts, and writes to the output folder only. You can safely run it as many times as you like.

Repack

Repack takes a folder of replacement files and produces a new Game.rgss3a with those files swapped in. Every other file in the archive stays exactly as it was.

Edit any extracted file. Keep its path inside your replacement folder identical to its path inside the archive.
Example: if you edited Graphics/Faces/Alice.png from the extract, your replacement folder should contain it at the same relative path.
In the GUI, click Browse next to Replacements folder and pick that folder.
Click Browse next to Output archive and pick a destination filename (e.g. Game.rgss3a.modded). Don't overwrite the original yet - keep your original safe until you've tested the modded one.
Click REPACK.

The log will report how many files were matched (replaced) and how many were unmatched (path didn't correspond to anything in the archive - usually a typo on your end). Files not in your replacement folder pass through unchanged from the original.

To use the modded archive: rename your existing Game.rgss3a to Game.rgss3a.backup, rename the modded one to Game.rgss3a, and launch the game.

If you've already installed the Mod Loader, the modded archive must replace the patched one - and the Mod Loader's automatic backup at Game.rgss3a.original.bak will be from BEFORE your repack. Re-running the Mod Loader installer will re-derive from that backup, undoing your repack. If you want both, use runtime asset overrides instead.

Building the Asset Extractor from source

Same workflow as the Mod Loader.

pip install PyInstaller PyQt6
cd "Asset Extractor/src"
pyinstaller --noconfirm --clean --onefile --windowed \
            --name "BlackSoulsAssetExtractor" \
            asset_extractor_gui.py

Output: src/dist/BlackSoulsAssetExtractor.exe. The exe uses Windows' default icon (no --icon flag).

Run from source (no exe)

pip install PyQt6
cd "Asset Extractor/src"
python asset_extractor_gui.py