🌊 OceanCooldown

A modern, ultra-lightweight, and fully customizable item, weapon, food, and enchantment cooldown plugin built natively for modern Minecraft servers (1.21+ and Paper/DivineMC forks).

Unlike older cooldown plugins that cause classpath errors or break on new server versions, OceanCooldown is designed from scratch with high-performance concurrency, modern Paper event listeners, and native Minecraft hotbar visual sweeps.

✨ Features

• 🗡️ Weapons & Combat Cooldowns: Full support for melee attacks, sword hits, axe swings, and the Mace (left-click, right-click, or both).
• 🔱 Native Enchantment Hooking:
  • Riptide: Reliable trident launch cooldowns via native Paper events.
  • Lunge: Native support for the Spear/Trident Lunge mechanic (EntityLungeEvent)!
  • Works with any vanilla or custom enchantment!
• 🍎 Food & Consumables: Apply cooldowns to Golden Apples, Enchanted Golden Apples (God Apples), Chorus Fruit, Potions, etc.
• 🚀 Projectiles & Movement: Custom cooldowns on Ender Pearls, Wind Charges, Elytra Firework Rockets, Snowballs, and more.
• 🎨 Visual Client Hotbar Sweep: Triggers the native vanilla grey sweep animation on the player's hotbar item slot.
• 💬 Actionbar & Chat Alerts: Sleek Actionbar notifications with real-time remaining countdowns (supports HEX colors and Unicode small-caps).
• 🛡️ Anti-Spam Debounce: Built-in millisecond throttle prevents alert and sound spam when players rapidly click items on cooldown.
• ⚡ Zero-Lag & Async-Safe: Built with thread-safe collections (ConcurrentHashMap) for maximum tick stability under high player loads.

📜 Commands & Permissions

Permissions:

• oceancooldown.admin: Grants access to management commands (Default: op).
• oceancooldown.bypass: Bypasses all item and enchantment cooldowns (Default: op).
• oceancooldown.bypass.<item_or_enchantment_key>: Bypasses a specific cooldown (e.g. oceancooldown.bypass.ender_pearl).

⚙️ Default Configuration (config.yml)

settings:
  prefix: "&8[&bᴏᴄᴇᴀɴ&3ᴄᴏᴏʟᴅᴏᴡɴ&8] &7"
  actionbar: true
  actionbar-message: "&c⌛ &f{item} &cɪs ᴏɴ ᴄᴏᴏʟᴅᴏᴡɴ! &7ʀᴇᴍᴀɪɴɪɴɢ: &e{time}s"
  chat-message: false
  chat-text: "&cᴛʜɪs ɪᴛᴇᴍ ɪs ᴏɴ ᴄᴏᴏʟᴅᴏᴡɴ! ᴘʟᴇᴀsᴇ ᴡᴀɪᴛ &e{time}s&c."
  cooldown-sound: "block.note_block.bass"
  visual-sweep-cooldown: true
  message-debounce-ms: 800

cooldowns:
  ENDER_PEARL:
    cooldown: 20.0
    click_type: "right"
    display_name: "&dᴇɴᴅᴇʀ ᴘᴇᴀʀʟ"

  GOLDEN_APPLE:
    cooldown: 5.0
    click_type: "consume"
    display_name: "&6ɢᴏʟᴅᴇɴ ᴀᴘᴘʟᴇ"

  ENCHANTED_GOLDEN_APPLE:
    cooldown: 30.0
    click_type: "consume"
    display_name: "&dɢᴏᴅ ᴀᴘᴘʟᴇ"

  CHORUS_FRUIT:
    cooldown: 8.0
    click_type: "consume"
    display_name: "&5ᴄʜᴏʀᴜs ғʀᴜɪᴛ"

  FIREWORK_ROCKET:
    cooldown: 3.0
    click_type: "right"
    display_name: "&cғɪʀᴇᴡᴏʀᴋ ʀᴏᴄᴋᴇᴛ"

  WIND_CHARGE:
    cooldown: 3.0
    click_type: "right"
    display_name: "&bᴡɪɴᴅ ᴄʜᴀʀɢᴇ"

  MACE:
    cooldown: 5.0
    click_type: "both"
    display_name: "&eᴍᴀᴄᴇ"

  enchantment:riptide:
    cooldown: 15.0
    click_type: "right"
    display_name: "&3ʀɪᴘᴛɪᴅᴇ"

  enchantment:lunge:
    cooldown: 8.0
    click_type: "both"
    display_name: "&6ʟᴜɴɢᴇ"

💻 Requirements & Compatibility

• Dependencies: None! Fully self-contained.

👤 Author & Support

• Author / Developer: mmk1386
• Server Network: OceanRealms (play.oceanrealms.ir)
• Discord: https://discord.gg/NxvQkMjDnR