BetterPunish

BetterPunish v1.4.0 - The Staff Desk Update

Punishments are rarely finished the moment they are issued. Reasons need correcting, durations change, and older cases need checking without digging through YAML files. Version 1.4.0 puts that work in one place. ---

New Features

Edit Existing Punishments

The new /punishedit <id> command opens an editor for an existing punishment. You can also make the change directly from chat: - /punishedit <id> reason <new reason> - /punishedit <id> duration <duration> - /punishedit <id> staff <staff> Durations use the same format as the rest of BetterPunish, including 30m, 12h, 7d, 30d, and permanent. A changed duration is still measured from the punishment's original creation time. Duration changes only apply to bans, mutes, and shadowmutes. Edits never replace the punishment or change its ID. BetterPunish keeps a local record of what changed, the old and new values, who made the change, and when it happened. The same information is also written to the console log. Proofs still belong to /proof; the editor links back to that existing system instead of creating a second place for evidence.

A Proper Punishment Dashboard

/punishgui and /punishments now open a central dashboard rather than a single active-punishment list. From there, staff can browse: - Active, recent, expired, and revoked punishments - Bans, mutes, warns, and shadowmutes - Punishment history for a searched player Lists use player heads and keep the useful information short: type, reason, moderator, ID, date, expiration, and current status. Left-click opens the full record. Staff with betterpunish.edit can right-click to edit it.

Details Without Command Hopping

Every punishment now has its own details screen. It shows the complete record, proof count, and a short edit-history summary. From there, staff can open the player's history, list attached proofs, or move into the editor. Active bans, mutes, and shadowmutes can also be removed from this screen. Removal always opens a confirmation menu first and checks betterpunish.unban or betterpunish.unmute again before doing anything.

Search, Filters, and Pages

Punishment lists are paginated and include clear back, previous-page, and next-page controls. Filters work with the punishment's real type and status rather than text from the item lore. Player search uses a short chat prompt, so the player does not need to be online. Type cancel to leave the prompt. Unfinished search and edit prompts expire automatically; the default timeout is 60 seconds. Expired temporary punishments are shown as EXPIRED as soon as their timestamp has passed, even when an older saved record was never explicitly updated. Revoked records stay REVOKED.

Permissions

The only new permission is: - betterpunish.edit – use /punishedit and edit records from the dashboard Opening the dashboard still requires betterpunish.gui. Proofs, player history, unbans, and unmutes keep their existing permissions, and every sensitive button checks the relevant permission on its own.

Improvements and Fixes

- Tab completion for edit fields and common duration values - Validation for unknown IDs, empty values, bad durations, and unsupported duration edits - Asynchronous local saves and Supabase updates through the existing storage services - Configurable dashboard titles, input prompts, timeout, cancellation text, and success messages - Built-in defaults for servers updating without the new config keys - New tests for editing, statuses, filters, pagination, and GUI permission checks

Configuration and Compatibility

There is no database migration for 1.4.0. Existing punishment IDs, proofs, local YAML files, and Supabase punishment rows remain compatible. If you want to change how long chat input stays open, set gui.input-timeout-seconds in config.yml. ---

Summary

1.4.0 is about making existing punishment data easier to work with. Staff can find a record, inspect it, correct it, check its evidence, and safely remove an active sanction without leaving the dashboard.

BetterPunish v1.3.1 - Network Name Hotfix

This hotfix makes the network name shown on the ban screen easy to customize.

Fixed

- Added the missing network-name option to the default config.yml. - Server owners can now replace "BetterPunish Network" with their own network name. - Added clear configuration comments explaining how to apply the change.

Configuration

Set your network name in config.yml:

network-name: "Your Network"

Run /punishreload or restart the server after changing the value.

BetterPunish v1.3.0 - Moderation Suite Update

Version 1.3.0 is a major update focused on faster staff work, cleaner chat, better investigations, and more consistent punishments. This release adds progressive offenses, staff notes, player profiles, chat control tools, a freeze system with disconnect protection, database wipe tools, and improved tab completion. ---

New Features

Progressive Offenses

Added /offend, a new command for rule-based punishment escalation. - Tracks offenses by category, such as cheating, spam, toxicity, advertising, hate speech, and more. - Automatically escalates punishments from warning to tempban to permanent ban. - Supports silent mode with -s. - Protects exempt players with tggpunish.offend.exempt. - Resets active category offenses when a player is unbanned or unmuted.

Global Chat Control

