L | Utility: OneTimeCraftUtils

L | Utility: CooldownUtils

---

Table of Contents

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

---

1. Overview

CooldownUtils is a utility class in FXItems for managing cooldowns on players, items, or abilities.
It helps you prevent spam, limit ability usage, and create fair gameplay mechanics.

---

2. What is CooldownUtils?

• Makes it easy to set, check, and manage cooldowns for players and items.
• Useful in custom item logic, ability handling, or command restrictions.
• Cooldowns can be global, per-item, or per-ability.

---

3. Basic Usage

Set a cooldown for an ability

CooldownUtils.setCooldown(player, "fireball", 100); // 100 ticks = 5 seconds

Check if a player is on cooldown

if (CooldownUtils.isOnCooldown(player, "fireball")) {
    player.sendMessage("§cYou must wait before using this again!");
    return;
}

Get remaining cooldown time

int ticksLeft = CooldownUtils.getCooldown(player, "fireball");
if (ticksLeft > 0) {
    player.sendMessage("§eWait " + (ticksLeft / 20.0) + "s before using again.");
}

---

4. API Reference

// Set a cooldown for a player and key (e.g. ability, item)
void CooldownUtils.setCooldown(Player player, String key, int ticks);

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

// Get remaining cooldown in ticks (returns 0 if not on cooldown)
int CooldownUtils.getCooldown(Player player, String key);

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

---

5. Advanced Patterns

• Per-item cooldowns:
  Use the item’s unique ID or type as the key.
• Cooldown feedback:
  Send action bar or title messages to notify players when cooldown expires.
• Multiple cooldowns:
  Track different abilities/items separately by using different keys.

---

6. Limitations & Troubleshooting

• Cooldowns are memory-based:
  By default, cooldowns reset if the server restarts. For persistent cooldowns, add custom save logic.
• Keys must be unique:
  Avoid accidental overlap by using descriptive keys (e.g., "item_jump_boots" vs "item_dash").
• Thread safety:
  Interact with Bukkit API on the main thread.

---

7. See Also

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

---