MaceGuard

A comprehensive Minecraft plugin that detects and prevents suspicious mace damage patterns to maintain fair gameplay with advanced detection algorithms and user-friendly configuration.

✨ Features

🔍 Advanced Detection

• Multi-Algorithm Detection: Combines multiple detection methods for accuracy
• Real-time Monitoring: Monitors mace damage patterns in real-time
• Fall Distance Correlation: Validates damage against fall distance
• Attack Pattern Analysis: Tracks suspicious attack patterns over time
• Damage Consistency Checks: Detects artificially consistent damage values

⚙️ Configuration & Management

• User-Friendly Config: Beautiful, well-documented configuration file
• Dynamic Reloading: Reload configuration without server restart
• Configurable Thresholds: Fine-tune detection sensitivity
• Advanced Settings: Performance optimization and debug options

🛡️ Security & Actions

• Automatic Punishments: Configurable kick/ban thresholds
• Admin Alerts: Real-time notifications for administrators
• Permission System: Bypass detection for trusted players
• Violation Decay: Automatic violation cleanup over time

📊 Statistics & Monitoring

• Comprehensive Stats: Track detection performance
• Debug Mode: Detailed logging for troubleshooting
• Player Tracking: Monitor individual player violations
• Performance Metrics: Built-in performance monitoring

🚀 Installation

1. Download the latest MaceGuard.jar from releases
2. Place it in your server's plugins/ directory
3. Restart your server
4. Configure the plugin using /maceguard reload after editing config.yml
5. Grant permissions to administrators

⚙️ Configuration

The plugin creates a comprehensive config.yml file with organized sections:

Detection Settings

detection:
  # Primary detection threshold
  suspicious-damage-threshold: 15.0
  
  # Advanced detection parameters
  advanced:
    damage-consistency-threshold: 3
    fall-distance-threshold: 2.0
    attack-time-window-ms: 5000
    pattern-analysis-enabled: true

Violation Management

violation-management:
  max-violations: 5
  violation-decay-time-ms: 300000  # 5 minutes
  cleanup-interval-minutes: 10

Actions & Punishments

actions:
  alert-admins: true
  kick:
    enabled: true
    threshold: 3
    message: "Custom kick message"
  ban:
    enabled: false
    threshold: 5
    duration-hours: 24  # 0 for permanent

Performance & Debug

performance:
  async-processing: true
  cache-size: 1000
  cleanup-interval-minutes: 10

debug:
  enabled: false
  log-level: "INFO"
  detailed-logging: false

Commands

Command	Permission	Description
/maceguard help	maceguard.admin	Show help message
/maceguard check <player>	maceguard.admin	Check player violations
/maceguard clear <player>	maceguard.admin	Clear player violations
/maceguard reload	maceguard.admin	Reload configuration
/maceguard info	maceguard.admin	Show plugin information

Aliases: /mg, /maceg

Permissions

Permission	Default	Description
maceguard.admin	op	Access to admin commands
maceguard.alerts	op	Receive violation alerts
maceguard.bypass	false	Bypass detection (for testing)

How It Works

Detection Methods

1. Damage Threshold Analysis

   • Compares actual damage against calculated maximum legitimate damage
   • Factors in enchantments, potion effects, and fall distance
   • Flags damage that significantly exceeds expected values

2. Fall Distance Correlation

   • Validates that high damage corresponds to appropriate fall distance
   • Detects cases where high damage occurs without sufficient fall
   • Accounts for legitimate mace mechanics

3. Pattern Recognition

   • Identifies consistent damage values that indicate artificial enhancement
   • Tracks attack patterns over time
   • Detects the characteristic ~64 damage signature of MaceDMG

4. Behavioral Analysis

   • Monitors for impossible damage scenarios
   • Validates damage against game physics
   • Cross-references multiple data points for accuracy

Violation System

• Progressive Penalties: Violations accumulate over time
• Automatic Decay: Violations decrease over time if no new violations occur
• Configurable Thresholds: Customizable violation limits before punishment
• Multiple Actions: Support for kicks, bans, and administrative alerts

Technical Details

Supported Versions

• Minecraft: 1.21+
• Server Software: Spigot, Paper, and derivatives
• Java: 21+

Performance

• Memory Usage: Minimal memory footprint with efficient data structures
• CPU Impact: Optimized event handling with negligible performance impact
• Network: No additional network overhead

Accuracy

• False Positives: Extremely low false positive rate through multi-layered detection
• Detection Rate: High detection accuracy for MaceDMG hack variants
• Bypass Resistance: Robust against common bypass attempts

Troubleshooting

Common Issues

Q: Players are getting false positives A: Adjust the suspicious-damage-threshold in config.yml to a higher value

Q: The plugin isn't detecting obvious cheaters A: Lower the detection thresholds or enable debug mode to analyze damage patterns

Q: Too many alerts are being sent A: Increase max-violations or adjust violation-decay-seconds

Debug Mode

Enable debug logging in config.yml:

debug:
  enabled: true
  log-all-attacks: true
  log-damage-calculations: true

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, bug reports, or feature requests:

• Create an issue on GitHub
• Join our Discord server
• Contact the development team

Changelog

Version 1.0

• Initial release
• MaceDMG detection system
• Administrative commands
• Configurable violation system
• Real-time alerts
• High-performance optimization

---

Note: This plugin is specifically designed to combat the MaceDMG cheat. For comprehensive anti-cheat protection, consider using this plugin alongside other anti-cheat solutions.