CraftersBan Wiki | Crafters Development

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.

Installation & Setup

CraftersBan works across multiple servers via a shared database to synchronize punishments.

Standard Installation

Download CraftersBan.jar from 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.

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);
}