Asset overrides

Replace any image, audio file, or data table by dropping a file into your mod's assets/ folder.

The basic idea

The loader scans every Mods/<mod>/assets/ at startup and hooks the game's asset-loading pipeline so reads are redirected to your replacement file before they ever touch Game.rgss3a. Original assets are never modified.

Folder layout

Mirror the archive's tree under assets/. The path inside assets/ is what the game uses as the asset's name.

Mods/<your_mod>/
└── assets/
    ├── Graphics/
    │   ├── Faces/<name>.png             replaces a face graphic
    │   ├── Characters/<name>.png        replaces a sprite sheet
    │   ├── Pictures/<name>.png          replaces a CG / event picture
    │   ├── System/<name>.png            replaces system UI (window skin, etc.)
    │   ├── Battlebacks1/<name>.png      battle background floor
    │   ├── Battlebacks2/<name>.png      battle background ceiling
    │   ├── Parallaxes/<name>.png        map parallax
    │   └── Animations/<name>.png        animation cells
    ├── Audio/
    │   ├── BGM/<name>.ogg               music track
    │   ├── BGS/<name>.ogg               background sound
    │   ├── ME/<name>.ogg                music effect (victory, etc.)
    │   └── SE/<name>.ogg                sound effect
    └── Data/
        └── <name>.rvdata2               replaces a database file (advanced)

Finding the original filename

Asset names in BS2 match what's in Game.rgss3a. To browse them:

Run the Asset Extractor - pick your game folder, pick an output folder, click EXTRACT ALL.
Browse the output. The path of any file is exactly the path you'd use in assets/.

Audio files live outside the archive - they're already loose under BLACK SOULS II/Audio/, so you can browse them directly without extracting.

Replacing a face graphic

Suppose you want to replace Alice's face. The original lives at Graphics/Faces/Alice.png inside the archive. Drop your edited PNG at:

Mods/my_mod/assets/Graphics/Faces/Alice.png

Restart the game. Anywhere the game shows Alice's face - menus, dialogue boxes, status windows - your version is shown instead. No Ruby code required.

Replacing audio

Mods/my_mod/assets/Audio/BGM/Theme01.ogg
Mods/my_mod/assets/Audio/SE/Decision1.ogg

Same rule - match the path. Supported formats are whatever the game itself supports (.ogg mostly, sometimes .mp3).

Replacing a data table

You can also override .rvdata2 files. Use the Asset Extractor to dump Data/Items.rvdata2 (or whichever), edit it (RPG Maker VX Ace editor or a tool like rvpacker), then put the modified file at:

Mods/my_mod/assets/Data/Items.rvdata2

For most data tweaks, runtime mutation is easier and safer - see the 03_data_tweak template under Templates.

How it works under the hood

At boot, the loader walks every Mods/<mod>/assets/**/* path and registers each file as an override keyed by its path relative to assets/ (with and without the file extension, since RGSS3 calls Bitmap.new("Graphics/Faces/Alice") without an extension).

The loader then installs three hooks:

Cache.normal_bitmap - the entry point for all graphics. Checks the override map first, falls back to the archive otherwise.
Kernel#load_data - used for .rvdata2 files. Same pattern.
Audio.bgm_play / bgs_play / me_play / se_play - same pattern for audio.

Lookups are O(1) hash hits, so there's no measurable performance impact for unmodded assets. The first read of each modded asset costs whatever the file system + Bitmap.new costs (i.e. essentially the same as reading from the archive).

Naming gotcha: RPG Maker is case-sensitive on some assets and case-insensitive on others. To be safe, match the exact case of the original filename from the archive.

Conflict resolution

If two mods register an override for the same asset path, the one loaded later wins. Mods are loaded in alphabetical order of folder name, so prefix your folder with a number (e.g. 00_my_skin/) to control priority.