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.
