☠️ BetterPunish

BetterPunish is a modern, feature-rich punishment and moderation plugin for Minecraft (Spigot/Paper).

It helps administrators and moderators manage player behavior with advanced tools like automated chat filtering, offline punishments, interactive GUIs, cloud sync, and anticheat integration.

---

🚀 Core Features

1. Advanced Punishment System

Sanction players instantly with preconfigured reasons or custom durations:

• Bans & Tempbans: Permanent or temporary bans with customizable kick screens.
• Mutes & Tempmutes: Mute players in public chat and private messages.
• Shadowmutes: Players think their messages are sent, but nobody else can see them. Staff members get alerts when shadowmuted players talk.
• Silent Punishments: Add -s or --silent to run punishments without public announcements.
• Warns & Kicks: In-game warnings and kicks. Offline players will receive their warnings with sound effects next time they join.
• Multiple Proofs: Attach multiple links or notes to any punishment as evidence using the /proof command.

2. Moderation Power-Ups (New!)

• Alt-Account Detection: Automatically tracks player IP addresses to detect and link alternative accounts. Alerts staff members when an alt-account joins.
• Mute Bypass Blocker: Prevents muted players from bypassing mutes through custom commands, book edits, or renaming items.
• In-game Report System: Players can report rule breakers using /report <player> <reason>. Staff can manage the report queue using a modern GUI (/reports).
• Vulcan AntiCheat Integration: Tracks suspicious players, calculates suspicion scores, and provides a Suspects Dashboard GUI (/sus or /suspects).

3. Intelligent Chat Filter & Anti-Spam

Protect your server from toxic behavior, insults, and spam:

• Anti-Spam: Prevents duplicate messages within a cooldown (default: 3 seconds).
• Intelligent Filter: Detects bypass attempts (like leetspeak, e.g., f4gg0t -> faggot or unicode tricks).
• Review Queue: Blocked messages are sent to /chatreview where staff members can dismiss or mute the player with one click.

4. Interactive In-Game GUIs

• Chat Review GUI (/chatreview): Process blocked messages. Left-click to dismiss, right-click to mute, or shift-left-click to view details.
• Punishment Dashboard (/punishgui): Overview of active bans/mutes. View details (reason, staff, expiration) by hovering over player heads.
• Reports Queue (/reports): A GUI to manage open, claimed, and resolved player reports.
• Suspects Menu (/sus): View players with high suspicion scores from Vulcan Anticheat flags.

5. Logging & Monitor

• Command & PM Logger: Logs executed commands and private messages.
• Live Monitor (/livecmds & /livemsgs): Watch player activity in real-time.

---

🛠️ Installation & Setup

1. Place BetterPunish.jar in your server's plugins folder.
2. Start the server to generate configuration files.
3. Customize config.yml to your liking.

Supabase Database Setup

Create these tables in your Supabase 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,
    proofs TEXT,
    silent BOOLEAN DEFAULT FALSE
);

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

CREATE INDEX IF NOT EXISTS idx_pending_warnings_player_uuid ON pending_warnings(player_uuid);

-- Table for player IP history (Alt Detection)
CREATE TABLE IF NOT EXISTS player_ips (
    player_uuid UUID NOT NULL,
    player_name TEXT NOT NULL,
    ip_address TEXT NOT NULL,
    last_seen TIMESTAMPTZ NOT NULL,
    PRIMARY KEY (player_uuid, ip_address)
);

-- Table for player reports
CREATE TABLE IF NOT EXISTS reports (
    id BIGINT PRIMARY KEY,
    reporter_uuid UUID NOT NULL,
    reporter_name TEXT NOT NULL,
    target_uuid UUID NOT NULL,
    target_name TEXT NOT NULL,
    reason TEXT NOT NULL,
    timestamp TIMESTAMPTZ NOT NULL,
    status TEXT NOT NULL,
    resolved_by TEXT
);

Enter your Supabase url and anon-key in config.yml.

---

⌨️ Commands & Permissions

Command	Description	Permission
/ban <player> <reason>	Apply a ban.	betterpunish.ban
/tempban <player> <duration> <reason>	Apply a temporary ban.	betterpunish.tempban
/unban <player|id>	Lift an active ban.	betterpunish.unban
/mute <player> <reason>	Apply a mute.	betterpunish.mute
/tempmute <player> <duration> <reason>	Apply a temporary mute.	betterpunish.tempmute
/shadowmute <player> <reason>	Apply a shadowmute.	betterpunish.shadowmute
/unmute <player|id>	Lift a mute or shadowmute.	betterpunish.unmute
/warn <player> <reason>	Warn a player (works offline).	betterpunish.warn
/kick <player> <reason>	Kick a player.	betterpunish.kick
/checkban <player|id>	Check active punishments.	betterpunish.checkban
/history <player>	Show punishment history.	betterpunish.history
/punishgui	Open active punishments GUI.	betterpunish.gui
/chatreview	Open chat review GUI.	betterpunish.chatreview
/punishmigrate	Sync local database to Supabase.	betterpunish.migrate
/punishpull	Pull database from Supabase.	betterpunish.pull
/report <player> <reason>	Report a player.	betterpunish.report
/reports	Open reports queue GUI.	betterpunish.reports
/proof <add|remove|list> <id> [url]	Manage proof links.	betterpunish.proof
/sus or /suspects	Open suspect GUI (Vulcan required).	betterpunish.sus