PunishmentX icon

PunishmentX -----

The professional moderation solution your network deserves. Smart, fast, and interactive.




PUNISHMENTX DOCUMENTATION
Complete technical guide for server administrators — v1.0.4


─────────────────────────────────────────────────────────────────────────

1. INSTALLATION
  1. Download PunishmentX.jar and place it in your /plugins/ folder.
  2. Ensure you are running Paper 1.21.4+ and Java 21. Spigot is NOT supported.
  3. Restart your server. PunishmentX will generate config.yml and messages.yml automatically.
  4. Configure your database in config.yml — SQLite is the default (no setup needed).
  5. For network/multi-server setups, switch to MySQL and fill in the credentials.
─────────────────────────────────────────────────────────────────────────

2. COMMANDS & PERMISSIONS

Moderation Core:
  • /ban <player> [duration] [reason|template] — punishmentx.ban — Bans a player. Supports temporary durations (1h, 7d, perm). Auto-resolves open reports on ban.
  • /mute <player> [duration] [reason|template] — punishmentx.mute — Mutes a player. They see a custom message when trying to chat.
  • /kick <player> [reason] — punishmentx.kick — Kicks a player with a clean disconnect screen. Auto-resolves reports.
  • /warn <player> [duration] [reason|template] — punishmentx.warn — Issues a formal warning. Triggers automated threshold rules if configured.
  • /unban <player> — punishmentx.unban — Lifts an active ban.
  • /unmute <player> — punishmentx.unmute — Lifts an active mute.
  • /unpunish <id> — punishmentx.admin — Rolls back a punishment by its database ID. Marks it as cancelled for audit logs.

Investigation Tools:
  • /history <player> — punishmentx.history — Opens a paginated GUI with the player's full punishment history. Filter by type. Loads asynchronously.
  • /alts <player> — punishmentx.alts — Lists all accounts that ever shared an IP with the target, plus their current ban/mute status.
  • /notes <player> — punishmentx.notes — Add and view private timestamped staff notes on a player.
Report System:
  • /report <player> <reason> — punishmentx.report (default: true) — Players submit reports. High-severity categories (Cheat/Fly) auto-sort to the top.
  • /reports — punishmentx.reports — Staff GUI to view, handle, and close pending player reports.

Staff Utilities:
  • /staff — punishmentx.staff — Toggle Staff Mode. Saves inventory & gamemode, switches to Creative with flight. Gives a dedicated hotbar (Inspect, Freeze, Vanish, History, Random TP, Exit).
  • /freeze <player> — punishmentx.freeze — Freezes a player in place for screenshare. Shows custom titles. If the player disconnects while frozen, they are auto-banned.
  • /sc <message> — punishmentx.staff — Sends a message in the private staff-only chat channel.
  • /chatlock — punishmentx.chatlock — Toggles global chat lock. Non-staff players cannot send messages.
  • /px reload — punishmentx.admin — Reloads the plugin configuration.

─────────────────────────────────────────────────────────────────────────

3. CONFIGURATION — config.yml

Database:
Code (Text):
[/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER]
[COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000][CENTER]settings:
  type: SQLITE        # SQLITE or MYSQL
  mysql:
    host: "localhost"
    port: 3306
    database: "punishmentx"
    username: "root"
    password: ""
 







SQLite creates a local punishmentx.db file — zero configuration needed. Switch to MYSQL for cross-server synchronization on networks. All queries use HikariCP v6 connection pooling and run fully asynchronously.

Automated Punishment Thresholds:
Code (Text):
[/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER]
[COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000][CENTER]punishment-rules:
  enabled: true
  thresholds:
    3:
      action: "BAN"
      duration: "1d"
      reason: "Automated: Reached 3 active warnings."
    5:
      action: "BAN"
      duration: "7d"
      reason: "Automated: Reached 5 active warnings."
 







