Bans

Bans is a punishment system for Paper servers. Bans, mutes, warnings and kicks all live in one database, so a player's full record is available at any time, not only while they are online.

The plugin does not use the vanilla banned-players.json. Every punishment is a row with a reason, an author, the time it was issued and when it runs out, so nothing is lost once a ban is lifted.

Temporary and permanent punishments share one command. Pass a duration and you get a temporary punishment, leave it out and you get a permanent one. The usual formats work: 30m, 2h, 7d, 1d12h, perm.

Mutes actually hold. Chat is blocked and so are commands like /msg, /r and /me. The command list is configurable, so a muted player cannot route around the punishment through private messages.

Offline players can be punished. Anyone who has joined the server before can be banned, muted or warned without being online.

Automatic escalation. Once a player reaches a set number of active warnings, the plugin issues a mute or a ban on its own. Thresholds and actions are set in the config, and the whole thing can be turned off.

Silent punishments. Adding -s to a command hides the announcement from regular players. Only staff sees it.

Immunity. Players with bans.exempt cannot be punished. Anyone holding bans.exempt.bypass can punish them anyway.

Punishment ids. Every punishment has an id shown on the disconnect screen. The player has something to quote in an appeal and the moderator has something to look up.

SQLite or MySQL. By default everything sits in a local file and needs no setup. If you run several servers, point them at MySQL and they share one punishment database.

Command	What it does
/ban <player> [duration] [reason] [-s]	Ban, permanent or temporary. Alias: /tempban
/mute <player> [duration] [reason] [-s]	Mute. Alias: /tempmute
/warn <player> [duration] [reason] [-s]	Warn. Alias: /tempwarn
/kick <player> [reason] [-s]	Kick a player from the server
/unban <player> [reason]	Lift a ban. Alias: /pardon
/unmute <player> [reason]	Lift a mute
/unwarn <player> [id] [reason]	Lift a warning, the most recent one by default
/history <player>	A player's punishment history. Aliases: /punishments, /checkpunish
/punishlog	Staff action log. Alias: /banlog
/bans reload	Reload the config and messages

/ban, /kick and /pardon override the vanilla ones. If another plugin claims the same names, the full form always works: /bans:ban, /bans:kick.

Examples:

/ban Steve 7d Griefing spawn
/mute Alex 30m Spamming chat
/warn Notch Insulting other players -s
/unwarn Notch 14 Moderator mistake

Player history. /history opens a menu with every punishment: type, reason, who issued it, date, length and current state. You can see whether it still applies, whether it ran out, or who lifted it and why.

Staff log. /punishlog lists the latest actions on the server together with the punished player and the moderator. Useful for checking that nobody on the team is leaning on their permissions.

Both menus are paginated and read their data off the main thread, so opening them does not cost you tick time.

config.yml holds the storage choice, the default reason, the date format, the list of commands a muted player cannot use, and the escalation rules:

escalation:
  enabled: true
  levels:
    3: "MUTE 1h Reached 3 warnings"
    5: "BAN 7d Reached 5 warnings"
    7: "BAN perm Reached 7 warnings"

messages.yml holds every piece of text: chat announcements, the disconnect screens for bans and kicks, the labels inside the menus. It uses MiniMessage, so colours and gradients are written inline. Reasons and player names are inserted without parsing tags, so a moderator cannot break your formatting through the reason text.

If punishments should only be visible to staff, set broadcast.public: false. Every punishment then behaves as if it was issued silently.

Permission	What it grants
bans.ban, bans.mute, bans.warn, bans.kick	Issuing the matching punishments
bans.unban, bans.unmute, bans.unwarn	Lifting punishments
bans.history	Access to a player's history
bans.log	Access to the staff log
bans.notify	Receive announcements, silent ones included
bans.silent	Use the -s flag
bans.exempt	Cannot be punished
bans.exempt.bypass	Punish exempt players
bans.admin	Reload the config

Installation

1. Drop the jar into plugins and restart the server.
2. Adjust config.yml and messages.yml if you need to, then run /bans reload.

There are no database drivers to install by hand. The server downloads the libraries it needs on first start.

Requirements: Paper 1.21 or newer, Java 21. Built against the 1.21 API and tested on Paper 26.1.2.