Home

WardenLib — Quick Wiki

A concise developer guide for using WardenLib inside your plugin.

---

Overview

WardenLib is a lightweight utility library for Spigot/Paper plugins (designed for Minecraft 1.21+). It centralizes common handlers and UI utilities so plugin authors don't reinvent the wheel.

Provided modules / handlers

• ConfigHandler — load & save YAML configs easily
• ActionBarHandler — send ActionBar messages (Adventure)
• SoundHandler — play sounds to players / at locations
• AnimationHandler — simple text animations (actionbar/title)
• BossBarHandler — create & manage boss bars
• EconomyHandler — Vault abstraction (optional)
• UIStarter / UIUtils — UI initialization and helpers for inventories/menus

---

📘 Table of Contents

Requirements

Installation

Initialization & Best Practices

Handlers — Quick API Reference

UIStarter / UIUtils

Example Commands Using WardenLib

BossBar Config Example

Optional: Detect Duplicate JARs (server warning)

FAQ

Contributing

Example repo structure

🧱 Requirements

• Java 21+
• PaperMC 1.21 or newer
• WardenLib installed on the server
• (optional) Vault for economy support

---

Installation

plugin.yml

Put WardenLib as a (soft) dependency so your plugin loads after the library when present:

name: MyPlugin
main: com.mycompany.myplugin.MyPlugin
version: 1.0.0
api-version: 1.21
softdepend:
  - WardenLib

Use depend: instead of softdepend: if WardenLib is required.

Gradle

You have to include it as a denpendency

Add it in your root settings.gradle at the end of repositories:

dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url 'https://jitpack.io' }
		}
	}

Add the dependency

dependencies {
	        implementation 'com.github.SohamTeamIndiaOfficial:WardenLib:-SNAPSHOT'
	}

Gradle.kts

Add it in your settings.gradle.kts at the end of repositories:

dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url = uri("https://jitpack.io") }
		}
	}

Add the dependency

dependencies {
	        implementation("com.github.SohamTeamIndiaOfficial:WardenLib:-SNAPSHOT")
	}

Maven

Add to pom.xml

<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Add the dependency

<dependency>
	    <groupId>com.github.SohamTeamIndiaOfficial</groupId>
	    <artifactId>WardenLib</artifactId>
	    <version>-SNAPSHOT</version>
	</dependency>

Prefer compileOnly — the server will provide the library at runtime.

---

Initialization & Best Practices

• Check UIStarter.isRegistered(plugin) before using UI APIs.
• Use EconomyHandler.hasEconomy() before calling economy methods.
• Keep one instance of each handler per plugin (store in fields or a small LibManager).
• Use Adventure Component for all messages (WardenLib handlers accept Adventure components).

Example onEnable:

public class MyPlugin extends JavaPlugin {
    private ConfigHandler config;
    private ActionBarHandler actionBar;
    private SoundHandler sounds;

    @Override
    public void onEnable() {
        saveDefaultConfig();
        config = new ConfigHandler(this, "config.yml");
        actionBar = new ActionBarHandler(this);
        sounds = new SoundHandler(this);

        if (!UIStarter.isRegistered(this)) UIStarter.register(this); // register UI system
    }
}

---

Handlers — Quick API Reference

These are example method signatures (adapt to actual WardenLib API names used in the jar).

ConfigHandler

ConfigHandler cfg = new ConfigHandler(plugin, "config.yml");
FileConfiguration conf = cfg.get();
String prefix = cfg.get().getString("messages.prefix");
cfg.save();
cfg.saveDefault();

ActionBarHandler

ActionBarHandler bars = new ActionBarHandler(plugin);
bars.send(player, Component.text("Hello", NamedTextColor.GREEN));
bars.broadcast(Component.text("Server event"));

SoundHandler

SoundHandler sounds = new SoundHandler(plugin);
sounds.play(player, Sound.ENTITY_PLAYER_LEVELUP, 1f, 1f);
sounds.playAt(location, Sound.ENTITY_EXPERIENCE_ORB_PICKUP, 0.8f, 1f);
sounds.playAll(Sound.UI_TOAST_CHALLENGE_COMPLETE, 1f, 1f);

AnimationHandler

AnimationHandler anim = new AnimationHandler(plugin);
anim.playActionBarAnimation(player, List.of(
    Component.text("S t a r t"),
    Component.text("READY")
), 10); // period in ticks

