Package dev.itsharshxd.zentrix.api.events.currency

Class CurrencyChangeEvent

java.lang.Object
org.bukkit.event.Event
dev.itsharshxd.zentrix.api.events.ZentrixEvent
dev.itsharshxd.zentrix.api.events.currency.CurrencyChangeEvent
All Implemented Interfaces:
org.bukkit.event.Cancellable
public class CurrencyChangeEvent extends ZentrixEvent implements org.bukkit.event.Cancellable
Called when a player's currency balance is about to change.

This event is fired before the balance modification is applied, allowing addons to:

  • Cancel the change entirely
  • Modify the new balance amount
  • Log or track balance changes
  • Implement custom restrictions

This event is cancellable. Cancelling prevents the balance change.

Example Usage


 @EventHandler
 public void onCurrencyChange(CurrencyChangeEvent event) {
     UUID playerId = event.getPlayerId();
     double oldBalance = event.getOldBalance();
     double newBalance = event.getNewBalance();
     double change = event.getChangeAmount();
     ChangeReason reason = event.getReason();

     // Log all currency changes
     getLogger().info(String.format(
         "Currency change for %s: %.2f -> %.2f (%s%.2f) [%s]",
         event.getPlayerName(),
         oldBalance, newBalance,
         change >= 0 ? "+" : "", change,
         reason.name()
     ));

     // Prevent negative balance
     if (newBalance < 0) {
         event.setNewBalance(0);
     }

     // Block changes from certain sources
     if (reason == ChangeReason.ADDON && !hasPermission(playerId)) {
         event.setCancelled(true);
         event.getPlayer().ifPresent(p ->
             p.sendMessage("Currency change blocked!"));
     }

     // Apply tax on large gains
     if (change > 1000) {
         double taxedAmount = change * 0.9; // 10% tax
         event.setNewBalance(oldBalance + taxedAmount);
     }
 }
