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:

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