PunishmentSystem

A punishment management plugin for Paper/Spigot servers running Minecraft 1.19+.

Features

• Permanent and temporary bans
• IP-based bans
• Permanent and temporary mutes
• Player kicks
• Punishment history with GUI
• Offline player support
• Multiple database backends (SQLite, MySQL, MongoDB)
• MiniMessage formatting for all messages
• Silent punishments for staff discretion
• Fully configurable messages and GUI

Requirements

• Paper 1.19.4+ or compatible server software
• Java 17 or higher

Installation

1. Download the latest release from the releases page
2. Place the JAR file in your server's plugins directory
3. Restart the server
4. Configure the plugin in plugins/PunishmentSystem/config.yml

Commands

Command	Description	Permission
/bansystem	Display help and available commands	punishments.help
/bansystem reload	Reload configuration files	punishments.reload
/ban <player> [-s] <reason>	Permanently ban a player	punishments.ban
/tempban <player> [-s] <duration> <reason>	Temporarily ban a player	punishments.tempban
/ipban <player> [-s] <reason>	Ban a player's IP address	punishments.ipban
/unban <player> [-s]	Remove a player's ban	punishments.unban
/mute <player> [-s] <reason>	Permanently mute a player	punishments.mute
/tempmute <player> [-s] <duration> <reason>	Temporarily mute a player	punishments.tempmute
/unmute <player> [-s]	Remove a player's mute	punishments.unmute
/kick <player> [-s] <reason>	Kick a player from the server	punishments.kick
/history <player>	View a player's punishment history	punishments.history

The -s or -silent flag executes the punishment silently. Only staff members with the punishments.silent permission will see the broadcast message.

Duration Format

Temporary punishments accept the following duration formats:

Unit	Example	Description
s	30s	Seconds
m	15m	Minutes
h	2h	Hours
d	7d	Days
w	2w	Weeks
M	1M	Months (30 days)
y	1y	Years (365 days)

Permissions

Permission	Description	Default
punishments.*	All punishment permissions	op
punishments.help	Access to /bansystem command	op
punishments.reload	Reload configuration files	op
punishments.ban	Ban players permanently	op
punishments.tempban	Ban players temporarily	op
punishments.ipban	IP ban players	op
punishments.unban	Unban players	op
punishments.mute	Mute players permanently	op
punishments.tempmute	Mute players temporarily	op
punishments.unmute	Unmute players	op
punishments.kick	Kick players	op
punishments.history	View punishment history	op
punishments.silent	See silent punishment broadcasts	op

Configuration

Database

The plugin supports three database backends. Configure your preferred option in config.yml:

SQLite (Default)

No additional setup required. Data is stored in plugins/PunishmentSystem/punishments.db.

database:
  type: SQLITE
  sqlite:
    file: "punishments.db"

MySQL

database:
  type: MYSQL
  mysql:
    host: "localhost"
    port: 3306
    database: "punishments"
    username: "root"
    password: "password"
    pool-size: 10
    use-ssl: false

MongoDB

database:
  type: MONGODB
  mongodb:
    connection-string: "mongodb://localhost:27017"
    database: "punishments"
    collection-prefix: "punishment_"

Messages

All messages support MiniMessage formatting. Available placeholders vary by message type:

• %player% - Target player name
• %staff% - Staff member name
• %reason% - Punishment reason
• %duration% - Punishment duration
• %expires% - Expiration date
• %remaining% - Time remaining
• %date% - Punishment date

Example message configuration:

messages:
  prefix: "<gradient:#FF6B6B:#4ECDC4>[Punishments]</gradient> "
  ban:
    success: "<green>Successfully banned <yellow>%player%</yellow> for: <white>%reason%</white></green>"
    broadcast: "<red><bold>BAN</bold></red> <gray>%player% has been banned by %staff% for: %reason%</gray>"

History GUI

The punishment history interface is configured in history-gui.yml. You can customize:

• Menu title and size
• Border decoration
• Filter buttons (All, Bans, Mutes, Kicks)
• Navigation buttons
• Punishment item display
• Player information display

Building from Source

git clone https://github.com/your-username/PunishmentSystem.git
cd PunishmentSystem
mvn clean package

The compiled JAR will be located at target/PunishmentSystem-1.0.0.jar.

Technical Notes

• All punishment operations support offline players except for kicks
• Expired temporary punishments are automatically invalidated on next lookup
• Player data (UUID, name, IP) is cached for offline punishment support
• Database connections use HikariCP for connection pooling (MySQL/SQLite)
• MongoDB uses the official MongoDB Java driver with indexed collections

License

This project is provided as-is without warranty. You are free to use and modify it for your server.