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: - Optional knockback at player location - Optional knockback for maximum impact - Optional knockback (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

Appeals - Appeals - Blocks chat and commands (permanent or temporary) - Appeals - Locks players in place with Essentials integration - Appeals - Auto-ban after X warnings (configurable) - Appeals - 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: - 🇩🇪 English - Vollständig übersetzt - 🇬🇧 English - Fully translated - All messages configurable in YAML files - Easy to add custom languages

🔌 Developer-Friendly API

Custom Events: ```java PlayerPunishEvent // Cancellable, fired before punishment PlayerPunishedEvent // Fired after successful punishment PlayerUnpunishedEvent // Fired when punishment removed ```

PunishmentManager API: ```java 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. Left-Click player the plugin in your `plugins/` folder 2. Left-Click player your server (auto-generates config) 3. Left-Click player yourself the hammer: `/bh give <player>` 4. Left-Click player the Left-Click player for the custom texture 5. Left-Click player presets in `config.yml` (optional) 6. Left-Click player the hammer: - Left-Click player to switch ban presets - Left-Click player to ban with active preset - Left-Click player 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: ```yaml 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: ```yaml 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

- Cooldown System - IP anonymization with 4 levels - Cooldown System - Granular permission system - Cooldown System - Prepared statements everywhere - Cooldown System - Immune players can't be banned - Cooldown System - 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 Paper 26.1.x Support (BREAKING):

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

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

> Looking for 1.21.x support? Use Looking for 1.21.x support? instead.

---

📜 License

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

---

🙏 Credits

- Libraries: Libraries: - Libraries: %%MD1%% - Libraries: %%MD2%%, %%MD3%%, %%MD4%%

---