Since:
1.0.0
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    CurrencyChangeEvent.ChangeReason
    Represents the reason for a currency balance change.

    Nested classes/interfaces inherited from class org.bukkit.event.Event

    org.bukkit.event.Event.Result

  • Constructor Summary

    Constructors
    Constructor
    Description
    CurrencyChangeEvent(@NotNull UUID playerId, @NotNull String playerName, double oldBalance, double newBalance, @NotNull CurrencyChangeEvent.ChangeReason reason)
    Constructs a new CurrencyChangeEvent without a source.
    CurrencyChangeEvent(@NotNull UUID playerId, @NotNull String playerName, double oldBalance, double newBalance, @NotNull CurrencyChangeEvent.ChangeReason reason, @Nullable String source)
    Constructs a new CurrencyChangeEvent.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addBonus(double bonus)
    Adds a bonus amount to the new balance.
    double
    getChangeAmount()
    Gets the amount of change (positive for gains, negative for losses).
    static @NotNull org.bukkit.event.HandlerList
    getHandlerList()
    Gets the static handler list for this event type.
    @NotNull org.bukkit.event.HandlerList
    getHandlers()
    Gets the handler list for this event.
    double
    getNewBalance()
    Gets the player's balance after the change.
    double
    getOldBalance()
    Gets the player's balance before the change.
    @NotNull Optional<org.bukkit.entity.Player>
    getPlayer()
    Gets the Bukkit player instance if online.
    @NotNull UUID
    getPlayerId()
    Gets the UUID of the player whose balance is changing.
    @NotNull String
    getPlayerName()
    Gets the name of the player whose balance is changing.
    @NotNull CurrencyChangeEvent.ChangeReason
    getReason()
    Gets the reason for the balance change.
    @NotNull Optional<String>
    getSource()
    Gets the source identifier for this change.
    boolean
    isAddonChange()
    Checks if this change was made by an addon.
    boolean
    isAdminChange()
    Checks if this change was made by an administrator.
    boolean
    isCancelled()
     
    boolean
    isEventReward()
    Checks if this change was triggered by a game event reward.
    boolean
    isGain()
    Checks if this is a balance increase (gain).
    boolean
    isLoss()
    Checks if this is a balance decrease (loss).
    boolean
    isNoChange()
    Checks if there is no actual change in balance.
    void
    multiplyChange(double multiplier)
    Applies a multiplier to the change amount.
    void
    setCancelled(boolean cancel)
     
    void
    setNewBalance(double newBalance)
    Sets the new balance that will be applied.

    Methods inherited from class org.bukkit.event.Event

    callEvent, getEventName, isAsynchronous

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • CurrencyChangeEvent

      public CurrencyChangeEvent(@NotNull @NotNull UUID playerId, @NotNull @NotNull String playerName, double oldBalance, double newBalance, @NotNull @NotNull CurrencyChangeEvent.ChangeReason reason, @Nullable @Nullable String source)
      Constructs a new CurrencyChangeEvent.
      Parameters:
      playerId - The UUID of the player whose balance is changing
      playerName - The name of the player
      oldBalance - The balance before the change
      newBalance - The balance after the change (can be modified)
      reason - The reason for the balance change
      source - Optional source identifier (e.g., addon name, event type)

    • CurrencyChangeEvent

      public CurrencyChangeEvent(@NotNull @NotNull UUID playerId, @NotNull @NotNull String playerName, double oldBalance, double newBalance, @NotNull @NotNull CurrencyChangeEvent.ChangeReason reason)
      Constructs a new CurrencyChangeEvent without a source.
      Parameters:
      playerId - The UUID of the player whose balance is changing
      playerName - The name of the player
      oldBalance - The balance before the change
      newBalance - The balance after the change
      reason - The reason for the balance change

  • Method Details

    • getPlayerId

      @NotNull public @NotNull UUID getPlayerId()
      Gets the UUID of the player whose balance is changing.
      Returns:
      The player's UUID (never null)

    • getPlayerName

      @NotNull public @NotNull String getPlayerName()
      Gets the name of the player whose balance is changing.
      Returns:
      The player's name (never null)

    • getPlayer

      @NotNull public @NotNull Optional<org.bukkit.entity.Player> getPlayer()
      Gets the Bukkit player instance if online.

      The player may be offline if the change is being made asynchronously or from storage operations.

      Returns:
      Optional containing the player, or empty if offline

    • getOldBalance

      public double getOldBalance()
      Gets the player's balance before the change.
      Returns:
      The old balance

    • getNewBalance

      public double getNewBalance()
      Gets the player's balance after the change.

      This value can be modified by event handlers before the change is applied.

      Returns:
      The new balance

    • setNewBalance

      public void setNewBalance(double newBalance)
      Sets the new balance that will be applied.

      Use this to modify the final balance. The value will be clamped to a minimum of 0 when applied.

      Parameters:
      newBalance - The new balance to set

    • getChangeAmount

      public double getChangeAmount()
      Gets the amount of change (positive for gains, negative for losses).

      This is calculated as newBalance - oldBalance.

      Returns:
      The change amount

    • isGain

      public boolean isGain()
      Checks if this is a balance increase (gain).
      Returns:
      true if the new balance is higher than the old balance

    • isLoss

      public boolean isLoss()
      Checks if this is a balance decrease (loss).
      Returns:
      true if the new balance is lower than the old balance

    • isNoChange

      public boolean isNoChange()
      Checks if there is no actual change in balance.
      Returns:
      true if old and new balance are equal

    • getReason

      @NotNull public @NotNull CurrencyChangeEvent.ChangeReason getReason()
      Gets the reason for the balance change.
      Returns:
      The change reason (never null)

    • getSource

      @NotNull public @NotNull Optional<String> getSource()
      Gets the source identifier for this change.

      This can be an addon name, event type, or other identifier that helps track where the change originated from.

      Returns:
      Optional containing the source, or empty if not specified

    • isEventReward

      public boolean isEventReward()
      Checks if this change was triggered by a game event reward.
      Returns:
      true if the reason is CurrencyChangeEvent.ChangeReason.EVENT_REWARD

    • isAdminChange

      public boolean isAdminChange()
      Checks if this change was made by an administrator.
      Returns:
      true if the reason is CurrencyChangeEvent.ChangeReason.ADMIN

    • isAddonChange

      public boolean isAddonChange()
      Checks if this change was made by an addon.
      Returns:
      true if the reason is CurrencyChangeEvent.ChangeReason.ADDON

    • addBonus

      public void addBonus(double bonus)
      Adds a bonus amount to the new balance.

      Convenience method to add to the new balance without knowing the current value.

      Parameters:
      bonus - The amount to add (can be negative to reduce)

    • multiplyChange

      public void multiplyChange(double multiplier)
      Applies a multiplier to the change amount.

      This modifies the new balance by multiplying the change amount. For example, a multiplier of 2.0 will double the gain/loss.

      Parameters:
      multiplier - The multiplier to apply to the change amount

    • isCancelled

      public boolean isCancelled()
      Specified by:
      isCancelled in interface org.bukkit.event.Cancellable

    • setCancelled

      public void setCancelled(boolean cancel)
      Specified by:
      setCancelled in interface org.bukkit.event.Cancellable

    • getHandlers

      @NotNull public @NotNull org.bukkit.event.HandlerList getHandlers()
      Gets the handler list for this event.
      Overrides:
      getHandlers in class ZentrixEvent
      Returns:
      The handler list

    • getHandlerList

      @NotNull public static @NotNull org.bukkit.event.HandlerList getHandlerList()
      Gets the static handler list for this event type.
      Returns:
      The handler list