# 🎨 Gui

## 🎨 GUI Configuration Overview

This section explains how to configure the basic elements of a GUI in **nwMMOUpgrade**, including filter slots, confirm buttons, GUI titles, display settings, and custom GUI items.

```yaml
applies-to:
  - SWORD;KATANA
  - PICKAXE

# Sound settings
# https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html
sounds:
  confirm-success: ENTITY_EXPERIENCE_ORB_PICKUP # Sound on successful upgrade
  confirm-fail: BLOCK_ANVIL_DESTROY # Sound on failed upgrade
  confirm-no-item: BLOCK_NOTE_BLOCK_PLING # Sound when confirming with no item

# GUI customization
gui:
  title: "&bSword Upgrade Station" # GUI title
  rows: 6 # GUI rows (1-6)
  display-slots:
    item:
      material: LIME_STAINED_GLASS_PANE
      name: "<color:#00FF4F>Place the item to upgrade<color:#57E342>"
      lore:
        - "&7Drag and drop your item here"
      cmd: 1
    material:
      material: YELLOW_STAINED_GLASS_PANE
      name: "<color:#E7FF00>Place the materials<color:#F2FF08>"
      lore:
        - "&7Drag and drop the required materials here"
      cmd: 1
    chance:
      material: PINK_STAINED_GLASS_PANE
      name: "<color:#FF00F8>Place a chance-enhancing stone (if any)<color:#E68DFF>"
      lore:
        - "&7Drag and drop the chance-enhancing stone here"
      cmd: 1
    protection:
      material: BLUE_STAINED_GLASS_PANE
      name: "<color:#FF00F8>Place a protection stone (if any)<color:#E68DFF>"
      lore:
        - "&7Drag and drop the protection stone here"
      cmd: 1
  slots:
    item: 13 # Slot for the item to upgrade
    confirm:
      material: GREEN_STAINED_GLASS_PANE # Confirm button material
      name: "&a&lConfirm Upgrade" # Confirm button name
      lore: # Confirm button lore
        - "&7Click to upgrade"
        - ""
        - "&fCost: &a{cost}"
        - "&fSuccess Chance: &6{chance}%"
        - "&fMaterials:"
        - "{material}"
      slot: 40 # Confirm button slot
      cmd: 1 # Custom Model Data (if any)
    filter:
      name: "&f" # Filter name (not displayed)
      material: BLACK_STAINED_GLASS_PANE # Filter material
      cmd: 1 # Custom Model Data (if any)

```

**Example:**

```yaml
title: "&bSword Upgrade Station" #Sets the title displayed at the top of the GUI window.
rows: 6 #Defines the number of rows in the GUI.
```

```yaml
name: "<white> </white>" #Defines the display name of the item shown in the GUI slot.
material: BLACK_STAINED_GLASS_PANE #Sets the type of item or block used in that GUI slot.
cmd: 1 # Assigns a Custom Model Data value for servers using a resource pack. Useful for customizing item appearance.
lore: #Adds descriptive hover text to the item in the GUI.
  - "&7Click to upgrade"
```

```yaml
#Customize slot
slot: 1 

slot:
- 1-5
- 6

slot: [1,2,3,4,5]
```

**Note:**\
If any name is set to `"<white> </white>"`, the item will appear **nameless** to players — commonly used for filler items.

## 🎨 Color Code Support

You can use the following color formats inside GUI text:

* **RGB** – `&#ffffff`
* **Standard** – `&f`
* **MiniMessage** – `<red>`
* **Legacy Hex** – `&x&...`

