1.2

Updated currency api

Author: Jan Kluka

src/main/java/dev/drawethree/xprison/api/currency/XPrisonCurrencyAPI.java

@@ -1,19 +1,16 @@
 package dev.drawethree.xprison.api.currency;
 
+import dev.drawethree.xprison.api.currency.enums.LostCause;
+import dev.drawethree.xprison.api.currency.enums.ReceiveCause;
 import dev.drawethree.xprison.api.currency.model.XPrisonCurrency;
+import org.bukkit.OfflinePlayer;
 
 import java.util.Collection;
 
-/**
- * API for interacting with XPrison's currency system.
- * <p>
- * Allows external plugins to register new currencies or retrieve existing ones.
- */
 public interface XPrisonCurrencyAPI {
 
     /**
      * Registers a new custom currency to the system.
-     * <p>
      * If a currency with the same name (case-insensitive) already exists, it will be overwritten.
      *
      * @param currency The {@link XPrisonCurrency} implementation to register.
@@ -34,4 +31,55 @@ public interface XPrisonCurrencyAPI {
      * @return A collection of all {@link XPrisonCurrency} objects.
      */
     Collection<XPrisonCurrency> getAllCurrencies();
+
+    /**
+     * Gets the current amount of a specific currency for the specified player.
+     *
+     * @param player The player whose balance to retrieve.
+     * @param currencyName The currency to check.
+     * @return The amount of currency the player currently has.
+     */
+    double getBalance(OfflinePlayer player, String currencyName);
+
+    /**
+     * Adds a specified amount of a specific currency to the player's balance.
+     *
+     * @param player The player to add currency to.
+     * @param currencyName The currency to add.
+     * @param amount The amount to add.
+     * @param receiveCause The reason for receiving the currency.
+     * @return true if added successfully, false otherwise.
+     */
+    boolean addBalance(OfflinePlayer player, String currencyName, double amount, ReceiveCause receiveCause);
+
+    /**
+     * Removes a specified amount of a specific currency from the player's balance.
+     *
+     * @param player The player to remove currency from.
+     * @param currencyName The currency to remove.
+     * @param amount The amount to remove.
+     * @param lostCause The reason for removing the currency.
+     * @return true if removed successfully, false otherwise.
+     */
+    boolean removeBalance(OfflinePlayer player, String currencyName, double amount, LostCause lostCause);
+
+    /**
+     * Sets the balance of a specific currency for the player.
+     *
+     * @param player The player whose balance to set.
+     * @param currencyName The currency to set.
+     * @param amount The amount to set.
+     * @return true if set successfully, false otherwise.
+     */
+    boolean setBalance(OfflinePlayer player, String currencyName, double amount);
+
+    /**
+     * Checks if the player has at least the specified amount of the given currency.
+     *
+     * @param player The player to check.
+     * @param currencyName The currency to check.
+     * @param amount The minimum amount required.
+     * @return true if player has enough, false otherwise.
+     */
+    boolean has(OfflinePlayer player, String currencyName, double amount);
 }

src/main/java/dev/drawethree/xprison/api/currency/model/AbstractXPrisonCurrency.java

@@ -1,74 +1,63 @@
 package dev.drawethree.xprison.api.currency.model;
 
-import dev.drawethree.xprison.api.currency.enums.LostCause;
-import dev.drawethree.xprison.api.currency.enums.ReceiveCause;
-import org.bukkit.OfflinePlayer;
+import org.bukkit.inventory.ItemStack;
 
 /**
- * Represents a generic currency system in the XPrison API.
+ * Represents the metadata and formatting configuration of a currency in the XPrison API.
+ * This includes display name, format rules, symbol settings, and optional icon.
  * <p>
- * This interface abstracts common currency operations such as querying,
- * adding, removing, and setting balances for players. Implementations
- * could represent different currency types like Tokens, Gems, Money, etc.
- * <p>
- * Methods that modify balances return a boolean indicating whether the
- * operation was successful (e.g., not blocked, not insufficient funds, etc.).
+ * Currency balance operations are handled by a separate CurrencyService.
  */
 public interface XPrisonCurrency {
 
     /**
-     * Gets the name of this currency.
-     * <p>
-     * This is typically used for display purposes, configuration keys,
-     * or to distinguish between multiple currency types (e.g., "Tokens", "Gems", "Money").
+     * Gets the internal ID or key of the currency (e.g., "money", "tokens").
      *
-     * @return The name of the currency.
+     * @return The unique name of this currency.
      */
     String getName();
 
     /**
-     * Gets the current amount of this currency for the specified player.
+     * Gets the starting amount of a currency
+     *
+     * @return The amount each player will have on first join
+     */
+    double getStartingAmount();
+
+    /**
+     * Gets the display name of the currency (e.g., "Money", "Tokens").
      *
-     * @param player The player (offline or online) whose balance to retrieve.
-     * @return The amount of currency the player currently has.
+     * @return The friendly display name of the currency.
      */
-    double getBalance(OfflinePlayer player);
+    String getDisplayName();
 
     /**
-     * Adds a specified amount of currency to the player's balance.
+     * Gets the prefix of the currency (e.g., "$").
      *
-     * @param player The player to add currency to.
-     * @param amount The amount of currency to add.
-     * @param receiveCause Why currency was added
-     * @return true if the currency was successfully added, false otherwise.
+     * @return The friendly display name of the currency.
      */
-    boolean addBalance(OfflinePlayer player, double amount, ReceiveCause receiveCause);
+    String getPrefix();
 
     /**
-     * Removes a specified amount of currency from the player's balance.
+     * Gets the suffix of the currency.
      *
-     * @param player The player to remove currency from.
-     * @param amount The amount of currency to remove.
-     * @param lostCause Why currency was lost
-     * @return true if the currency was successfully removed, false (e.g., insufficient funds) otherwise.
+     * @return The friendly display name of the currency.
      */
-    boolean removeBalance(OfflinePlayer player, double amount, LostCause lostCause);
+    String getSuffix();
 
     /**
-     * Sets the player's currency balance to a new specified amount.
+     * Formats a raw double value according to the currency's configuration.
      *
-     * @param player The player whose balance to set.
-     * @param amount The new amount to set.
-     * @return true if the balance was successfully set, false otherwise.
+     * @param amount The amount to format.
+     * @return The formatted currency string (e.g., "$1.2k", "$3,000").
      */
-    boolean setBalance(OfflinePlayer player, double amount);
+    String format(double amount);
 
     /**
-     * Checks if the specified player has at least the given amount of this currency.
+     * Gets the configured physical item for this currency, if any.
+     * This can be used in GUIs or displays to represent the currency visually.
      *
-     * @param player The player whose balance to check.
-     * @param amount The minimum amount to verify.
-     * @return true if the player has at least the specified amount, false otherwise.
+     * @return The {@link ItemStack} used as the item, or null if not set.
      */
-    boolean has(OfflinePlayer player, double amount);
+    ItemStack getPhysicalItem();
 }