ItemCooldown

ItemCooldown is a lightweight and highly configurable Minecraft plugin that allows server owners to apply cooldown restrictions to specific items during PvP combat.
It prevents players from abusing powerful items such as Totems, Elytra, Ender Pearls, Golden Apples, etc. by temporarily blocking their usage when combat starts.

The plugin is designed to be fully configurable, lightweight, and safe, with support for multiple item actions and automatic inventory handling.

---

Key Features

⚔️ Combat-Based Cooldowns

Cooldowns begin immediately when a player enters PvP combat.
Both the attacker and the victim receive cooldowns for all configured items.

Combat detection includes:

• Direct player hits
• Projectiles shot by players
• Creative attackers
• Area-effect damage from players

Ignored damage sources:

• Self damage
• Ender pearl damage
• Non-player attackers

---

🧩 Configurable Item Actions

Each item can restrict different types of interactions:

Action	Description
pickup	Prevents players from picking up the item
equip	Prevents players from equipping the item
use	Prevents players from using the item
containers	Prevents players from moving the item into or out of containers and bundles

Example config:

{
  "TOTEM_OF_UNDYING": {
    "cooldown": 60,
    "action": ["pickup", "use"]
  },
  "ELYTRA": {
    "cooldown": 120,
    "action": ["equip"]
  }
}

Cooldown values are in seconds.

---

🪂 Smart Equipment Handling

If a player already has a restricted item equipped when combat begins, the plugin will automatically:

1. Unequip the item
2. Move it to the player's inventory

If the inventory is full:

• the item is temporarily stored in a virtual buffer
• it will automatically return to the inventory when space becomes available

This prevents bypassing cooldowns with already-equipped items such as Elytra or armor pieces.

---

⚙️ Fully Configurable

The plugin uses Bukkit material names and JSON configuration.

Structure:

plugins/ItemCooldown/

config.json
config-examples.txt

translations/
  messages.json

Features include:

• Editable messages
• Configurable cooldowns
• Configurable actions per item
• Built-in documentation examples

---

🔄 Hot Reload Support

You can reload the configuration and translation files without restarting the server.

/itemcooldown reload

If configuration files are missing, the plugin will automatically recreate them.

---

Commands

Command	Description
/itemcooldown help	Displays all plugin commands
/itemcooldown list [page]	Lists configured cooldown items
/itemcooldown info <material>	Shows information about a configured item
/itemcooldown add <material> <cooldown> <actions>	Adds a new item cooldown
/itemcooldown edit <material> <cooldown> <actions>	Edits an existing item
/itemcooldown remove <material>	Removes an item cooldown
/itemcooldown reload	Reloads the plugin configuration

---

Permissions

Permission	Description	Default
itemcooldown.help	Allows /itemcooldown help	true
itemcooldown.info	Allows /itemcooldown info	op
itemcooldown.list	Allows /itemcooldown list	op
itemcooldown.reload	Allows /itemcooldown reload	op
itemcooldown.add	Allows adding new cooldown items	op
itemcooldown.edit	Allows editing cooldown items	op
itemcooldown.remove	Allows removing cooldown items	op
itemcooldown.update.notify	Allows receiving in-game update notifications	op

---

Why Use ItemCooldown?

Many PvP servers suffer from item abuse during combat, such as:

• Elytra escaping
• Totem stacking
• Infinite ender pearl usage
• Golden apple spam

ItemCooldown provides a clean and configurable solution to balance PvP while keeping gameplay fair.

---

Compatibility

• Minecraft 1.20+
• Spigot / Paper
• Lightweight with minimal performance impact

---

Example Use Cases

Common items servers restrict:

TOTEM_OF_UNDYING
ENDER_PEARL
ELYTRA
GOLDEN_APPLE
ENCHANTED_GOLDEN_APPLE
SHIELD
TRIDENT

---

Configuration Philosophy

ItemCooldown is designed to be:

• Simple
• Flexible
• Server-friendly

You decide which items, which actions, and how long the cooldown lasts.

---

Support

If you encounter issues or have feature requests, feel free to open an ticket in the Discord server!

Enjoy fair and balanced PvP!