☠️ 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

Place BetterPunish.jar into the plugins folder of your Spigot/Paper server.
Start the server once to generate the default configuration files.
Customize config.yml to your liking.
(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+

BetterPunish

📖About BetterPunish