{% content-ref url="configuration/message.yml" %}
[message.yml](https://nwplugin.gitbook.io/nwplugin-or-nn/my-plugins/nwmmoupgrade-premium/configuration/message.yml)
{% endcontent-ref %}

***

## 🧩 1. Applies To

You can specify **multiple MMOItem types** that the GUI configuration applies to.

You can also target a **specific MMOItem** directly by using:

```
type:id
```

This lets you apply separate GUI configurations for:

* an entire MMOItem type, or
* a single specific item.

```yaml
applies-to:
  - SWORD;KATANA
  - PICKAXE
```

## 🔊 2. Sound

Each GUI can specify its own sound effects.

```
sound: custom:xxx
```

Sound can be:

* Vanilla sound names
* Custom sound using `custom:`

```yaml
# Sound settings
# https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html
sounds:
  confirm-success: ENTITY_EXPERIENCE_ORB_PICKUP # Sound on successful upgrade
  confirm-fail: BLOCK_ANVIL_DESTROY # Sound on failed upgrade
  confirm-no-item: BLOCK_NOTE_BLOCK_PLING # Sound when confirming with no item
```

```yaml
# Sound settings
# https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html
sounds:
  confirm-success: custom:upgrade.success # Sound on successful upgrade
  confirm-fail: custom:upgrade.fail# Sound on failed upgrade
  confirm-no-item: custom:upgrade.noitem# Sound when confirming with no item
```

## 📦 3. Display Slots

Display slots act as visual indicators that help players understand what items belong in which slot.

For each display slot, you can customize:

* Name
* Lore
* Material
* Command (cmd)
* Slot position

#### **Supported Placeholders (for chance/material/protection items only)**

| Placeholder   | Description                          |
| ------------- | ------------------------------------ |
| **{items}**   | Shows all items required in the slot |
| **{item}**    | Shows one required item              |
| **{item\_x}** | Shows a specific item by index       |
| **{count}**   | Shows how many items can be inserted |

```yaml
display-slots:
    item:
      material: LIME_STAINED_GLASS_PANE
      name: "<color:#00FF4F>Place the item to upgrade<color:#57E342>"
      lore:
        - "&7Drag and drop your item here"
      cmd: 1
    material:
      material: YELLOW_STAINED_GLASS_PANE
      name: "<color:#E7FF00>Place the materials<color:#F2FF08>"
      lore:
        - "&7Drag and drop the required materials here"
        - "{items}"
      cmd: 1
    chance:
      material: PINK_STAINED_GLASS_PANE
      name: "<color:#FF00F8>Place a chance-enhancing stone (if any)<color:#E68DFF>"
      lore:
        - "&7Drag and drop the chance-enhancing stone here"
      cmd: 1
    protection:
      material: BLUE_STAINED_GLASS_PANE
      name: "<color:#FF00F8>Place a protection stone (if any)<color:#E68DFF>"
      lore:
        - "&7Drag and drop the protection stone here"
        - "{items}"
      cmd: 1
    gem: #gemadditem station
      material: PURPLE_STAINED_GLASS_PANE
      name: "<color:#00FF4F>Place the item to gem<color:#57E342>"
      lore:
        - "&7Drag and drop your gem here"
      cmd: 1
    result: #merge station
      material: RED_STAINED_GLASS_PANE
      name: "<color:#FF0000>Place the result item to merge<color:#FF1818>"
      lore:
        - "&7Drag and drop your item here"
      cmd: 1
    display-gem-un-socket: #gemunsocket station
      material: PURPLE_STAINED_GLASS_PANE
      name: "&f"
      lore:
        - "&f"
      cmd: 1
      slot: [28, 29, 30, 31, 32, 33, 34]
```

**Example**&#x20;

<figure><img src="https://1245303946-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEMKTTfYtO1c14jr3rkcH%2Fuploads%2FpuSrWGT1pdctinUJV1VI%2Fimage.png?alt=media&#x26;token=7530d099-6fef-4251-a240-dec76c0ae008" alt=""><figcaption><p>Display Item</p></figcaption></figure>

***

## ✔️ 4. Confirm Button

The Confirm Button allows a player to finalize the selected action in a station.

This button triggers the upgrade action defined inside the station’s configuration.

```yaml
  slots:
    confirm:
      material: GREEN_STAINED_GLASS_PANE # Confirm button material
      name: "&a&lConfirm Upgrade" # Confirm button name
      lore: # Confirm button lore
        - "&7Click to upgrade"
        - ""
        - "&fCost: &a{cost}"
        - "&fSuccess Chance: &6{chance}%"
        - "&fMaterials:"
        - "{material}"
      slot: 40 # Confirm button slot
      cmd: 1 # Custom Model Data (if any)

```

**Example**&#x20;

<figure><img src="https://1245303946-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEMKTTfYtO1c14jr3rkcH%2Fuploads%2Fx6bz0ce0yPftMxgQTVNs%2Fimage.png?alt=media&#x26;token=9a56d71f-411d-4d41-aa9f-7a560405be71" alt=""><figcaption><p>Confirm Button</p></figcaption></figure>

***

## 🧱 5. Filter Item

Filter items are placed in empty or unused GUI slots to:

* Prevent players from interacting with those slots
* Prevent exploits
* Fill unused space visually

Filter items usually use filler panes or blank items.

```yaml
slots:
    ....
    filter:
      name: "&f" # Filter name (not displayed)
      material: BLACK_STAINED_GLASS_PANE # Filter material
      cmd: 1 # Custom Model Data (if any)
```

**Example**&#x20;

<figure><img src="https://1245303946-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEMKTTfYtO1c14jr3rkcH%2Fuploads%2FQNX5lcMwMiZUKDuxbGSB%2Fimage.png?alt=media&#x26;token=6c19cc66-c93e-4fd4-b3c0-5b488b1c0885" alt=""><figcaption><p>Filter Item</p></figcaption></figure>

***

## ⭐ 6. Custom GUI Item

Custom GUI Items allow you to add **fully customized items** anywhere inside the GUI.

They can:

* Display a custom name
* Display custom lore
* Perform **custom actions** when clicked
* Be placed in single or multiple slots
* Use any material
* Include commands via `actions:`

These items do **not** affect the upgrade logic — they are utility or decorative items added to the GUI.

#### **Configuration Example**

```yaml
##########################################################################
#
#                         nwMMOUpgrade - Reroll
#      Created By Discord NN#7999 (Newworld Server)
#
#      Supports RGB and standard color codes.
#      1.RGB = &#ffffff
#      2.Standard = &f
#      3. MiniMessage = <red>
#      4. Legacy Hex = &x
#      https://www.birdflop.com/resources/rgb/
#
##########################################################################

#Contact&Support: https://discord.gg/gwXcr7c6Gq

#MMOItems Type
applies-to:
  - SWORD

# Sound settings
#https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html
sounds:
  confirm-success: ENTITY_EXPERIENCE_ORB_PICKUP
  confirm-fail: BLOCK_ANVIL_DESTROY
  confirm-no-item: BLOCK_NOTE_BLOCK_PLING

#GUI customization
gui:
  #GUI title, should support images normally.
  title: "&bReroll Stat Item"
  rows: 6 #GUI slots
  display-slots:
    item:
      material: LIME_STAINED_GLASS_PANE
      name: "<color:#00FF4F>Place the item to upgrade<color:#57E342>"
      lore:
        - "&7Drag and drop your item here"
      cmd: 1
    material:
      material: YELLOW_STAINED_GLASS_PANE
      name: "<color:#E7FF00>Place the materials<color:#F2FF08>"
      lore:
        - "&7Drag and drop the required materials here"
      cmd: 1
    chance:
      material: PINK_STAINED_GLASS_PANE
      name: "<color:#FF00F8>Place a chance-enhancing stone (if any)<color:#E68DFF>"
      lore:
        - "&7Drag and drop the chance-enhancing stone here"
      cmd: 1
  slots:
    #Slot for the item you want to add Gem slots to.
    item: 13
    confirm:
      material: BRICK
      name: "&a&lConfirm" #Button name
      lore: #Add your messages here.
        - "&7Click to add a Reroll"
        - ""
        - "&fCost: &a{cost}"
        - "&fSuccess Chance: &6{chance}%"
        - "&fMaterials:"
        - "{material}" # edit custom line -> missing-material-line: "- &4<gray>{material} <red>{amount}"
      slot:
        - 48-50
      #Supports custom model data.
      cmd: 2600
    filter:
      name: "&f" #Name
      material: BLACK_STAINED_GLASS_PANE
      cmd: 1
    custom:
      wallpaper: <----- You can name anything.
        name: "&f" #Name
        material: RED_STAINED_GLASS_PANE
        slots: 8
        cmd: 1
        lore: #Add your messages here.
          - "&7Click to add a Reroll"
        actions:
          - guild invite %player%
      free-item:  <----- You can name anything.
        name: "&f" #Name
        material: YELLOW_STAINED_GLASS_PANE
        slots:
          - 1
          - 2
          - 3
        cmd: 1
        lore: #Add your messages here.
          - "&7Click to add a Reroll"
        actions:
          - say 55555
```

***

## 🗝️ 7. Main Item

This represents the **primary slot** used to place the item that will be upgraded or processed.

Players must place their main item here for the station to work.

```yaml
slots:
    item: 13
    result: 24 #merge station
    gem: 22 # gemadditem station
    .....
```

**Example**

<figure><img src="https://1245303946-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEMKTTfYtO1c14jr3rkcH%2Fuploads%2FPZ9mMe2ievTlJCNGfagI%2Fimage.png?alt=media&#x26;token=d98d2e9e-6601-40ab-9d4d-4cd7f19b7343" alt=""><figcaption><p>item slot</p></figcaption></figure>

***