☠️ BetterPunish

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 reviews GUI.	betterpunish.chatreview
/playermsgs	/playermsgs <player> [limit]	View logged private messages for a player.	betterpunish.commandlogs
/playercommands	/playercommands <player> [limit]	View executed commands for a player.	betterpunish.commandlogs
/allmsgs	/allmsgs [limit]	View global MSG logs of all players.	betterpunish.commandlogs
/livemsgs	/livemsgs <player|all|off>	Toggle live monitor for private messages.	betterpunish.live
/livecommands	/livecommands <player|all|off>	Toggle live monitor for commands.	betterpunish.live
/punishmigrate	/punishmigrate	Migrate local punishments database to Supabase.	betterpunish.migrate
/punishreload	/punishreload	Reload configuration files and services.	betterpunish.reload

---

🔐 Permissions

• betterpunish.*: Grants full access to all commands (default: Operator).
• betterpunish.ban: Access to /ban.
• betterpunish.tempban: Access to /tempban.
• betterpunish.unban: Access to /unban.
• betterpunish.mute: Access to /mute.
• betterpunish.tempmute: Access to /tempmute.
• betterpunish.shadowmute: Access to /shadowmute.
• betterpunish.tempshadowmute: Access to /tempshadowmute.
• betterpunish.unmute: Access to /unmute.
• betterpunish.warn: Access to /warn.
• betterpunish.kick: Access to /kick.
• betterpunish.checkban: Access to /checkban.
• betterpunish.history: Access to /history.
• betterpunish.gui: Access to /punishgui and /punishments.
• betterpunish.reload: Access to /punishreload.
• betterpunish.chatreview: Access to /chatreview.
• betterpunish.commandlogs: Access to logging commands.
• betterpunish.live: Access to live monitors.
• betterpunish.chatfilter.bypass: Bypass the chat filter (default: false).
• betterpunish.chatfilter.notify: Receive alerts when the chat filter flags a message.
• betterpunish.spam.bypass: Bypass the anti-spam limit.
• betterpunish.migrate: Access to /punishmigrate.

---

⚙️ Configuration Example (config.yml)

# BetterPunish Global Configuration

# The name of your network/server. Used in the ban screen and default broadcast messages.
network-name: "BetterPunish Network"

# Discord Integration
discord:
  invite-url: "https://discord.gg/yourserver"
  display: "discord.gg/yourserver"
  bot-url: "http://localhost:3000"

# Supabase Cloud Integration
supabase:
  url: "https://your-project-id.supabase.co"
  anon-key: "YOUR_ANON_KEY_HERE"

# Predefined ban reasons
ban-reasons:
  Cheating:
    display: "Cheating"
    duration: "7d"
  NSFW:
    display: "NSFW Content"
    duration: "10d"

---

📂 Technical Details & Storage

• Local Storage: If Supabase is not configured, the plugin stores all data locally in YAML format:
  • punishments.yml: Sanctions and offline warning data.
  • chatfilter-flags.yml: Blocked chat messages awaiting review.
  • command-logs.yml: Up to 5000 command and MSG logs.
• Asynchronous & Virtual Threads: The plugin uses Bukkit's async schedulers and Java Virtual Threads (Thread.ofVirtual()) to handle all database queries and HTTP requests off the main server thread, preventing any tick lag.
• Adventure API (MiniMessage): Rich formatting for all in-game text, hover actions, and gradients.

---

📄 License & Author

• Author: pa_mife
• API Version: 1.21.11+