xPunish Documentation

xPunish is a high-performance, Paper-exclusive moderation solution designed for communities that prioritize precision, accountability, and streamlined workflows.

Featuring a dynamic, rank-adaptive GUI alongside high-speed direct command bypasses, xPunish automates punishment escalation scales while maintaining a permanent, unalterable audit trail.

🖥️ System Architecture & Mechanics

1. Dynamic GUI Control Panel

xPunish relies on intuitive, state-aware inventory menus to eliminate syntax errors, typos, and improper duration assignments.

Main Menu (`/punish <player>`)

A 36-slot interface centered around the target player's skull. It dynamically adapts based on the executing staff member's permissions.

Slot	Interface Item	Action	Function
10	Book / Barrier	Warn	Records a formal infraction warning.
11	Feather / Barrier	Kick	Severs the target's current connection.
12	Compass / Barrier	Mute	Toggles global chat restrictions.
14	TNT / Barrier	Ban	Restricts server access across the network.
20	Lime Dye / Barrier	Clear	Instantly revokes an active Mute or Ban.
22	Lava Bucket / Barrier	Wipe	Permanently purges the target's entire history.

⚠️
Rank Enforcement: Barrier items automatically replace action icons if the executing staff member lacks the required rank configuration node, preventing accidental or unauthorized interactions.

Contextual Sub-Menus

Target Status Skull (Slot 13): Displays a live breakdown of the target's status (Connection state, active mute status, time remaining, and current strike metrics for future escalations).
Reason Selection Menu: Generates a dynamically sized inventory pulling preset reasons from messages.yml. A permanent ✎ Custom Reason... item is appended to the end. Selecting it closes the GUI and safely prompts the administrator via chat input (type cancel to abort).
Confirmation Menu: A 27-slot safety gate displaying a comprehensive summary of the pending action. Consists of Green Wool (Confirm) and Red Wool (Cancel).

2. Punishment Framework & Escalation

xPunish tracks infractions across independent vertical streams. Infraction data operates under the following ruleset:

Punishment Type	Escalates Strikes	Persists in History	Runtime Effect
Warn	No	✅	Sends a formatted warning alert to online targets.
Kick	No	✅	Disconnects the player with a formatted kick screen.
Mute	✅ (Mute Track)	✅	Blocks chat throughput; displays remaining duration on attempt.
Ban	✅ (Ban Track)	✅	Imposes a profile restriction via native Paper APIs.

Escalation Rules

Isolation: Mute and Ban tracks operate independently. Accumulating mute strikes will never accelerate a player's ban tier progression.
Strike Expiry: Active escalation strikes expire after a set duration (strike_expiry_days in config.yml). Expired strikes remain fully documented in the history logs but no longer influence penalty multipliers.
Real-time Expiry Polling: When a mute expires, the plugin pushes an automated notification to the player within a 30-second polling window if they are online.

⌨️ Command Reference

Administrative & GUI Commands

Command	Permission Node	Description
`/punish <player>`	`punish.use`	Initializes the primary punishment control panel.
`/history <player>`	`punish.history`	Opens a paginated 54-slot player profile history log.
`/stafflog <staff>`	`punish.stafflog`	Opens a paginated 54-slot log filtered by moderator output.
`/punishment clear <player>`	`punish.clear`	Revokes active penalties while preserving history.
`/punishment wipe <player>`	`punish.wipe`	Permanently deletes a player profile from the database.
`/xpunish reload`	`punish.admin`	Performs a live, hot-reload of all configurations and ranks.

Direct Commands (GUI Bypass)

Experienced staff can execute direct punishments. These commands bypass the escalation matrix table for the specified duration but do count as an incremental strike for future GUI escalations.

Command Syntax	Base Node + Rank Condition	Context Notes
`/warn <player> [reason]`	`punish.warn` + `can_warn`	Works on offline players.
`/kick <player> [reason]`	`punish.kick` + `can_kick`	Target must be actively connected.
`/tempmute <player> <duration> [reason]`	`punish.mute` + `can_mute`	Extends strict manual duration overrides.
`/tempban <player> <duration> [reason]`	`punish.ban` + `can_ban`	Extends strict manual duration overrides.
`/unmute <player>`	`punish.unmute` + `can_unmute`	Immediate liftoff of active chat silences.

Duration Parsing

Manual duration inputs support compound arguments. Rich tab-completion suggestions are available out of the box.

30m — 30 Minutes
6h — 6 Hours
1d12h — 36 Hours
1w2d — 9 Days
perm — Indefinite / Permanent

⚙️ Configuration Guide

1. Rank & Permission Structuring (`ranks.yml`)

Modify permissions hierarchies via ranks.yml. Changes apply instantly using /xpunish reload. The internal level integer enforces Rank Protection (lower or equal ranks cannot punish higher ranks).

jr_mod:
  level: 2                  # Hierarchy weight (Higher values override lower values)
  can_warn: true
  can_kick: true
  can_mute: true
  can_unmute: true          # Requires explicit 'punish.unmute' permission node
  can_ban: false
  can_clear: false
  can_wipe: false
  can_history: true
  bypass_rank_protection: false

xPunish Documentation

🖥️ System Architecture & Mechanics

1. Dynamic GUI Control Panel

Main Menu (/punish <player>)

Rank Enforcement: Barrier items automatically replace action icons if the executing staff member lacks the required rank configuration node, preventing accidental or unauthorized interactions.

Contextual Sub-Menus

2. Punishment Framework & Escalation

Escalation Rules

⌨️ Command Reference

Administrative & GUI Commands

Direct Commands (GUI Bypass)

Duration Parsing

⚙️ Configuration Guide

1. Rank & Permission Structuring (ranks.yml)

Main Menu (`/punish <player>`)

Rank Enforcement: `Barrier` items automatically replace action icons if the executing staff member lacks the required rank configuration node, preventing accidental or unauthorized interactions.

1. Rank & Permission Structuring (`ranks.yml`)