# <img src="media/Textures/logo.png" width="25" height="25"> <span style="color:#05dffa">B</span><span style="color:#05dffa">L</span><span style="color:#05dffa">U</span> <span style="color:#fff">|</span> <span style="color:#05dffa">B</span><span style="color:#fff">etter </span><span style="color:#05dffa">L</span><span style="color:#fff">evel-</span><span style="color:#05dffa">U</span><span style="color:#fff">p</span><span style="color:#05dffa">!</span>
## <img src="media/Textures/logo.png" height="20" alt="BLU logo"> <span style="color:#8B1538">R</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span> <span style="color:#4ecdc4">Mods</span> <span style="color:#3598db">-</span> [<span style="color:#8B1538">R</span><span style="color:#7598b6">ealm</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span>](https://realmgx.com) <span style="color:#05dffa">Community Project</span>

<div align="center">

<img src="media/Textures/logo.png" alt="BLU Logo" width="128" height="128">

[![BLU](https://img.shields.io/badge/BLU-Better%20Level%20Up!-05dffa?style=for-the-badge&logo=github&logoColor=white)](https://github.com/donniedice/BLU)
[![RGX Mods](https://img.shields.io/badge/RGX-Mods%20Collection-8B1538?style=for-the-badge&logo=github&logoColor=white)](https://discord.gg/N7kdKAHVVF)

### <span style="color:#05dffa">🌟 Join the </span> <span style="color:#8B1538">R</span><span style="color:#7598b6">ealm</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span> <span style="color:#4ecdc4">Community</span> <span style="color:#3598db">-</span> <span style="color:#8B1538">G</span><span style="color:#7598b6">amers e</span><span style="color:#8B1538">X</span><span style="color:#7598b6">treme!</span> <span style="color:#05dffa">🌟</span>
[![Discord](https://img.shields.io/discord/N7kdKAHVVF?color=7289da&label=Join%20Our%20Discord&logo=discord&logoColor=white&style=for-the-badge)](https://discord.gg/N7kdKAHVVF)

### <span style="color:#05dffa">🎵 </span> <span style="color:#e67e23">*Experience level-up sounds from your favorite games in WoW!*</span> <span style="color:#05dffa">🎵</span>

**<span style="color:#05dffa">B</span><span style="color:#05dffa">L</span><span style="color:#05dffa">U</span> <span style="color:#e67e23">is a professional</span> <span style="color:#06c">World of Warcraft</span> <span style="color:#e67e23">addon that replaces default sounds with iconic audio from 50+ games, with extensive customization options.</span>**

**<span style="color:#05dffa">🎯 </span> <span style="color:#e67e23">Connect with fellow gamers, get support, and be part of the</span> <span style="color:#8B1538">R</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span> <span style="color:#4ecdc4">Mods</span> <span style="color:#e67e23">family!</span>**

---

<!-- GitHub Stats & Badges -->
[![GitHub release](https://img.shields.io/github/v/release/donniedice/BLU?style=for-the-badge&logo=github&color=success)](https://github.com/donniedice/BLU/releases)
[![GitHub stars](https://img.shields.io/github/stars/donniedice/BLU?style=for-the-badge&logo=github&color=yellow)](https://github.com/donniedice/BLU/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/donniedice/BLU?style=for-the-badge&logo=github&color=blue)](https://github.com/donniedice/BLU/network/members)
[![GitHub issues](https://img.shields.io/github/issues/donniedice/BLU?style=for-the-badge&logo=github&color=red)](https://github.com/donniedice/BLU/issues)
[![GitHub license](https://img.shields.io/github/license/donniedice/BLU?style=for-the-badge&logo=github&color=lightgrey)](https://github.com/donniedice/BLU/blob/main/LICENSE)

[![GitHub last commit](https://img.shields.io/github/last-commit/donniedice/BLU?style=flat-square&logo=github)](https://github.com/donniedice/BLU/commits/main)
[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/donniedice/BLU?style=flat-square&logo=github)](https://github.com/donniedice/BLU/graphs/contributors)
[![GitHub repo size](https://img.shields.io/github/repo-size/donniedice/BLU?style=flat-square&logo=github)](https://github.com/donniedice/BLU)

<!-- Platform Badges -->
[![CurseForge](https://img.shields.io/badge/CurseForge-Downloads-orange?style=flat-square&logo=curseforge)](https://www.curseforge.com/wow/addons/blu-better-level-up)
[![Wago](https://img.shields.io/badge/Wago.io-Downloads-purple?style=flat-square&logo=wago)](https://addons.wago.io/addons/blu)
[![WoWInterface](https://img.shields.io/badge/WoWInterface-Downloads-blue?style=flat-square&logo=worldofwarcraft)](https://www.wowinterface.com/downloads/info26465-BLU-BetterLevelUp.html)

<!-- WoW Compatibility -->
[![WoW Retail](https://img.shields.io/badge/WoW-Retail%20Midnight-05dffa?style=flat-square&logo=worldofwarcraft)](https://worldofwarcraft.com)
[![Version](https://img.shields.io/badge/Version-v6.5.0-blue?style=flat-square)](https://github.com/donniedice/BLU/releases)

[Features](#features) • [Quick Start](#quick-start) • [Commands](#command-reference) • [Compatibility](#compatibility) • [Installation](#installation) • [Support](#support)

</div>

---

## <span style="color:#05dffa">🌟 Join the </span> <span style="color:#8B1538">R</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span> <span style="color:#4ecdc4">Mods Community!</span>

<div align="center">

### <span style="color:#b96ad9">💬 </span> <span style="color:#8B1538">R</span><span style="color:#7598b6">ealm</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span> <span style="color:#05dffa">Discord</span> <span style="color:#3598db">-</span> <span style="color:#2dc26b">Your Gaming Home!</span>

[![Join Discord](https://img.shields.io/badge/Join%20Our%20Discord-RealmGX%20Community-7289da?style=for-the-badge&logo=discord&logoColor=white&labelColor=5865F2)](https://discord.gg/N7kdKAHVVF)

**<span style="color:#05dffa">🎮 </span> [<span style="color:#8B1538">R</span><span style="color:#7598b6">ealm </span> <span style="color:#8B1538">G</span><span style="color:#7598b6">amers e</span><span style="color:#8B1538">X</span><span style="color:#7598b6">treme</span>](https://realmgx.com) <span style="color:#3598db">-</span> <span style="color:#4ecdc4">Where WoW Enthusiasts Unite!</span>**

</div>

**<span style="color:#e67e23">✨ What awaits you in our Discord:</span>**
- <span style="color:#2dc26b">🛠️ **Instant addon support**</span> <span style="color:#e67e23">from the</span> <span style="color:#8B1538">R</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span> <span style="color:#4ecdc4">Mods</span> <span style="color:#e67e23">team</span>
- <span style="color:#ff6b6b">🎯 **Feature requests**</span> <span style="color:#e67e23">and direct dev communication</span>
- <span style="color:#b96ad9">🚀 **Beta testing**</span> <span style="color:#e67e23">opportunities for new releases</span>
- <span style="color:#4ecdc4">🤝 **Community of WoW players**</span> <span style="color:#e67e23">sharing tips and experiences</span>
- <span style="color:#05dffa">📢 **First to know**</span> <span style="color:#e67e23">about new</span> <span style="color:#8B1538">R</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span> <span style="color:#4ecdc4">Mods</span> <span style="color:#e67e23">releases</span>
- <span style="color:#e67e23">🎉 **Events, giveaways**, and community activities</span>

<div align="center">

<img src="media/Textures/logo.png" alt="BLU Logo" width="100">

**<span style="color:#ff6b6b">⚠️ WARNING:</span>** <span style="color:#e67e23">May cause excessive nostalgia for your favorite games.</span>

**<span style="color:#2dc26b">The Kiwi Says:</span>** <span style="color:#b96ad9">"Bwwiiiee."</span>

</div>

---

<a id="support"></a>
## <span style="color:#05dffa">💖 Support </span> <span style="color:#8B1538">R</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span> <span style="color:#4ecdc4">Mods</span>

<div align="center">

**<span style="color:#e67e23">Your support helps keep</span> <span style="color:#8B1538">R</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span> <span style="color:#4ecdc4">Mods</span> <span style="color:#e67e23">alive and constantly improving!</span>**

| | |
|---|---|
| [![Donate](https://img.shields.io/badge/Donate-CashApp-00C853?style=for-the-badge&logo=cash-app&logoColor=white)](https://bit.ly/3fyxxSU) | [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Support-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/donniedice) |
| [![GitHub Sponsor](https://img.shields.io/badge/Sponsor-GitHub-ff69b4?style=for-the-badge&logo=github-sponsors&logoColor=white)](https://github.com/sponsors/donniedice) | [![Star](https://img.shields.io/badge/⭐-Star%20this%20repository-yellow?style=for-the-badge&logo=github)](https://github.com/donniedice/BLU) |

_<span style="color:#e67e23">Every coffee helps fund new features and sound additions!</span>_

</div>

---

## <span style="color:#05dffa">🎯 What is BLU?</span>

**<span style="color:#05dffa">B</span><span style="color:#05dffa">L</span><span style="color:#05dffa">U</span> <span style="color:#fff">|</span> <span style="color:#05dffa">B</span><span style="color:#fff">etter </span><span style="color:#05dffa">L</span><span style="color:#fff">evel-</span><span style="color:#05dffa">U</span><span style="color:#fff">p!</span>** <span style="color:#e67e23">transforms the repetitive sounds in</span> <span style="color:#06c">World of Warcraft</span> <span style="color:#e67e23">by letting you hear iconic sounds from your favorite games when you level up, complete activities, gain reputation, or achieve milestones. With support for over 50 games and extensive customization options, BLU makes every achievement feel special.</span>

### <span style="color:#05dffa">🔥 Why Choose BLU?</span>
- **<span style="color:#2dc26b">🎮 50+ Games:</span>** <span style="color:#e67e23">Iconic sounds from Final Fantasy, Zelda, Mario, Skyrim, and many more</span>
- **<span style="color:#05dffa">🌟 Sound Pack API:</span>** <span style="color:#e67e23">Addon devs can build BLU-compatible sound packs with 3-tier volume variants and register them directly with BLU</span>
- **<span style="color:#b96ad9">🛠️ Modular:</span>** <span style="color:#e67e23">Only load the feature modules you actually use</span>
- **<span style="color:#4ecdc4">🎯 No Dependencies:</span>** <span style="color:#e67e23">Auto-discovers sounds from other addons — no libraries required</span>
- **<span style="color:#ff6b6b">💬 Active Support:</span>** <span style="color:#e67e23">Join our Discord for instant help!</span>

**<span style="color:#e67e23">Note</span><span style="color:#3598db">:</span>** <span style="color:#e67e23">For Classic WoW support, use</span> [<span style="color:#05dffa">BLU Classic</span>](https://github.com/donniedice/BLU_Classic)<span style="color:#e67e23">.</span>

---

<a id="features"></a>
## <span style="color:#05dffa">✨ Features</span>

<div align="center">

| Feature | Description |
|---------|-------------|
| 🎵 **50+ Game Sounds** | Choose from iconic sounds from games like Final Fantasy, Zelda, Mario, and more |
| 🏆 **Achievement Earned** | Play a sound when you earn an Achievement |
| 📊 **Achievement Progress** | Play a sound when you complete a criteria step toward an Achievement |
| 🐾 **Battle-Pet Level-Up** | Play a sound when a Battle-Pet levels up |
| 🥚 **Battle-Pet Captured** | Play a sound when you capture a Battle-Pet |
| ⛏️ **Delve Companion Level-Up** | Play a sound when your Delve Companion levels up |
| 💀 **Delve Life Lost** | Play a sound when you lose a life inside a Delve |
| ❤️ **Delve Life Gained** | Play a sound when you gain a life inside a Delve |
| ⚔️ **Honor Rank Up** | Play a sound when you gain an Honor Rank |
| 🏠 **Housing XP Gained** | Play a sound when your house gains favor (XP) |
| 🏠 **Housing Level-Up** | Play a sound when your house levels up |
| 🏠 **Housing Rewards Received** | Play a sound when you receive housing level rewards |
| 🏠 **Housing Decor Collected** | Play a sound when you collect a new Decor item |
| 📈 **Character Level-Up** | Play a sound when your character levels up |
| 📋 **Quest Accepted** | Play a sound when you accept a quest |
| 📋 **Quest Turned In** | Play a sound when you turn in a quest |
| 📋 **Quest Complete** | Play a sound when you reach a quest giver with a completed quest |
| 📋 **Quest Objective Progress** | Play a sound when a tracked quest objective advances |
| 🌟 **Renown Rank Up** | Play a sound when you gain a Renown rank with a major faction |
| 👥 **Reputation Rank Up** | Play a sound when your standing with a faction increases |
| 🏪 **Trading Post Activity** | Play a sound when you complete a Trading Post activity or purchase |
| 🔇 **Granular Default Sound Muting** | Selectively mutes WoW's built-in sounds per-event so you never hear both at once |
| 🔊 **Volume Control** | Per-event volume adjustment |
| 📦 **Sound Pack Support** | Auto-discovers sounds from other addons — no dependencies required |
| 🗂️ **User Custom Sounds** | Add your own `.ogg`/`.mp3`/`.wav` files from the Sounds tab or with `/blu addcustom` |
| 🔌 **Third-Party API** | Addon devs can register BLU-compatible packs via `BLU:RegisterSoundPack()` or bridge simple single-file packs via `BLU:RegisterExternalSoundPack()` |
| ⚙️ **Modular System** | Only load the features you need |
| 💾 **Profile Support** | Save different configurations |
| 🎨 **Modern UI** | Clean tabbed interface with inline sound previews |
| 🔧 **Debug Mode** | Built-in debugging for troubleshooting |

</div>

---

## <span style="color:#05dffa">🎵 Available Game Sounds</span>

<div align="center">

### <span style="color:#05dffa">🎮 50+ Games Available!</span>

| | | | |
|---|---|---|---|
| Altered Beast | Fly For Fun | Old School Runescape |
| Assassin's Creed | Fortnite | Palworld |
| Castlevania | GTA - San Andreas | Path of Exile |
| Diablo 2 | Kingdom Hearts 3 | Pokemon |
| Dragon Quest | Kirby | Ragnarok Online |
| DotA 2 | League of Legends | Shining Force 2 |
| Elden Ring | Legend of Zelda | Shining Force 3 |
| EverQuest | Maplestory | Skyrim |
| Fallout - New Vegas | Metal Gear Solid 5 | Sonic the Hedgehog |
| Fallout 3 | Minecraft | Spyro The Dragon |
| Final Fantasy | Modern Warfare 2 | Super Mario Bros 3 |
| Fire Emblem | Morrowind | Warcraft 3 |
| Fire Emblem Awakening | | The Witcher 3 |

_`Note`: Each game includes Low, Medium, and High volume variants for all sound types._

</div>

### <span style="color:#05dffa">🎯 Special Sound Collections</span>
- **Elden Ring**: 6 unique variations
- **Shining Force 3**: 11 different battle themes
- **Warcraft 3**: Multiple unit acknowledgment sounds
- **The Witcher 3**: Quest completion variations

---

## <span style="color:#05dffa">🎮 Sound Events</span>

### <span style="color:#4ecdc4">Supported Events:</span>

**Achievements**
- **<span style="color:#2dc26b">Achievement Earned</span>:** Play a sound when you earn an Achievement
- **<span style="color:#2dc26b">Achievement Progress</span>:** Play a sound when you complete a criteria step toward an Achievement

**Battle-Pets**
- **<span style="color:#ff69b4">Battle-Pet Level-Up</span>:** Play a sound when a Battle-Pet levels up
- **<span style="color:#ff69b4">Battle-Pet Captured</span>:** Play a sound when you capture a Battle-Pet

**Delves**
- **<span style="color:#b96ad9">Delve Companion Level-Up</span>:** Play a sound when your Delve Companion levels up
- **<span style="color:#b96ad9">Delve Life Lost</span>:** Play a sound when you lose a life inside a Delve
- **<span style="color:#b96ad9">Delve Life Gained</span>:** Play a sound when you gain a life inside a Delve

**Honor**
- **<span style="color:#ff6b6b">Honor Rank Up</span>:** Play a sound when you gain an Honor Rank

**Housing**
- **<span style="color:#4a90e2">Housing XP Gained</span>:** Play a sound when your house gains favor (XP)
- **<span style="color:#4a90e2">Housing Level-Up</span>:** Play a sound when your house levels up
- **<span style="color:#4a90e2">Housing Rewards Received</span>:** Play a sound when you receive housing level rewards
- **<span style="color:#4a90e2">Housing Decor Collected</span>:** Play a sound when you collect a new Decor item

**Level-Up**
- **<span style="color:#ffe568">Character Level-Up</span>:** Play a sound when your character levels up

**Quests**
- **<span style="color:#ffe568">Quest Accepted</span>:** Play a sound when you accept a quest
- **<span style="color:#ffe568">Quest Turned In</span>:** Play a sound when you turn in a quest
- **<span style="color:#ffe568">Quest Complete</span>:** Play a sound when you reach a quest giver with a completed quest
- **<span style="color:#ffe568">Quest Objective Progress</span>:** Play a sound when a tracked quest objective advances

**Reputation**
- **<span style="color:#4ecdc4">Renown Rank Up</span>:** Play a sound when you gain a Renown rank with a major faction
- **<span style="color:#4ecdc4">Reputation Rank Up</span>:** Play a sound when your standing with a faction increases

**Trading Post**
- **<span style="color:#ff6b6b">Trading Post Activity</span>:** Play a sound when you complete a Trading Post activity or make a purchase

### <span style="color:#4ecdc4">Sound System:</span>
**<span style="color:#05dffa">BLU uses a 3-tier sound system:</span>**

1. **<span style="color:#2dc26b">Default WoW Sounds</span><span style="color:#3598db">:</span>** <span style="color:#e67e23">Original game sounds (no volume control)</span>
2. **<span style="color:#05dffa">BLU Internal Sounds</span><span style="color:#3598db">:</span>** <span style="color:#e67e23">Custom sounds with 3 volume variants — High, Medium (default), Low</span>
3. **<span style="color:#b96ad9">External Sound Packs</span><span style="color:#3598db">:</span>** <span style="color:#e67e23">Auto-discovered from other loaded addons at startup through BLU's native bridge/discovery system. Devs can register full BLU-compatible packs via `BLU:RegisterSoundPack()` or simple bridge packs via `BLU:RegisterExternalSoundPack()`</span>

### <span style="color:#4ecdc4">Sound Pack API (for addon developers):</span>
<span style="color:#e67e23">For clear instructions on both supported pack types â€” simple single-file third-party packs and full BLU-compatible `_low` / `_med` / `_high` packs â€” see the</span> [<span style="color:#05dffa">Sounds Guidelines wiki</span>](https://github.com/DonnieDice/BLU/wiki/Sounds-Guidelines)<span style="color:#e67e23">.</span>

```lua
-- Full BLU-compatible pack with low / medium / high variants
BLU:RegisterSoundPack("my_pack", "My Pack", {
    my_pack_victory = {
        name = "Victory",
        file = "Interface\\AddOns\\MyPack\\media\\sounds\\victory_med.ogg",
        category = "all",
        source = "BLU",
    },
})
```

<span style="color:#e67e23">The wiki covers both supported approaches: `BLU:RegisterExternalSoundPack()` for simple single-file third-party packs and `BLU:RegisterSoundPack()` for full BLU-compatible 3-volume packs.</span>

---

<a id="quick-start"></a>
## <span style="color:#05dffa">🚀 Quick Start</span>

1. **<span style="color:#2dc26b">Install</span>** <span style="color:#05dffa">B</span><span style="color:#05dffa">L</span><span style="color:#05dffa">U</span> <span style="color:#e67e23">from your preferred platform</span>
2. **<span style="color:#4ecdc4">Launch</span>** <span style="color:#06c">World of Warcraft</span>
3. **<span style="color:#b96ad9">Type</span>** `/blu` <span style="color:#e67e23">to open the options panel</span>
4. **<span style="color:#ff6b6b">Choose</span>** <span style="color:#e67e23">your favorite sounds for each event</span>
5. **<span style="color:#05dffa">Enjoy</span>** <span style="color:#e67e23">your personalized WoW experience!</span>

---

<a id="command-reference"></a>
## <span style="color:#05dffa">📋 Command Reference</span>

<span style="color:#e67e23">Use</span> <span style="color:#2dc26b">`/blu`</span> <span style="color:#e67e23">followed by</span><span style="color:#3598db">:</span>

<div align="center">

| Command | Description |
|---------|-------------|
| `/blu` | Open the options panel |
| `/blu help` | Display help information |
| `/blu debug` | Toggle debug mode on/off |
| `/blu status` | Show addon status |
| `/blu enable` | Enable addon |
| `/blu disable` | Disable addon |
| `/blu refresh` | Rebuild external and user custom sound pack registry |
| `/blu rescan` | Rescan for newly registered media |
| `/blu addcustom myfile` | Tries common AddOns folders and adds the first matching `.ogg`/`.mp3`/`.wav` |
| `/blu removecustom path` | Removes a previously added custom sound |

</div>

---

<a id="compatibility"></a>
## <span style="color:#05dffa">📋 Compatibility</span>

<div align="center">

### <span style="color:#05dffa">🌍 Supported WoW Versions</span>

| WoW Version | Interface | Status |
|-------------|-----------|--------|
| **Midnight (Retail)** | `120001` | ✅ Fully Supported |

**<span style="color:#e67e23">Note</span><span style="color:#3598db">:</span>** <span style="color:#e67e23">For Classic support, use</span> [<span style="color:#05dffa">BLU Classic</span>](https://github.com/donniedice/BLU_Classic)<span style="color:#e67e23">.</span>

</div>

---

<a id="installation"></a>
## <span style="color:#05dffa">📥 Installation</span>

1. **<span style="color:#2dc26b">Download</span>** <span style="color:#e67e23">from your preferred platform</span><span style="color:#3598db">:</span>
   - [<span style="color:#ff6b6b">CurseForge</span>](https://www.curseforge.com/wow/addons/blu-better-level-up)
   - [<span style="color:#b96ad9">Wago.io</span>](https://addons.wago.io/addons/blu)
   - [<span style="color:#4ecdc4">WoWInterface</span>](https://www.wowinterface.com/downloads/info26465-BLU-BetterLevelUp.html)
   - [<span style="color:#24292e">GitHub</span>](https://github.com/donniedice/BLU/releases)

2. **<span style="color:#4ecdc4">Extract</span>** <span style="color:#e67e23">to your</span> <span style="color:#06c">WoW</span> <span style="color:#e67e23">AddOns directory</span><span style="color:#3598db">:</span>
   - <span style="color:#e67e23">**Retail**: `World of Warcraft/_retail_/Interface/AddOns`</span>

3. **<span style="color:#b96ad9">Restart</span>** <span style="color:#06c">WoW</span> <span style="color:#e67e23">and enable in AddOns menu</span>

---

## <span style="color:#05dffa">🆕 What's New in v6.5.0</span>

<span style="color:#05dffa">🎉 Click to see the latest updates!</span>

### <span style="color:#4ecdc4">🆕 Latest Updates</span>
- <span style="color:#2dc26b">✅ **Real Combat page added**</span> <span style="color:#e67e23">— Combat now has a proper options panel with the same header toggle style used by the other modules</span>
- <span style="color:#05dffa">✅ **Compact 8-slot combat paging layout**</span> <span style="color:#e67e23">— the new Combat UI can display 8 trigger cards per page in a 2-column layout</span>
- <span style="color:#ff6b6b">✅ **Nested sound selection in combat rows**</span> <span style="color:#e67e23">— Combat trigger dropdowns now use the same grouped BLU sound menu structure as the event panels</span>
- <span style="color:#4ecdc4">✅ **Combat cue placeholders are now real UI rows**</span> <span style="color:#e67e23">— `Combat Start`, `Combat End`, and `Combat Music Track` now exist as functional visual settings for ongoing module work</span>


---

## <span style="color:#05dffa">🛠️ Configuration Tips</span>

<table width="100%">
<tr>
<td width="50%" valign="top">

### <span style="color:#4ecdc4">Recommended Settings:</span>
- **<span style="color:#2dc26b">Level-Up</span><span style="color:#3598db">:</span>** <span style="color:#e67e23">Final Fantasy, Pokemon, or Zelda for nostalgic feels</span>
- **<span style="color:#05dffa">Achievements</span><span style="color:#3598db">:</span>** <span style="color:#e67e23">Elden Ring for epic moments</span>
- **<span style="color:#b96ad9">Quests</span><span style="color:#3598db">:</span>** <span style="color:#e67e23">Skyrim or Witcher 3 for immersive RPG experience</span>
- **<span style="color:#ff6b6b">Reputation</span><span style="color:#3598db">:</span>** <span style="color:#e67e23">Warcraft 3 sounds to stay in the Warcraft universe</span>

</td>
<td width="50%" valign="top">

### <span style="color:#4ecdc4">Performance:</span>
- <span style="color:#e67e23">Use "Low" volume variants if you experience any audio delays</span>
- <span style="color:#e67e23">Debug mode can help identify issues with sound playback</span>
- <span style="color:#e67e23">All sounds are optimized `.ogg` files for minimal impact</span>

</td>
</tr>
</table>

---

## <span style="color:#05dffa">🐛 Known Issues</span>

- <span style="color:#e67e23">Double quest accept sound in Classic is a Blizzard bug, not BLU-related</span>
- <span style="color:#e67e23">Some sounds may have slight delays on first play (cached after first use)</span>

---

## <span style="color:#05dffa">🔧 Troubleshooting</span>

**<span style="color:#ff6b6b">No sound playing?</span>**
- <span style="color:#e67e23">Check that your in-game Master volume is not muted</span>

**<span style="color:#ff6b6b">Sound pack not showing up?</span>**
- <span style="color:#e67e23">Run</span> `/blu rescan` <span style="color:#e67e23">to re-discover newly registered media</span>
- <span style="color:#e67e23">Run</span> `/blu refresh` <span style="color:#e67e23">to rebuild the external and user custom sound pack registry</span>
- <span style="color:#e67e23">If you're building your own pack or adding custom files, follow the</span> [<span style="color:#05dffa">Sounds Guidelines wiki</span>](https://github.com/DonnieDice/BLU/wiki/Sounds-Guidelines) <span style="color:#e67e23">for the current folder paths and registration examples</span>

**<span style="color:#ff6b6b">Still having trouble?</span>**
- <span style="color:#e67e23">Join our</span> [<span style="color:#7289da">Discord</span>](https://discord.gg/N7kdKAHVVF) <span style="color:#e67e23">for instant support</span>
- <span style="color:#e67e23">Open a</span> [<span style="color:#ff6b6b">GitHub Issue</span>](https://github.com/donniedice/BLU/issues)

---

## <span style="color:#05dffa">🤝 Contributing</span>

<span style="color:#e67e23">Contributions are welcome! Feel free to</span><span style="color:#3598db">:</span>
- <span style="color:#2dc26b">🐛 **Report bugs**</span> <span style="color:#e67e23">via</span> [<span style="color:#b96ad9">GitHub Issues</span>](https://github.com/donniedice/BLU/issues)
- <span style="color:#ff6b6b">💡 **Suggest features**</span> <span style="color:#e67e23">in our</span> [<span style="color:#7289da">Discord</span>](https://discord.gg/N7kdKAHVVF)
- <span style="color:#4ecdc4">🌍 **Help with translations**</span> <span style="color:#e67e23">for global players</span>
- <span style="color:#05dffa">🎵 **Suggest new game sounds**</span> <span style="color:#e67e23">to add to the library</span>
- <span style="color:#2dc26b">⭐ **Star the repository**</span> <span style="color:#e67e23">to show your support</span>

---

## <span style="color:#05dffa">📄 License</span>

<span style="color:#e67e23">This project is licensed under the</span> [<span style="color:#2dc26b">MIT License</span>](https://github.com/donniedice/BLU/blob/main/LICENSE)<span style="color:#e67e23">.</span>

---

<div align="center">

### <span style="color:#4ecdc4">🌟 Thank you for choosing </span> <span style="color:#8B1538">R</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span> <span style="color:#4ecdc4">Mods! 🌟</span>

**<span style="color:#e67e23">Made with ❤️ by the</span> [<span style="color:#8B1538">R</span><span style="color:#7598b6">ealm</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span>](https://realmgx.com) <span style="color:#05dffa">Community</span>**
**<span style="color:#2dc26b">Lead Developer</span><span style="color:#3598db">:</span>** [<span style="color:#b96ad9">DonnieDice</span>](https://github.com/donniedice)

_<span style="color:#e67e23">"Make every level count with sounds that matter!"</span>_

**<span style="color:#05dffa">⚠️ WARNING:</span>** <span style="color:#e67e23">May cause excessive nostalgia for your favorite games.</span>

<img src="media/Textures/logo.png" alt="BLU Logo" width="80">

**<span style="color:#2dc26b">The Kiwi Says:</span>** <span style="color:#b96ad9">"Bwwiiiee."</span>

</div>

---

## Custom Sound Shortcuts

BLU still supports no-edit auto-detect for common numbered files like `custom01.ogg`, but the main user-friendly flow is now built into the Sounds tab.

Recommended in-game flow:

- Open `/blu`
- Go to the `Sounds` tab
- Use the `User Custom Sounds` panel on the right
- Click `Add Custom Sound`
- Type a short name like `myfile` or `myfile.ogg`

BLU will try common AddOns locations automatically and add the first compatible match it finds.

You can also use slash commands if you prefer:

Examples:

```text
/blu addcustom myfile
/blu addcustom myfile.ogg
/blu addcustom Interface\AddOns\myfile.ogg | My Custom Sound
```

If you only provide a short file name, BLU will try these common locations automatically:

- `Interface\AddOns\`
- `Interface\AddOns\sounds\`
- `Interface\AddOns\BLU\`
- `Interface\AddOns\BLU\sounds\`
- `Interface\AddOns\BLU\media\sounds\`

The first compatible `.ogg`, `.mp3`, or `.wav` match gets registered and appears under `User Custom Sounds` in the nested dropdown and in the Sounds tab manager list.

---

<div align="center">

### <span style="color:#05dffa">Part of the RGX Mods Collection</span>

[<span style="color:#05dffa">BLU Classic</span>](https://github.com/donniedice/BLU_Classic) | [<span style="color:#9b59b6">CCU</span>](https://github.com/donniedice/CoordinationCloakUtility) | [<span style="color:#ffe568">FFLU</span>](https://github.com/donniedice/FinalFantasyLevelUp) | [<span style="color:#58be81">PetBuddy2</span>](https://github.com/donniedice/PetBuddy2) | [<span style="color:#e74c3c">RND</span>](https://github.com/DonnieDice/RemoveNameplateDebuffs) | [<span style="color:#58be81">SQP</span>](https://github.com/donniedice/SimpleQuestPlates) | [<span style="color:#8B4513">SRLU</span>](https://github.com/donniedice/SkyrimLevelUp)

**<img src="media/Textures/logo.png" width="18" height="18" alt="BLU logo"> <span style="color:#8B1538">R</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span> <span style="color:#4ecdc4">Mods</span> <span style="color:#3598db">-</span> <span style="color:#e67e23">Powered by</span> [<span style="color:#8B1538">R</span><span style="color:#7598b6">ealm</span><span style="color:#8B1538">G</span><span style="color:#8B1538">X</span>](https://realmgx.com) <span style="color:#e67e23">Community</span>**

</div>
