** \ud83d\udcd6 **MaceCooldown Plugin – Complete Description**<\/p>\n
—<\/p>\n
\ud83c\udfaf **Overview**<\/p>\n
**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.<\/p>\n
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.<\/p>\n
—<\/p>\n
\u2728 **Key Features**<\/p>\n
**1. Cooldown System**
\n– \u23f1\ufe0f **Configurable Duration**: Set cooldown time in seconds (default: 120 seconds \/ 2 minutes)
\n– \ud83c\udfae **Native Minecraft API**: Uses official `Player.setCooldown()` method for seamless integration
\n– \ud83d\udd04 **Automatic Conversion**: Seconds automatically converted to Minecraft ticks (1 second = 20 ticks)
\n– \ud83d\udcac **Player Feedback**: Visual messages inform players when cooldown is applied<\/p>\n
**2. Smart Detection**
\n– \ud83c\udfaf **Entity Attack Trigger**: Activates only when a player actually hits an entity
\n– \u270b **Main Hand Detection**: Only triggers when Mace is in the main hand slot
\n– \ud83d\udee1\ufe0f **Entity-Agnostic**: Works with all entity types (players, mobs, bosses, custom entities)<\/p>\n
**3. Configuration System**
\n– \ud83d\udcdd **Fully Customizable**: Edit `config.yml` to suit your server needs
\n– \ud83d\udd0c **Toggle On\/Off**: Completely disable the plugin without uninstalling
\n– \ud83d\udd04 **Hot Reload**: Apply config changes without server restart using `\/macecooldown reload`
\n– \ud83d\udccb **Well-Documented**: Config file includes clear comments for each setting<\/p>\n
**4. Administration**
\n– \ud83d\udc51 **Admin Commands**: `\/macecooldown reload` for managing the plugin
\n– \ud83d\udd10 **Permission System**: `macecooldown.admin` permission (OP by default)
\n– \ud83d\udcca **Status Feedback**: Command shows current configuration when reloading<\/p>\n
**5. Performance & Compatibility**
\n– \u26a1 **Lightweight**: Minimal resource usage, optimized event handling
\n– \ud83c\udfae **Modern Minecraft**: Supports 1.21.1 through 1.21.11
\n– \u2615 **Java 21**: Built with the latest Java LTS for maximum performance
\n– \ud83c\udf10 **Paper\/Spigot**: Compatible with both server platforms<\/p>\n
—<\/p>\n
\ud83c\udfae **Use Cases & Applications**<\/p>\n
**PvP Servers**
\n– **Balance Combat**: Prevent Mace spam in duels and arenas
\n– **Strategic Gameplay**: Players must time their Mace attacks carefully
\n– **Weapon Diversity**: Encourages switching between different weapons
\n– **Skill-Based Fighting**: Rewards tactical thinking over button mashing<\/p>\n
**Survival\/SMP Servers**
\n– **Boss Fights**: Make boss battles more challenging and engaging
\n– **Mob Grinding**: Prevent trivializing mob farms with Mace spam
\n– **Resource Balance**: Encourages varied weapon use and durability management<\/p>\n
**RPG\/Adventure Servers**
\n– **Class Systems**: Integrate with class-based systems for warrior cooldowns
\n– **Quest Balance**: Make quests more challenging by limiting powerful weapons
\n– **Progression Control**: Gate powerful Mace usage behind cooldown mechanics<\/p>\n
**Mini-Games**
\n– **PvP Arenas**: Add strategic depth to combat mini-games
\n– **Custom Events**: Create timed challenges with weapon cooldowns
\n– **Tournament Balance**: Ensure fair fights in competitive events<\/p>\n
—<\/p>\n
\ud83d\udd27 **How It Works**<\/p>\n
**Technical Flow:**<\/p>\n
“`
\n1. Player attacks entity with Mace in main hand
\n \u2193
\n2. Plugin detects EntityDamageByEntityEvent
\n \u2193
\n3. Checks if cooldown-enabled = true
\n \u2193
\n4. Validates attacker is a Player
\n \u2193
\n5. Checks if weapon is Material.MACE
\n \u2193
\n6. Converts config seconds to ticks (seconds \u00d7 20)
\n \u2193
\n7. Applies cooldown using player.setCooldown(Material.MACE, ticks)
\n \u2193
\n8. Player receives feedback message
\n \u2193
\n9. Mace cannot be used until cooldown expires
\n“`<\/p>\n
**Visual Player Experience:**<\/p>\n
– \u2705 **Before Cooldown**: Mace works normally
\n– \u2694\ufe0f **Attack Entity**: Player hits any mob\/player with Mace
\n– \u23f3 **Cooldown Activates**: Mace icon shows cooldown animation
\n– \ud83d\udcac **Message Appears**: “Mace cooldown applied for 120 seconds!”
\n– \u23f1\ufe0f **Wait Period**: Player must wait (or switch weapons)
\n– \u2705 **Cooldown Expires**: Mace becomes usable again<\/p>\n
—<\/p>\n
\u2699\ufe0f **Configuration Details**<\/p>\n
**config.yml Breakdown:**<\/p>\n
“`yaml
\ncooldown-enabled: true
\n“`
\n– **Type**: Boolean (`true` or `false`)
\n– **Default**: `true`
\n– **Purpose**: Master toggle for the entire plugin
\n– **Effect**: When `false`, plugin does nothing (useful for temporary disabling)<\/p>\n
“`yaml
\ncooldown-seconds: 120
\n“`
\n– **Type**: Integer (whole number)
\n– **Default**: `120` (2 minutes)
\n– **Range**: Any positive number (recommended: 10-300)
\n– **Purpose**: Duration in real-world seconds
\n– **Conversion**: Automatically multiplied by 20 for Minecraft ticks<\/p>\n
**Configuration Examples:**<\/p>\n
| Use Case | cooldown-seconds | Real Time | Best For |
\n|———-|——————|———–|———-|
\n| Fast-Paced PvP | 30 | 30 seconds | Quick respawn servers |
\n| Balanced PvP | 60 | 1 minute | Arena\/duels |
\n| **Default** | **120** | **2 minutes** | **General use** |
\n| Hard Survival | 180 | 3 minutes | Challenging PvE |
\n| Boss Battles | 300 | 5 minutes | Epic encounters |<\/p>\n
—<\/p>\n
\ud83d\udccb **Commands & Permissions**<\/p>\n
**Commands:**<\/p>\n
| Command | Aliases | Description | Permission |
\n|———|———|————-|————|
\n| `\/macecooldown reload` | `\/mcd reload` | Reloads config.yml | `macecooldown.admin` |<\/p>\n
**Permissions:**<\/p>\n
| Permission | Default | Description |
\n|————|———|————-|
\n| `macecooldown.admin` | OP | Access to reload command and admin functions |<\/p>\n
**Command Usage:**<\/p>\n
“`bash
\n Reload configuration after editing config.yml
\n\/macecooldown reload
\n\/mcd reload Shorter alias<\/p>\n
Output example:
\n\u2713 MaceCooldown configuration reloaded successfully!
\n Cooldown enabled: true
\n Cooldown duration: 120 seconds
\n“`<\/p>\n
—<\/p>\n
\ud83d\udce6 **Installation Guide**<\/p>\n
**Step 1: Download**
\n– Compile from source using Maven: `mvn clean package`
\n– Or download pre-compiled `.jar` from releases<\/p>\n
**Step 2: Install**
\n1. Stop your server
\n2. Copy `MaceCooldown-1.0.0.jar` to `plugins\/` folder
\n3. Start your server<\/p>\n
**Step 3: Configure**
\n1. Find `plugins\/MaceCooldown\/config.yml` (auto-generated)
\n2. Edit settings as desired
\n3. Run `\/macecooldown reload` (no restart needed!)<\/p>\n
**Step 4: Test**
\n1. Join your server
\n2. Get a Mace: `\/give @s mace`
\n3. Attack any mob\/player
\n4. Observe cooldown activation<\/p>\n
—<\/p>\n
\ud83d\udca1 **Benefits & Advantages**<\/p>\n
**For Server Owners:**
\n– \u2705 **Easy Setup**: Drop-in installation, works immediately
\n– \u2705 **No Database**: Lightweight, no SQL or storage needed
\n– \u2705 **Zero Dependencies**: No external plugins required
\n– \u2705 **Customizable**: Adjust to your server’s needs
\n– \u2705 **Performance**: Negligible impact on TPS<\/p>\n
**For Players:**
\n– \u2705 **Fair Combat**: No weapon spam abuse
\n– \u2705 **Strategic Depth**: More thoughtful combat decisions
\n– \u2705 **Visual Feedback**: Clear cooldown indicator
\n– \u2705 **Balanced PvP**: Skill matters more than spam-clicking<\/p>\n
**For Developers:**
\n– \u2705 **Clean Code**: Well-documented, easy to modify
\n– \u2705 **Modern API**: Uses Paper\/Spigot best practices
\n– \u2705 **Open Source**: Fully customizable
\n– \u2705 **Java 21**: Future-proof implementation<\/p>\n
—<\/p>\n
\ud83d\udda5\ufe0f **System Requirements**<\/p>\n
**Server Requirements:**
\n– **Minecraft Version**: 1.21.1, 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.7, 1.21.8, 1.21.9, 1.21.10, 1.21.11
\n– **Server Software**: Paper (recommended) or Spigot
\n– **Java Version**: Java 21 or higher
\n– **RAM**: Minimal (< 1MB)\n- **Storage**: < 100KB\n\n **Client Requirements:**\n- **No Client Mods Needed**: Works with vanilla clients\n- **Version**: Must match server version\n\n---\n\n \ud83c\udfaf **Plugin Behavior Details**\n\n **What Triggers Cooldown:**\n\u2705 Hitting any entity with Mace in **main hand** \n\u2705 Any successful attack (damage dealt) \n\u2705 PvP attacks (player vs player) \n\u2705 PvE attacks (player vs mob) \n\n **What Does NOT Trigger:**\n\u274c Mace in **off-hand** (only main hand counts) \n\u274c Missing attacks (not hitting anything) \n\u274c Attacking while cooldown is disabled in config \n\u274c Attacking with other weapons \n\u274c Breaking blocks with Mace \n\n **Cooldown Scope:**\n- \ud83c\udfaf **Per-Player**: Each player has their own independent cooldown\n- \ud83d\udd28 **Material-Based**: Cooldown applies to ALL Maces in inventory\n- \ud83d\udd04 **Persistent**: Lasts through death, teleports, dimension changes\n- \u23f1\ufe0f **Timed**: Expires automatically after configured duration\n\n---\n\n \ud83d\udcca **Performance Metrics**\n\n| Metric | Value |\n|--------|-------|\n| Event Listeners | 1 (EntityDamageByEntityEvent) |\n| Memory Footprint | < 1 MB |\n| CPU Impact | Negligible (< 0.1% TPS) |\n| Disk Usage | < 100 KB |\n| Startup Time | < 50ms |\n| Config Reload Time | < 10ms |\n\n---\n\n \ud83d\udd12 **Security & Safety**\n\n- \u2705 **No Exploits**: No known duplication or bypass methods\n- \u2705 **Permission-Based**: Commands protected by permission system\n- \u2705 **Input Validation**: Config values validated on load\n- \u2705 **Error Handling**: Graceful fallback to defaults on invalid config\n- \u2705 **No External Connections**: Completely offline, no telemetry\n\n---\n\n \ud83c\udd9a **Comparison with Alternatives**\n\n| Feature | MaceCooldown | Generic Cooldown Plugins | Manual Config |\n|---------|--------------|-------------------------|---------------|\n| Mace-Specific | \u2705 Optimized | \u26a0\ufe0f Generic | \u274c Complex |\n| Easy Setup | \u2705 1 file | \u26a0\ufe0f Multiple configs | \u274c Requires knowledge |\n| Performance | \u2705 Lightweight | \u26a0\ufe0f Varies | \u2705 N\/A |\n| 1.21+ Support | \u2705 Native | \u26a0\ufe0f May lag behind | \u2705 If supported |\n| Hot Reload | \u2705 Built-in | \u26a0\ufe0f Varies | \u274c Requires restart |\n\n---\n\n \ud83c\udf93 **Example Scenarios**\n\n **Scenario 1: PvP Arena**\n**Setup**: 60-second cooldown \n**Effect**: Players can use Mace once per minute in fights \n**Result**: Encourages weapon switching and tactical planning\n\n **Scenario 2: Survival Server**\n**Setup**: 120-second cooldown (default) \n**Effect**: Mace becomes a powerful but limited tool \n**Result**: Players save Mace for tough mobs, use other weapons for farming\n\n **Scenario 3: Boss Battle Event**\n**Setup**: 300-second cooldown (5 minutes) \n**Effect**: Mace usable once or twice per boss fight \n**Result**: Makes boss fights more challenging and strategic\n\n **Scenario 4: Temporarily Disable**\n**Setup**: Set `cooldown-enabled: false` \n**Effect**: Plugin stays installed but does nothing \n**Result**: Quickly disable for special events, re-enable after\n\n---\n\n \u2753 **FAQ**\n\n**Q: Does this work with custom Maces from other plugins?** \nA: Yes, as long as the item type is `Material.MACE`.\n\n**Q: Can I set different cooldowns for different players?** \nA: Not in this version, but you can modify the code to add permission-based tiers.\n\n**Q: Does it work with off-hand Maces?** \nA: No, only main hand attacks trigger cooldown (design choice for balance).\n\n**Q: What happens if I set cooldown to 0?** \nA: The cooldown will be instant (essentially disabled for that player after attack).\n\n**Q: Is there a maximum cooldown limit?** \nA: No hard limit, but extremely high values (> 1 hour) are impractical.<\/p>\n
**Q: Does this affect Mace durability?**
\nA: No, normal durability loss still applies.<\/p>\n
**Q: Can players bypass with multiple Maces?**
\nA: No, cooldown applies to the Material type, affecting all Maces.<\/p>\n
—<\/p>\n
\ud83d\udcde **Support & Updates**<\/p>\n
**Getting Help:**
\n– Check `config.yml` comments for setting explanations
\n– Review console logs for error messages
\n– Ensure Java 21 and Paper\/Spigot 1.21.x are installed<\/p>\n
—<\/p>\n
\ud83c\udfc6 **Why Choose MaceCooldown?**<\/p>\n
1. \u2705 **Purpose-Built**: Specifically designed for Mace balancing
\n2. \u2705 **Modern**: Uses latest Minecraft and Java versions
\n3. \u2705 **Simple**: One plugin, one config, one command
\n4. \u2705 **Reliable**: Uses native Minecraft API (no hacks)
\n5. \u2705 **Free**: Open source, no hidden costs
\n6. \u2705 **Efficient**: Minimal performance impact
\n7. \u2705 **Flexible**: Customize to your exact needs<\/p>\n
—<\/p>\n
**MaceCooldown** – *Balance Your Combat, Enhance Your Server* \u2694\ufe0f**<\/p>\n