PunishmentX - Speedgot

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

Download PunishmentX.jar and place it in your /plugins/ folder.
Ensure you are running Paper 1.21.4+ and Java 21. Spigot is NOT supported.
Restart your server. PunishmentX will generate config.yml and messages.yml automatically.
Configure your database in config.yml — SQLite is the default (no setup needed).
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):

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):

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):

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

Staff Mode:

Code (Text):

Freeze System:

Code (Text):

Discord Webhooks:

Code (Text):

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):

Ban Screen:

Code (Text):

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

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 <gray>Reason: <white>{reason} 
<gray>Duration: <white>{expiry} <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):

Need help? Join the Discord!

View on SpigotMC

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