Economy API

Overview

The Economy API provides a clean, simple interface for external plugins to interact with PhantomDungeons economy system. Handle payments, transfers, balance checks, and formatting without worrying about the underlying database operations.

Getting Started

Follow these steps to hook into the economy system safely.

1

Get the Instance

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

import me.fergs.phantomdungeons.modules.economy.api.EconomyAPI;

// Get the singleton instance
EconomyAPI economyAPI = EconomyAPI.get();

Note: This will throw an exception if PhantomDungeons isn't loaded yet. Make sure to add depend: [PhantomDungeons] to your plugin.yml.

2

Cache for Performance

Don't call .get() every time. Store it in your main plugin class for easy access.

public final class MyPlugin extends JavaPlugin {
    private EconomyAPI economy;
    
    @Override
    public void onEnable() {
        if (getServer().getPluginManager().getPlugin("PhantomDungeons") != null) {
            this.economy = EconomyAPI.get();
            getLogger().info("hooked.");
        }
    }
    
    public EconomyAPI getEconomy() {
        return economy;
    }
}

3

Safe Null Checks

Always ensure the economy exists before using it to prevent potential errors or bad/messy startups.

if (economy == null) {
    getLogger().warning("Economy not available!");
    return;
}

---

Core Operations

Checking Balances

Reading a balance is synchronous and instant because values are cached in memory. You do not need to use CompletableFuture for this.

// Get specific currency balance for a player
double balance = economy.getBalance(player, "money");

// Works with UUIDs for offline players
double souls = economy.getBalance(offlinePlayerUUID, "souls");

Adding Currency

Use this to give rewards. It automatically fires events (so boosters work) and saves asynchronously.

economy.addBalance(player, "money", 1000.0)
    .thenAccept(newBalance -> {
        // Runs after the money is safely added
        player.sendMessage("§aYou received $1000!");
        player.sendMessage("§7New Balance: " + newBalance);
    });

Tip: Always use addBalance instead of setBalance. addBalance triggers the CurrencyGainEvent, ensuring multipliers and boosters are applied correctly.

Removing Currency

Use this for shop purchases or penalties.

economy.removeBalance(player, "money", 500.0)
    .thenAccept(newBalance -> {
        player.sendMessage("§cPaid $500.");
    });

Validating Funds

Before removing money, check if they can afford it.

double cost = 500.0;

if (economy.hasBalance(player, "money", cost)) {
    // Proceed with purchase
    economy.removeBalance(player, "money", cost);
} else {
    player.sendMessage("§cInsufficient funds!");
}

---

Advanced Features

Transfers

Send currency from one player to another safely. The API handles the math and database syncing for both sides.

economy.transfer(sender, receiver, "money", 100.0)
    .thenAccept(success -> {
        if (success) {
            sender.sendMessage("§aSent $100!");
            receiver.sendMessage("§aReceived $100!");
        } else {
            sender.sendMessage("§cTransfer failed (insufficient funds).");
        }
    });

Formatting

Don't display raw numbers (e.g., 1000000.0). Use the formatter to get nice strings like 1M or 1,000,000.

double amount = 1500.50;
String display = economy.format("money", amount);

player.sendMessage("§7Current Balance: §a" + display);
// Output: "Current Balance: $1.5k" (depending on config)

Currency Metadata

Need to know the name of a currency dynamically?

String name = economy.getCurrencyName("souls"); // Returns "Souls"
String symbol = economy.getCurrencySymbol("money"); // Returns "$"
boolean exists = economy.currencyExists("gemstones"); // Returns true/false

---

Example: Creating a Shop Command

Here is a full example of a command that lets a player buy an item.

public void onBuyCommand(Player player) {
    double price = 250.0;
    
    if (!economy.hasBalance(player, "money", price)) {
        String formattedPrice = economy.format("money", price);
        player.sendMessage("§cYou need " + formattedPrice + " to buy this!");
        return;
    }
    
    economy.removeBalance(player, "money", price)
        .thenAccept(newBalance -> {
            
            // 3. Give the item (Run on main thread if needed)
            Bukkit.getScheduler().runTask(plugin, () -> {
                player.getInventory().addItem(new ItemStack(Material.DIAMOND));
                player.sendMessage("§aPurchase successful!");
            });
            
        }).exceptionally(ex -> {
            // Handle errors
            player.sendMessage("§cAn error occurred processing payment.");
            ex.printStackTrace();
            return null;
        });
}

---

Events API

You can listen for when players gain currency to add custom logic (like achievements).

@EventHandler
public void onCurrencyGain(PlayerCurrencyGainEvent event) {
    Player player = event.getPlayer();
    String currency = event.getCurrencyId();
    double amount = event.getAmount();

    // Example: Achievement for earning 1 million coins
    if (currency.equals("money") && amount >= 1000000) {
        player.sendMessage("§6§lACHIEVEMENT UNLOCKED: Millionaire!");
    }
}

---

FAQ

Is this thread-safe?

Yes. Data is read from memory (safe) and writes are handled via CompletableFuture (async).

Can balances go negative?

Generally no. removeBalance will fail if the result is negative, unless the specific currency config allows debt.

How do I create new currencies?

Just add a new YAML file in the economies/ folder of the PhantomDungeons plugin.

Why use `addBalance` over `setBalance`?

setBalance overrides the value directly. addBalance calculates the difference and fires events, ensuring compatibility with boosters.