📖About PunisherXX

PunisherXX

PunisherXX is a configurable punishment plugin for Paper 1.21.x focused on fast moderation workflows.

It supports custom punish types, warning escalation, and built-in ban, kick, and mute logic, while keeping everything editable in config.

Why PunisherXX

Config-driven punish flows for different rule breaks
Built-in action keywords for warning, kicking, banning, and muting
Warning escalation rules (example: 3 warnings -> temporary ban)
Timed punishments with human-friendly durations like 30m, 12h, 7d, 2w, or perm
Permission-node friendly design for LuckPerms and similar permission plugins
Persistent punishment data stored in data.yml

Commands

/punish [reason]
/punish reload
/warn [time] [reason]
/pban [reason]
/pkick [reason]
/pmute [reason]

Permissions

Default nodes:

punisher.punish
punisher.warn
punisher.ban
punisher.kick
punisher.mute
punisher.reload

Dynamic node template:

punisher.punish.%type%

You can fully customize node names in config.yml.

Config Style

Define punish types as either direct action lists or structured blocks with custom permissions.

Example:

punish:
  xray:
    permission: punisher.punish.xray
    actions:
      - "kill %player%"
      - "clear %player%"
      - "pban 30d %reason%"

Warning escalation example:

warnings:
  default-duration: 30d
  escalation:
    "3":
      duration: 7d
      reason: Reached 3 active warnings.
    "5":
      duration: 30d
      reason: Reached 5 active warnings.

Placeholders

Common placeholders in actions and messages:

%player%
%reason%
%type%
%actor%
%duration%
%count%

Compatibility

Server software: Paper (1.21.x)
Java: 21

Install

Build the plugin or download the release jar.
Put the jar into your server plugins folder.
Start the server once to generate config files.
Edit config.yml for your punish logic and permissions.
Use /punish reload after changes.

Notes

PunisherXX is intended for server staff moderation. Review your punish commands and escalation thresholds before using in production.