# Report System

{% hint style="info" %}
The **Crown Report System** is a comprehensive tool designed to streamline communication between players and staff. It features a unique dual-interface design: an interactive **Book GUI** for players to submit detailed reports and a robust **Inventory GUI** for staff to manage, track, and resolve them.
{% endhint %}

### Key Features

* **Interactive Book Interface:** Players file reports via a clickable Written Book, ensuring a guided and detailed submission process.
* **Multi-Type Reporting:** Support for reporting **Players**, **Clans**, or **Server Issues**.
* **Data Snapshots:** Automatically collects target data (Inventory, Location, Health, Ping, etc.) at the moment of the report.
* **Workflow Management:** Report status tracking (Pending, Taken, Assigned, Resolved, Rejected).
* **Staff Assignment:** Assign specific reports to specific moderators.
* **Integrated Actioning:** Punish targets directly from the report menu.

***

### For Players: Submitting a Report

Players initiate reports using a simple command. The system then opens a book that guides them through categorization to ensure staff get the right information.

#### Commands

| Command            | Description                                                                              | Permission                         |
| ------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------- |
| `/report [player]` | Opens the report book. If a player name is provided, it skips the target selection step. | `crown.report.create` (if enabled) |

#### The Reporting Flow

1. **Target Selection:** Choose to report a **Player**, a **Clan**, or a **Server Issue**.
2. **Categorization:** Select a category (e.g., *Disruptive Gameplay*, *Bad Behavior*).
3. **Reason:** Select a specific reason (e.g., *Kill Aura*, *Chat Spam*).
4. **Details:** The player enters specific details in chat or confirms the selection.
5. **Submission:** The report is sent to the database, and online staff are notified.

{% hint style="warning" %}
**Note:** When reporting a player who is online, the system automatically takes a "snapshot" of their current stats (Health, Ping, Location, Gamemode) to aid investigation.
{% endhint %}

***

### For Staff: Managing Reports

Staff members manage reports via a centralized GUI.

#### Commands

| Command              | Description                                                   | Permission          |
| -------------------- | ------------------------------------------------------------- | ------------------- |
| `/reports`           | Opens the main reports list.                                  | `crown.report.view` |
| `/reports <player>`  | Opens reports filtered by a specific player as the target.    | `crown.report.view` |
| `/reports #<id>`     | Opens a specific report directly by ID.                       | `crown.report.view` |
| `/reports !<player>` | Opens reports filtered by a specific player as the requester. | `crown.report.view` |

#### 1. The Reports Menu

The main menu lists reports sorted by date (newest first).

* **Filter by Status:** Toggle between Pending, Taken, Assigned, Resolved, Rejected, or All.
* **Filter by Type:** Toggle between Player, Clan, or Server reports.
* **Filter by Name:** Search for reports against a specific target or from a specific requester.
* **My Reports:** Quickly filter to show only reports assigned to you.

#### 2. Report Details View

Clicking a report opens the **Management Dashboard** for that specific entry.

| Item                 | Function                                                                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Target Info**      | View the reported player's profile (heads to `/profile`).                                                                 |
| **Requester Info**   | View the profile of the player who sent the report.                                                                       |
| **Record Summaries** | See punishment history statistics for both the Target and Requester (useful to spot serial offenders or false reporters). |
| **Collected Data**   | View the snapshot data (HP, Ping, Location) captured at the time of the report.                                           |
| **Punish Buttons**   | Shortcuts to open the Punish Menu for the Target (or the Requester, in case of abuse).                                    |

#### 3. Workflow Actions

Staff can change the state of a report to keep the team organized:

* **Take Report:** Assigns the report to yourself and sets status to Taken.
* **Assign:** Assign the report to another specific moderator (requires `crown.report.assign`).
* **Resolve:** Marks the report as Resolved (e.g., punishment issued).
* **Reject:** Marks the report as Rejected (e.g., insufficient evidence).
* **Mark Pending:** Resets the report to Pending and unassigns it.

***

### &#x20;Configuration

#### Global Settings (`config.yml`)

You can configure anti-spam measures and permission requirements.

```yaml
report-system:
  # If true, players need 'crown.report.create' to use the command.
  require-permission: false
  
  # Seconds a player must wait between reports.
  cooldown: 60
  
  # Prevent spamming multiple reports in a short time.
  rate-limit:
    enabled: true
    amount: 5    # Max reports...
    period: 300  # ...per 5 minutes.
```

#### Customizing the Book (`reports.yml`)

You can fully customize the text, categories, and flow of the player reporting book. The system uses a page-based navigation logic.

**Example of a Category Page:**

```yaml
    player_categories:
      title: "<color:#00c6ff><bold>Select a Category</bold></color>"
      options:
        - text: "<color:#ff5555>Disruptive Gameplay</color>"
          hover: "<color:#b0b0b0>Cheating, hacking, exploiting.</color>"
          # Navigates to the 'disruptive_reasons' page and sets the category data
          action: "GOTO:disruptive_reasons;SET_CATEGORY:Disruptive Gameplay"
```

#### GUI Customization

* **`reports_menu.yml`**: Customize the layout and items of the main list.
* **`report_details_menu.yml`**: Customize the layout of the specific report view.

***

### Permissions

| Permission Node               | Description                                                  | Recommended For   |
| ----------------------------- | ------------------------------------------------------------ | ----------------- |
| `crown.report.create`         | Allows submitting reports (if `require-permission` is true). | Default / Players |
| `crown.report.bypasscooldown` | Bypasses the report cooldown and rate limit.                 | VIPs / Staff      |
| `crown.report.view`           | Allows access to `/reports` and viewing report details.      | Moderators        |
| `crown.report.assign`         | Allows assigning reports to other staff members.             | Admins / Sr. Mods |

***

### Database Structure

Reports are stored in the `reports` table (MySQL or SQLite).

* **report\_id**: Unique 8-character ID.
* **status**: Current state (PENDING, TAKEN, etc.).
* **collected\_data**: Serialized string containing snapshot data.
* **moderator\_uuid**: UUID of the staff member currently handling the report.
* **resolved\_at**: Timestamp of when the report was closed.