BossBarHandler

BossBarHandler boss = new BossBarHandler(plugin);
BossBar bar = boss.createBar(Component.text("Event"), BarColor.PURPLE, BarStyle.SOLID);
boss.show(player, bar);
boss.setProgress(bar, 0.5f);

• Config toggle: create bar only if config.getBoolean("bossbar.enabled") is true.

EconomyHandler (Vault optional)

if (EconomyHandler.hasEconomy()) {
    double bal = EconomyHandler.getBalance(player);
    EconomyHandler.deposit(player, 50.0);
    EconomyHandler.withdraw(player, 10.0);
}

WardenLib wraps Vault calls. If Vault is absent, hasEconomy() returns false and methods should be no-ops or return failure.

UIStarter / UIUtils

if (!UIStarter.isRegistered(plugin)) UIStarter.register(plugin);
// Create menus via UIUtils helpers
UIUtils.openMenu(player, menuBuilder);

UILoader is deprecated — use UIStarter.

---

Example Commands Using WardenLib

/webalance (shows balance):

public boolean onCommand(CommandSender s, Command cmd, String label, String[] args) {
    if (!(s instanceof Player p)) return false;
    if (!EconomyHandler.hasEconomy()) {
        p.sendMessage(Component.text("No economy", NamedTextColor.RED));
        return true;
    }
    double bal = EconomyHandler.getBalance(p);
    p.sendMessage(Component.text("Balance: ").append(Component.text(String.format("%.2f", bal))));
    return true;
}

/wetpall (teleport everyone to target):

Player caller = (Player) sender;
Player target = Bukkit.getPlayerExact(args[0]);
for (Player pl : Bukkit.getOnlinePlayers()) {
    if (pl.equals(target)) continue;
    pl.teleport(target.getLocation());
}

---

BossBar Config Example

Add to your config.yml:

bossbar:
  enabled: true
  title: "Server Event"
  color: PURPLE
  style: SOLID
  durationSeconds: 30

Create bar only if enabled and use BossBarHandler to show/auto-hide after duration.

---

Optional: Detect Duplicate JARs (server warning)

You can add a small check in onEnable() to scan the plugins folder for duplicate names and warn admins:

File pluginsDir = getServer().getPluginsFolder();
Map<String, List<File>> byName = new HashMap<>();
for (File f : Objects.requireNonNull(pluginsDir.listFiles())) {
    if (!f.getName().endsWith(".jar")) continue;
    String base = f.getName().replaceAll("(\\.jar)$", "");
    byName.computeIfAbsent(base.toLowerCase(), k -> new ArrayList<>()).add(f);
}
byName.forEach((name, files) -> {
    if (files.size() > 1) getLogger().warning("Duplicate plugin jars detected for: " + name);
});

This avoids relying on Plugin.getFile() which isn't available in older APIs.

---

FAQ

Q: Vault missing — how to handle? A: Wrap economy calls with EconomyHandler.hasEconomy() checks and present friendly messages.

Q: I see UILoader deprecation warnings — what to do? A: Replace UILoader usage with UIStarter.register(plugin) and UIStarter.isRegistered(plugin) checks.

Q: Which text API should I use? A: Adventure Component everywhere — WardenLib uses Adventure for messaging.

---

Contributing

Add new handlers to com.svteam.wardenlib.handlers. Keep APIs small and focused. Provide unit-testable logic when possible (avoid static state).

---

Example repo structure

wardenlib/
 ┣ src/main/java/com/svteam/wardenlib/
 ┃ ┣ handlers/
 ┃ ┃ ┣ ConfigHandler.java
 ┃ ┃ ┣ ActionBarHandler.java
 ┃ ┃ ┣ EconomyHandler.java
 ┃ ┃ ┣ SoundHandler.java
 ┃ ┃ ┣ AnimationHandler.java
 ┃ ┃ ┗ BossBarHandler.java
 ┃ ┣ ui/
 ┃ ┃ ┣ UIListener
 ┃ ┃ ┣ UILoader [Deprecated]
 ┃ ┃ ┣ UIStarter [Use this instead of UILoader]
 ┃ ┃ ┣ UIUtils
 ┃ ┣ Main.java
 ┃ ┣ ScoreboardAPI.java
 ┗ plugin.yml

---