🖼️Menu & Item Syntax

Configuration files located in plugins/CrownPunishments/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)

Note: Inventory slots are indexed from 0. A standard double chest size is 0-53.

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

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

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

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 (Crown Feature)

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

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.).

<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>"