⚡ BanHammer 3.1.0 - Enhanced Edition

The most feature-rich ban hammer plugin for Paper & Folia 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:

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

Install the plugin in your plugins/ folder
Start your server (auto-generates config)
Give yourself the hammer: /bh give <player>
Configure presets in config.yml (optional)
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.1.0?

Folia Support (NEW!):

✨ Full Folia compatibility - runs on Paper AND Folia from a single JAR
✨ Automatic platform detection at startup
✨ All schedulers, teleports, and player operations use the correct thread

Previous Major Features (3.0):

✨ 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 (3.0.1):

✅ Fixed unjail not teleporting players back to original location
✅ Fixed thread-unsafe SimpleDateFormat
✅ Fixed unban/unmute not finding temp-bans/temp-mutes
✅ Fixed Discord webhook shutdown hook leak on reload
✅ Fixed IPv6 validation, HttpURLConnection leak, memory leaks

📦 Requirements

Server: Paper or Folia 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)

**⭐ If you enjoy BanHammer, please leave a rating! ⭐** Made with ❤️ for the Minecraft community

BS BanHammer