# Menu & Item Syntax

Configuration files located in `plugins/Crown/menus/` (e.g., `punish_menu.yml`, `profile_menu.yml`) utilize a standardized syntax for defining items.

### Standard Item Configuration

This structure applies to almost every button or icon found in the Crown GUIs.

#### Basic Properties

| Property            | Type          | Description                                                   | Required |
| ------------------- | ------------- | ------------------------------------------------------------- | -------- |
| `material`          | String        | The Minecraft material name (e.g., `DIAMOND_SWORD`, `PAPER`). | **Yes**  |
| `slot`              | String/Int    | The position in the inventory (see **Slot Syntax** below).    | **Yes**  |
| `name`              | String        | The display name of the item. Supports colors/placeholders.   | No       |
| `lore`              | List\<String> | The item description lines. Supports colors/placeholders.     | No       |
| `quantity`          | Integer       | The stack size of the item (Default: 1).                      | No       |
| `custom_model_data` | Integer       | Custom integer used for Resource Packs.                       | No       |

#### Slot Syntax

Crown offers flexible ways to assign items to slots.

* **Single Slot:** `slot: 4`
* **Multiple Slots:** `slot: '0,8,9,17'` (Comma-separated)
* **Range:** `slot: '0-8'` (Fills slots 0 through 8)
* **Complex:** `slot: '0-8, 17, 45-53'` (Mix of ranges and single slots)

{% hint style="info" %}
**Note:** Inventory slots are indexed from 0. A standard double chest size is 0-53.
{% endhint %}

#### Player Head Configuration

To use player heads, set `material: PLAYER_HEAD` and use the `player_head` property.

| Value Type        | Syntax Example                      | Description                                              |
| ----------------- | ----------------------------------- | -------------------------------------------------------- |
| **Dynamic Name**  | `player_head: '{target}'`           | Shows the skin of the player being targeted/punished.    |
| **Specific Name** | `player_head: 'Notch'`              | Shows the skin of a specific Minecraft account.          |
| **Texture URL**   | `player_head: 'http://textures...'` | Uses a Base64/Mojang texture URL. Best for custom icons. |

#### Example: Standard Item

```yaml
ban_button:
  material: 'NETHERITE_AXE'
  slot: 13
  quantity: 1
  custom_model_data: 5
  name: '<gradient:#ff0000:#aa0000><bold>Ban Player</bold></gradient>'
  lore:
    - '<gray>Click to ban <yellow>{target}</yellow>.'
  left_click_actions:
    - 'OPEN_MENU:ban_details'
```

***

### Toggle State Items

Used primarily in the **Settings Menu** (`settings_menu.yml`), these items change their appearance based on a boolean condition (e.g., Enabled vs Disabled).

| Property                        | Description                                     |
| ------------------------------- | ----------------------------------------------- |
| `material_on` / `material_off`  | Material to show when setting is True vs False. |
| `player_head_on` / `_off`       | Texture to show when True vs False.             |
| `custom_model_data_on` / `_off` | Model Data to use when True vs False.           |

#### Example: Toggle Item

```yaml
silent_mode:
  slot: 22
  # State: Enabled
  material_on: 'BELL'
  # State: Disabled
  material_off: 'BARRIER'
  name: '<bold>Silent Mode</bold>'
  lore:
    - 'Current Status: {status}'
  left_click_actions:
    - 'TOGGLE_SETTING:silent'
```

***

### Confirmation State

Any item can require a "Double Click" to confirm an action (e.g., clearing an inventory or unbanning). When clicked once, the item visually changes to the `confirm_state`. Clicking again executes the action.

| Property        | Type    | Description                                           |
| --------------- | ------- | ----------------------------------------------------- |
| `confirm_state` | Section | Defines the temporary item shown during confirmation. |

**Inside `confirm_state`:**

* `material`
* `name`
* `lore`
* *(Note: The item automatically gets the Enchantment Glint when in confirm state).*

#### Example: Confirmation Button

```yaml
clear_inventory:
  material: 'TNT'
  slot: 49
  name: '<red>Clear Inventory</red>'
  left_click_actions:
    - 'REQUEST_CLEAR_FULL_INVENTORY'
  # Configuration for the "Are you sure?" state
  confirm_state:
    material: 'REDSTONE_BLOCK'
    name: '<dark_red><bold>CONFIRM DELETION</bold></dark_red>'
    lore:
      - '<red>Click again to permanently delete items.</red>'
```

***

### Report Book Syntax

The report system (`reports.yml`) uses a unique **Book-based** syntax rather than an inventory GUI.

