Package dev.itsharshxd.zentrix.api.currency

Interface CurrencyService

public interface CurrencyService
Service for currency-related queries within Zentrix.

This service provides access to player balances, currency configuration, and reward information. Balance modifications should be done through the event system.

Example Usage


 CurrencyService currencyService = ZentrixProvider.get().getCurrencyService();

 // Get player's balance
 double balance = currencyService.getCachedBalance(player);

 // Get formatted balance
 String formatted = currencyService.formatBalance(balance);
 // Result: "⛃ 150"

 // Check reward for an event
 double killReward = currencyService.getEventReward(CurrencyEventType.PLAYER_KILL);
Since:
1.0.0

  • Method Details

    • getBalance

      @NotNull @NotNull CompletableFuture<Double> getBalance(@NotNull @NotNull UUID playerId)
      Gets a player's balance asynchronously.

      This method fetches the balance from storage if not cached. For synchronous access, use getCachedBalance(UUID).

      Parameters:
      playerId - The player's UUID
      Returns:
      CompletableFuture containing the balance

    • getBalance

      @NotNull @NotNull CompletableFuture<Double> getBalance(@NotNull @NotNull org.bukkit.entity.Player player)
      Gets a player's balance asynchronously.
      Parameters:
      player - The player
      Returns:
      CompletableFuture containing the balance

    • getCachedBalance

      double getCachedBalance(@NotNull @NotNull UUID playerId)
      Gets a player's cached balance for immediate access.

      Returns the cached value if available, or the starting balance if not yet cached. Use this for scoreboards and GUIs where async operations are not desirable.

      Parameters:
      playerId - The player's UUID
      Returns:
      The cached balance (may be slightly outdated)

    • getCachedBalance

      double getCachedBalance(@NotNull @NotNull org.bukkit.entity.Player player)
      Gets a player's cached balance for immediate access.
      Parameters:
      player - The player
      Returns:
      The cached balance (may be slightly outdated)

    • getDisplayName

      @NotNull @NotNull String getDisplayName()
      Gets the currency display name.

      Example: "invalid input: '&'6Coins" or "invalid input: '&#'FFD700Gold"

      Returns:
      The display name with color codes (never null)

    • getSymbol

      @NotNull @NotNull String getSymbol()
      Gets the currency symbol.

      Example: "⛃" or "$"

      Returns:
      The currency symbol (never null)

    • getStartingBalance

      double getStartingBalance()
      Gets the starting balance for new players.
      Returns:
      The starting balance

    • isEventEnabled

      boolean isEventEnabled(@NotNull @NotNull CurrencyEventType eventType)
      Checks if a specific event type has rewards enabled.
      Parameters:
      eventType - The event type to check
      Returns:
      true if the event awards currency

    • getEventReward

      double getEventReward(@NotNull @NotNull CurrencyEventType eventType)
      Gets the reward amount for a specific event type.

      Returns 0 if the event is not enabled. Negative values indicate penalties (currency deduction).

      Parameters:
      eventType - The event type
      Returns:
      The reward amount (can be negative for penalties)

    • formatAmount

      @NotNull @NotNull String formatAmount(double amount)
      Formats a currency amount for display.

      Example: formatAmount(10.0) returns "10" Example: formatAmount(10.5) returns "10.5"

      Parameters:
      amount - The amount to format
      Returns:
      Formatted string (never null)

    • formatBalance

      @NotNull @NotNull String formatBalance(double balance)
      Formats a balance with the currency symbol.

      Example: formatBalance(150.0) returns "⛃ 150"

      Parameters:
      balance - The balance to format
      Returns:
      Formatted string with symbol (never null)

    • refreshCache

      void refreshCache(@NotNull @NotNull UUID playerId)
      Refreshes the cached balance for a player.

      Fetches the latest balance from storage and updates the cache.

      Parameters:
      playerId - The player's UUID

    • refreshCache

      void refreshCache(@NotNull @NotNull org.bukkit.entity.Player player)
      Refreshes the cached balance for a player.
      Parameters:
      player - The player