** 📖 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:

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)

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:

📋 Commands & Permissions

Commands:

Permissions:

Command Usage:

 Reload configuration after editing config.yml
/macecooldown reload
/mcd reload   Shorter alias

 Output example:
✓ MaceCooldown configuration reloaded successfully!
  Cooldown enabled: true
  Cooldown duration: 120 seconds

📦 Installation Guide

Step 1: Download

• Compile from source using Maven: mvn clean package
• Or download pre-compiled .jar from releases

Step 2: Install

1. Stop your server
2. Copy MaceCooldown-1.0.0.jar to plugins/ folder
3. Start your server

Step 3: Configure

1. Find plugins/MaceCooldown/config.yml (auto-generated)
2. Edit settings as desired
3. Run /macecooldown reload (no restart needed!)

Step 4: Test

1. Join your server
2. Get a Mace: /give @s mace
3. Attack any mob/player
4. Observe cooldown activation

💡 Benefits & Advantages

For Server Owners:

• ✅ Easy Setup: Drop-in installation, works immediately
• ✅ No Database: Lightweight, no SQL or storage needed
• ✅ Zero Dependencies: No external plugins required
• ✅ Customizable: Adjust to your server's needs
• ✅ Performance: Negligible impact on TPS

For Players:

• ✅ Fair Combat: No weapon spam abuse
• ✅ Strategic Depth: More thoughtful combat decisions
• ✅ Visual Feedback: Clear cooldown indicator
• ✅ Balanced PvP: Skill matters more than spam-clicking

For Developers:

• ✅ Clean Code: Well-documented, easy to modify
• ✅ Modern API: Uses Paper/Spigot best practices
• ✅ Open Source: Fully customizable
• ✅ Java 21: Future-proof implementation

🖥️ System Requirements

Server Requirements:

• 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
• Server Software: Paper (recommended) or Spigot
• Java Version: Java 21 or higher
• RAM: Minimal (< 1MB)
• Storage: < 100KB

Client Requirements:

• No Client Mods Needed: Works with vanilla clients
• Version: Must match server version

🎯 Plugin Behavior Details

What Triggers Cooldown: ✅ Hitting any entity with Mace in main hand
✅ Any successful attack (damage dealt)
✅ PvP attacks (player vs player)
✅ PvE attacks (player vs mob)

What Does NOT Trigger: ❌ Mace in off-hand (only main hand counts)
❌ Missing attacks (not hitting anything)
❌ Attacking while cooldown is disabled in config
❌ Attacking with other weapons
❌ Breaking blocks with Mace

Cooldown Scope:

• 🎯 Per-Player: Each player has their own independent cooldown
• 🔨 Material-Based: Cooldown applies to ALL Maces in inventory
• 🔄 Persistent: Lasts through death, teleports, dimension changes
• ⏱️ Timed: Expires automatically after configured duration

📊 Performance Metrics

🔒 Security & Safety

• ✅ No Exploits: No known duplication or bypass methods
• ✅ Permission-Based: Commands protected by permission system
• ✅ Input Validation: Config values validated on load
• ✅ Error Handling: Graceful fallback to defaults on invalid config
• ✅ No External Connections: Completely offline, no telemetry

🆚 Comparison with Alternatives

🎓 Example Scenarios

Scenario 1: PvP Arena Setup: 60-second cooldown
Effect: Players can use Mace once per minute in fights
Result: Encourages weapon switching and tactical planning

Scenario 2: Survival Server Setup: 120-second cooldown (default)
Effect: Mace becomes a powerful but limited tool
Result: Players save Mace for tough mobs, use other weapons for farming

Scenario 3: Boss Battle Event Setup: 300-second cooldown (5 minutes)
Effect: Mace usable once or twice per boss fight
Result: Makes boss fights more challenging and strategic

Scenario 4: Temporarily Disable Setup: Set cooldown-enabled: false
Effect: Plugin stays installed but does nothing
Result: Quickly disable for special events, re-enable after

❓ FAQ

Q: Does this work with custom Maces from other plugins?
A: Yes, as long as the item type is Material.MACE.

Q: Can I set different cooldowns for different players?
A: Not in this version, but you can modify the code to add permission-based tiers.

Q: Does it work with off-hand Maces?
A: No, only main hand attacks trigger cooldown (design choice for balance).

Q: What happens if I set cooldown to 0?
A: The cooldown will be instant (essentially disabled for that player after attack).

Q: Is there a maximum cooldown limit?
A: No hard limit, but extremely high values (> 1 hour) are impractical.

Q: Does this affect Mace durability?
A: No, normal durability loss still applies.

Q: Can players bypass with multiple Maces?
A: No, cooldown applies to the Material type, affecting all Maces.

📞 Support & Updates

Getting Help:

• Check config.yml comments for setting explanations
• Review console logs for error messages
• Ensure Java 21 and Paper/Spigot 1.21.x are installed

🏆 Why Choose MaceCooldown?

1. ✅ Purpose-Built: Specifically designed for Mace balancing
2. ✅ Modern: Uses latest Minecraft and Java versions
3. ✅ Simple: One plugin, one config, one command
4. ✅ Reliable: Uses native Minecraft API (no hacks)
5. ✅ Free: Open source, no hidden costs
6. ✅ Efficient: Minimal performance impact
7. ✅ Flexible: Customize to your exact needs

MaceCooldown - Balance Your Combat, Enhance Your Server ⚔️**