MaceCooldownn

** 📖 **MaceCooldown Plugin - Complete Description** --- 🎯 **Overview** **MaceCooldown** is a lightweight, performance-optimized Minecraft plugin designed for **Paper/Spigot 1.21.1-1.21.11** servers. It introduces a strategic cooldown mechanic to the **Mace** weapon, preventing spam attacks and adding tactical depth to PvP and PvE combat scenarios. When a player attacks any entity using a Mace, the weapon is placed on cooldown for a configurable duration, during which the player cannot use the Mace again. This creates balanced gameplay and prevents overpowered Mace spamming. --- ✨ **Key Features** **1. Cooldown System** - ⏱️ **Configurable Duration**: Set cooldown time in seconds (default: 120 seconds / 2 minutes) - 🎮 **Native Minecraft API**: Uses official `Player.setCooldown()` method for seamless integration - 🔄 **Automatic Conversion**: Seconds automatically converted to Minecraft ticks (1 second = 20 ticks) - 💬 **Player Feedback**: Visual messages inform players when cooldown is applied **2. Smart Detection** - 🎯 **Entity Attack Trigger**: Activates only when a player actually hits an entity - ✋ **Main Hand Detection**: Only triggers when Mace is in the main hand slot - 🛡️ **Entity-Agnostic**: Works with all entity types (players, mobs, bosses, custom entities) **3. Configuration System** - 📝 **Fully Customizable**: Edit `config.yml` to suit your server needs - 🔌 **Toggle On/Off**: Completely disable the plugin without uninstalling - 🔄 **Hot Reload**: Apply config changes without server restart using `/macecooldown reload` - 📋 **Well-Documented**: Config file includes clear comments for each setting **4. Administration** - 👑 **Admin Commands**: `/macecooldown reload` for managing the plugin - 🔐 **Permission System**: `macecooldown.admin` permission (OP by default) - 📊 **Status Feedback**: Command shows current configuration when reloading **5. Performance & Compatibility** - ⚡ **Lightweight**: Minimal resource usage, optimized event handling - 🎮 **Modern Minecraft**: Supports 1.21.1 through 1.21.11 - ☕ **Java 21**: Built with the latest Java LTS for maximum performance - 🌐 **Paper/Spigot**: Compatible with both server platforms --- 🎮 **Use Cases & Applications** **PvP Servers** - **Balance Combat**: Prevent Mace spam in duels and arenas - **Strategic Gameplay**: Players must time their Mace attacks carefully - **Weapon Diversity**: Encourages switching between different weapons - **Skill-Based Fighting**: Rewards tactical thinking over button mashing **Survival/SMP Servers** - **Boss Fights**: Make boss battles more challenging and engaging - **Mob Grinding**: Prevent trivializing mob farms with Mace spam - **Resource Balance**: Encourages varied weapon use and durability management **RPG/Adventure Servers** - **Class Systems**: Integrate with class-based systems for warrior cooldowns - **Quest Balance**: Make quests more challenging by limiting powerful weapons - **Progression Control**: Gate powerful Mace usage behind cooldown mechanics **Mini-Games** - **PvP Arenas**: Add strategic depth to combat mini-games - **Custom Events**: Create timed challenges with weapon cooldowns - **Tournament Balance**: Ensure fair fights in competitive events --- 🔧 **How It Works** **Technical Flow:** ``` 1. Player attacks entity with Mace in main hand ↓ 2. Plugin detects EntityDamageByEntityEvent ↓ 3. Checks if cooldown-enabled = true ↓ 4. Validates attacker is a Player ↓ 5. Checks if weapon is Material.MACE ↓ 6. Converts config seconds to ticks (seconds × 20) ↓ 7. Applies cooldown using player.setCooldown(Material.MACE, ticks) ↓ 8. Player receives feedback message ↓ 9. Mace cannot be used until cooldown expires ``` **Visual Player Experience:** - ✅ **Before Cooldown**: Mace works normally - ⚔️ **Attack Entity**: Player hits any mob/player with Mace - ⏳ **Cooldown Activates**: Mace icon shows cooldown animation - 💬 **Message Appears**: "Mace cooldown applied for 120 seconds!" - ⏱️ **Wait Period**: Player must wait (or switch weapons) - ✅ **Cooldown Expires**: Mace becomes usable again --- ⚙️ **Configuration Details** **config.yml Breakdown:** ```yaml cooldown-enabled: true ``` - **Type**: Boolean (`true` or `false`) - **Default**: `true` - **Purpose**: Master toggle for the entire plugin - **Effect**: When `false`, plugin does nothing (useful for temporary disabling) ```yaml cooldown-seconds: 120 ``` - **Type**: Integer (whole number) - **Default**: `120` (2 minutes) - **Range**: Any positive number (recommended: 10-300) - **Purpose**: Duration in real-world seconds - **Conversion**: Automatically multiplied by 20 for Minecraft ticks **Configuration Examples:** | Use Case | cooldown-seconds | Real Time | Best For | |----------|------------------|-----------|----------| | Fast-Paced PvP | 30 | 30 seconds | Quick respawn servers | | Balanced PvP | 60 | 1 minute | Arena/