Currencies API

Overview

The currency system supports multiple custom currencies with configurable properties like maximum values, starting amounts, and display names. All currency operations use BigDecimal for precise handling of large numbers and decimal values.

---

Balance Operations

Balance Retrieval

BigDecimal getCurrency(UUID uuid, String currency)

• Description: Gets a player's current balance for a specific currency

• Parameters:

  • uuid - Player's unique identifier

  • currency - Currency identifier (e.g., "money", "gems", "tokens")

• Returns: Current balance as BigDecimal

• Usage: Check player funds, display balances, transaction validation

Balance Modification

void setCurrency(UUID uuid, String currency, BigDecimal amount)

• Description: Sets a player's balance to a specific amount

• Parameters:

  • uuid - Player's unique identifier

  • currency - Currency identifier

  • amount - New balance amount

• Usage: Administrative balance setting, account resets, initialization

void addCurrency(UUID uuid, String currency, BigDecimal amount)

• Description: Adds currency to a player's balance

• Parameters:

  • uuid - Player's unique identifier

  • currency - Currency identifier

  • amount - Amount to add (positive values)

• Usage: Reward distribution, earning money, balance increases

void removeCurrency(UUID uuid, String currency, BigDecimal amount)

• Description: Removes currency from a player's balance

• Parameters:

  • uuid - Player's unique identifier

  • currency - Currency identifier

  • amount - Amount to remove (positive values)

• Usage: Purchases, penalties, transaction costs

---

Currency Validation

void isCurrency(String currency)

• Description: Validates if a currency identifier exists in the system

• Parameters: currency - Currency identifier to validate

• Usage: Input validation, configuration checking

• Note: Method name suggests boolean return, but signature shows void - check implementation

---

Currency Configuration

Limits and Constraints

double getMaxCurrencyValue(String currency)

• Description: Gets the maximum allowed value for a currency

• Parameters: currency - Currency identifier

• Returns: Maximum value (0.0 for unlimited)

• Usage: Validate transactions, prevent overflow, display limits

double getStartingCurrencyValue(String currency)

• Description: Gets the default starting amount for new players

• Parameters: currency - Currency identifier

• Returns: Starting balance amount

• Usage: Initialize new player accounts, reset balances

Display Information

String getCurrencyName(String currency)

• Description: Gets the display name for a currency

• Parameters: currency - Currency identifier

• Returns: Human-readable currency name

• Usage: User interfaces, transaction messages, display formatting

---

Usage Examples

Basic Balance Operations

EdDungeonsCurrencyAPI currencyAPI = EdDungeonsAPI.getInstance().getCurrencyAPI();
UUID playerUUID = player.getUniqueId();

// Check player's money balance
BigDecimal balance = currencyAPI.getCurrency(playerUUID, "money");
player.sendMessage("§6Balance: §f" + balance + " " + 
    currencyAPI.getCurrencyName("money"));

// Add money reward
BigDecimal reward = new BigDecimal("1000");
currencyAPI.addCurrency(playerUUID, "money", reward);
player.sendMessage("§a+1000 money!");

// Check if player can afford something
BigDecimal cost = new BigDecimal("500");
BigDecimal currentBalance = currencyAPI.getCurrency(playerUUID, "money");
if (currentBalance.compareTo(cost) >= 0) {
    currencyAPI.removeCurrency(playerUUID, "money", cost);
    player.sendMessage("§aPurchase successful!");
} else {
    player.sendMessage("§cInsufficient funds!");
}