Crafters Development

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.

Global Bans Mutes Warnings Player History IP Punishments

Getting Started

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.
Folder Structure
plugins/
  CraftersBan.jar
  CraftersBan/
    config.yml
    messages.yml
    punishments.yml

Moderation

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.

Daily Usage

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.

Control

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.

Server

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/k6KNKPXsUb"

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"

For Developers

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