GUI System

Overview

The GriefPrevention GUI Addon provides a graphical user interface for managing claims, flags, and related features of the GriefPrevention plugin. Each GUI is defined in a separate YAML configuration file, allowing server admins to customize its appearance and functionality. Admins can also define custom GUIs in config.yml. This wiki details the structure of the GUI system, themes, available GUIs, their configuration, and general GUI settings.

---

GUI System

The GUI system enables claim owners and trusted players to interact with claim settings through intuitive menus. GUIs are defined in individual YAML files, each containing a data section for overall properties and an items section for interactive elements, similar to the structure of FlagOptions.yml. The system supports dynamic content via placeholders, custom themes, and special sections for custom GUIs.

Key Features

• Customizable GUIs: Each GUI is defined in its own file, with additional custom GUIs configurable in config.yml.

• Dynamic Content: GUIs use placeholders (e.g., %gpextension_getbyid_location_{claimid}%, <itemname>) to display claim-specific or context-sensitive information.

• Interactive Elements: Items can trigger commands on left or right clicks, such as teleporting, setting flags, or opening other menus.

• Conditional Display: Items can have view_requirement conditions to control visibility based on permissions or settings.

• Navigation Controls: Multi-page GUIs include Previous and Next sections for navigation, defined in the items section with specific slots and display names.

• Custom GUIs: Certain GUIs (e.g., ICON_SELECTOR) dynamically populate content and require specific sections in their configuration. User-defined custom GUIs can be added in config.yml.

• Themes: GUIs can apply visual themes (e.g., default, nature, clean) defined in separate _EN.yml files in the theme folder, with high-priority items that can be overridden.

---

Themes

The GriefPrevention GUI Addon supports customizable themes to enhance the visual appearance of GUIs. Themes are defined in individual YAML files located in the theme folder, with names matching the theme specified in the GUI’s data section, appended with _EN.yml (e.g., default uses default_EN.yml). Themes are loaded first during GUI initialization, with items set to a high priority (e.g., 5), allowing GUI items with lower priority to override them.

Theme Configuration

• File Naming: Theme files must be named <theme_name>_EN.yml (e.g., default_EN.yml, nature_EN.yml) and placed in the theme folder.

• Structure: Each theme file contains an items section defining decorative items (e.g., glass panes, grass) that fill specific slots in the GUI.

• Priority: Theme items are assigned a high priority (e.g., 5) so that GUI items with lower priority (e.g., 1, 2) can replace them in overlapping slots.

• Application: The theme is specified in the GUI’s data section via the theme field (e.g., theme: clean_4 for ClaimUpgradeNoEnter_EN.yml).

• Custom Themes: Admins can create custom themes by adding new <theme_name>_EN.yml files and specifying the theme name in the GUI’s data section.

Default Themes

The GriefPrevention GUI Addon includes the following default themes:

1. default (default_EN.yml):

   • Uses black stained glass panes to create a dark border around the GUI.

   • Configuration:

     items:
       BACKGROUND_2:
         priority: 5
         material: BLACK_STAINED_GLASS_PANE
         slots:
           - 0
           - 1
           - 2
           - 3
           - 4
           - 5
           - 6
           - 7
           - 8
           - 9
           - 17
           - 18
           - 26
           - 27
           - 35
           - 36
           - 44
           - 45
           - 46
           - 47
           - 48
           - 49
           - 50
           - 51
           - 52
           - 53
         display_name: " "

2. nature (nature_EN.yml):

   • Uses a mix of glass panes, grass, and plants for a natural, outdoor aesthetic.

   • Configuration:

     items:
       blue_glass_pane:
         material: LIGHT_BLUE_STAINED_GLASS_PANE
         priority: 5
         display_name: " &r "
         slots:
           - 5
           - 6
           - 7
           - 26
           - 27
           - 35
           - 36
           - 44
       white_glass_pane:
         material: WHITE_STAINED_GLASS_PANE
         priority: 5
         display_name: " &r "
         slots:
           - 1
           - 3
           - 4
           - 17
           - 18
       white_glass:
         material: WHITE_STAINED_GLASS
         priority: 5
         display_name: " &r "
         slots:
           - 2
           - 9
       tall_grass:
         material: TALL_GRASS
         priority: 5
         display_name: " &r "
         slots:
           - 47
           - 48
           - 51
           - 52
       rose:
         material: ROSE_BUSH
         priority: 5
         display_name: " &r "
         slots:
           - 46
       dark_oak:
         material: DARK_OAK_SAPLING
         priority: 5
         display_name: " &r "
         slots:
           - 50

