Compatibility
Minecraft: Java Edition
Platforms
Tags
Creators
Details
BetterPunish
BetterPunish is a staff toolkit for Paper servers. It handles punishments, reports, chat moderation, player investigations, evidence, and staff logs without forcing moderators to jump between several plugins or edit data files by hand.
Every punishment gets its own ID and history. Staff can look it up later, attach proof, check its status, or correct it when something changes.
Why Server Owners Like It
- Bans, mutes, shadowmutes, warns, and kicks in one punishment history
- Configurable offense tiers for repeat rule breaks
- A paginated dashboard for active, expired, revoked, and older punishments
- Reports, staff notes, player profiles, freeze tools, and alt-account hints
- Chat filtering, anti-spam, slowmode, global mute, and chat clearing
- Local YAML storage by default, with optional Supabase synchronization
- Optional LuckPerms mute-group and Vulcan flag integrations
Main Features
Punishments That Stay Manageable
BetterPunish supports permanent and temporary bans, mutes, and shadowmutes, plus warns and kicks. Reasons and default durations live in config.yml, and staff can use -s or --silent on supported punishment commands when a public announcement is not wanted.
Warnings also work for offline players. They are saved and delivered when the player next joins.
Evidence stays tied to the punishment ID through /proof. A punishment can have several proof links, and those links remain available from lookups and the new details menu.
The Staff Desk
Version 1.4.0 turns /punishgui and /punishments into the main place for punishment work.
The first menu links to active, recent, expired, and revoked records, along with separate lists for bans, mutes, warns, and shadowmutes. Lists are paginated, use player heads, and show the important details without filling the lore with walls of text.
Left-click a record to open its details. Staff with betterpunish.edit can right-click it to edit. The details menu links to proof and player history and uses a confirmation screen before an active ban, mute, or shadowmute can be removed.
Player search works through a short chat prompt and does not require the player to be online. Type cancel to leave the prompt; abandoned prompts expire automatically.
Correct a Punishment Instead of Replacing It
/punishedit <id> opens the editor for an existing record. Reason, total duration, and displayed moderator can also be changed directly:
/punishedit <id> reason <new reason>/punishedit <id> duration <duration>/punishedit <id> staff <staff>
Duration changes use the normal BetterPunish format, such as 30m, 12h, 7d, 30d, or permanent. The total duration is measured from the original creation time and is only available for bans, mutes, and shadowmutes.
The original punishment ID is never replaced. Each edit records the field, old and new values, staff member, and time in local history and the console log. Proofs continue to use /proof rather than a separate edit-only evidence system.
Progressive Offenses
/offend applies the next configured punishment for a rule category. A first offense can be a warning, the next a temporary punishment, and a later one permanent. Categories, tiers, display names, reset time, and default duration are all configurable.
The punishment system can run in LEGACY, OFFENSE, or HYBRID mode, so an existing command workflow does not need to be replaced all at once.
Chat Protection
The chat filter removes formatting, normalizes Unicode and common leetspeak, checks joined words, and squeezes repeated characters before testing the configured rules. Blocked messages can be logged, shown to staff, and placed in /chatreview for a decision.
BetterPunish also catches repeated-message spam and blocks common mute bypasses through private-message commands, signs, books, and anvil renames. Shadowmuted players still see their own messages while regular players do not.
For wider chat problems, staff can use /clearchat, /mutechat, and /slowmode.
Reports and Staff Tools
Players can report an online player with /report. Staff handle open, claimed, and resolved reports from the /reports inventory.
Internal notes can be added to known players with /note. /check, /checkban, and /pinfo bring together active punishments, freeze state, notes, history, and locally linked accounts where that information is available.
The freeze system locks movement and common interactions while a player is being investigated. It shows the configured support link and can issue a configurable freeze-log ban if the player disconnects.
Vulcan Support
When Vulcan is installed, BetterPunish listens for flag events and builds a suspicion score. /sus and /suspects open the resulting staff dashboard. Vulcan is optional; the rest of BetterPunish works without it.
Command and Private-Message Logs
BetterPunish records player commands and configured private-message aliases when logging is enabled. Staff can search by player, review recent private messages, or watch commands and messages live.
The maximum log size, query limit, aliases, and autosave interval are configurable.
Local Storage and Supabase
Local data is stored under plugins/BetterPunish/data/ in separate YAML files for punishments, reports, notes, chat-review entries, command logs, and observed player IPs. Older files in the plugin root are moved into the data folder when they are first loaded.
Supabase is optional. When configured, BetterPunish can synchronize punishments, proofs, supported punishment edits, pending warnings, reports, and player IP observations through the Supabase REST API. /punishmigrate uploads local punishment history, and /punishpull imports punishment records back into local storage.
Discord Companion Service
The configured Discord invite can be shown on ban and freeze screens. Servers with a compatible BetterPunish companion service can also set discord.bot-url to forward punishment, report, and suspicious-player events to its HTTP broadcast endpoint.
The companion service is not bundled with the plugin and is not required.
Installation
- Stop the server.
- Put the BetterPunish 1.4.0 JAR into the server's
pluginsfolder. - Start the server once to generate
plugins/BetterPunish/config.ymland the local data folder. - Set up reasons, offense tiers, messages, GUI titles, chat rules, and any optional integrations.
- Give each staff group only the permissions it needs.
Existing installations do not need a database migration for 1.4.0. Missing GUI and input-message settings use built-in defaults.
Commands & Permissions
| Command | What it does | Permission |
|---|---|---|
/ban <player> <reason> |
Ban a player with a configured or custom reason. | betterpunish.ban |
/tempban <player> <duration> <reason> |
Temporarily ban a player. | betterpunish.tempban |
/unban <player|id> |
Revoke an active ban. | betterpunish.unban |
/mute <player> <reason> |
Mute a player with a configured or custom reason. | betterpunish.mute |
/tempmute <player> <duration> <reason> |
Temporarily mute a player. | betterpunish.tempmute |
/unmute <player|id> |
Revoke an active mute or shadowmute. | betterpunish.unmute |
/shadowmute <player> <reason> |
Shadowmute a player. | betterpunish.shadowmute |
/tempshadowmute <player> <duration> <reason> |
Temporarily shadowmute a player. | betterpunish.tempshadowmute |
/warn <player> <reason> |
Warn a player or queue an offline warning. | betterpunish.warn |
/kick <player> <reason> |
Kick an online player and record it. | betterpunish.kick |
/offend <player> <reason> |
Apply the next offense tier for a category. | betterpunish.offend |
/history <player> [page] |
Show a player's punishment history. | betterpunish.history |
/checkban <player|id> |
Check active sanctions or inspect one punishment. | betterpunish.checkban |
/check <player|id> |
Check sanctions, freeze state, and notes. | betterpunish.checkban |
/pinfo <player|id> |
Open the player moderation profile. | betterpunish.checkban |
/punishgui [category] [page] |
Open the punishment dashboard or a filtered list. | betterpunish.gui |
/punishments [category] [page] |
Open the punishment dashboard. | betterpunish.gui |
/punishedit <id> |
Open the editor for a punishment. | betterpunish.edit |
/punishedit <id> reason <reason> |
Change the displayed reason. | betterpunish.edit |
/punishedit <id> duration <duration> |
Change the total duration from its original start time. | betterpunish.edit |
/punishedit <id> staff <staff> |
Change the displayed moderator. | betterpunish.edit |
/proof <add|remove|list> <id> [url] |
Manage evidence attached to a punishment. | betterpunish.proof |
/report <player> <reason> |
Report an online player. | betterpunish.report |
/reports [page] |
Open the report queue. | betterpunish.reports |
/chatreview [page] |
Open the blocked-message review queue. | betterpunish.chatreview |
/note <add|list|remove|clear> <player> [text/id] |
Manage internal staff notes. | betterpunish.note |
/freeze <player> [reason] |
Freeze or unfreeze an online player. | betterpunish.freeze |
/unfreeze <player> |
Unfreeze an online player. | betterpunish.freeze |
/clearchat [all] [reason] |
Clear chat for regular players or everyone. | betterpunish.clearchat |
/mutechat [reason] |
Toggle the global chat mute. | betterpunish.mutechat |
/slowmode <seconds|off> |
Set or disable the chat delay. | betterpunish.slowmode |
/playermsgs <player> [limit] |
Show logged private messages involving a player. | betterpunish.commandlogs |
/playercommands <player> [limit] |
Show a player's logged commands. | betterpunish.commandlogs |
/allmsgs [limit] |
Show recent logged private messages. | betterpunish.commandlogs |
/livemsgs <player|all|off> |
Start or stop live private-message monitoring. | betterpunish.live |
/livecommands <player|all|off> |
Start or stop live command monitoring. | betterpunish.live |
/sus or /suspects |
Open the suspicious-player menu. | betterpunish.sus |
/punishreload |
Reload configuration and punishment data. | betterpunish.reload |
/punishmigrate |
Upload local punishment history to Supabase. | betterpunish.migrate |
/punishpull |
Import punishment history from Supabase. | betterpunish.pull |
/punishcleardb |
Clear local and configured remote punishment data. | betterpunish.cleardb |
/report is available to players by default. Staff commands default to server operators.
Useful supporting permissions include:
betterpunish.stafffor general staff alerts and selected bypassesbetterpunish.chatfilter.notifyfor chat-filter notificationsbetterpunish.chatfilter.bypassfor an explicit filter bypassbetterpunish.offend.exemptto block/offendfrom targeting a player
Dashboard access does not automatically grant edit, proof, history, unban, or unmute access. Those buttons check their own permissions.
Requirements
- Server: Paper 1.21.11
- Java: 21 or newer
- Required plugins: None
- Optional: LuckPerms 5.x for mute-group synchronization
- Optional: Vulcan for anti-cheat flag tracking
- Optional services: Supabase and a compatible Discord companion endpoint
Best For
BetterPunish fits SMP, survival, PvP, and network servers that want a shared punishment history and straightforward staff tools without requiring a remote database.
Support
When asking for help, include the BetterPunish version, Paper version, Java version, and the relevant console error. Remove Supabase keys, player IPs, proof links, and other private data before sharing files.