⚡ BanHammer 3.0 - Enhanced Edition

The most feature-rich ban hammer plugin for Paper 1.21.x servers

Transform your moderation workflow with a dramatic ban hammer that strikes players with lightning, particles, and sound effects - all while maintaining a complete punishment database and Discord integration.

---

🎯 What Makes BS-BanHammer Special?

🔨 Dual-Action Preset System

Ban Presets (Shift + Right-Click):

• Cycle through unlimited predefined ban types on-the-fly
• Each preset has custom duration, reason, IP-ban option, and sound
• Actionbar feedback shows active preset
• No commands needed - just shift-click and ban!

Kick/Jail Presets (Shift + Left-Click):

• Mix instant kicks and timed jails in one preset list
• Left-click players to execute with active preset
• Perfect for quick moderation without typing commands
• Separate preset tracking from ban presets

Example Workflow:

1. Shift + Right-Click → Switch to "7 Day Ban" preset
2. Right-Click on griefer → Instantly banned for 7 days with lightning!
3. Shift + Left-Click → Switch to "30 Min Jail" preset
4. Left-Click on spammer → Jailed for 30 minutes

⚡ Dramatic Visual Effects

Every punishment comes with spectacular effects:

• Lightning strikes at player location
• Thunder & explosion sounds for maximum impact
• Particle effects (critical hits & smoke)
• Optional knockback for extra drama
• Fully configurable per preset

📊 Complete Database System

SQLite or MySQL - Your Choice:

• SQLite for single-server setups (zero configuration)
• MySQL for multi-server networks (shared ban database)
• Complete punishment history tracking
• Staff statistics and leaderboards
• Automatic cleanup of expired punishments
• GDPR-compliant IP anonymization

🔄 Auto-Unban Scheduler

Set it and forget it:

• Automatic unbanning when temporary punishments expire
• Works for temp-bans, temp-mutes, and jail sentences
• Configurable check intervals (default: 60 seconds)
• Discord notifications on auto-unbans
• Event system for external plugins

🎭 Extended Punishment Types

Beyond Bans:

• Mute System - Blocks chat and commands (permanent or temporary)
• Jail System - Locks players in place with Essentials integration
• Warning System - Auto-ban after X warnings (configurable)
• IP Bans - Network-wide bans with anonymization options
• Appeals - Let players submit unban requests

🌐 Essentials Jail Integration

Smart Integration (NEW in 3.0!):

• Soft dependency - no hard requirement
• Automatically uses Essentials jails if available
• Falls back to built-in jail system
• Works with existing Essentials jail configurations
• Reflection-based - no version conflicts

💬 Discord Webhook Integration

Real-Time Moderation Logs:

• Color-coded embeds for different actions
• Rich information: player, staff, reason, duration
• Works independently of database
• Configurable per event type (bans, kicks, mutes, unbans, appeals)
• Automatic notifications on punishment expiry

🌍 Multi-Language Support

Fully translated:

• 🇩🇪 German - Vollständig übersetzt
• 🇬🇧 English - Fully translated
• All messages configurable in YAML files
• Easy to add custom languages

🔌 Developer-Friendly API

Custom Events:

PlayerPunishEvent      // Cancellable, fired before punishment
PlayerPunishedEvent    // Fired after successful punishment
PlayerUnpunishedEvent  // Fired when punishment removed

PunishmentManager API:

pm.banPlayer(staff, victim, reason, duration, ipBan)
pm.mutePlayer(staff, victim, reason, duration)
pm.jailPlayer(staff, victim, reason, duration)
pm.getHistory(playerUuid, limit)

REST API:

• Full punishment database access via HTTP
• JWT token authentication
• Rate limiting built-in
• Perfect for web dashboards

📈 Statistics & Appeals

Track Everything:

• Staff leaderboards (most bans, kicks, etc.)
• Player punishment history
• Active punishment counts
• Exportable via API

Appeal System:

• Players can submit appeals via /appeal <text>
• Cooldown system prevents spam
• Staff review with /bh approve/deny
• Discord notifications for new appeals

---

🚀 Quick Start

1. Install the plugin in your plugins/ folder
2. Start your server (auto-generates config)
3. Give yourself the hammer: /bh give <player>
4. Configure presets in config.yml (optional)
5. Use the hammer:
   • Shift + Right-Click to switch ban presets
   • Right-Click player to ban with active preset
   • Shift + Left-Click to switch kick/jail presets
   • Left-Click player to kick/jail with active preset

---

📝 Commands Overview

Command	Description
/bh give <player>	Give the Ban Hammer item
/bh reload	Reload config (reinitializes Discord & DB)
/bh history <player>	View punishment history
/bh unban <player>	Manually unban a player
/bh stats [player]	View moderation statistics
/bh appeals	View pending appeals
/mute <player> <duration>	Mute a player
/jail <player> <duration>	Jail a player
/warn <player> [reason]	Warn a player

Full command list in README.md

---

⚙️ Configuration Highlights

Ban Presets Example:

presets:
  warning:
    displayName: "Warning Ban"
    reason: "First offense"
    duration: "1h"
    ipBan: false
    sound: "BLOCK_NOTE_BLOCK_PLING"

  serious:
    displayName: "7 Day Ban"
    reason: "Serious rule violation"
    duration: "7d"
    ipBan: false
    sound: "BLOCK_NOTE_BLOCK_BASS"

  permanent:
    displayName: "Permanent Ban"
    reason: "Permanently banned"
    duration: "permanent"
    ipBan: true
    sound: "BLOCK_ANVIL_LAND"

Kick/Jail Presets Example:

kickJailPresets:
  quick_kick:
    displayName: "Quick Kick"
    reason: "Kicked from server"
    # No duration = instant kick

  jail_30m:
    displayName: "30 Min Jail"
    reason: "Jailed for 30 minutes"
    duration: "30m"  # Has duration = jail

---

🔒 Security & Privacy

• GDPR Compliant - IP anonymization with 4 levels
• Permission-based - Granular permission system
• SQL Injection Protected - Prepared statements everywhere
• Bypass Protection - Immune players can't be banned
• Self-Protection - Can't ban yourself
• Cooldown System - Prevents spam abuse

---

🌟 What's New in 3.0?

Major Features:

• ✨ Ban Presets System with preset cycling
• ✨ Kick/Jail Presets System (separate from ban presets)
• ✨ Essentials Jail Integration
• ✨ Modrinth Update Checker
• ✨ Complete translation system (DE/EN)
• ✨ Discord works without database requirement
• ✨ Database & Discord reinitialize on reload

Bug Fixes:

• ✅ Fixed jail auto-release not working
• ✅ Fixed expired punishment spam
• ✅ Fixed unjail requiring database
• ✅ Fixed resourcepack not loading
• ✅ Removed all hardcoded strings

---

📦 Requirements

• Server: Paper 1.21.x or higher
• Java: 21 or higher
• Optional: MySQL Server (for MySQL mode)
• Optional: Essentials Plugin (for enhanced jail system)

---

📜 License

MIT License - Free for all server types (commercial & non-commercial)

---