CraftersBan
CraftersBan organizes bans, mutes, warns, and kicks into a consistent flow for teams that need to sanction players with clarity, traceability, and simple configuration.
CraftersBan is the moderation and punishment enforcement layer of the Crafters ecosystem see the sections below for setup, commands, permissions, configuration, and the developer API.
What's New in CraftersBan 2.9
CraftersBan 2.9 introduces a more reliable punishment-tracking foundation, improved startup behavior, safer optional integrations, and new statistics for server administrators. This release is compatible with Spigot, Paper, and Purpur 1.13–1.21+, as well as BungeeCord and Velocity networks.
Independent Sequential Punishment IDs
Each punishment category now has its own sequential counter. This keeps identifiers organized and makes it easier to identify a record by type.
| Category | Counter |
|---|---|
| Permanent bans | /ban permanent bans (#1, #2, ...) |
| Temporary bans | /tempban or /ban <duration> |
| IP bans | /ipban |
| Player and IP mutes | /mute and /ipmute use separate counters |
| Kicks and warnings | /kick, /warn, and their independent sequences |
The repository layer now exposes getNextTypeId, and punishment dispatch assigns
the correct type_id before inserting a record. Ban, IP ban, mute, IP mute, warn,
and kick commands support this assignment system.
New Statistics and Placeholders
Use these placeholders in supported messages, kick screens, and PlaceholderAPI integrations. Global placeholders do not require a target player.
| Scope | Placeholder | Description |
|---|---|---|
| Messages | %craftersban_total_sanctions% | Total recorded sanctions, including bans, mutes, kicks, and warnings. |
| Messages | %craftersban_total_permanent_bans% | Total permanent bans. |
| Messages | %craftersban_total_temporary_bans% | Total temporary bans. |
| Messages | %craftersban_total_ip_bans% | Total IP bans. |
| Global PAPI | %craftersban_total_punishments%%craftersban_total_sanctions% | Total recorded punishments. |
| Global PAPI | %craftersban_total_permanent_bans%%craftersban_total_perm_bans% | Total permanent bans. |
| Global PAPI | %craftersban_total_temporary_bans%%craftersban_total_temp_bans% | Total temporary bans. |
| Global PAPI | %craftersban_total_ip_bans%%craftersban_total_ipbans% | Total IP bans. |
| Player PAPI | %craftersban_player_total_sanctions%%craftersban_player_total_punishments% | Total punishments recorded for the target player. |
| Player PAPI | %craftersban_player_permanent_bans% | Total permanent bans received by the target player. |
| Player PAPI | %craftersban_player_temporary_bans% | Total temporary bans received by the target player. |
| Player PAPI | %craftersban_player_ip_bans% | Total IP-related punishments associated with the target player. |
Adventure and MiniMessage Formatting
Message delivery now preserves native Adventure components, including gradients and other
MiniMessage styles in the [CraftersBan] prefix. Legacy component re-serialization
was removed from the main send path, and listeners now use component-based delivery for
lockdown, muted-command, mute/IP-mute, blocked-word, and related messages.
Startup, Database, and Packaging Improvements
- Database credentials are loaded correctly during
onEnable()fromsettings/database.ymlthrough typed configuration accessors. - HikariCP, MySQL, and H2 initialization failures now include detailed severe-level stack traces.
- Guice and MaxMind dependencies are shaded and relocated under
dev.xunknown.craftersban.libs.*to reduce plugin class conflicts. - The Maven and CircleCI deployment pipeline was verified for supported Paper 1.20+ and 1.21+ environments.
Safer Optional PlaceholderAPI Integration
PlaceholderAPI remains optional. CraftersBan now starts normally when it is not installed,
without attempting to load PlaceholderAPI classes during module initialization. When the
integration is absent, the console displays a concise notice explaining that PlaceholderAPI
is required for %craftersban_...% placeholders and where to download it.
Installation & Setup
CraftersBan works across multiple servers via a shared database to synchronize punishments.
Standard Installation
- Download
CraftersBan.jarfrom an official source. - Place the file inside the
plugins/folder of your proxy or backend server. - Restart the server to generate the plugin files.
- Configure MySQL for cross-server synchronization (recommended) or use SQLite for a standalone setup.
Consistent and Auditable Sanctions
The goal of CraftersBan is to ensure that every sanction has a reason, a duration, and a visible response to the player. This helps prevent improvised decisions and keeps all staff working under the same criteria.
You can separate temporary, permanent, and warning punishments to build a clear disciplinary policy within your community. Every action is logged and can be viewed via the history command.
Commands List
| Command | Permission | Description |
|---|---|---|
/ban <player> [time] [reason] |
craftersban.ban |
Permanently or temporarily bans a player. |
/ipban <ip/player> [time] [reason] |
craftersban.ipban |
Bans a player by IP address to block alt accounts. |
/mute <player> [time] [reason] |
craftersban.mute |
Permanently or temporarily mutes a player in chat. |
/ipmute <ip/player> [time] [reason] |
craftersban.ipmute |
Mutes all accounts sharing the same IP. |
/warn <player> [reason] |
craftersban.warn |
Issues an administrative warning to a player. |
/tempwarn <player> <time> [reason] |
craftersban.warn |
Issues a temporary warning that expires after the given duration. |
/kick <player> [reason] |
craftersban.kick |
Kicks a player from the server. |
/unban <player/ip> |
craftersban.unban |
Lifts an active ban from a player or IP. |
/unmute <player/ip> |
craftersban.unmute |
Lifts an active mute from a player or IP. |
/unwarn <player> [id] |
craftersban.unwarn |
Removes a warning from a player, optionally by ID. |
/history <player> |
craftersban.history.others |
Views the full paginated punishment history of a player. |
/checkban <player/ip> |
craftersban.checkban |
Checks the current ban status of a player or IP. |
/checkmute <player/ip> |
craftersban.checkmute |
Checks the current mute status of a player or IP. |
/checkwarn <player> |
craftersban.checkwarn |
Lists all active warnings for a player. |
/alts <player/ip> |
craftersban.alts |
Looks up known alternative accounts by IP history. |
/geoip <player/ip> |
craftersban.geoip |
Displays geolocation information for a player's IP. |
/banlist |
craftersban.banlist |
Shows a paginated list of all active bans. |
/mutelist |
craftersban.mutelist |
Shows a paginated list of all active mutes. |
/warnlist |
craftersban.warnlist |
Shows a paginated list of all active warnings. |
/lockdown <on/off> |
craftersban.lockdown |
Activates or deactivates server lockdown mode for maintenance or emergencies. |
/punish <player> |
craftersban.punish |
Opens an interactive punishment GUI to quickly apply sanctions. |
/shadowban <player> |
craftersban.admin |
Silently bans a player without notifying them they are banned. |
/rollback <player> |
craftersban.admin |
Reverts all active punishments for a player at once. |
/mutechat |
craftersban.admin |
Globally mutes chat so only staff can send messages. |
/craftersban reload |
craftersban.admin |
Reloads plugin configuration files without restarting. |
Permission Nodes
| Permission | Granted Access |
|---|---|
craftersban.ban |
/ban and temp-ban commands. |
craftersban.ipban |
/ipban ban by IP address. |
craftersban.mute |
/mute and temp-mute commands. |
craftersban.ipmute |
/ipmute mute by IP address. |
craftersban.warn |
/warn and /tempwarn commands. |
craftersban.kick |
/kick command. |
craftersban.unban |
/unban lift active bans. |
craftersban.unmute |
/unmute lift active mutes. |
craftersban.unwarn |
/unwarn remove active warnings. |
craftersban.history.others |
/history view other players' records. |
craftersban.checkban |
/checkban check ban status. |
craftersban.checkmute |
/checkmute check mute status. |
craftersban.alts |
/alts look up alt accounts by IP. |
craftersban.geoip |
/geoip view player geolocation. |
craftersban.banlist |
/banlist list all active bans. |
craftersban.lockdown |
/lockdown toggle server lockdown. |
craftersban.notify |
Receive staff punishment notifications in chat. |
craftersban.admin |
Grants all permissions including shadowban, rollback, mutechat, and plugin reload. |
Base Configuration
Keeping messages and durations in YAML makes it easy for owners and admins to adjust the system without touching code. You can also define predefined punishment templates.
Predefined Reasons
Developer API
CraftersBan provides an API allowing other plugins to execute punishments, check a player's record, or hook into punishment events (like listening to when a player is banned).
Maven Repository
API Examples
Here are some examples of how to query punishments programmatically.
Events
Use events to listen when staff members issue punishments.
Crafters Development