3. clean (clean_EN.yml):

   • Uses air (AIR) to create a minimalistic, transparent background for standard-sized GUIs.

   • Configuration:

     items:
       SKIP:
         material: AIR
         priority: 5
         slots:
           - 0
           - 1
           - 2
           - 3
           - 4
           - 5
           - 6
           - 7
           - 8
           - 9
           - 17
           - 18
           - 26
           - 27
           - 35
           - 36
           - 44
           - 45
           - 46
           - 47
           - 48
           - 49
           - 50
           - 51
           - 52
           - 53
         display_name: ' &r  '

4. clean_4 (clean_4_EN.yml):

   • A specialized version of the clean theme designed for the smaller ClaimUpgradeNoEnter GUI (4 rows), using air (AIR) for a transparent background.

   • Configuration:

     items:
       SKIP:
         material: AIR
         priority: 5
         slots:
           - 0
           - 1
           - 2
           - 3
           - 4
           - 5
           - 6
           - 7
           - 8
           - 9
           - 17
           - 18
           - 19
           - 20
           - 21
           - 22
           - 23
           - 24
           - 25
           - 26
         display_name: ' &r  '

Theme Loading and Priority

• Loading Process: Themes are loaded first when a GUI is initialized, populating the specified slots with theme items (e.g., glass panes, air) at priority 5.

• Item Override: GUI items with a lower priority (e.g., 1 or 2) override theme items in the same slots. For example, in ClaimUpgradeBiomeSelector_EN.yml, the goback item (priority 2, slot 45) will replace a default theme’s BACKGROUND_2 item (priority 5, slot 45).

• Customization: Admins can create custom themes by adding new <theme_name>_EN.yml files in the theme folder and referencing them in the GUI’s data section (e.g., theme: my_custom_theme).

---

Available GUIs

The GriefPrevention GUI Addon includes the following default GUIs, each serving a specific purpose. GUIs marked as Custom dynamically populate content and require a specific section in their items configuration (e.g., ICON_SELECTOR for the Icon Selector GUI).

GUI Name	File Name	Custom	Purpose
MAIN_MENU	ClaimMenu.yml	No	Main interface for managing claims and accessing other GUIs.
CLAIM_INFO	ClaimInfo.yml	No	Displays detailed information about a specific claim.
CLAIM_PERMISSIONS	ClaimPermissions.yml	No	Manages trust and permission settings for a claim.
CLAIM_BLOCKS	ClaimBlock.yml	No	Handles claim block-related actions.
CLAIM_DELETE	ClaimDelete.yml	No	Confirms deletion of a specific claim.
CLAIM_DELETE_ALL	ClaimDeleteAll.yml	No	Confirms deletion of all claims owned by a player.
CLAIM_KICK	ClaimKick.yml	No	Allows kicking players from a claim.
CLAIM_LEAVE	ClaimLeave.yml	No	Confirms leaving a specific claim.
CLAIM_LEAVE_ALL	ClaimLeaveAll.yml	No	Confirms leaving all claims.
CLAIM_UPGRADE_NO_ENTER	ClaimUpgradeNoEnter.yml	No	Manages upgrades for claims with restricted entry.
ICON_SELECTOR	IconSelector.yml	Yes	Allows selection of a claim icon (dynamically populates icons).
NO_MOB_SPAWNS_TYPE	NoMobSpawnsType.yml	Yes	Configures mob spawn restrictions for a claim.
PLAYER_LIST	PlayerList.yml	Yes	Lists players for trust or permission management.
WARP	WarpList.yml	Yes	Displays a list of claims available for teleportation via ClaimWarp.
EXPIRING_CLAIMS	ExpiringClaimList.yml	Yes	Shows claims nearing expiration.
CLAIM_LIST	ClaimList.yml	Yes	Lists all claims owned or accessible by a player.
CLAIM_TRUST	TrustList.yml	Yes	Manages trusted players for a claim.
BLOCKS	ClaimBlock.yml	Yes	Manages claim block purchases or allocations.
BLACKLIST	BlackList.yml	Yes	Manages blacklisted players for a claim.
WHITELIST	Whitelist.yml	Yes	Manages whitelisted players for a claim.
CLAIM_INVITES	ClaimInvites.yml	Yes	Manages claim invitations.
CLAIM_UPGRADE	ClaimUpgrade.yml	Yes	Handles claim upgrades (e.g., biome changes).
CLAIM_BLOCKS_SELECTOR	ClaimBlockSelector.yml	Yes	Allows selection of claim block options.

