Developer API

Developer API

The X-Prison public API lives in a dedicated project: X-PrisonAPI on GitHub

---

Adding X-PrisonAPI as a Dependency

Add the API artifact to your plugin's build tool. The API is published to the Drawethree Maven repository.

Maven:

<repository>
    <id>drawethree-repo</id>
    <url>https://repo.drawethree.dev/releases</url>
</repository>

<dependency>
    <groupId>dev.drawethree</groupId>
    <artifactId>X-PrisonAPI</artifactId>
    <version>LATEST</version>
    <scope>provided</scope>
</dependency>

Gradle (Kotlin DSL):

repositories {
    maven("https://repo.drawethree.dev/releases")
}

dependencies {
    compileOnly("dev.drawethree:X-PrisonAPI:LATEST")
}

Declare X-Prison as a dependency in your plugin.yml:

depend: [X-Prison]
# or if optional:
softdepend: [X-Prison]

---

Accessing the API

import dev.drawethree.xprison.api.XPrisonAPI;

XPrisonAPI api = XPrisonAPI.getInstance();

Each module exposes its own sub-API through the main API instance:

api.getEnchantsAPI()      // Enchant system
api.getRanksAPI()         // Ranks
api.getPrestigesAPI()     // Prestiges
api.getRebirthAPI()       // Rebirths
api.getBlocksAPI()        // Block tracking
api.getCurrencyApi()      // Currency balances
api.getGangsAPI()         // Gangs
api.getMultipliersApi()   // Global, player, and rank multipliers
api.getAutoSellApi()      // Auto-sell prices and regions
api.getMinesApi()         // Mine management
api.getBombsApi()         // Bomb items
api.getAutoMinerApi()     // Auto-miner time

Dashboard integration (requires Dashboard addon):

api.setDashboardUrl(String url)   // called by the Dashboard addon on startup
api.getDashboardUrl()             // returns the active panel URL, or null if not running

Module and addon management:

api.getModules()                        // List<XPrisonModule> — all registered modules
api.isModuleEnabled(String configKey)   // true if module is active
api.enableModule(String configKey)
api.disableModule(String configKey)

api.getLoadedAddons()                          // List<XPrisonAddon>
api.enableAddon(String name)
api.disableAddon(String name)
api.loadAddonFromFile(File jar)                // runtime load without restart

---

Building an Addon (XPrisonAddonContext)

Addons are JARs placed in plugins/X-Prison/addons/. Declare the main class and metadata in the JAR manifest:

X-Prison-Addon-Class: com.example.MyAddon
X-Prison-Addon-Name: MyAddon
X-Prison-Addon-Description: Does something useful
X-Prison-Addon-Version: 1.0.0
X-Prison-Addon-Author: YourName
X-Prison-Min-Version: 2026.2.2.4-BETA

Implement XPrisonAddon:

public class MyAddon implements XPrisonAddon {

    private XPrisonAddonContext context;

    @Override
    public void onEnable(XPrisonAddonContext context) {
        this.context = context;

        XPrisonAPI api = context.getAPI();           // full X-Prison API
        File dataFolder = context.getDataFolder();   // plugins/X-Prison/addons/MyAddon/
        Logger log = context.getLogger();            // prefixed logger
        String name = context.getAddonName();
        String version = context.getAddonVersion();

        // Register Bukkit event listeners
        context.registerEvents(new MyListener());

        log.info("MyAddon enabled.");
    }

    @Override
    public void onDisable() {
        context.getLogger().info("MyAddon disabled.");
    }
}

Tip: Use context.getDataFolder() for your own config files. Do not read or write to X-Prison's own data folder.

X-Prison-Min-Version is optional. If declared, a warning is printed at startup if the running X-Prison version is older than the declared minimum.

---

Registering a Custom Enchant

Custom enchants must extend XPrisonEnchantment and are driven by JSON config files (placed in plugins/X-Prison/enchants/), just like built-in enchants.

@Override
public void onEnable(XPrisonAddonContext context) {
    MyCustomEnchant enchant = new MyCustomEnchant();
    context.getAPI().getEnchantsAPI().registerEnchant(enchant);
}

