BS-BanHammer

[3.0.0] - 2026-01-08

🎉 Main Features

Ban Presets System (NEW!)

Shift + Right-Click to switch between predefined ban presets
Actionbar feedback shows current preset when switching
Sound feedback individually configurable per preset
Unlimited presets definable in config.yml
Each preset with own duration, reason, IP-ban flag and sound
Per-player tracking of active preset
Configurable switch cooldown (250ms default)
Works everywhere: on players, blocks or in the air

Kick/Jail Presets System (NEW!)

Shift + Left-Click to switch between predefined kick/jail presets
Mix kicks and jails in one preset list (no duration = kick, with duration = jail)
Actionbar feedback shows current preset when switching
Sound feedback individually configurable per preset
Unlimited presets definable in config.yml
Per-player tracking of active kick/jail preset
Same configurable cooldown as ban presets
Left-Click on Player executes kick or jail with active preset

Modrinth Update Checker (NEW!)

Automatic update checking on server startup
Periodic checks with configurable interval (default: 6 hours)
Admin notifications on login (permission: banhammer.updatenotify)
Semantic version comparison
Download URLs and changelog links
Rate limiting (max 1 check per hour)
Fully configurable in config.yml

Database System

SQLite support for single-server (no setup required)
MySQL support for multi-server networks
Complete ban history with detailed tracking
Automatic schema creation and migrations
Connection pooling with HikariCP for optimal performance
WAL mode for SQLite (better concurrency)
Optimized indexes for fast queries

Auto-Unban System