---

Custom User-Defined GUIs

Admins can define custom GUIs in config.yml under gui.custom_guis. These GUIs are loaded by the plugin and must follow specific naming and configuration rules.

• Definition: List custom GUIs in config.yml under gui.custom_guis (e.g., ClaimUpgradeBiomeSelector).

• File Naming: The plugin loads the corresponding YAML file with _EN appended to the name (e.g., ClaimUpgradeBiomeSelector loads ClaimUpgradeBiomeSelector_EN.yml).

• GUI Type: The gui_type in the GUI file’s data section must exactly match the name listed in gui.custom_guis (e.g., ClaimUpgradeBiomeSelector).

• File Location: Custom GUI files must be placed in the GUI folder alongside default GUI files.

Example:

• In config.yml:

  gui:
    custom_guis:
      - ClaimUpgradeBiomeSelector

• The plugin loads ClaimUpgradeBiomeSelector_EN.yml, and its data section must include gui_type: ClaimUpgradeBiomeSelector.

---

GUI Configuration Files

Each GUI, whether default or custom, is defined in a YAML file with two main sections: data and items. Below is an overview of these sections and their properties.

data Section

The data section defines the overall properties of the GUI, such as its title, size, and theme.

• Key Fields:

  • menu_title: The title displayed at the top of the GUI, supporting placeholders (e.g., &7%gpextension_title% (&2/ClaimIcon&7)).

  • args: A list of arguments required by the GUI (e.g., id, itemname for claim ID or item selection).

  • rows: The number of rows in the GUI (e.g., 6 for a 54-slot inventory).

  • theme: Specifies the theme to apply (e.g., default, clean_4). The plugin loads <theme_name>_EN.yml from the theme folder (e.g., clean_4_EN.yml).

  • version: A developer-only field specifying the configuration version (e.g., 1.0). Do not edit, as it may break the plugin.

  • gui_type: A developer-only field indicating the type of GUI (e.g., ICON_SELECTOR). For custom GUIs, it must match the name in gui.custom_guis. Do not edit for default GUIs.

• Example (from ClaimUpgradeNoEnter_EN.yml):

  data:
    menu_title: "%griefprevgui_title% &7(&2No Enter&7)"
    version: "1.1"
    args:
      - claimid
    rows: 4
    theme: clean_4
    gui_type: CLAIM_UPGRADE_NO_ENTER

• Notes:

  • Admins should only modify menu_title, args, rows, and theme as needed.

  • For custom GUIs, ensure gui_type matches the custom_guis entry in config.yml.

  • Editing version or gui_type for default GUIs can cause compatibility issues.

items Section

The items section defines the interactive elements (buttons, icons, etc.) displayed in the GUI, structured similarly to FlagOptions.yml. Each item is configured under a unique section name (e.g., teleport, plains) and supports properties to control its appearance and behavior. Multi-page GUIs include Previous and Next sections for navigation.

