Skip to main content

​
Overview

The BD2 Mod Manager provides comprehensive mod management capabilities, allowing you to easily add, enable, disable, search, filter, and organize your mods. All mods are stored in a staging directory separate from the game’s mod folder, giving you complete control over which mods are active.

​
Mod types

The manager automatically detects and categorizes five types of mods based on their .modfile name:
  • Idle - Character idle animations (char<id>.modfile)
  • Cutscene - Character cutscene animations (cutscene_char<id>.modfile)
  • Scene - Special illustrations and story packs (specialillust<id>.modfile, illust_special<id>.modfile, storypack<id>.modfile)
  • NPC - NPC character mods (npc<id>.modfile, illust_talk<id>.modfile)
  • Dating - Dating scene character mods (illust_dating<id>.modfile)
Each mod type is automatically identified from the modfile pattern in src/models/models.py:50-59.

​
Adding mods

You can add mods to the manager in two ways:

​
Drag and drop

Simply drag mod folders or compressed archives (ZIP, RAR, 7z) directly into the Mod Manager window. The manager will automatically:
  1. Extract compressed files to a temporary location
  2. Locate the .modfile inside
  3. Validate the mod structure
  4. Copy it to your staging mods directory
Drag and drop is not available when using Symlink sync mode due to Windows admin restrictions.

​
Manual installation

Alternatively, you can manually move mod folders into the mods/ directory:
1

Locate your mods folder

Click Open Mods Folder in the mod manager, or navigate to the mods/ directory where the app is installed.
This is not the BrownDustX mods directory. It’s a separate folder managed by BD2 Mod Manager.
2

Copy mod folders

Copy or move your mod folders into this directory. Each mod folder must contain a .modfile.
3

Refresh the mod list

Click the refresh button in the mod manager to detect newly added mods.

​
Enabling and disabling mods

Mods can be enabled or disabled individually or in bulk:
  • Single mod: Toggle the checkbox next to the mod name
  • Multiple mods: Select multiple mods and use the bulk enable/disable actions
  • Profile-based: Each profile saves different enabled mod states (see Profiles)
Changing a mod’s enabled state only takes effect after you sync your mods to the game folder.

​
Searching and filtering

The mod manager provides powerful search and filtering capabilities: Use the search bar to quickly find mods by:
  • Mod name
  • Character name
  • Author name
  • Mod type

​
Filter by type

Filter mods by their type to focus on specific categories:
  • Show only Idle mods
  • Show only Cutscene mods
  • Show only Scene mods
  • Show only NPC mods
  • Show only Dating mods

​
Filter by state

  • Enabled mods only
  • Disabled mods only
  • All mods

​
Recursive search mode

By default, the mod manager searches for mods in the immediate subdirectories of your mods folder (mods/*/*.modfile). You can enable recursive search mode in settings to search through all nested subdirectories (mods/**/*.modfile). This is controlled in src/models/mod_manager_model.py:566-571: 
if self._recursive_mode:
    modfiles = list(self._staging_mods_directory.rglob("*.modfile"))
else:
    modfiles = list(self._staging_mods_directory.glob("*/*.modfile"))
Enable recursive search if you organize your mods into nested folders by character, type, or other categories.

​
Renaming mods

You can rename mod folders directly in the mod manager:
1

Select a mod

Right-click on a mod or select it and choose Rename.
2

Enter new name

Provide a valid folder name. The manager validates the name to ensure it’s compatible with your file system.
3

Automatic updates

The manager automatically updates all profile references to use the new name (see src/models/mod_manager_model.py:389-392).
You cannot rename a mod to a name that already exists. The manager will prevent duplicate mod names.

​
Deleting mods

Remove mods you no longer need:
  • Single deletion: Right-click a mod and select Delete
  • Bulk deletion: Select multiple mods and use the bulk delete action
When you delete a mod:
  1. The mod folder is permanently removed from your staging directory
  2. All profile references are automatically cleaned up
  3. Metadata is removed from the manager’s data file
This is handled in src/models/mod_manager_model.py:252-261: 
for profile in self._profile_manager.get_profiles():
    try:
        if profile.get_mod(mod_name):
            profile.remove_mod(mod_name)
            self._profile_manager.save_profile(profile)
    except Exception as e:
        logger.critical(
            "CRITICAL: Mod '%s' was deleted from disk, but failed to update profile '%s'."
        )

​
Managing mod metadata

​
Author information

You can set the author for each mod:
  • Single mod: Edit the author field in mod details
  • Bulk editing: Select multiple mods and set the author for all at once
Author information is stored in mods_data.json and preserved across sessions.

​
Modfile editing

Advanced users can edit the .modfile JSON directly from the manager:
  1. Select a mod and click Edit Modfile
  2. Modify the JSON configuration
  3. Save changes
The manager validates and safely writes the updated modfile using atomic file operations (see src/models/mod_manager_model.py:704-738).
Editing modfile data incorrectly may cause mods to malfunction. Only modify modfiles if you understand the BrownDustX mod format.

​
Syncing mods

After making any changes to your mods, you must sync to apply them to the game:
1

Make changes

Enable, disable, add, remove, or rename mods as needed.
2

Click sync

Click the Sync button in the mod manager.
3

Choose sync method

The manager uses your configured sync method (Copy or Symlink). See Sync Methods for details.
4

Wait for completion

A progress dialog shows the sync status. The manager creates a BD2MM folder inside the BrownDustX mods directory with all enabled mods.
The sync process compares your staged mods with the game folder and only copies/links what has changed, making subsequent syncs faster.

​
Opening mod folders

Quickly access mod folders in Windows Explorer:
  • Open mods folder: Opens the main staging directory
  • Open mod folder: Opens a specific mod’s folder for manual inspection or editing
This is useful for adding custom files, checking mod contents, or troubleshooting issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us