Automatic unbanning when temporary bans expire
Configurable check intervals (default: 60 seconds)
Asynchronous processing (doesn't block main thread)
Event triggers for external plugins
Discord notifications on auto-unbans
Supports temp-bans, temp-mutes and jail times

Discord Integration

Webhook-based notifications
Color-coded embeds for different actions:
- 🔴 Bans (Red)
- 🟠 Kicks (Orange)
- 🟢 Unbans (Green)
- 🟡 Mutes (Yellow)
Staff names, player names, duration and reason in embeds
Server names for multi-server setups
Configurable which events are sent
NEW: Discord now works independently of database (no database required)
NEW: Discord webhook reinitializes on /bh reload without server restart

Essentials Jail Integration (NEW!)

Soft Dependency: Optional Essentials plugin integration via softdepend in plugin.yml
Reflection-Based: No hard dependency - uses reflection to access Essentials API
Smart Preference System: Automatically uses Essentials jail if available, falls back to built-in
Automatic Detection: Checks for Essentials on startup and enables integration
Built-in Fallback: Own jail system continues to work if Essentials not installed
Seamless Integration: Works with existing Essentials jail configurations
Debug Logging: Comprehensive DEBUG TELEPORT logs for troubleshooting

✨ New Features

Extended Punishment Types

Mute System: Blocks chat and commands
- Permanent and temporary
- Cache-based for performance
- Shows remaining time
Jail System: Locks players in place
- Configurable jail location via /setjail
- Prevents teleportation and movement
- Optional: Prevents damage and commands
Warning System: Warnings with auto-ban
- Counts warnings per player
- Auto-ban after X warnings (configurable)
- Non-active punishment (only tracking)

Ban Appeals System

Players can submit appeals via /appeal <text>
Cooldown system (default: 24 hours)
Maximum appeals per punishment (default: 3)
Staff can approve/deny appeals
Discord notifications for new appeals
Appeal status tracking (PENDING, APPROVED, DENIED)

Statistics & Leaderboards

Tracking of all punishments per staff member
Total counts: Bans, kicks, mutes, warnings
Leaderboard system
GUI view via /bh stats
Exportable via REST API

GDPR & Privacy Features

IP anonymization with 4 levels:
- NONE: Full IP storage
- PARTIAL: Last octet removed (192.168.1.0)
- HASH: One-way hash with server salt
- FULL: Complete masking
Automatic salt generation
Salt validation (min. 16 characters, 3 character types)
Configurable data retention

🔧 Improvements

Performance Optimizations

Asynchronous database initialization (no longer blocks server start)
loadActiveMutes() loads mutes into cache on startup
Optimized warning count via SELECT COUNT(*) instead of N+1 query
SQLite connection pool set to 1 (single-writer)
Race condition in getActiveMute() fixed via computeIfPresent()
Composite indexes for common query patterns

Error Handling & Robustness

Separate try-catch blocks in ban flow (prevents partial state)
Improved Discord webhook validation
- URL format check
- Clear error messages
- Graceful degradation
Robust duration parsing
- Supports: "7d", "1h30m", "PT24H", "permanent"
- Case-insensitive
- Warnings for invalid format
Improved IPv6 validation via InetAddress

Thread-Safety

Mute cache removes expired entries atomically
Switch cooldown via ConcurrentHashMap
Database operations fully async
Events fired on main thread

📝 Commands

New commands:

/bh appeals - Shows pending appeals
/bh approve <id> [response] - Approves appeal
/bh deny <id> [response] - Denies appeal
/bh stats [player] - Shows statistics
/bh reload - IMPROVED: Now reinitializes Discord webhook and Database connection
/appeal <text> - Submits appeal
/mute <player> <duration> [reason] - Mutes player
/unmute <player> [reason] - Unmutes player
/jail <player> <duration> [reason] - Jails player (uses Essentials if available)
/unjail <player> [reason] - Releases from jail (works without database)
/setjail - Sets jail location (only needed for built-in jail)
/warn <player> [reason] - Warns player

🔑 Permissions

New permissions:

banhammer.appeals - Can view appeals
banhammer.appeals.review - Can review appeals
banhammer.appeal - Can submit appeals (default: true)
banhammer.mute - Can mute players
banhammer.jail - Can jail players
banhammer.warn - Can warn players
banhammer.stats - Can view statistics
banhammer.updatenotify - Receive update notifications

🎨 API

Custom Events

PlayerPunishEvent - Fired BEFORE punishment (cancellable)
PlayerPunishedEvent - Fired AFTER successful punishment
PlayerUnpunishedEvent - Fired when punishment removed

PunishmentManager API

// Fully async with CompletableFuture
pm.banPlayer(staff, victim, reason, duration, ipBan)
pm.mutePlayer(staff, victim, reason, duration)
pm.jailPlayer(staff, victim, reason, duration)
pm.warnPlayer(staff, victim, reason)
pm.getHistory(playerUuid, limit)
pm.getWarningCount(playerUuid)

Database Interface

Abstract interface for SQLite/MySQL
All operations via CompletableFuture
Prepared statements against SQL injection

🐛 Bug Fixes

Critical Bug Fixes

✅ Expired Punishment Spam (CRITICAL): Fixed infinite "Found 1 expired punishment(s), processing..." spam
- Root Cause: NULL UUID handling in deactivatePunishment() caused NullPointerException
- Fix: Added null check for staffUuid in SQLiteDatabase.java:396 and MySQLDatabase.java:406
- Impact: Prevented database corruption and console spam
✅ Jail Auto-Release Not Working (CRITICAL): Players weren't automatically released after jail time expired
- Root Cause: Missing JAIL case in UnbanScheduler switch statement
- Fix: Added JAIL case to UnbanScheduler.java:110-114
- Impact: Jail time now properly expires and releases players automatically
✅ Unjail Required Database: /unjail command didn't work without database even with Essentials
- Root Cause: Database check blocked everything in handleUnjail()
- Fix: Removed database requirement, calls JailManager.releasePlayer() directly
- Impact: Unjail now works with both Essentials and built-in jail without database
✅ Resourcepack Not Loading: Resourcepack wasn't being sent to players
- Root Cause: Empty URL and hash in config.yml
- Fix: Added proper URL and SHA-1 hash to config.yml
- Impact: Resourcepack now loads correctly for all players

Translation & Localization Fixes

✅ Incomplete Translations: Many messages were hardcoded in German
- Fix: Added 30+ new message keys to messages_de.yml and messages_en.yml
- Fix: Replaced 28 hardcoded strings across PunishmentCommands.java (15), BanHammerCommand.java (11), and AppealCommand.java (2)
- Fix: Extended Messages.java with 30+ new methods
- Impact: Plugin is now fully translatable, no hardcoded strings remaining

Reload Functionality Fixes

✅ Discord Not Reinitializing on Reload: Discord webhook required server restart after config changes
- Fix: Added reinitializeDiscord() method in BanHammerPlugin.java
- Impact: Discord webhook now reloads with /bh reload command
✅ Database Not Reinitializing on Reload: Database connection required server restart after config changes
- Fix: Added reinitializeDatabase() method in BanHammerPlugin.java
- Impact: Database connection now reloads with /bh reload command

Essentials Integration Fixes

✅ Essentials Jail Teleport Errors: "wrong number of arguments" and "Location.getLocation()" errors
- Fix: Fixed reflection to get Location directly from getJail() method
- Fix: Get jail list from Essentials and use first available jail
- Impact: Essentials jail integration now works correctly
✅ Jail Messages Not Colored: Jail/unjail messages showed raw MiniMessage tags instead of colors
- Fix: Added proper jail/unjail message calls to both Essentials and built-in jail paths
- Impact: Messages now display with proper colors

Logging Improvements

✅ Console Spam: Too many DEBUG messages during normal operation
- Fix: Reduced routine logs to DEBUG level, only show important info (Jail, Essentials, Discord, critical problems)
- Impact: Console is now clean and readable
✅ Missing Debug Logs for Troubleshooting: Hard to diagnose teleport and resourcepack issues
- Fix: Added comprehensive DEBUG TELEPORT logs (EssentialsJailIntegration.java:107-133)
- Fix: Added comprehensive DEBUG RESOURCEPACK logs (ResourcePackSender.java)
- Impact: Easier troubleshooting with debug mode enabled

Previous Bug Fixes

✅ Temporal bans were permanent → Duration parsing fixed
✅ Discord webhook no error messages → Validation added
✅ Server start blocks on DB init → Async initialization
✅ Mute cache memory leak → UnbanScheduler cleans cache
✅ Race condition in getActiveMute() → Atomic operation
✅ IPv6 validation incomplete → InetAddress validation
✅ SQL indexes wrongly defined → Separate CREATE INDEX statements
✅ N+1 query for warning count → Optimized COUNT query
✅ Resource leaks in ban flow → Separate error handling

🔄 Breaking Changes

No breaking changes - Version 3.0.0 is fully backwards compatible with 2.x configurations.

New features are optional and must be explicitly enabled:

database:
  enabled: false  # Default: off
discord:
  enabled: false  # Default: off
presets:
  # Created automatically if not present
kickJailPresets:
  # Created automatically if not present
updateChecker:
  enabled: true  # Default: on

📦 Dependencies

Required:

Paper API: 1.21.1-R0.1-SNAPSHOT
Java: 21
HikariCP: 5.1.0
SQLite JDBC: 3.47.1.0
MySQL Connector/J: 9.1.0
Gson: 2.11.0
Discord Webhooks: 0.8.4

Optional (Soft Dependencies):

Essentials (any recent version) - For enhanced jail system integration

📋 Technical Details

Code Quality

Modern Java 21 features (Records, Text Blocks, Switch Expressions)
Thread-safe implementations
Async-first approach with CompletableFuture
Event-based architecture
Clean code principles

Architecture

Manager pattern for business logic
Database abstraction layer
Event system for extensibility
Preset system for flexible ban types
Cache layer for performance

BS-BanHammer 3.0.0