• Key Fields:

  • material: The Minecraft item representing the element (e.g., ENDER_PEARL, GRASS_BLOCK).

  • display_name: The name shown in the GUI, supporting color codes and placeholders (e.g., &7Plains).

  • lore: A list of text lines displayed when hovering, often including descriptions and placeholders (e.g., &8• &7Current: &f%gpextension_getbyid_flags_parma_ChangeBiome_{claimid}%).

  • slot: The specific slot where the item appears, as a single integer (e.g., 10, 31).

  • slots: A list of slots where the item appears (e.g., [10, 11, 12]), used instead of slot.

  • amount: The stack size of the item (defaults to 1 if not specified or invalid).

  • glow: If true, the item appears enchanted (e.g., true for add).

  • model_data: Custom model data for resource pack textures (optional, e.g., 0).

  • left_click_commands: Commands executed on left-click (e.g., [player] claim tp {claimid}).

  • right_click_commands: Commands executed on right-click (e.g., [player] gpguiflags set {claimid} ChangeBiome PLAINS).

  • click_commands: Commands executed for both left and right clicks (used instead of separate left/right commands).

  • priority: Determines the rendering order of items (e.g., 1 for disabled). Items with lower priority override theme items (priority 5).

  • view_requirement: Conditions for item visibility (e.g., checking if a feature is enabled or if the player has permissions).

• Navigation Controls:

  • Multi-page GUIs include Previous and Next sections to navigate between pages, typically placed in slots 47 and 51, respectively.

  • Example configuration:

    Previous:
      material: ARROW
      model_data: 0
      display_name: "&cPrevious Page &7[&a<page>&7/&2<max_page>&7]"
      lore:
        - "&7Go to the previous page"
      slot: 47
    Next:
      material: ARROW
      model_data: 0
      display_name: "&aNext Page &7[&a<page>&7/&2<max_page>&7]"
      lore:
        - "&7Go to the next page"
      slot: 51

• Special Sections for Custom GUIs:

  • Some custom GUIs (e.g., ICON_SELECTOR, NO_MOB_SPAWNS_TYPE) require a specific section in items matching their gui_type (e.g., ICON_SELECTOR for dynamic icon population).

  • User-defined custom GUIs (e.g., ClaimUpgradeBiomeSelector) typically use predefined items and may not require a dynamic section.