Added tools to quickly control server chat during raids, spam waves, or heated situations. - /clearchat [reason] clears chat for regular players while keeping staff history visible. - /clearchat all [reason] or /clearchat -a clears chat for everyone. - /mutechat [reason] toggles global chat mute. - /slowmode <seconds|off> adds or removes a delay between messages. - Staff and players with betterpunish.chat.bypass are exempt where appropriate.

Player Freeze System

Added /freeze and /unfreeze for live investigations and screen checks. - Stops frozen players from moving, fighting, interacting, dropping items, using inventory actions, or running blocked commands. - Shows clear title, subtitle, actionbar, and chat instructions. - Supports a clickable Discord support link. - Automatically alerts staff if a frozen player disconnects. - Can automatically ban freeze-loggers for a configurable duration.

Staff Notes

Added /note so staff can keep internal context on player behavior. - /note add <player> <text...> adds a note. - /note list <player> shows saved notes. - /note remove <player> <id> removes one note. - /note clear <player> removes all notes for a player. - Notes are saved asynchronously in notes.yml.

Player Profiles

Improved /pinfo and /check into a central player overview. The profile can show: - Active bans, mutes, and shadowmutes - Freeze status - Staff notes - Linked alt accounts by IP address

Database Wipe Command

Added /punishcleardb for administrators who need a clean reset. - Clears local YAML punishment data. - Clears remote Supabase PostgreSQL tables when configured. - Requires betterpunish.cleardb.

Better Tab Completion

Added tab completion support across the main command set, including punishments, notes, chat tools, reports, freeze commands, proof commands, player checks, suspects, and offenses. ---

Summary

BetterPunish v1.3.0 makes moderation faster, clearer, and more consistent. Staff get stronger tools, players get a cleaner chat experience, and server owners get a more complete moderation setup in one plugin.

BetterPunish v1.2.1 - New Additions

This release introduces major moderation power-ups, full cheat detection integration, player reports, and evidence management. ---

New Features

#### 1. Alt-Account Detection IP Tracking Database*: Automatically logs player IP addresses (player_ips table in Supabase or local player_ips.yml). Join Alerts*: When a player joins, the plugin scans for other accounts sharing that IP. If an alt-account is banned, staff members receive an in-game alert showing the banned account's name, Ban ID, and ban reason. Discord Logs*: Sends real-time warning alerts to the Discord Webhook. #### 2. Mute Bypass Blocker Communication Blocked*: Muted players can no longer bypass punishments via non-chat elements: Signs*: Blocked from editing signs (sends warning). Books*: Blocked from editing or signing books (sends warning). Anvils*: Blocked from renaming items (sends warning). PM Commands*: Blocked from using messaging commands (/msg, /tell, /w, /r). Shadowmute Interception: Shadowmuted players receive fake success feedback* so they believe their message went through: Fake Sign Edits*: The server sends client-side packets (sendSignChange) so the player sees their text on the sign, but other players see a blank sign. Fake PMs*: Displays a fake [me -> Target] message feedback to the sender. Staff Alerts*: Staff and console receive hidden notifications ([Shadow Sign], [Shadow Book], [Shadow Rename], [Shadow PM]) to monitor their activity. #### 3. In-Game Report System Command*: Players can report rule-breakers via /report <player> <reason>. Staff Reports GUI (`/reports`)*: Interactive menu displaying heads of reported players. Left-Click*: Teleport directly to the reported player. Right-Click*: Claim the report (status changes to CLAIMED, marking it for your investigation). Shift + Right-Click*: Mark the report as RESOLVED. Middle-Click*: Open the punishment dashboard (/punishgui) for that player. #### 4. Vulcan AntiCheat Integration (Sus Menu) Suspicion Scoring*: Connects with Vulcan Anticheat. Tracks player kick histories and individual check flags to calculate a live suspicion score. Suspects Dashboard (`/sus` or `/suspects`)*: Shows heads of suspicious players sorted by score. Hover Details*: Shows suspicion score, total kicks, and a list of all check flags with individual counts. Left-Click*: Teleport to the suspect. Right-Click*: Reset the player's suspicion score. Middle-Click*: Open the punishment dashboard (/punishgui). Automated Alerts*: Alerts staff members and Discord if a player's score crosses the configurable threshold (default: 50). #### 5. Multiple Proofs Evidence Management Command*: /proof <add|remove|list> <id> [url] allows staff to manage proof links for any ban or mute ID. Cloud Syncing*: Automatically joins proofs using | and patches the database column proofs on Supabase. ---

Command & Sync Improvements

Command Autocomplete*: Added tab-completion support for /unban and /unmute commands. Database Pull Command*: Added /punishpull to pull all active and historical punishments from Supabase back into your local storage file (punishments.yml).

BetterPunish

