Package dev.itsharshxd.zentrix.api.currency

Interface CurrencyService

public interface CurrencyService
Provides currency queries for Zentrix games.

Use it to read player balances, currency configuration, and reward values. Change balances through the event system.

Example


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

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

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

 // Check an event reward
 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.

      If the balance is not cached, this loads it from storage. Use getCachedBalance(UUID) for synchronous access.

      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 when available, or the starting balance otherwise. Use this for scoreboards and GUIs that cannot wait for an async result.

      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: &6Coins or &#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