Skip to content

Creating-GUIs.md

Latest commit

 

History

History
253 lines (216 loc) · 8.24 KB

Creating-GUIs.md

File metadata and controls

253 lines (216 loc) · 8.24 KB

🎨 CREATING GUIS

Creating GUIs

Define custom inventory menus with YAML configuration

GUIs in GUIPlus are defined as YAML files inside the plugins/GUIPlus/CustomGuis/ folder. Each file represents one GUI menu.

Tip: You can also create GUIs through the in-game editor with /gui. The editor generates the YAML for you. See Getting Started for the editor workflow.

📐 GUI Structure

Every GUI file follows this structure:

id: mygui                    # Unique identifier (required)
type: chest                  # Inventory type (required)
rows: 3                      # Number of rows (chest only, 1-6)
title: §6My Menu             # Display title shown to players
commandAlias: mymenu         # Optional shortcut command to open this GUI
commandAliasTarget: OPTIONAL  # OPTIONAL, REQUIRED, or DISABLED
permission: my.perm.node     # Optional permission required to view
disable-scene-animation: false  # Disable animated scene transitions for this GUI
scenes:
  '0':                       # First scene (zero-indexed)
    delay: 0                 # Delay in ticks before this scene opens
    items:
      '1':                   # Item ID (unique within the scene)
        slot: 0              # Inventory slot (0-indexed, left to right, top to bottom)
        item: DIAMOND        # Material type
        amount: 1            # Stack size
        item-name: §bMy Item # Display name (supports color codes)
        item-lore:           # Lore lines
          - §7Description
        item-flags: []       # Item flags (HIDE_ENCHANTS, HIDE_ATTRIBUTES, etc.)
        unbreakable: false   # Whether the item is unbreakable
        click-events:        # Click event actions (see Click Events page)
          message:
            message: §aHello!
        conditions:          # Show conditions (see Conditions page)
          has-permission:
            permission: some.perm

📦 Inventory Types

Type Size Description
chest 9-54 slots (1-6 rows) Standard chest inventory. Use the rows field to set the size.
dispenser 9 slots (3x3) Dispenser-style layout. Fixed size.
dropper 9 slots (3x3) Dropper-style layout. Fixed size.
hopper 5 slots (1x5) Hopper-style layout. Fixed size.

🔢 Slot Numbers

Slots are numbered starting from 0, going left to right, top to bottom:

Chest (3 rows):

 0  1  2  3  4  5  6  7  8
 9 10 11 12 13 14 15 16 17
18 19 20 21 22 23 24 25 26

Hopper:

 0  1  2  3  4

Dispenser / Dropper:

 0  1  2
 3  4  5
 6  7  8

🏷 Item Properties

Each item in a scene supports the following properties:

Property Type Description
slot Integer The inventory slot position (required)
item String Minecraft material name, e.g. DIAMOND_SWORD (required)
amount Integer Stack size (default: 1)
item-name String Custom display name with color codes
item-lore List Lines of lore text
item-flags List Bukkit ItemFlags: HIDE_ENCHANTS, HIDE_ATTRIBUTES, HIDE_UNBREAKABLE, etc.
unbreakable Boolean Whether the item should be unbreakable
item-enchants Map Enchantments to apply, e.g. DURABILITY: 1
skullBase64 String Base64-encoded texture for PLAYER_HEAD items (see Custom Heads)
item-custom-model-data Integer Custom model data value for resource packs
item-model String Item model key as a namespaced ID (Minecraft 1.21.2+ only)
leather-color Integer Leather armor color as an ARGB integer (only for leather armor items)
item-attributes Map Attribute modifiers (see Item Attributes below)
click-events Map Actions triggered on click (see Click Events)
conditions Map Conditions for showing this item (see Conditions)
conditionFailMessage String Message shown when conditions are not met

Note: The sorting-group property is managed through the in-game editor and is stored in the item's compressed data. It is not a hand-writable YAML field. See Conditions — Sorting Groups for details.

⚔ Item Attributes

You can add attribute modifiers to items using the item-attributes property. Each attribute has a modifier with an amount, operation, and UUID:

item-attributes:
  GENERIC_ATTACK_DAMAGE:
    damage-boost:
      amount: 10.0
      operation: ADD_NUMBER
      uuid: 550e8400-e29b-41d4-a716-446655440000
Field Description
Attribute key A Bukkit attribute name (e.g., GENERIC_ATTACK_DAMAGE, GENERIC_MAX_HEALTH, GENERIC_MOVEMENT_SPEED)
Modifier key A unique name for this modifier
amount The modifier value
operation ADD_NUMBER, ADD_SCALAR, or MULTIPLY_SCALAR_1
uuid A UUID to identify this modifier (use any valid UUID)

🎨 Color Codes

GUIPlus supports standard Minecraft color codes using § (section sign):

Code Color Code Format
§0 Black §l Bold
§1 Dark Blue §m Strikethrough
§2 Dark Green §n Underline
§3 Dark Aqua §o Italic
§4 Dark Red §r Reset
§5 Dark Purple
§6 Gold
§7 Gray
§8 Dark Gray
§9 Blue
§a Green
§b Aqua
§c Red
§d Light Purple
§e Yellow
§f White

🏷 Command Alias

The commandAlias field registers a shortcut command for your GUI:

id: shop
commandAlias: shop

Players can now use /shop to open this GUI directly, instead of /gui open shop.

🎯 Command Target

The commandAliasTarget field controls whether the command alias accepts a player argument:

Value Behavior
OPTIONAL /shop opens for self, /shop PlayerName opens for target
REQUIRED /shop PlayerName is required (useful for admin tools)
DISABLED No player argument accepted

🛡 Example: Complete Admin Panel

id: adminpanel
rows: 3
type: chest
title: §cAdmin Panel
commandAlias: adminpanel
scenes:
  '0':
    delay: 0
    items:
      '1':
        slot: 11
        item: DAMAGED_ANVIL
        amount: 1
        item-name: §cBan User
        item-lore:
          - ''
          - §7Is someone breaking the
          - §7rules? or want them gone?
          - ''
          - §cClick to ban
        item-flags: []
        unbreakable: false
        conditionFailMessage: §cYou can't do that!
        conditions:
          has-permission:
            permission: gui.ban.user
        click-events:
          player-picker-by-player-command:
            command: ban %player% Banned by %executor%
          message:
            message: §bYou have §cbanned §7%player%§b!
      '2':
        slot: 13
        item: ELYTRA
        amount: 1
        item-name: §eKick User
        item-lore:
          - ''
          - §7Want to kick a user?
          - §7you have come to right
          - §7place!
          - ''
          - §eClick to kick
        item-flags: []
        unbreakable: false
        conditionFailMessage: §cYou can't do that!
        conditions:
          has-permission:
            permission: gui.kick.user
        click-events:
          player-picker-by-player-command:
            command: kick %player% You have been kicked by %executor%
          message:
            message: §eYou have kicked §7%player%§e!
      '3':
        slot: 15
        item: LECTERN
        amount: 1
        item-name: §aPardon User
        item-lore:
          - ''
          - §7You can unban/pardon a
          - §7user!
          - ''
          - §bClick to pardon
        item-flags: []
        unbreakable: false
        conditions:
          has-permission:
            permission: gui.pardon.user
        click-events:
          offline-player-picker-command:
            command: unban %player%
          message:
            message: §aYou have successfully unbanned §7%player%§a!
← Previous Next →
Configuration Scenes