Official Documentation

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.

CategoryCounter
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.

ScopePlaceholderDescription
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() from settings/database.yml through 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

  1. Download CraftersBan.jar from an official source.
  2. Place the file inside the plugins/ folder of your proxy or backend server.
  3. Restart the server to generate the plugin files.
  4. Configure MySQL for cross-server synchronization (recommended) or use SQLite for a standalone setup.
plugins/ CraftersBan.jar CraftersBan/ config.yml messages.yml punishments.yml

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.

# CraftersBan Configuration storage: type: "mysql" # Recommended for proxy networks punishments: broadcast: true require-reason: true silent-prefix: "-s" # Example: /ban -s Player Cheating ip-punishments-enabled: true appeals: enabled: true url: "https://discord.gg/5srYxV4Z4t"

Predefined Reasons

# punishments.yml template templates: cheating: duration: "30d" message: "Unfair Advantage / Cheating" spam: duration: "2h" message: "Chat Spam or Flood" toxicity: duration: "7d" message: "Toxic Behavior"

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

<repository> <id>crafters-repo</id> <url>https://repo.craftersdevelopment.net/releases</url> </repository> <dependency> <groupId>dev.xunknown</groupId> <artifactId>CraftersBan-API</artifactId> <version>2.0</version> <scope>provided</scope> </dependency>

API Examples

Here are some examples of how to query punishments programmatically.

import dev.xunknown.craftersban.api.CraftersBanAPI; import dev.xunknown.craftersban.api.PunishmentRequest; import dev.xunknown.craftersban.models.PunishmentType; import org.bukkit.Bukkit; import org.bukkit.plugin.RegisteredServiceProvider; // Obtain the API via Bukkit's ServicesManager RegisteredServiceProvider<CraftersBanAPI> provider = Bukkit.getServicesManager().getRegistration(CraftersBanAPI.class); if (provider != null) { CraftersBanAPI api = provider.getProvider(); // Check if a player has an active ban api.isActivePunishment(playerUUID, PunishmentType.BAN) .thenAccept(isBanned -> { if (isBanned) { Bukkit.getLogger().info("Player is banned."); } }); // Issue a 30-day ban via the API (async, full pipeline) PunishmentRequest request = PunishmentRequest.builder() .target(playerUUID) .executor(null) // null = CONSOLE .type(PunishmentType.BAN) .duration(30L * 24 * 60 * 60 * 1000) // 30 days in ms .reason("Auto-Ban: Unfair Advantage") .build(); api.dispatchPunishment(request).thenAccept(result -> { if (result.isSuccessful()) { Bukkit.getLogger().info("Ban applied successfully!"); } }); }

Events

Use events to listen when staff members issue punishments.

@EventHandler public void onPlayerPunished(PlayerPunishEvent event) { String targetName = event.getTargetName(); String staffName = event.getStaffName(); String type = event.getPunishmentType().name(); // BAN, MUTE, WARN System.out.println(staffName + " just issued a " + type + " to " + targetName); }