File structure

Directory organization and file locations in BD2 Mod Manager

BD2 Mod Manager uses a specific directory structure to organize application data, user files, mods, and configuration. Understanding this structure helps you locate important files and troubleshoot issues.

Application directories

The application manages several directory paths defined in src/utils/paths.py. The structure differs depending on whether you’re running the .exe or running from source.

App path

The root directory where the application executable is located.

When running .exe:

C:/path/to/BD2ModManager.exe  // The executable location

When running from source:

/path/to/BD2ModManager/  // The project root directory

User data path

Writable location for user-specific data. This is determined by Qt’s QStandardPaths.AppLocalDataLocation.

Windows:

C:/Users/{username}/AppData/Local/Bruhnn/BD2ModManager/

Linux:

~/.local/share/Bruhnn/BD2ModManager/

macOS:

~/Library/Application Support/Bruhnn/BD2ModManager/

This directory contains:

• data/ - User-writable CSV data files
• characters_assets/ - User character assets
• profiles/ - Profile JSON files
• cache/ - Cached temporary data
• tools/ - User tools directory
• manifest.json - Update manifest
• manifest_v2.json - Version 2 update manifest
• mods.json - Mods database

Mods folder structure

BD2 Mod Manager uses a separate mods folder from the BrownDustX mods directory.

Manager’s mods folder

This is where you add your mods by:

• Dragging and dropping them into the application
• Manually moving them into the mods/ folder

{Selected Directory}/mods/
  ├── Character_Name_ModName/
  │   ├── char000101.modfile
  │   └── [other mod files]
  ├── Another_Mod/
  │   ├── cutscene_char000234.modfile
  │   └── [other mod files]
  └── ...

This is NOT the BrownDustX mods directory. It’s a separate folder managed by BD2 Mod Manager.

BrownDustX mods directory

When you sync your mods, the application creates a BD2MM folder inside the BrownDustX mods directory:

{Brown Dust 2 Directory}/BrownDustX/mods/
  └── BD2MM/
      ├── Character_Name_ModName/  // Enabled mod (copied or symlinked)
      ├── Another_Mod/             // Enabled mod (copied or symlinked)
      └── ...

Location example:

F:/Neowiz/Browndust2/Browndust2_10000001/BrownDustX/mods/BD2MM/

Only enabled mods appear in the BD2MM folder after syncing.

Profile storage

Profiles are stored as JSON files in the profiles directory.

Path: {user_data_path}/profiles/

Structure:

profiles/
  ├── default.json          // Default profile (always exists)
  ├── {profile_id}.json     // User-created profiles
  └── ...

Profile file format:

{
  "id": "unique_profile_id",
  "name": "Profile Name",
  "description": "Profile description",
  "mods": {
    "mod_folder_name": true,  // enabled
    "another_mod": false      // disabled
  }
}

Configuration files

Configuration and manifest files are stored in the user data path.

mods.json

Path: {user_data_path}/mods.json

Stores mod metadata including authors and enabled states.

manifest.json and manifest_v2.json

Paths:

• {user_data_path}/manifest.json
• {user_data_path}/manifest_v2.json

Track versions of data files and assets for auto-update functionality.

Default manifest URL:

https://raw.githubusercontent.com/bruhnn/BD2ModManager/refs/heads/main/src/manifest_v2.json

Data files

The application uses CSV files to store character, dating, and NPC data.

Bundled data files

Path: {bundle_path}/src/data/ (or {bundle_path}/data/ when running as .exe)

Files:

• characters.csv - Character definitions with ID, name, costume, and collab status
• datings.csv - Dating scene to character ID mappings
• npcs.csv - NPC definitions with optional character linkages
• authors.csv - Mod author information

User data files

Path: {user_data_path}/data/

Files:

• characters.csv - User-writable copy of character data
• datings.csv - User-writable copy of dating data
• npcs.csv - User-writable copy of NPC data
• authors.csv - User-writable copy of author data

The application copies bundled data to the user directory and updates it when newer versions are available.

Resources

Bundled application resources are stored in the resources directory.

Path: {bundle_path}/src/resources/ (or {bundle_path}/resources/ when running as .exe)

Structure:

resources/
  ├── assets/
  │   └── characters/
  │       ├── 000101.png
  │       ├── 000102.png
  │       └── ...
  ├── fonts/
  │   └── Cinzel/
  │       └── Cinzel-VariableFont_wght.ttf
  ├── icon.ico
  └── [other resources]

User character assets

Path: {user_data_path}/characters_assets/

Allows users to provide their own character asset images that override the bundled ones.

Cache directory

Path: {user_data_path}/cache/

Stores temporary cached data used by the application.

Tools directory

Bundled path: {bundle_path}/tools/

User path: {user_data_path}/tools/

Contains bundled tools and user tools.

Log files

Log files are created in the application root directory.

Path: {app_path}/BD2ModManager-logs.log

Configuration:

• Default log level: DEBUG
• Mode: Overwrite on each run (mode="w")
• Encoding: UTF-8

Command-line options:

# Set log level
BD2ModManager.exe --log-level info

# Filter logs by module
BD2ModManager.exe --log-filter "ModManager"

# Disable logging
BD2ModManager.exe --no-logs

Log files contain detailed information about application operations, errors, and warnings, useful for troubleshooting.

Directory creation

The application automatically creates required directories on startup in paths.py:52-63:

• User data path
• User data subpath (data/)
• User characters assets
• Profiles path
• User cache path
• User tools path

You don’t need to manually create these directories.