• Example Configurations:

  IconSelector.yml (Default Custom GUI with dynamic content and navigation):

  data:
    menu_title: "&7%gpextension_title% (&2/ClaimIcon&7)"
    args:
      - id
      - itemname
    version: "1.0"
    rows: 6
    theme: default
    gui_type: ICON_SELECTOR
  items:
    mode_selector_category:
      material: CREEPER_BANNER_PATTERN
      model_data: 0
      slot: 0
      display_name: "&7Item Category &7(&a<mode_category>&7)"
      lore:
        - ""
        - "&2Description:"
        - "   &7Change the sorting of materials"
        - ""
        - "   &7Current: &a<mode_category>"
        - ""
        - "&7Categories:"
        - ""
        - "   &8• &7<selected_block>"
        - "   &8• &7<selected_edible>"
        - "   &8• &7<selected_record>"
        - "   &8• &7<selected_allmaterial>"
        - ""
        - "&7Click to change the Item Category."
    add:
      material: PAPER
      glow: true
      model_data: 0
      priority: 1
      display_name: "&7Change by name"
      lore:
        - ""
        - "&2Description"
        - ""
        - "    &8• &7Status: &f%gpextension_getbyid_flags_isactive_ClaimIcon_{id}%"
        - ""
      slot: 8
      click_commands:
        - "[sound] UI_BUTTON_CLICK"
        - "[player] gpguiflags set {id} ClaimIcon <anvilreply>"
    goback:
      material: OAK_DOOR
      model_data: 0
      display_name: "&7⟰ &aGo Back"
      left_click_commands:
        - "[sound] BLOCK_WOODEN_DOOR_OPEN"
        - "[player] claim"
      slot: 45
    Previous:
      material: ARROW
      model_data: 0
      display_name: "&cPrevious Page &7[&a<page>&7/&2<max_page>&7]"
      lore:
        - "&7Go to the previous page"
      slot: 47
    Next:
      material: ARROW
      model_data: 0
      display_name: "&aNext Page &7[&a<page>&7/&2<max_page>&7]"
      lore:
        - "&7Go to the next page"
      slot: 51
    filler:
      material: LIGHT_BLUE_STAINED_GLASS_PANE
      model_data: 0
      display_name: " &r "
    ICON_SELECTOR:
      display_name: "<itemname>"
      lore:
        - ""
        - "&2Description:"
        - ""
        - "    &8• &7Name: &f<itemname>"
        - "    &8• &7Category: &f<itemcategory>"
        - ""
        - "&a&l| &2Click to select"
      click_commands:
        - "[player] gpguiflags set {id} ClaimIcon {itemname}"
        - "[close]"
        - "[sound] UI_BUTTON_CLICK"

  ClaimUpgradeBiomeSelector_EN.yml (User-Defined Custom GUI with predefined items):

  data:
    menu_title: "%gpextension_title% &7(&2Biome Selector&7)"
    version: "1.0"
    args:
      - claimid
    rows: 6
    theme: default
    gui_type: ClaimUpgradeBiomeSelector
  items:
    goback:
      material: OAK_DOOR
      priority: 2
      display_name: "&7⟰ &aGo Back"
      click_commands:
        - "[sound] BLOCK_WOODEN_DOOR_OPEN"
        - "[player] claim"
      slot: 45
    disabled:
      material: BARRIER
      priority: 1
      display_name: "&cReset Biome"
      lore:
        - ""
        - "    &8• &7Current: &f%gpextension_getbyid_flags_parma_ChangeBiome_{claimid}%"
        - "&a&l| &2Click to reset biome to default."
      slot: 53
      click_commands:
        - "[player] gpguiflags unset {claimid} ChangeBiome true"
    plains:
      material: GRASS_BLOCK
      priority: 2
      display_name: "&7Plains"
      lore:
        - ""
        - "&2Biome Description:"
        - "   &7A peaceful grassy landscape filled with flowers and animals."
        - ""
        - "    &8• &7Current: &f%gpextension_getbyid_flags_parma_ChangeBiome_{claimid}%"
        - ""
        - "&a&l| &2Click to set this biome."
      click_commands:
        - "[player] gpguiflags set {claimid} ChangeBiome PLAINS"
        - "[sound] UI_BUTTON_CLICK"
      slot: 10
    forest:
      material: OAK_LOG
      priority: 2
      display_name: "&7Forest"
      lore:
        - ""
        - "&2Biome Description:"
        - "   &7A dense forest with tall oak and birch trees."
        - ""
        - "    &8• &7Current: &f%gpextension_getbyid_flags_parma_ChangeBiome_{claimid}%"
        - ""
        - "&a&l| &2Click to set this biome."
      click_commands:
        - "[player] gpguiflags set {claimid} ChangeBiome FOREST"
        - "[sound] UI_BUTTON_CLICK"
      slot: 11
    # Additional biome items omitted for brevity, following the same structure

• Notes:

  • The ICON_SELECTOR section in IconSelector.yml is required for dynamic icon population.

  • ClaimUpgradeBiomeSelector_EN.yml uses predefined items for biomes and does not require a dynamic section.

  • Navigation controls (Previous and Next) are defined as specific sections in multi-page GUIs, typically in slots 47 and 51.

  • Commands use placeholders (e.g., {claimid}, <anvilreply>) and special actions (e.g., [close], [sound]).

  • Theme items (priority 5) are overridden by GUI items with lower priority (e.g., 1, 2).

---

GUI Settings in config.yml

The gui section in config.yml configures general GUI behavior and allows defining custom GUIs.

• Key Settings:

  • theme: Sets the default theme for GUIs (default, nature, clean). Individual GUI files can override this via the theme field in their data section (e.g., ClaimUpgradeNoEnter_EN.yml uses clean_4).

  • remove_claim_from_warp_list_on_no_enter.enable: If true, claims with the NoEnter flag are excluded from the warp list (default: true).

  • disable_gui_on_grief_prevention_disabled_worlds: If true, GUIs are disabled in worlds where GriefPrevention is disabled (default: false).

  • claim_list_size_limit: Limits the number of claims shown in CLAIM_LIST (default: enable: false, size: 45).

  • player_list_size_limit: Limits the number of players shown in PLAYER_LIST (default: enable: true, size: 100).

  • default_claim_list_icon.material: Sets the default icon for claims in CLAIM_LIST (default: GRASS_BLOCK).

  • default_claim_list_icon.model_data: Custom model data for the default icon (default: 0).

  • default_sort: Configures default sorting for CLAIM_LIST (default: permission: ALL, online_status: Online, distance: Nearest).

  • fancy_icons_in_claim_list_by_default.enable: If true, CLAIM_LIST icons use the claim’s center block once cached (default: true).

  • disabled_guis: Lists GUIs to disable (e.g., ["Claim_List"]). Bypassed with gpgui.bypass.guidisabled permission (default: []).

  • custom_guis: Lists custom GUI names (e.g., ["ClaimUpgradeBiomeSelector"]). The plugin loads corresponding files with _EN appended (e.g., ClaimUpgradeBiomeSelector_EN.yml).