@Override
public void onDisable() {
    // unregister if needed
}

Your enchant class overrides these methods:

Method	Called when
onEquip(Player, ItemStack, int)	Player picks up or equips the pickaxe
onUnequip(Player, ItemStack, int)	Player removes or drops the pickaxe
onBlockBreak(BlockBreakEvent, int)	A block is broken in a mine with this enchant active
reload()	The plugin is reloaded — re-read your config values here

---

Ranks API

XPrisonRanksAPI ranks = api.getRanksAPI();

// Online and offline reads
Rank rank = ranks.getPlayerRank(player);
Rank rank = ranks.getPlayerRankOffline(uuid);           // DB lookup, works for offline players
Rank next = ranks.getNextPlayerRank(player);
double progress = ranks.getRankupProgress(player);      // 0.0 – 1.0
boolean isMax = ranks.isMaxRank(player);

// Writes
ranks.setPlayerRank(player, rank);
ranks.setPlayerRankOffline(uuid, rank);                 // persists to DB immediately
ranks.resetPlayerRank(player);

// Leaderboard
List<RankLeaderboardEntry> top = ranks.getTopByRank(10);

// All player UUIDs that have rank data
Set<UUID> uuids = ranks.getAllPlayerUUIDs();

// Rank list
List<Rank> allRanks = ranks.getAllRanks();
Rank max = ranks.getMaxRank();
Rank defaultRank = ranks.getDefaultRank();
Rank byId = ranks.getRankById(id);

---

Prestiges API

XPrisonPrestigesAPI prestiges = api.getPrestigesAPI();

Prestige prestige = prestiges.getPlayerPrestige(player);
Prestige prestige = prestiges.getPlayerPrestigeOffline(uuid);   // offline lookup
double progress = prestiges.getPrestigeProgress(player);
boolean isMax = prestiges.isMaxPrestige(player);
Prestige next = prestiges.getNextPlayerPrestige(player);

prestiges.setPlayerPrestige(player, prestige);
prestiges.setPlayerPrestigeOffline(uuid, prestige);             // persists to DB immediately
prestiges.resetPlayerPrestige(player);

List<PrestigeLeaderboardEntry> top = prestiges.getTopByPrestige(10);
Set<UUID> uuids = prestiges.getAllPlayerUUIDs();

List<Prestige> all = prestiges.getAllPrestiges();
Prestige max = prestiges.getMaxPrestige();

---

Rebirth API

XPrisonRebirthAPI rebirth = api.getRebirthAPI();

Rebirth r = rebirth.getPlayerRebirth(player);
Rebirth r = rebirth.getPlayerRebirthOffline(uuid);   // offline lookup
boolean isMax = rebirth.isMaxRebirth(player);
Rebirth next = rebirth.getNextPlayerRebirth(player);

rebirth.setPlayerRebirth(player, r);
rebirth.setPlayerRebirthOffline(uuid, r);            // persists to DB immediately
rebirth.resetPlayerRebirth(player);
rebirth.tryRebirth(player);                          // attempts rebirth, checks requirements

List<RebirthLeaderboardEntry> top = rebirth.getTopByRebirth(10);
Set<UUID> uuids = rebirth.getAllPlayerUUIDs();

List<Rebirth> all = rebirth.getAllRebirths();
Rebirth max = rebirth.getMaxRebirth();

---

Currency API

XPrisonCurrencyAPI currency = api.getCurrencyApi();

// Balance operations — all work for online AND offline players
BigDecimal balance = currency.getBalance(uuid, currencyName);
currency.addBalance(uuid, currencyName, amount);
currency.removeBalance(uuid, currencyName, amount);    // clamped to 0
currency.setBalance(uuid, currencyName, amount);
boolean has = currency.has(uuid, currencyName, amount);
currency.transferBalance(fromUuid, toUuid, currencyName, amount);

// Leaderboard
List<CurrencyLeaderboardEntry> top = currency.getTopByBalance(currencyName, 10);
List<CurrencyLeaderboardEntry> top = currency.getTopByBalance(currencyName, 10, offset);

