ray's admin utils

AdminPunish
A lightweight, self-contained punishment system for Paper 1.21.1 servers.
No dependencies. No database setup. Drop the jar in, restart, and your staff team has a full punishment toolkit available immediately.

Overview
AdminPunish is an OP-only punishment plugin that covers every common moderation action through a single unified command interface. All data is stored locally in JSON files, persists across restarts, and is indexed by UUID so player records survive name changes. The plugin was written as a direct Java port of a battle-tested Skript script, preserving every behaviour precisely while gaining the performance and reliability of compiled code.

Features
Permanent Ban
Issues an indefinite ban. The banned player is immediately kicked with a formatted disconnect screen showing the reason, issuing staff member, and an appeal prompt. The ban is enforced on every subsequent login attempt until lifted with /unban.
Temporary Ban
Issues a time-limited ban using a compact duration format: 30s, 15m, 12h, 7d, 2w. The player is kicked on issuance and blocked on login with a screen showing the time remaining. When the ban expires it is lifted automatically the next time the player attempts to connect, requiring no manual intervention.
Kick
Disconnects an online player with a formatted reason screen. The action is broadcast to all online players.
Numbered Warnings
Issues a warning that is numbered sequentially per player and stored permanently. The warned player receives a visible chat notification, then is kicked three seconds later with a warning screen showing the warning number, reason, and issuing staff. Warnings can be reviewed in full with /warnings and erased with /clearwarnings.
Jail
Freezes a player at their current position without requiring any jail location to be configured in advance. Jailed players are switched to Adventure mode, receive a persistent action bar message every second, and are fully restricted:

Block-level movement is prevented while head rotation is still allowed
All teleportation is blocked, including ender pearls, chorus fruit, /tp, and stasis chamber pulls
Ender pearl throws are cancelled at the source
Block breaking and placing is prevented
All inventory interaction is prevented
Item dropping and picking up is prevented
Combat is blocked in both directions — jailed players cannot be hit and cannot hit others
Command usage is blocked for non-OP jailed players

If a jailed player disconnects, a 30-minute temporary ban is automatically issued and broadcast to the server. On their next login the ban is checked: if it has expired, the jail is also cleared and they join freely; if it has not expired, they are blocked at the login screen with the remaining time. When a staff member issues /unjail, the player is restored to Survival mode and receives a release notification.

Commands
CommandDescription/punish ban [reason]Permanently ban a player/punish tempban [reason]Temporarily ban a player/punish kick [reason]Kick an online player/punish warn [reason]Issue a numbered warning/punish jail [reason]Jail a player at their current position/unban Lift any active ban/unjail Release a jailed player/warnings View the full warning history for a player/clearwarnings Erase all warnings for a player
All commands support tab-completion for online player names. /unban and /unjail additionally suggest names from the stored UUID cache, allowing offline players to be targeted by name.
Duration format for /punish tempban: append a unit character to a positive integer. Supported units are s (seconds), m (minutes), h (hours), d (days), and w (weeks). Examples: 30m, 12h, 7d, 2w.

Permissions
All commands require the adminpunish.use permission, which defaults to OP. No configuration file is needed; permissions work out of the box on any standard Paper server.

Data Storage
All records are stored as human-readable JSON files inside the plugin's data folder:

bans.json — active and expired ban records keyed by UUID
warnings.json — warning history lists keyed by UUID
jail.json — active jail records keyed by UUID
players.json — UUID-to-name and name-to-UUID cache populated on every join

Records are written to disk immediately on every change. No scheduler or batch-write delay is involved.

Compatibility

Server software: Paper 1.21.1 (API version 1.21)
Java version: Java 21
Dependencies: None — Gson is shaded into the jar
Soft dependencies: None

Installation

Download AdminPunish-2.4.0.jar
Place it in your server's plugins/ folder
Restart the server

No configuration is required. The plugin is operational immediately after the first restart.