• Example Configuration:

  gui:
    theme: "default"
    remove_claim_from_warp_list_on_no_enter:
      enable: true
    disable_gui_on_grief_prevention_disabled_worlds: false
    claim_list_size_limit:
      enable: false
      size: 45
    player_list_size_limit:
      enable: true
      size: 100
    default_claim_list_icon:
      material: "GRASS_BLOCK"
      model_data: 0
    default_sort:
      permission: ALL
      online_status: Online
      distance: Nearest
    fancy_icons_in_claim_list_by_default:
      enable: true
    disabled_guis: []
    custom_guis:
      - ClaimUpgradeBiomeSelector

• Notes:

  • Custom GUIs listed in custom_guis must have corresponding YAML files ending in _EN in the GUI folder.

  • The gui_type in the custom GUI file must match the name in custom_guis exactly.

  • The theme setting in config.yml sets the default theme, but individual GUIs can override it (e.g., theme: clean_4 in ClaimUpgradeNoEnter_EN.yml).

---

Usage Notes

• Accessing GUIs: GUIs are accessed via commands (e.g., /claim menu for MAIN_MENU) or by interacting with flags (e.g., clicking ClaimIcon to open ICON_SELECTOR or ChangeBiome to open ClaimUpgradeBiomeSelector).

• Custom GUIs: Default custom GUIs (e.g., ICON_SELECTOR) dynamically populate items and require a matching section in items. User-defined custom GUIs (e.g., ClaimUpgradeBiomeSelector) are added in config.yml and loaded from _EN-suffixed files.

• Themes: Apply themes via the theme field in the GUI’s data section (e.g., clean_4 for ClaimUpgradeNoEnter). Custom themes can be created by adding <theme_name>_EN.yml files.

• Customization: Admins can modify menu_title, rows, args, theme, item properties, and config.yml settings to tailor the GUI experience.

• Placeholders: Use placeholders (e.g., %gpextension_getbyid_flags_parma_ChangeBiome_{claimid}%, <itemname>) to display dynamic information.

• Navigation: Multi-page GUIs include Previous and Next sections for easy navigation, typically in slots 47 and 51.

---

Troubleshooting

• GUI Not Opening: Verify that the GUI file exists and is correctly formatted. For custom GUIs, ensure they are listed in config.yml under gui.custom_guis and the file name ends in _EN (e.g., ClaimUpgradeBiomeSelector_EN.yml). Check for errors in the server console.

• Theme Not Applied: Ensure the theme field in the GUI’s data section matches a <theme_name>_EN.yml file in the theme folder (e.g., default_EN.yml). Verify the theme file’s syntax.

• Items Not Displaying: Ensure slot is a valid integer (0–53 for a 6-row GUI) or slots is a valid list of integers, and that view_requirement conditions are met. Check that GUI item priorities are lower than theme item priorities (e.g., 1 or 2 vs. 5).

• Navigation Not Working: Confirm that Previous and Next sections are defined in the items section for multi-page GUIs, typically in slots 47 and 51.

• Dynamic Items Missing: For default custom GUIs, confirm that the required section (e.g., ICON_SELECTOR) is present in items.

• Commands Not Executing: Check that left_click_commands, right_click_commands, or click_commands are correctly defined and use valid syntax.

• Broken GUI: Avoid editing version or gui_type in the data section for default GUIs. For custom GUIs, ensure gui_type matches the custom_guis entry.

• Disabled GUIs: If a GUI is disabled in config.yml (disabled_guis), use the gpgui.bypass.guidisabled permission to access it.

For further assistance, contact the server admin or refer to the GriefPrevention GUI Addon documentation.