https://github.com/ark-repoleved/bdroid_x
PC-free Browndust II Mod manager for Android
https://github.com/ark-repoleved/bdroid_x
2 bd2 brown brown-dust-2 browndust2 dust
Last synced: about 2 months ago
JSON representation
PC-free Browndust II Mod manager for Android
- Host: GitHub
- URL: https://github.com/ark-repoleved/bdroid_x
- Owner: Ark-Repoleved
- Created: 2025-10-01T12:01:06.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-01-17T09:11:50.000Z (5 months ago)
- Last Synced: 2026-01-17T20:20:05.149Z (5 months ago)
- Topics: 2, bd2, brown, brown-dust-2, browndust2, dust
- Language: JavaScript
- Homepage:
- Size: 49.5 MB
- Stars: 34
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
README
[](https://github.com/Ark-Repoleved/BDroid_X/releases) [](https://github.com/Ark-Repoleved/BDroid_X/releases/latest)
[English](./README.md) | [繁體中文](./README.zh-TW.md) | [Usability Survey](https://github.com/Ark-Repoleved/bd2-android-mod-manager/discussions/5) |
# BrownDust 2 Android Mod Manager
**Manage and install your BrownDust 2 mods directly on your phone. No PC required.**
---
## ✨ Key Features
* **📱 PC-Free Operation**: Unpacks, converts textures (ASTC), and repacks mods entirely on your Android device.
* **🧠 Smart Mod Grouping**: Automatically scans your mod folder and groups mods by the game files they modify, preventing conflicts.
* **⚡ Batch Processing**: Select and install multiple mods from different groups in a single operation.
* **🔀 Shizuku Integration**: Move repacked files to the game directory with a single tap.
* **👀 Live Animation Preview**: Long-press any mod to preview its Spine animation before you install it.
* **🔧 Built-in Utilities**: Includes tools to merge texture atlases and unpack game bundles.
---
## 🚀 Getting Started
### Requirements
* Android 8 or higher.
* The latest official version of BrownDust 2 installed.
* [Shizuku](https://shizuku.rikka.app/) for one-tap file transfer to the game directory.
### Installation & Setup
1. **Download the App**: Download the latest `.apk` from the [Releases page](https://github.com/Ark-Repoleved/bd2-android-mod-manager/releases) and install it.
2. **Select Mod Folder**:
* Open the app.
* Tap the **"Select Mod Source Folder"** button.
* Navigate to the folder where you store your mods and tap **"Use this folder"**.
> **💡 Recommendation:** For best results, create a dedicated folder (e.g., `.BD2_Mods`) in your phone's internal storage and place all your mod files there.
---
## 🛠️ How to Use
### 1. Prepare Your Mods (Important!)
For the app to recognize your mods, they must follow a specific structure. Each mod needs its own folder, and the filenames inside must **exactly match** the game's original asset names.
> **⚠️ Warning:** All filenames must be **lowercase** (e.g., `char000104.png`, not `Char000104.png`). Additionally, the image filename referenced inside the `.atlas` file must also be **lowercase**. Otherwise, the game might **crash**.
**Example Folder Structure:**
```
📁 .BD2_Mods/
├── 📁 Lathel_DarkKnight_IDLE/
│ ├── 📄 char000104.skel (or .json for the skeleton)
│ ├── 📄 char000104.atlas (the atlas mapping file)
│ └── 🖼️ char000104.png (the texture image)
│
└── 📁 Another_Mod/
└── ... (other mod files)
```
### 2. Install Mods
1. **Select Mods**: In the app, check the boxes for the mods you want to install.
2. **Start Repacking**: Tap the floating **Repack (✓)** button at the bottom right.
3. **Wait for Processing**: The app will automatically download the necessary original game files and repack your selected mods. A dialog will show the live progress.
4. **Move Files to Game Directory**:
* Once complete, a new **`Shared`** folder containing all your modded game files will be saved to your phone's **`Download`** folder.
* **With Shizuku (Recommended):** If [Shizuku](https://shizuku.rikka.app/) is running, a **"Move to Game Directory"** button will appear. Tap it to automatically move the files — this works even on Android 16+.
* **Without Shizuku:** You can manually move the `Shared` folder into the game's cache directory using a third-party file manager, or copy the provided ADB command.
* The destination path is: `/Android/data/com.neowizgames.game.browndust2/files/UnityCache/`.
---
## 🔧 Other Tools
### Spine Animation Preview
Not sure what a mod looks like in action?
1. Find the mod in the list.
2. **Long-press** on it.
3. A preview screen will open, playing the animation.
### Spine Atlas Merger (Troubleshooting Tool)
**Automated with manual fallback.**
The app automatically detects and merges mismatched textures during repacking, preventing most crashes. However, if a mod still displays incorrectly:
1. On the main screen, find the mod that is causing the crash. Select **only that mod**.
2. Tap the **"Merge Spine"** button.
3. The app will process the files. The originals will be backed up into a new `.old` subfolder.
4. Re-install the newly merged mod. The crash should be resolved.
### Standalone Bundle Unpacker
For users who want to extract original game files:
1. Make sure no mods are selected on the main screen.
2. Tap the floating **unarchive (📤)** icon.
3. Select the `__data` file you want to unpack.
4. The extracted contents will be saved to the **`Download/outputs`** folder.
---
## ❤️ Support This Project
If you find this tool useful and want to support its development, please consider buying me a coffee . Every contribution is greatly appreciated!
---
## ❓ FAQ
* **Q: My mods aren't showing up!**
* **A:** Double-check that you've selected the correct "Mod Source Folder" in the setup. Also, ensure your mods are in unzipped folders and follow the correct [folder structure](#1-prepare-your-mods-important).
* **Q: The game crashes after installing a mod.**
* **A:** This is usually due to one of the following:
1. **Texture Count Mismatch:** The mod's `.png` count differs from the original (the app usually fixes this automatically).
2. **Incorrect Filenames:** All filenames must be **lowercase** (e.g., `char000104.png`). The image reference inside `.atlas` must also be lowercase.
If the issue persists, try using the **'Merge Spine'** feature manually. If it still fails, the mod itself might be corrupted or incompatible.
* **Q: The installation failed. What should I do?_
* **A:** Failures are usually caused by:
1. Poor network connection (failed to download original files).
2. Incorrect mod filenames.
3. An unexpected repacking error.
Check the error message in the dialog for clues.
* **Q: The in-game graphics are broken after installing a mod.**
* **A:** This usually means the mod is incomplete or not compatible with the Android version. A complete character mod requires three files: `.png`, `.atlas`, and either `.skel` or `.json`.
---
## 🙏 Credits
This tool was made possible by these incredible open-source projects:
* **[browndust2-repacker-android](https://codeberg.org/kxdekxde/browndust2-repacker-android)**: For the core repacking and texture compression techniques.
* **[ReDustX](https://github.com/Jelosus2/ReDustX)**: For the `.json`-to-`.skel` conversion logic and CDN download methods.
* **[UnityPy](https://github.com/K0lb3/UnityPy)**: For reading and modifying Unity game assets.
* **[astc-encoder](https://github.com/ARM-software/astc-encoder)**: For the official ASTC texture encoder.
---
## ⭐ Stargazers over time
[](https://starchart.cc/Ark-Repoleved/BDroid_X)