H | Utility: CooldownUtils

H | Utility: CooldownUtils

---

Table of Contents

• 1. Overview
• 2. What is CooldownUtils?
• 3. Basic Usage
• 4. API Reference
• 5. Advanced Patterns
• 6. Troubleshooting & Notes
• 7. See Also

---

1. Overview

CooldownUtils is a utility class in FXItems that gives you a simple, reliable way to manage per-player cooldowns for abilities, items, foods, or any custom logic.
It is designed for use in FXItemBehavior, FXFoodBehavior, event listeners, and anywhere you want to rate-limit player actions.

---

2. What is CooldownUtils?

A toolkit for:

• Preventing ability spam (e.g., right-click powers, spells)
• Rate-limiting effects (e.g., only allow a boost every X seconds)
• Easily querying, setting, and clearing cooldowns for any player/ability combo

All cooldowns are tracked per-player and per-key (so you can have multiple independent cooldowns per player).

---

3. Basic Usage

Example: Simple Cooldown Check

@Override
public void onRightClick(Player player, ItemStack item, Block block, Action action) {
    if (CooldownUtils.isOnCooldown(player, "beam_sword")) {
        player.sendMessage("§cStill recharging!");
        return;
    }
    // Activate effect here...
    CooldownUtils.setCooldown(player, "beam_sword", 40); // 40 ticks = 2 seconds
}

• Key: "beam_sword" is a unique identifier for this cooldown. Use a different key for each separate cooldown you want to track.

---

4. API Reference

Methods

// Check if a player is on cooldown for a specific ability/key
boolean CooldownUtils.isOnCooldown(Player player, String key);

// Set a cooldown (ticks: 20 ticks = 1 second)
void CooldownUtils.setCooldown(Player player, String key, int ticks);

// Get remaining cooldown time (in ticks)
int CooldownUtils.getCooldown(Player player, String key);

// Remove a cooldown (early reset)
void CooldownUtils.removeCooldown(Player player, String key);

// Clear all cooldowns for a player (dangerous, rarely needed)
void CooldownUtils.clearCooldowns(Player player);

Key Parameter

• The key can be any string.
  Best practice: use a unique, lowercase string for each ability/item (e.g., "ice_staff", "dash_ability").

---

5. Advanced Patterns

Multiple Cooldowns Per Player

You can set as many independent cooldowns as you want, each with its own key:

CooldownUtils.setCooldown(player, "slash", 20);
CooldownUtils.setCooldown(player, "dash", 60);

These do not interfere with each other.

Global Cooldowns

If you want a cooldown to apply across all abilities for a player (rare), use a generic key like "global".

Cooldown Feedback

Always give players feedback when an action is on cooldown:

if (CooldownUtils.isOnCooldown(player, "fireball")) {
    int ticksLeft = CooldownUtils.getCooldown(player, "fireball");
    player.sendMessage("§cWait " + (ticksLeft / 20.0) + "s before using this again!");
    return;
}

Removing/Resetting Cooldowns

You can remove a cooldown early if desired (e.g., as a reward):

CooldownUtils.removeCooldown(player, "beam_sword");

---

6. Troubleshooting & Notes

• Cooldowns are NOT saved on server restart (they are in-memory only).
• Always use unique keys for different abilities to avoid conflicts.
• Ticks: Minecraft uses 20 ticks = 1 second.
  If you want a 5 second cooldown, use 100 ticks.
• Performance: CooldownUtils is highly efficient and safe for frequent use.

---

7. See Also

• E | Advanced: Custom Effects in FXItems
• K | Utility: ManaUtils
• J | Utility: EffectUtils

---