Levelling API

Overview

The Leveling API provides a clean interface for external plugins to interact with PhantomDungeons infinitely configurable leveling system. Manage player levels, check progression status, and trigger level-up rewards without worrying about database operations.

---

Getting Started

Follow these steps to integrate with the leveling system.

1

Get the Instance

In your plugin's onEnable, grab the API instance.

import me.fergs.phantomdungeons.modules.level.api.LevelingAPI;

// Get the singleton instance
LevelingAPI levelingAPI = LevelingAPI.get();

Note: Add depend: [PhantomDungeons] to your plugin.yml.

2

Cache for Performance

Store it in your main plugin class.

public class MyPlugin extends JavaPlugin {
    private LevelingAPI levelingAPI;
    
    @Override
    public void onEnable() {
        try {
            this.levelingAPI = LevelingAPI.get();
        } catch (IllegalStateException e) {
            getLogger().warning("PhantomDungeons not loaded!");
        }
    }
}

3

Safe Null Checks

Always check availability before using.

if (levelingAPI == null) {
    getLogger().warning("Leveling API not available!");
    return;
}

---

Core Operations

Checking Levels

Reading levels is synchronous and instant (cached in memory).

// Get player's level in a progression
int swordLevel = levelingAPI.getLevel(player, "sword-level");
player.sendMessage("§7Sword Level: §a" + swordLevel);

// Check if at max level
if (levelingAPI.isMaxLevel(player, "sword-level")) {
    player.sendMessage("§6Max level reached!");
}

// Check if can level up further
if (levelingAPI.canLevelUp(player, "sword-level")) {
    player.sendMessage("§aYou can level up!");
}

Adding & Removing Levels

Use async operations to modify levels.

// Add levels to player
levelingAPI.addLevels(player, "sword-level", 5)
    .thenAccept(newLevel -> {
        player.sendMessage("§aLevel up! Now level " + newLevel);
    });

// Remove levels (penalties, demotions, etc.)
levelingAPI.removeLevels(player, "sword-level", 2)
    .thenAccept(newLevel -> {
        player.sendMessage("§cLevel decreased to " + newLevel);
    });

// Set to specific level (admin)
levelingAPI.setLevel(player, "sword-level", 50)
    .thenRun(() -> player.sendMessage("§aLevel set to 50!"));

Progression Metadata

Query progression information.

// Check if progression exists
if (levelingAPI.progressionExists("prestige")) {
    // Safe to use
}

// Get progression name
String name = levelingAPI.getProgressionName("sword-level"); // "Sword Level"

// Get max level
int maxLevel = levelingAPI.getMaxLevel("sword-level");
int current = levelingAPI.getLevel(player, "sword-level");
player.sendMessage("§7Progress: " + current + "§7/§a" + maxLevel);

// Get all progressions
for (String progressionId : levelingAPI.getAllProgressions()) {
    System.out.println("Progression: " + progressionId);
}

---

Advanced Features

Progress Bars

Generate nice progress bar strings.

String progressBar = levelingAPI.buildProgressBar(player, "sword-level");
player.sendMessage("§7Level Progress: " + progressBar);
// Output: "§7Level Progress: §a████████░░ §715/20"

Reset Levels

Reset player progression (useful for prestige systems).

// Reset one progression
levelingAPI.resetLevel(player, "sword-level")
    .thenRun(() -> player.sendMessage("§cSword level reset!"))

// Reset all progressions
levelingAPI.resetAllLevels(player)
    .thenRun(() -> player.sendMessage("§cAll levels reset!"));

Get All Levels

Retrieve all progression levels for a player.

levelingAPI.getAllLevels(player)
    .thenAccept(levels -> {
        for (String progression : levels.keySet()) {
            int level = levels.get(progression);
            System.out.println(progression + ": " + level);
        }
    });

Level Requirements

Get cost for next level.

double nextLevelCost = levelingAPI.getNextLevelRequirement("sword-level");
player.sendMessage("§7Next level costs: §a" + nextLevelCost);

---

Events API

Listen for level-up events in your plugin.

@EventHandler
public void onLevelUp(PlayerLevelUpEvent event) {
    Player player = event.getPlayer();
    String progression = event.getProgressionId();
    int newLevel = event.getNewLevel();
    
    player.sendMessage("§6§l⬆ Level Up! §r§7" + progression + " is now level " + newLevel);
}

---

FAQ

Can I have unlimited progressions?

Yes! Add as many .yml files in the levels/ folder as you want.

Does it work offline?

Yes! Use UUID instead of Player for offline players.

Are level changes async?

Yes. All modifications return CompletableFuture.

Can progressions have no level cap?

Yes. Set max-level: 0 in the config for unlimited levels.

What happens on server restart?

Levels are persisted in the database and restored on startup in memory cache.

Can I check if progression exists?

Yes. Use progressionExists(progressionId) first.

---