[](https://w… [](h… A sophisticated, feature-rich, and visually appealing punishment and moderation plugin for Minecraft (Spigot/Paper). This plugin provides administrators and moderators with comprehensive tools for managing player sanctions, an intelligent three-stage chat filter with leetspeak bypass protection, in-game GUIs for punishments and chat reviews, command and private message logging, cloud synchronization via Supabase, and webhook notifications via a Discord Bot. ---

Core Features

1. Comprehensive Punishment System

Supports all common punishment types with preconfigured or custom reasons and durations: Bans & Tempbans*: Permanent or temporary exclusion from the server with a customizable kick screen and appeal link (e.g., Discord). Mutes & Tempmutes*: Global chat muting as well as private message muting. Shadowmutes & Tempshadowmutes*: An invisible mute. The player believes their messages and private messages (PMs) are sent normally, but other players cannot see them. Staff members receive in-game notifications about shadow activity. Silent Punishments*: Appending -s or --silent to any punishment command suppresses the public broadcast message and sound in the global chat. The punishment is executed silently and only reported to staff members. Warns & Kicks*: Directly warn or kick players. Offline Warnings*: Warnings for offline players are cached locally or in the Supabase cloud and delivered when the player next joins with a prominent notification box and sound effect.

2. Intelligent Chat Filter & Anti-Spam

Proactively protects the server from toxic behavior, insults, and spam: Anti-Spam*: Prevents players from sending identical messages within a cooldown (default: 3 seconds). Violations result in automatic warnings and staff alerts. Three-Stage Normalization*: The chat filter removes color codes, normalizes Unicode characters, and detects bypass attempts (e.g., leetspeak like f4gg0t -> faggot or umlaut replacements). Three Scan Layers*: 1. Plain Scan: Checks the normalized text including spaces. 2. Joined Scan: Removes spaces to detect joined words (e.g., f u c k). 3. Squeezed Scan: Reduces consecutive duplicate characters (e.g., fuuuuuckkkk -> fuck). Review Queue*: Blocked messages are not simply deleted; they are automatically flagged and placed in a review queue. Staff members receive in-game notifications with click actions.

3. Interactive In-Game GUIs (Inventory Menus)

Chat Review GUI (`/chatreview`)*: A modern in-game queue manager to process blocked messages. Actions: Left-click to Dismiss, right-click to Mute the player (automatically applies the mapped mute reason), or shift-left-click for a Detail View*. Sorting*: Sortable by date (newest/oldest) or expected mute duration. Punishment Dashboard (`/punishgui` or `/punishments`)*: Overview of all active bans and mutes, represented as player heads. * Shows all relevant details (reason, issuer, expiration date, remaining time) in the tooltip (Lore). Clicking prints detailed information in the chat.

4. Command & MSG Logger with Live Monitor

Command Logger*: Logs all commands executed by players. Private messages (e.g., /msg, /tell, /w, /r) are analyzed separately to capture the sender, recipient, and message content. Autosave*: Stores up to 5000 logs in the background and saves them asynchronously. Live Monitor (`/livecmds` & `/livemsgs`)*: Allows staff members to monitor player commands or private messages in real-time.

5. LuckPerms Mute Group Synchronization

* Automatically assigns a LuckPerms group (default: mutet) when a player is muted. * The group is automatically removed when the mute expires or is lifted. * Ideal for network-wide mutes (BungeeCord/Velocity) and custom chat formatting for muted players.

6. Cloud Integration & Discord Webhooks

Supabase Synchronization*: Stores all punishments, IP logs, and offline warnings securely in a PostgreSQL cloud database. Data Migration*: Easily migrate all locally stored punishments (punishments.yml) to the cloud using /punishmigrate. Discord Webhook*: Sends real-time notifications about punishments and alerts to a configured Discord webhook bot. ---

Installation & Setup

1. Place BetterPunish.jar into the plugins folder of your Spigot/Paper server. 2. Start the server once to generate the default configuration files. 3. Customize [config.yml](file:///c:/Users/Paul/Documents/GitHub/TGGPunish/src/main/resources/config.yml) to your liking. 4. (Optional) Set up LuckPerms and Supabase integration.

A. LuckPerms Group Setup

If mute-group-sync is enabled in the config, create the corresponding group in LuckPerms (e.g., mutet):

/lp creategroup mutet
/lp group mutet permission set minecraft.command.me false

B. Supabase Database Setup

Create the following tables in your Supabase project SQL Editor to enable cloud synchronization:

-- Table for punishments (Bans, Mutes, Kicks, Warns)
CREATE TABLE IF NOT EXISTS punishments (
    id TEXT PRIMARY KEY,
    type TEXT NOT NULL,
    player_uuid UUID NOT NULL,
    player_name TEXT NOT NULL,
    actor_id TEXT NOT NULL,
    actor_name TEXT NOT NULL,
    reason TEXT NOT NULL,
    duration TEXT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL,
    expires_at TIMESTAMPTZ
);

-- Index for faster UUID queries
CREATE INDEX IF NOT EXISTS idx_punishments_player_uuid ON punishments(player_uuid);

-- Table for pending warnings
CREATE TABLE IF NOT EXISTS pending_warnings (
    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    player_uuid UUID NOT NULL,
    staff_name TEXT NOT NULL,
    reason TEXT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL
);

-- Index for faster offline warning queries
CREATE INDEX IF NOT EXISTS idx_pending_warnings_player_uuid ON pending_warnings(player_uuid);

Then, enter your Supabase url and anon-key in config.yml. ---

Commands

| Command | Syntax | Description | Permission | | :--- | :--- | :--- | :--- | | /ban | /ban <player> <reason> | Apply a configured or permanent ban. | betterpunish.ban | | /tempban | /tempban <player> <duration> <reason> | Apply a temporary ban (e.g., 7d, 12h). | betterpunish.tempban | | /unban | /unban <player\|id> | Lift an active ban by name or ID. | betterpunish.unban | | /mute | /mute <player> <reason> | Apply a configured or permanent mute. | betterpunish.mute | | /tempmute | /tempmute <player> <duration> <reason> | Apply a temporary mute. | betterpunish.tempmute | | /shadowmute | /shadowmute <player> <reason> [-s] | Apply a permanent or configured shadowmute. | betterpunish.shadowmute | | /tempshadowmute | /tempshadowmute <player> <duration> <reason> [-s] | Apply a temporary shadowmute. | betterpunish.tempshadowmute | | /unmute | /unmute <player\|id> | Lift a mute or shadowmute. | betterpunish.unmute | | /warn | /warn <player> <reason> | Warn a player (can be done offline). | betterpunish.warn | | /kick | /kick <player> <reason> | Kick an online player from the server. | betterpunish.kick | | /checkban | /checkban <player\|id> | Check active punishments or details of an ID. | betterpunish.checkban | | /history | /history <player> | Show the last 10 punishments of a player. | betterpunish.history | | /punishgui | /punishgui [bans\|mutes] [page] | Open the active bans/mutes GUI. | betterpunish.gui | | /chatreview | /chatreview [page] | Open the pending chat rev

The "Control & Protection" Update (v1.1.0)

This update marks the transition of BetterPunish from a simple tool to a complete moderation suite. We've added massive quality-of-life features for server administrators.

What's New?

📋 Active Punishments GUI:* A brand new interface (/punishments) to manage all current bans and mutes. Click to lift punishments instantly! 🛡️ Built-in Chat Filter:* Protect your chat from unwanted words and links. Fully customizable and linked to the auto-warn system. 🔔 Staff Notification System:* Real-time alerts for the whole team when someone gets punished or the filter is triggered. 🔕 Individual Notify Toggle:* Staff members can now use /punishnotify to turn their personal alerts on or off. 🔄 Admin Reload Command:* Added /punishreload to apply config changes (like new filter words) instantly without a restart.

Improvements & Fixes

Code Polish:* Resolved a Paper-specific API conflict in the GUI logic. Visuals:* Added a sleek black glass frame and player heads to the GUI for a more professional look. Logic:* History now accurately tracks warnings, auto-mutes, and filter violations. Action Required: Please delete your old `config.yml` before starting the server to ensure all new filter and notification settings are generated correctly!

The Polish & Protection Update (v1.0)

This update introduces a new layer of automation and a complete visual overhaul for a better moderation experience.

New Features

Automated Warning System:* Moderators can now use /warn. After 3 warnings, players are automatically muted for 1 hour. No more repetitive manual muting for minor offenses! Visual GUI Overhaul:* The punishment menu now features a sleek black stained glass frame and displays the target player's head in the center. Fully Dynamic Items:* You can now add, remove, or modify every item in the punishment GUI via the config.yml. Change slots, materials, and durations with ease. Scalable Icons:* Added a professional scale icon () to chat messages for better branding.

Improvements & Fixes

Config 2.0:* Completely restructured the configuration for better readability. History Logs:* Warns and auto-mutes are now properly tracked in the history and log files. Multi-Language Polish:* Fixed minor translation errors in the German locale.

Important Update Note

Please delete your old `config.yml` before restarting your server to allow the plugin to generate the new dynamic GUI settings and warning messages.

Language Update

use

/punishlang de

supported languages: English (en) and German (de)