#### Page Structure

| Property       | Type    | Description                                      |
| -------------- | ------- | ------------------------------------------------ |
| `book-title`   | String  | The title displayed at the top of the book item. |
| `initial-page` | String  | The key of the page opened first (e.g., `root`). |
| `pages`        | Section | Container for all book pages.                    |

#### Page Definition

Each key under `pages` represents a view in the book.

| Property  | Description                                  |
| --------- | -------------------------------------------- |
| `title`   | The bold header text at the top of the page. |
| `options` | A list of clickable text entries.            |

#### Option Definition

| Property | Description                                                 |
| -------- | ----------------------------------------------------------- |
| `text`   | The text displayed in the book.                             |
| `hover`  | Text shown when hovering over the option.                   |
| `action` | Special actions triggered on click (See logic table below). |

#### Report Logic Actions

These are specific to `reports.yml` `action` field. You can chain actions with `;`.

| Action Syntax                      | Description                                             |
| ---------------------------------- | ------------------------------------------------------- |
| `GOTO:<page_key>`                  | Navigates to another page defined in the YAML.          |
| `SET_TYPE:<type>`                  | Sets report type (`PLAYER`, `CLAN`, `SERVER`).          |
| `SET_CATEGORY:<cat>`               | Sets the category (e.g., "Cheating").                   |
| `SET_TARGET:<name>`                | Hardcodes the target name (e.g., "Server").             |
| `SELECT_REASON:<reason>`           | Sets the final reason and moves to detail entry.        |
| `REQUEST_INPUT:<type>:<next_page>` | Closes book and asks for chat input (`PLAYER`, `CLAN`). |

#### Example: Report Page

```yaml
pages:
  root:
    title: "<red>Report Menu</red>"
    options:
      - text: "<blue>Report a Player</blue>"
        hover: "Click to report a user"
        action: "REQUEST_INPUT:PLAYER:player_categories"
      - text: "<green>Report Server Lag</green>"
        hover: "Report performance issues"
        action: "GOTO:server_options;SET_TYPE:SERVER"
```

***

### General Item Syntax

This reference block covers every possible configuration option available for a menu item in Crown. You can copy and paste this structure into any menu configuration file (`punish_menu.yml`, `profile_menu.yml`, etc.).

```yaml
<item_identifier>:
  material: <material_name> # Required: Bukkit Material name (e.g., DIAMOND_SWORD, PAPER, PLAYER_HEAD).
  name: <display_name> # Optional: Display name. Supports MiniMessage, Legacy (&), and Hex colors.
  lore: # Optional: List of lore lines.
    - "<line_1>"
    - "<line_2>"
  
  player_head: <player_name_or_texture_url> # Optional: Player username ("{target}") or direct Texture URL. Requires material: PLAYER_HEAD.
  quantity: <quantity> # Optional: Item stack amount (default: 1).
  glow: true #Optional: Item glowing effect (enchanting effect)
  slot: <slot_number(s)> # Required: Inventory slot(s). Examples: '4', '0,8', '9-17', '0-8,45-53'.
  custom_model_data: <integer> # Optional: Integer for Resource Pack CustomModelData.

  # --- Toggle States (Used primarily in settings_menu.yml) ---
  material_on: <material_name> # Optional: Material used when the setting is Enabled.
  material_off: <material_name> # Optional: Material used when the setting is Disabled.
  player_head_on: <name_or_url> # Optional: Texture used when the setting is Enabled.
  player_head_off: <name_or_url> # Optional: Texture used when the setting is Disabled.
  custom_model_data_on: <integer> # Optional: Model Data used when the setting is Enabled.
  custom_model_data_off: <integer> # Optional: Model Data used when the setting is Disabled.

  # --- Interactions & Actions ---
  left_click_actions: # Optional: List of actions to execute on Left Click.
    - "<ACTION_NAME>:<ARGUMENTS>"
    - "PLAY_SOUND:UI_BUTTON_CLICK:1:1"
  
  right_click_actions: # Optional: List of actions to execute on Right Click.
    - "<ACTION_NAME>:<ARGUMENTS>"
  
  shift_left_click_actions: # Optional: List of actions to execute on Shift + Left Click.
    - "<ACTION_NAME>:<ARGUMENTS>"

  # --- Safety Confirmation ---
  confirm_state: # Optional: Defines a temporary item state requiring a second click to confirm.
    material: <material_name>
    name: <confirmation_display_name>
    lore:
      - "<confirmation_warning_line>"
```
