H | Utility: CooldownUtils

Utility: CooldownUtils (Every Function & Example)

CooldownUtils helps you manage ability cooldowns for players. Every function is documented with usage and examples.

---

1. setCooldown(UUID playerId, String key, double seconds)

What it does:
Sets a cooldown for the given player and key (e.g., the name of the ability/item).

Example:

CooldownUtils.setCooldown(player.getUniqueId(), "FireballAbility", 10);

Sets a 10-second cooldown for "FireballAbility" for this player.

---

2. isOnCooldown(UUID playerId, String key): boolean

What it does:
Checks whether the cooldown is still active for the given player/key.

Example:

if (CooldownUtils.isOnCooldown(player.getUniqueId(), "FireballAbility")) {
    // Block ability use
}

---

3. getRemainingCooldown(UUID playerId, String key): double

What it does:
Returns the number of seconds left on the cooldown. If not on cooldown, returns 0 or negative.

Example:

double secondsLeft = CooldownUtils.getRemainingCooldown(player.getUniqueId(), "FireballAbility");
if (secondsLeft > 0) {
    player.sendMessage("Wait " + secondsLeft + " seconds!");
}

---

4. sendCooldownMessage(Player player, String key, double timeLeft)

What it does:
Sends a formatted message to the player about how many seconds are left.

Example:

CooldownUtils.sendCooldownMessage(player, "FireballAbility", CooldownUtils.getRemainingCooldown(player.getUniqueId(), "FireballAbility"));

Displays a message like: “FireballAbility is on cooldown for 7.2 more seconds!”

---

5. clearCooldowns(Player player)

What it does:
Removes all cooldowns for a single player.

Example:

CooldownUtils.clearCooldowns(player);

---

6. clearAllCooldowns()

What it does:
Removes all cooldowns for all players.

Example:

CooldownUtils.clearAllCooldowns();

---

7. saveCooldowns(File file) / loadCooldowns(File file)

What it does:
Saves or loads all cooldown data to/from a file.

Example:

CooldownUtils.saveCooldowns(new File(plugin.getDataFolder(), "cooldowns.dat"));
CooldownUtils.loadCooldowns(new File(plugin.getDataFolder(), "cooldowns.dat"));

---

Usage Patterns

• Use cooldowns to restrict how often an item/ability can be used.
• Store the key as "AbilityName", "ItemName", etc. for clarity.
• Always call isOnCooldown before triggering an ability.
• Optionally, call sendCooldownMessage to provide user feedback.

---