Economy

Economy

The economy subsystem lets you register currencies and read or modify player balances. A server can hold multiple currencies at once, each identified by a stable UUID, and one of them can be marked as the primary currency exposed to Vault.

Getting the service

Obtain the EconomyService from the API entry point:

EconomyService economy = VoxyAPI.getAPI().getEconomyService();

All EconomyService operations are synchronous and blocking. They return plain values (no CompletableFuture), and lookups that miss return null rather than an Optional. Because reads and writes may touch persistence, treat them like any other blocking call and keep them off the main thread when doing bulk work.

Currencies

A Currency has three fields: a persistent UUID, a case-insensitive id used in commands and config, and a human-readable displayName.

public UUID getUuid();
public String getId();
public String getDisplayName();

Creating and looking up currencies

createCurrency returns the existing currency if one with the same id already exists, otherwise it creates a new one:

Currency coins = economy.createCurrency("coins", "Coins");
UUID coinsId = coins.getUuid();

Look up a currency by its id (case-insensitive) or by its UUID. Both return null when nothing is registered under that key, so guard the result:

Currency byId = economy.getCurrency("coins");     // may be null
Currency byUuid = economy.getCurrency(coinsId);   // may be null

if (byId == null) {
    getLogger().warning("The 'coins' currency is not registered.");
    return;
}

List every registered currency as an immutable view:

for (Currency currency : economy.getCurrencies()) {
    getLogger().info(currency.getId() + " -> " + currency.getDisplayName());
}

Renaming and deleting

economy.renameCurrency(coinsId, "gold");           // updates id and display name
boolean removed = economy.deleteCurrency(coinsId); // also clears associated balances

deleteCurrency returns true if the currency existed and was removed.

Player balances

Balances are keyed by player UUID and currency UUID.

The balance methods take the currency's UUID, not its string id, so resolve the Currency first and pass getUuid().

UUID playerId = player.getUniqueId();
UUID currencyId = economy.getCurrency("coins").getUuid();

Reading a balance

getBalance returns a double and yields zero when the player has no stored balance for that currency:

double balance = economy.getBalance(playerId, currencyId);

Giving, taking, and setting

// Give: adds to the balance
economy.deposit(playerId, currencyId, 250.0);

// Take: removes funds only if the player can afford it
boolean paid = economy.withdraw(playerId, currencyId, 100.0);
if (!paid) {
    player.sendMessage("You do not have enough coins.");
}

// Set: overwrites the balance outright
economy.setBalance(playerId, currencyId, 0.0);

deposit and setBalance return void. withdraw returns a boolean: true on success, false when the player has insufficient funds (the balance is left unchanged).

The primary currency

One currency can be marked as primary. This is the currency Voxy uses by default and the one exposed to Vault for other plugins that read balances through Vault's economy abstraction.

UUID primary = economy.getPrimaryCurrency(); // may be null if none is set
if (primary != null) {
    double main = economy.getBalance(playerId, primary);
}

economy.setPrimaryCurrency(currencyId);

getPrimaryCurrency returns the primary currency UUID, or null if none has been configured.

Key methods