📚 NukeLexicon API

A powerful, centralized core utility API for Spigot/Paper plugins, specializing in native multi-language (i18n) support and modern text formatting.

---

✨ Features

• 🎨 Modern Formatting: Native support for MiniMessage (RGB, Gradients, Click Events).
• 🌐 Smart i18n: Multi-language support with automatic player locale detection and fallback systems.
• 🎭 Rich Media Delivery: Send Titles, Action Bars, and Sounds with a single line of code, fully integrated with the translation engine.
• 🔄 PlaceholderAPI Integration: Seamlessly converts legacy %placeholders% into MiniMessage tags while preserving RGB formatting.
• ⚡ Zero Boilerplate: Optimized utility classes to dispatch formatted components or retrieve safe config values (Int, Float, Boolean).
• 🛠️ Developer Toolbox: Robust YAML configuration updater and a component-based API for GUIs and items.

---

📦 Installation (Gradle Kotlin DSL)

Add the Nukecraft5419 Repository and the dependency to your build.gradle.kts:

repositories {
    mavenCentral()
    maven("https://repo.nukecraft5419.com/")
}

dependencies {
    // Replace '1.1.0' with the latest release version
    implementation("dev.nukecraft5419:nukelexicon:1.1.0")
}

---

⚠️ Note on Shading:

Since you are using implementation, it is highly recommended to use the Shadow Gradle Plugin to shade and relocate NukeLexicon inside your plugin's JAR. This prevents version conflicts if multiple plugins on the same server use different versions of this API. If you prefer server owners to install NukeLexicon as a standalone plugin, use compileOnly instead.

---

Option A: Quick Initialization (Recommended)

Automatically detects your plugin's name, prefix, and uses en_US as the default language:

@Override
public void onEnable() {
    // Essential for Adventure Audiences and internal managers
    NukeLexicon.init(this);
}

---

Option B: Advanced Initialization

Manually define the fallback language and the default prefix:

@Override
public void onEnable() {
    // Parameters: Plugin instance, Fallback language, Default Prefix
    NukeLexicon.init(this, "en_GB", "<dark_gray>[<gold>MyPlugin</gold>]");
}

---

🧹 Clean Shutdown

To prevent memory leaks, remember to close the API in your onDisable:

@Override
public void onDisable() {
    NukeLexicon.close();
}

---

💬 Send Formatted Messages

Use SendUtils to deliver MiniMessage-formatted strings to any CommandSender:

// Supports MiniMessage tags, hex colors, and PAPI placeholders
SendUtils.sendMessage(player, "<gradient:aqua:blue>Welcome back, %player_name%!</gradient>");

// New in 1.1.0: Send Titles with custom timings (in milliseconds)
// Parameters: Player, TitlePath, SubtitlePath, FadeIn, Stay, FadeOut
SendUtils.sendTitle(player, "titles.welcome.main", "titles.welcome.sub", 500, 3000, 1000);

// New in 1.1.0: Send Action Bar messages
SendUtils.sendActionBar(player, "messages.actionbar_info");

// New in 1.1.0: Play sounds using Kyori Adventure keys
SendUtils.playSound(player, "entity.experience_orb.pickup", 1.0f, 1.0f);

// Log formatted messages to console
SendUtils.log("<red>[Alert]</red> System core initialized.");

---

🛠️ Component API

Need a formatted component for an Item name, Lore, or GUI title? Use getTranslationComponent to fetch the localized and parsed Component directly:

// Returns a Kyori Component with full MiniMessage and PAPI support
Component displayName = SendUtils.getTranslationComponent(player, "items.sword_name");

---

🌍 Localization (i18n)

Retrieve and send messages based on the player's client language automatically:

// Fetches the path 'messages.welcome' from the player's locale file
SendUtils.sendTranslation(player, "messages.welcome");

---

📊 Metrics

NukeLexicon uses bStats to track anonymous usage data. View global statistics here:

---

🤝 Contributing

Contributions are welcome! If you have suggestions or find bugs, feel free to open an issue or a pull request. Let's make localized plugins easier for everyone!

---

📄 License

This project is licensed under the MIT License.

---

_{Built with ❤️ by Nukecraft5419}