# Overview

**Crown** is a comprehensive, enterprise-grade moderation and punishment solution designed for Minecraft servers (Spigot/Paper). It bridges the gap between standard punishment plugins and advanced administration suites by integrating punishments, player forensics, reporting, and moderator utilities into a single, cohesive ecosystem.

Unlike simple ban plugins, Crown focuses on **context and evidence**. Every action is logged, player states are snapshotted at the moment of infraction, and confiscated items are securely stored rather than deleted.

### **🚀 Key Features**

<div data-with-frame="true"><figure><img src="https://1647821688-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fu39fYRhEyWTBeKitWrt8%2Fuploads%2F0T6CjsO9liSx4PYmqdUU%2FCP_banner_3bis.png?alt=media&#x26;token=e4826e3d-dffb-434f-8fc5-9d1225267380" alt=""><figcaption></figcaption></figure></div>

#### ⚖️ Advanced Punishment System

Crown offers a robust punishment engine that goes beyond simple bans.

* **6 Punishment Types:** Ban, Mute, Kick, Warn, **Softban** (blocks specific commands), and **Freeze** (immobilizes player + admin-only chat).
* **IP Synchronization:** Punishments can be applied by IP automatically. If a player is banned by IP, all accounts associated with that IP are also punished immediately.
* **Forensic Snapshots:** When a player is punished, Crown records their snapshot data: Inventory, Location, Health, Gamemode, IP, and Ping.
* **Escalating Warnings:** A configurable warning system where accumulating warnings can trigger automatic actions (e.g., *Warn #3 triggers a 7-day Softban*). Warning expiration can be unique or incremental.

#### 🛡️ Moderator Mode (`/mod`)

<div data-with-frame="true"><figure><img src="https://1647821688-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fu39fYRhEyWTBeKitWrt8%2Fuploads%2FkEbm5zdgL6IJTJFEiVHe%2Fmodmodebanner.png?alt=media&#x26;token=530693da-d7a0-43ff-92a8-e06dd0107f29" alt=""><figcaption></figcaption></figure></div>

A fully integrated state-switching system for staff.

* **Session Management:** Saves the staff member's inventory, location, and stats before putting them into Mod Mode. Restores everything exactly upon exit (even after server crashes).
* **Mod Tools:** Configurable hotbar tools including:
  * **Vanish/Spectator:** Toggle visibility and collision.
  * **Player Selector:** Quickly target players for inspection.
  * **Freeze Tool:** Left/Right click to freeze/unfreeze.
  * **InvSee:** Inspect target inventories instantly.
  * **Random TP:** Teleport to random players to spot-check behavior.
* **Persistent Preferences:** Moderators can toggle settings like **Container Spy**, **Silent Mode** (fake quit/join), **Night Vision**, and **Fly Speed**, which persist across sessions.

#### 📝 Dynamic Report System

<div data-with-frame="true"><figure><img src="https://1647821688-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fu39fYRhEyWTBeKitWrt8%2Fuploads%2FfYw4z3wyWBy4nX0DEfLZ%2Freportsbanner.png?alt=media&#x26;token=c95bc96a-8a5a-445d-8f7b-2f1350e8ec42" alt=""><figcaption></figcaption></figure></div>

An anti-abuse reporting system that allows players to report others using an intuitive **Book GUI**.

* **Interactive Book Interface:** Players select categories (Player, Clan, Server), specific reasons, and input details via chat without memorizing commands.
* **Staff GUI (`/reports`):** A filterable menu for staff to view, claim ("Take"), resolve, or reject reports.
* **Data Collection:** Reports automatically attach a snapshot of the reported player's stats (HP, Location, Kills, Ping) for context.

<div data-with-frame="true"><figure><img src="https://1647821688-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fu39fYRhEyWTBeKitWrt8%2Fuploads%2FCIzNKKTbmHRcQuLE4OAc%2Flockerbanner.png?alt=media&#x26;token=9414ec39-e1a4-484f-a323-afc167421a2a" alt=""><figcaption></figcaption></figure></div>

#### 🎒 The Locker System (Evidence Vault)

Crown introduces a unique **Confiscation Locker**.

* **Confiscation:** When a moderator removes an illegal item from a player's inventory via the Inspection Menu, it is **not deleted**.
* **Evidence Storage:** The item is serialized and sent to the "Locker".
* **Review:** Admins can view the Locker to see exactly what items were confiscated, when, and by whom. Items can be deleted permanently or returned to the moderator's inventory.

<div data-with-frame="true"><figure><img src="https://1647821688-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fu39fYRhEyWTBeKitWrt8%2Fuploads%2FAo2lAmeqptMuQ1ynwv1V%2Fprofilebanner.png?alt=media&#x26;token=765d505d-0de7-40f1-9780-4babc4b445a7" alt=""><figcaption></figcaption></figure></div>

#### 👤 Deep Profiling & History

Complete oversight of player data.

* **`/profile <player>`:** A GUI displaying live health, food, EXP, location, and quick access to their Inventory, Ender Chest, and Punishment History.
* **`/history <player>`:** View active and expired punishments. Active punishments show exact expiry times and allow for re-punishing or un-punishing directly from the GUI.
* **Operator Audit Log:** Tracks administrative actions performed on a player (e.g., *AdminX cleared inventory of PlayerY*).

### ⚙️ Technical Architecture

#### Database Support

Crown is built for scalability, supporting both local and network environments.

* **SQLite:** Zero-setup local storage for single servers.
* **MySQL:** Optimized HikariCP connection pooling for networks, allowing cross-server data syncing.

#### Asynchronous Operations

To ensure zero lag impact on the main server thread:

* Database queries (Lookups, Logs, History) are executed asynchronously.
* Heavy tasks like inventory serialization are handled off-thread.
* Menus load with "Loading..." indicators while fetching data.

#### Customizability

* **MiniMessage & Legacy Colors:** Full support for RGB gradients and standard color codes in all messages.
* **GUIs:** Every menu (Punish, History, Profile) is configurable via YAML.
* **Placeholders:** Native PlaceholderAPI support for messages and scoreboards.

***

### 🛑 Comparison: Punishments

<table><thead><tr><th width="128">Feature</th><th width="76" align="center">Ban</th><th width="112" align="center">Mute</th><th width="112" align="center">Softban</th><th width="106" align="center">Freeze</th><th width="98" align="center">Kick</th><th width="92" align="center">Warn</th></tr></thead><tbody><tr><td><strong>Prevents Join</strong></td><td align="center">✅</td><td align="center">❌</td><td align="center">❌</td><td align="center">❌</td><td align="center">✅ (Once)</td><td align="center">❌</td></tr><tr><td><strong>Blocks Chat</strong></td><td align="center">❌</td><td align="center">✅</td><td align="center">❌</td><td align="center">✅ (Public)</td><td align="center">❌</td><td align="center">❌</td></tr><tr><td><strong>Blocks Commands</strong></td><td align="center">❌</td><td align="center">⚠️ (Config)</td><td align="center">✅ (Config)</td><td align="center">✅</td><td align="center">❌</td><td align="center">❌</td></tr><tr><td><strong>Immobilizes</strong></td><td align="center">❌</td><td align="center">❌</td><td align="center">❌</td><td align="center">✅</td><td align="center">❌</td><td align="center">❌</td></tr><tr><td><strong>Duration</strong></td><td align="center">Temp/Perm</td><td align="center">Temp/Perm</td><td align="center">Temp/Perm</td><td align="center">Manual</td><td align="center">Instant</td><td align="center">Expiring</td></tr><tr><td><strong>IP Sync</strong></td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td><td align="center">✅</td><td align="center">❌</td></tr></tbody></table>

***

### 🔜 Getting Started

Ready to install Crown? Check the **Installation** guide to set up your database and permissions.

* **Commands:** View the full list of commands and aliases.
* **Permissions:** Configure access for Helpers, Mods, and Admins.
* **Configuration:** Learn how to tweak the `config.yml` and `messages.yml`.
