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 <player> ban [reason]Permanently ban a player/punish <player> tempban <duration> [reason]Temporarily ban a player/punish <player> kick [reason]Kick an online player/punish <player> warn [reason]Issue a numbered warning/punish <player> jail [reason]Jail a player at their current position/unban <player>Lift any active ban/unjail <player>Release a jailed player/warnings <player>View the full warning history for a player/clearwarnings <player>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.