// Currency CRUD (live — changes apply immediately and persist to currencies.yml)
currency.createCurrency(name, displayName, prefix, suffix, format, startingBalance);
currency.updateCurrency(name, displayName, prefix, suffix, format);
currency.deleteCurrency(name);
XPrisonCurrency c = currency.getCurrency(name);
List<XPrisonCurrency> all = currency.getAllCurrencies();

---

Multipliers API

XPrisonMultipliersAPI multipliers = api.getMultipliersApi();

// Global multipliers (server-wide, per currency)
GlobalMultiplier g = multipliers.getGlobalMultiplier(currencyName);
multipliers.setGlobalMultiplier(currencyName, value, duration, unit);
multipliers.addGlobalMultiplier(currencyName, value, duration, unit);  // extends if active
multipliers.resetGlobalMultiplier(currencyName);

// Player multipliers (per player, per currency)
PlayerMultiplier p = multipliers.getPlayerMultiplier(player, currencyName);
multipliers.setPlayerMultiplier(player, currencyName, value, duration, unit);

// Rank multipliers (assigned via permission node xprison.multiplier.<rank>)
RankMultiplier r = multipliers.getRankMultiplier(player, currencyName);

---

Mines API

XPrisonMinesAPI mines = api.getMinesApi();

List<Mine> allMines = mines.getMines();
Mine mine = mines.getMine(name);

// Mine interface — key methods
String name = mine.getName();
World world = mine.getWorld();
int filled = mine.getFilledBlocks();
int total = mine.getTotalBlocks();
double pct = mine.getPercentageFull();            // 0.0 – 1.0
int players = mine.getPlayerCount();

// Added for Dashboard / addon support:
Map<String, Integer> effects = mine.getEffects();         // uppercase effect name → amplifier
String resetType = mine.getResetTypeName();               // "INSTANT" or "GRADUAL"

// Block palette
BlockPalette palette = mine.getBlockPalette();
List<MineBlock> blocks = palette.getBlocks();
palette.setPaletteByIds(Map<String, Double> blockIdToPercentage);  // save and apply new palette

mine.reset();

---

Auto-Sell API

XPrisonAutoSellAPI autoSell = api.getAutoSellApi();

// Global prices
Map<String, Double> global = autoSell.getGlobalPrices();
autoSell.addSellPrice(MineBlock block, double price);
autoSell.removeSellPrice(MineBlock block);

// Sell regions (per WorldGuard region)
List<SellRegion> regions = autoSell.getSellRegions();
SellRegion region = regions.get(i);
String id = region.getId();
World world = region.getWorld();
String permission = region.getRequiredPermission();
Map<String, Double> prices = region.getPrices();

autoSell.addRegionSellPrice(String regionId, MineBlock block, double price);
autoSell.removeRegionSellPrice(String regionId, MineBlock block);

---

Events

Listen to X-Prison events like any Bukkit event. All events are in the dev.drawethree.xprison.api package hierarchy.

Enchant Events

Event	Cancellable	Description
XPrisonEnchantPrestigeEvent	Yes	Fired when a player prestiges an enchant. Exposes getOldPrestige(), getNewPrestige() (mutable), and the enchantment. Cancelling prevents the prestige.

Progression Events

Event	Cancellable	Description
XPrisonRankupEvent	Yes	Player ranks up
XPrisonPrestigeEvent	Yes	Player prestiges
XPrisonRebirthEvent	Yes	Player rebirths

Block Events

Event	Cancellable	Description
XPrisonBlockBreakEvent	No	Fired for every block broken by an X-Prison pickaxe

---

PrestigeableEnchant Interface

Enchants that support prestiging implement dev.drawethree.xprison.api.enchants.model.PrestigeableEnchant:

public interface PrestigeableEnchant {
    boolean isPrestigeEnabled();
    int getMaxPrestige();
    double getMultiplierPerPrestige();
    long getRequiredActivations(int currentPrestige);
}

Use this to check whether an enchant supports prestiging and read its configuration at runtime.

---

Notes

• The API jar is provided scope — do not shade it into your plugin or addon.
• Check the X-PrisonAPI GitHub repository for the most up-to-date interface definitions.
• For questions about the API, open a ticket in the Discord server.