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:

Example config:

{
  "_settings": {
    "display": "actionbar",
    "update_ticks": 1
  },
  "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

Permissions

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!