When a player accumulates the defined number of active warnings, the punishment is applied automatically. Actions: BAN or MUTE. Duration format: 30m, 1h, 7d, perm.

Sanction Templates:
Code (Text):
[/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER]
[COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000][CENTER]templates:
  spam_1h:
    type: "MUTE"
    duration: "1h"
    reason: "Spam / Excessive Messaging"
  toxicity_1d:
    type: "MUTE"
    duration: "1d"
    reason: "Toxic Behavior / Insults"
  cheat_perm:
    type: "BAN"
    duration: "perm"
    reason: "Unfair Advantage / Cheating"
 







Usage: /ban <player> cheat_perm — instantly applies the full template including duration and reason.

Staff Mode:
Code (Text):
[/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER]
[COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000][CENTER]staff-mode:
  vanish-on-join: false       # Auto-vanish staff on join
  disable-item-pickup: true
  disable-block-break: true
  disable-block-place: true
  disable-damage: true
  hide-in-tab: true           # Hide vanished staff from tab list
 








Freeze System:
Code (Text):
[/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER]
[COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000][CENTER]freeze:
  allow-commands: false
  alert-on-quit: true         # Auto-ban if player disconnects while frozen
  title: "<red><bold>FROZEN"
  subtitle: "<gray>Follow the instructions in chat!"
 








Discord Webhooks:
Code (Text):
[/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER]
[COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000][CENTER]discord:
  enabled: false
  webhook-url: "YOUR_WEBHOOK_URL_HERE"
  username: "PunishmentX Logs"
  avatar-url: "https://crafatar.com/renders/head/{uuid}"
 







Every ban, mute, kick, and warn is sent to your Discord staff channel in real-time. Avatars use dynamic {uuid} replacement via Crafatar to display 3D player head renders.

Security:
Code (Text):
[/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER]
[COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000][CENTER]security:
  anti-vpn:
    enabled: true
    api-type: "IP-API"          # IP-API (free) or PROXYCHECK (API key required)
    proxycheck-key: "YOUR_KEY"
    kick: true
    alert-staff: true
  cloud-blacklist:
    enabled: true
    url: "https://github.com/Skytoone/PunishmentX-Cloud/raw/refs/heads/main/blacklist.txt"
 








Ban Screen:
Code (Text):
[/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER]
[COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000][CENTER]ban-screen:
  title: "<red><bold>YOU ARE BANNED"
  color: "red"
  show-staff: true
  footer: "<gray>If you believe this is an error, appeal at:"
 








─────────────────────────────────────────────────────────────────────────

4. CHAT FILTER — config.yml

Code (Text):
[/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER]
[COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000][CENTER]chat-filter:
  enabled: true
  shadow-mute: true             # Player thinks message sent, nobody else sees it

  anti-spam:
    enabled: true
    delay: 2000                 # Min ms between messages

  anti-link:
    enabled: true
    allow-discord: false

  anti-caps:
    enabled: true
    threshold: 0.7              # Block if 70%+ of message is uppercase

  anti-gibberish:
    enabled: true               # Shannon entropy check (detects "asdfghjkl")

  blocked-words:
    - "badword1"

  custom-regex:
    - "(\\d{1,3}\\.){3}\\d{1,3}"      # IPv4 addresses
    - "discord\\.(gg|io|me|li)\\/\\w+" # Discord invites

  dynamic-slowmode:
    enabled: true
    threshold: 10               # Triggers if >10 messages/sec globally
    cooldown: 3000

  action: "WARN"                # WARN, MUTE, or NONE on violation
  alert-staff: true
 







The filter normalizes unicode, leet-speak (1→i, 0→o, 3→e…), and uses fuzzy Levenshtein matching to catch variations of blocked words.

5. AI MODERATION — config.yml

