BS-BanHammer

BanHammer 4.0.0 - Enhanced Edition

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

---

🎨 Resource Pack

The BanHammer texture pack is available as a separate download:

BS-BanHammer Resource Pack

Staff members will see a clickable download hint on join (configurable in config.yml).

---

🎯 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)

📈 Statistics & Appeals

Track Everything:

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

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. Download the Resource Pack for the custom texture
5. Configure presets in config.yml (optional)
6. 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

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 4.0.0?

Paper 26.1.x Support (BREAKING):

• Targets Paper 26.1.2+ with the new Minecraft versioning
• Requires Java 25
• All deprecated APIs modernized (Adventure Components, no more legacy color codes)
• Smart update checker filters by game version (1.21.x users won't see 4.x updates)
• Resource pack moved to separate download

Previous Major Features:

• Folia Support (dual Paper/Folia compatibility)
• Ban Presets System with preset cycling
• Kick/Jail Presets System (separate from ban presets)
• Essentials Jail Integration
• Modrinth Update Checker with game version filtering
• Complete translation system (DE/EN)
• Discord works without database requirement

---

📦 Requirements

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

Looking for 1.21.x support? Use BanHammer v3.1.1 instead.

---

📜 License

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

---

🙏 Credits

• Plugin Development: BoondockSulfur
• Resource Pack: BS-BanHammer Resource Pack
• Libraries: HikariCP, discord-webhooks, Adventure

---