Code (Text):
[/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER]
[COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000][CENTER]ai-moderation:
  enabled: true
  threshold: 0.7                # 0.4=Strict, 0.7=Balanced, 0.9=Lenient
  shadow-mute-bypass: true
  action: "WARN"                # WARN, MUTE, or NONE
  alert-staff: true

  context-analysis:
    enabled: true
    suspicious-threshold: 0.4
    trigger-consecutive: 3      # Alert after 3 consecutive suspicious messages
    cache-limit: 5
    alert-cooldown: 30000       # 30s between staff alerts per player

  weighted-words:
    hate: 0.5
    kill: 0.8
    suicide: 1.0
 







The AI engine scores each message 0.0–1.0 using weighted keywords. It also translates slang (kys → kill yourself) and detects leet-speak bypass attempts (e.g. k1ll). Context analysis tracks message history per player and alerts staff with a confidence % and a clickable /history link.

─────────────────────────────────────────────────────────────────────────

6. MESSAGES — messages.yml

Every user-facing message is fully customizable in messages.yml. Full MiniMessage format is supported including gradients, hex colors, hover events, and click events.

Code (Text):
[/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER]
[COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000][CENTER]prefix: "<gray>[<gradient:#ff5555:#ffaa00>PunishmentX</gradient>] "

punishment:
  ban-success: "<green>User <white>{player} <green>has been successfully banned."
  screen:
    ban: "<red><bold>BANNED FROM NETWORK<br><br><gray>Reason: <white>{reason}<br>
          <gray>Duration: <white>{expiry}<br><br><gray>Appeal Code: <yellow>{code}"

filter:
  ai-alert: "<red><bold>[AI ALERT] <yellow>{player} <gray>flagged for <red>Toxicity ({score})<gray>: <white>{message}"
 








Available placeholders vary per message — {player}, {reason}, {duration}, {operator}, {expiry}, {code}, {appeal_link}, {score}, {confidence}, etc.

─────────────────────────────────────────────────────────────────────────

7. PERMISSIONS REFERENCE

Permission Description Default
punishmentx.ban Ban players op
punishmentx.mute Mute players op
punishmentx.kick Kick players op
punishmentx.warn Warn players op
punishmentx.unban Unban players op
punishmentx.unmute Unmute players op
punishmentx.freeze Freeze players for screenshare op
punishmentx.history View punishment history GUI op
punishmentx.alts Check alternate accounts op
punishmentx.notes View/manage staff notes op
punishmentx.reports View/handle player reports op
punishmentx.report Submit a player report true
punishmentx.staff Staff mode & staff chat op
punishmentx.chatlock Lock/unlock global chat op
punishmentx.admin Full admin access (/unpunish, /reload) op
punishmentx.filter.bypass Bypass chat filter entirely op
punishmentx.anti-vpn.bypass Bypass VPN/Proxy check false


─────────────────────────────────────────────────────────────────────────

8. DURATION FORMAT

Format Example Duration
Xm 30m 30 minutes
Xh 6h 6 hours
Xd 7d 7 days
perm perm Permanent


9. DEVELOPER API
PunishmentX exposes its core managers via a static getInstance() accessor, allowing other plugins to hook into punishments, check player history, and listen to moderation events.

Code (Text):
[/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER][/COLOR][/CENTER]
[COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000]
[CENTER][COLOR=#000000][CENTER]PunishmentX api = PunishmentX.getInstance();

// Check if a player is banned (async)
api.getPunishmentManager().getActiveBan(uuid).thenAccept(ban -> {
    if (ban != null) {
        // Player is banned
    }
});

// Get full punishment history
api.getPunishmentManager().getPunishments(uuid).thenAccept(list -> {
    // list of Punishment objects
});
 









Need help? Join the Discord!

[​IMG]
Resource Information
Author:
----------
Total Downloads: 45
First Release: May 5, 2026
Last Update: May 26, 2026
Category: ---------------
All-Time Rating:
0 ratings
Version -----
Released: --------------------
Downloads: ------
Version Rating:
----------------------
-- ratings