# BetterGUI


BetterGUI is a Spigot plugin to create inventory menus. It's known for the modular design so that addons can be made to add more features to the main plugin.

## Feature

* Stable
* Modular design
* From Simple to Complex
* [Menu]({{% ref "menu/overview" %}}) to make your dream one
* [Button]({{% ref "button/overview" %}}) to add
* [Item Modifier]({{% ref "modifier/overview" %}}) to edit your display item
* [Action]({{% ref "action/overview" %}}) to execute
* [Requirement]({{% ref "requirement/overview" %}}) to check before doing actions
* [Arguments in menus]({{% ref "argument" %}})
* [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) support
* More features with [Addon]({{% ref "addon" %}})
  * [BungeeCord support]({{% ref "addon/bungee-link" %}})
  * [Vault support]({{% ref "addon/vault-bridge" %}})
  * [PlayerPoints support]({{% ref "addon/player-points-bridge" %}})
  * [Custom conditions]({{% ref "addon/eval-extra" %}})
  * [PaperMC support]({{% ref "addon/paper-spec" %}})
  * [Custom item check]({{% ref "addon/item-gotcha" %}})
  * [Animated inventory title]({{% ref "addon/dynamic-title" %}})
  * [...and more]({{% ref "addon" %}})
---


# Basic

This contains the basic tutorials of the plugin, including the installation, the commands & the FAQs
---



## Install the plugin

1. Download the plugin
2. Copy/Cut the plugin and paste it to your `plugins` folder
3. Start the server to let it load
4. Stop the server
5. Make some configs and menus
6. Start the server and voila

---


## Add a menu

1. Go to the `plugins/BetterGUI/menu` folder
2. Create a ".yml" file
3. Open the created file
4. [Add some menu settings and buttons]({{% ref "menu" %}})
5. Save the file
6. Reload the plugin
7. Done

---


## Add an addon

1. [Download the addon]({{% ref "addon" %}})
2. Go to the `plugins/BetterGUI/addon` folder
3. Copy/Cut the downloaded jar file and paste it to the folder
4. Start/Restart the server
5. Done

{{% notice style="warning" %}}
It's recommended to use [Addon Downloader]({{% ref "menu/addon" %}}) to install the addons.

For those who choose to manually download the official addons, make sure to download the one with `-shaded` in its name.
{{% /notice %}}

---


## Command & Permission

| Command | Permission | Description |
| --- | --- | :---: |
| `bettergui` | bettergui.help | Show available commands and menu commands |
| `addons` | bettergui.addons | Get the loaded addons |
| `openmenu <filename.yml> [player] [args]` | bettergui.openmenu | Open the specific menu (for a specific player) |
| `reloadmenu` | bettergui.reload | Reload all menus |
| `reloadplugin` | bettergui.reload | Reload the plugin |
| `getvariables` | bettergui.variable | Get the registered variables |
| `getvariables <filename.yml>` | bettergui.variable | Get the registered variables for a menu |
| `gettemplatebuttons` | bettergui.templatebuttons | Get the registered template buttons |
| | bettergui.\<filename\>.yml | The permission that is required to open the menu |
| | bettergui.openmenu.bypass | Allow the player to open all menus |

---


## Config

```yaml
# Use BetterGUI's Click Type with support for number keys
use-modern-click-type: false

# Whether the plugin replaces all similar variables on every check
replace-all-variables-each-check: true

# Use the legacy button that supports the old settings
use-legacy-button: true

# Whether the plugin should use the relative path name instead of the file name when registering menus
relative-menu-name: false

# Whether the plugin should trim the file extension of the menu name
trim-menu-file-extension: false

# Whether the config file name should be included in template name
# If set to true, the template name will be "<config>/<template>" instead of "<template>"
include-menu-in-template: false
```

---


## Frequently Asked Questions

## Why does this plugin exist?

I used Chest Commands GUI to make menus for a long time. Some other GUI plugins (like DeluxeMenus and BossShop) are awesome, but I'm lazy to learn just to create the menu I want. I want a plugin with the same format as Chest Commands GUI and the features I need. Therefore, I created this.

## Why does it look like Chest Commands?

Before starting this plugin, I also made a fork for Chest Commands called "Chest Commands GUI - Forked". Due to some frustrating problems while working with it, I decided to shut it down and make my own. I keep the old style because it's the simplest one and many people have been using it for years.

## Why should I use this plugin?
I don't know. I'm bad at giving you a motivation to use this. There are even a lot of GUI plugins that are somehow better than this. But this plugin preserves some basic features of a GUI plugin should have (like Chest Commands, one of the famous plugin). You can use this to make some basic or animated menus. The style of the menu settings is fairly simple to learn (but the wiki may not). You can join my Discord to get support, I'm happy to help you_

**TL;DR**: Basic features, simple style, good support

## Why don't you combine all features from addons into one big plugin?

One of the goals of this plugin is to create a plugin that can be used by any type of servers. Since I don't know which feature is commonly used, combining all features would be a waste of resources, as some functions are rarely used. So I give the users the choice of choosing which features they want.

## Why does X not work?

Join [my Discord server](https://discord.gg/5vpVM6g4SV). I'm there to help you

## How to use X?

Read the wiki

## Why don't you add a migrator from other GUI plugins? Like Chest Commands GUI, DeluxeMenus, BossShop, TrMenu, etc

Those plugins combine a lot of features into one plugin only. BetterGUI has a different approach, only useful features are in the main plugin, Others are in addons. I won't support all features of these plugins in BetterGUI, because I don't have any reason to create and maintain a converter from their plugins. One more thing, These plugins are not abandoned, the authors still support and update them (Maybe not in a frequent time), so why don't you use them?

## Why are you slow in helping us on your plugins?

I'm a human, you know. I have a life, and get busy with it. My plugins are free and I only do these plugins in my free-time, to fulfill my own needs. Therefore, my help support is voluntary, not mandatory, so are my Discord helpers. I may answer your questions when I have time, and I don't have a responsibility to answer your question instantly. Well, my time is important than yours, don't expect me to spend my busy time for free, but if it's in my free time, I can help you.

## I don't like the wiki. Don't waste my time. Make it easy to use already. I don't understand how to use it. I'll give you 1 star for this.

So you are not a patient person, and want to do everything fast? Well, then you will not get anything useful from this wiki, or any wiki from any big plugins. It takes time to learn something, I don't even encourage you to use this plugin. Your choice is yours. Your time is yours. But sometimes a few things in your life cannot be done fast. Even if it can, it may be done poorly, so I want to avoid it and do slowly and steadily. If you are finding a plugin that is easy or fast to create your dream menus, or has an in-game editor, this is not the place, choose another one. But if you choose this plugin, spend some time reading the full wiki, as you may miss features that are useful. Don't be [this meme](meme.jpg)

## Can you add X to your plugin?

Before requesting, you should check if your request already exists on the [Addon]({{% ref "addon" %}}). If it does not exist, you can either join [my Discord server](https://discord.gg/5vpVM6g4SV) or create [an issue](https://github.com/BetterGUI-MC/Issue-Tracker/issues).

---




## Install the plugin

1. Download the plugin
2. Copy/Cut the plugin and paste it to your `plugins` folder
3. Start the server to let it load
4. Stop the server
5. Make some configs and menus
6. Start the server and voila
---




---


## Add a menu

1. Go to the `plugins/BetterGUI/menu` folder
2. Create a ".yml" file
3. Open the created file
4. [Add some menu settings and buttons]({{% ref "menu" %}})
5. Save the file
6. Reload the plugin
7. Done
---




---


## Add an addon

1. [Download the addon]({{% ref "addon" %}})
2. Go to the `plugins/BetterGUI/addon` folder
3. Copy/Cut the downloaded jar file and paste it to the folder
4. Start/Restart the server
5. Done

{{% notice style="warning" %}}
It's recommended to use [Addon Downloader]({{% ref "menu/addon" %}}) to install the addons.

For those who choose to manually download the official addons, make sure to download the one with `-shaded` in its name.
{{% /notice %}}
---




---


## Command & Permission

| Command | Permission | Description |
| --- | --- | :---: |
| `bettergui` | bettergui.help | Show available commands and menu commands |
| `addons` | bettergui.addons | Get the loaded addons |
| `openmenu <filename.yml> [player] [args]` | bettergui.openmenu | Open the specific menu (for a specific player) |
| `reloadmenu` | bettergui.reload | Reload all menus |
| `reloadplugin` | bettergui.reload | Reload the plugin |
| `getvariables` | bettergui.variable | Get the registered variables |
| `getvariables <filename.yml>` | bettergui.variable | Get the registered variables for a menu |
| `gettemplatebuttons` | bettergui.templatebuttons | Get the registered template buttons |
| | bettergui.\<filename\>.yml | The permission that is required to open the menu |
| | bettergui.openmenu.bypass | Allow the player to open all menus |
---




---


## Config

```yaml
# Use BetterGUI's Click Type with support for number keys
use-modern-click-type: false

# Whether the plugin replaces all similar variables on every check
replace-all-variables-each-check: true

# Use the legacy button that supports the old settings
use-legacy-button: true

# Whether the plugin should use the relative path name instead of the file name when registering menus
relative-menu-name: false

# Whether the plugin should trim the file extension of the menu name
trim-menu-file-extension: false

# Whether the config file name should be included in template name
# If set to true, the template name will be "<config>/<template>" instead of "<template>"
include-menu-in-template: false
```
---




---


## Frequently Asked Questions

## Why does this plugin exist?

I used Chest Commands GUI to make menus for a long time. Some other GUI plugins (like DeluxeMenus and BossShop) are awesome, but I'm lazy to learn just to create the menu I want. I want a plugin with the same format as Chest Commands GUI and the features I need. Therefore, I created this.

## Why does it look like Chest Commands?

Before starting this plugin, I also made a fork for Chest Commands called "Chest Commands GUI - Forked". Due to some frustrating problems while working with it, I decided to shut it down and make my own. I keep the old style because it's the simplest one and many people have been using it for years.

## Why should I use this plugin?
I don't know. I'm bad at giving you a motivation to use this. There are even a lot of GUI plugins that are somehow better than this. But this plugin preserves some basic features of a GUI plugin should have (like Chest Commands, one of the famous plugin). You can use this to make some basic or animated menus. The style of the menu settings is fairly simple to learn (but the wiki may not). You can join my Discord to get support, I'm happy to help you_

**TL;DR**: Basic features, simple style, good support

## Why don't you combine all features from addons into one big plugin?

One of the goals of this plugin is to create a plugin that can be used by any type of servers. Since I don't know which feature is commonly used, combining all features would be a waste of resources, as some functions are rarely used. So I give the users the choice of choosing which features they want.

## Why does X not work?

Join [my Discord server](https://discord.gg/5vpVM6g4SV). I'm there to help you

## How to use X?

Read the wiki

## Why don't you add a migrator from other GUI plugins? Like Chest Commands GUI, DeluxeMenus, BossShop, TrMenu, etc

Those plugins combine a lot of features into one plugin only. BetterGUI has a different approach, only useful features are in the main plugin, Others are in addons. I won't support all features of these plugins in BetterGUI, because I don't have any reason to create and maintain a converter from their plugins. One more thing, These plugins are not abandoned, the authors still support and update them (Maybe not in a frequent time), so why don't you use them?

## Why are you slow in helping us on your plugins?

I'm a human, you know. I have a life, and get busy with it. My plugins are free and I only do these plugins in my free-time, to fulfill my own needs. Therefore, my help support is voluntary, not mandatory, so are my Discord helpers. I may answer your questions when I have time, and I don't have a responsibility to answer your question instantly. Well, my time is important than yours, don't expect me to spend my busy time for free, but if it's in my free time, I can help you.

## I don't like the wiki. Don't waste my time. Make it easy to use already. I don't understand how to use it. I'll give you 1 star for this.

So you are not a patient person, and want to do everything fast? Well, then you will not get anything useful from this wiki, or any wiki from any big plugins. It takes time to learn something, I don't even encourage you to use this plugin. Your choice is yours. Your time is yours. But sometimes a few things in your life cannot be done fast. Even if it can, it may be done poorly, so I want to avoid it and do slowly and steadily. If you are finding a plugin that is easy or fast to create your dream menus, or has an in-game editor, this is not the place, choose another one. But if you choose this plugin, spend some time reading the full wiki, as you may miss features that are useful. Don't be [this meme](meme.jpg)

## Can you add X to your plugin?

Before requesting, you should check if your request already exists on the [Addon]({{% ref "addon" %}}). If it does not exist, you can either join [my Discord server](https://discord.gg/5vpVM6g4SV) or create [an issue](https://github.com/BetterGUI-MC/Issue-Tracker/issues).
---




---



# Menu

The biggest unit which serves as an interface the user can interact & do actions with.
---



## Overview

* Menus are what BetterGUI is for. It's the thing displayed to the player.
* There are many built-in types of Menu (Check the sidebar). A developer can also make his own menu and register to the plugin.
* Generally, a menu contains 2 sections: `menu-settings` and [**Button**]({{% ref "../button/overview" %}})
* You can set the type of menu by setting the `menu-type` value in the `menu-settings` section

## Example
```yaml
menu-settings:
  name: '&c&lExample Menu'
  rows: 6
  command: menu
  auto-refresh: 5
  open-action:
    - "tell: &eYou opened the example menu"
  close-action:
    - "tell: &cYou closed the example menu"

# Buttons
spawn-cmd:
  COMMAND: 'spawn'
  NAME: '&u/spawn'
  LORE:
    - 'It just executes /spawn'
    - 'as the player who clicked.'
  ID: ender_pearl
  POSITION-X: 1
  POSITION-Y: 2
```

---


## Simple Menu

This is the default menu type of BetterGUI, represents a chest-like GUI.

## Format

```yaml
menu-settings:
  menu-type: simple # You don't need to set this type. It's the default value

  # The actions when the player opens the menu
  open-action:
  - action
  - action
  - action
  ...

  # The actions when the player closes the menu
  close-action:
  - action
  - action
  - action
  ...

  # The type of the display inventory
  # https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/InventoryType.html
  inventory-type: <inventory-type>
  #inventory: <inventory-type>

  # The rows <1-6> of the inventory if the type is CHEST
  rows: <1-6>

  # How frequently the menu will refresh itself
  auto-refresh: <ticks>
  #ticks: <ticks>

  # The requirement before the player can open the menu
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The requirement before the player can close the menu
  close-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The permission required to open the menu
  permission: bettergui.test

  # The command to open the menu
  command:
  - command1
  - command2
  ...

  # The title of the inventory
  title: <name>
  #name: <name>

  # Save the display to the cache for later use
  # This option is mainly used to fix a "self-open" issue when the player open the same menu
  cached: <true/false>

  # The creator to create the inventory. Mainly used to create custom inventories provided by addons.
  creator: default

  # The list of argument processors to process the arguments of the command to open the menu
  argument-processor:
  - <argument-processor>
  - <argument-processor>
 
  # The delay in milliseconds that a player can click the buttons of the menu
  click-delay: <millis>

# This is a special button. It will fill all empty slots of the inventory (You don't need to set this button)
default-button:
  <button-settings>

button1:
  <button-settings>
button2:
  <button-settings>
...
```

## Note

* `open-action`: the [Action]({{% ref "action/overview" %}}) when the menu is opened.
* `close-action`: the [Action]({{% ref "action/overview" %}}) when the menu is closed.
* `view-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before opening the menu. If it is not met, the menu will not be opened.
* `close-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before closing the menu. If it is not met, the menu will not be closed.
* `argument-processor`: the [Argument Processor]({{% ref "argument" %}}) to handle the arguments of the command to open the menu.

## Example

```yaml
menu-settings:
  name: '&c&lExample Menu'
  rows: 6
  command: menu
  auto-refresh: 5
  open-action:
    - "tell: &eYou opened the example menu"
  close-action:
    - "tell: &cYou closed the example menu"

default-icon:
  type: animated
  child:
    frame1:
      id:
        - RED_STAINED_GLASS_PANE
        - STAINED_GLASS_PANE:14
    frame2:
      id:
        - GREEN_STAINED_GLASS_PANE
        - STAINED_GLASS_PANE:13
    frame3:
      id:
        - BLUE_STAINED_GLASS_PANE
        - STAINED_GLASS_PANE:11

# Buttons
spawn-cmd:
  COMMAND: 'spawn'
  NAME: '&u/spawn'
  LORE:
    - 'It just executes /spawn'
    - 'as the player who clicked.'
  ID: ender_pearl
  POSITION-X: 1
  POSITION-Y: 2

durability-armor:
  NAME: '&aDamaged armor'
  LORE:
    - 'This armor is damaged.'
  ID: diamond helmet
  DAMAGE: 100
  POSITION-X: 2
  POSITION-Y: 2
```

---


## Addon Downloader

* This is a special menu that displays the available addons of BetterGUI.
* You can view the addons and read their wiki
* You can also download addons and they'll be installed automatically (Requires restarting the server after downloading to enable the addons)

## Format

```yaml
menu-settings:
  menu-type: addon

  # The name of the menu
  name: '&c&lAddon Downloader'

  # The rows of the menu
  rows: 3

  # The command to open the menu
  command:
    - addondownloader
    - addondl

  # The period in ticks to refresh the menu
  auto-refresh: 5

# The button for each addon
button:
  material:
    - LIGHT_BLUE_STAINED_GLASS_PANE
    - STAINED_GLASS_PANE:3
  name: "&f{name} &c- &4{status}"
  lore:
    - "&f{description}"
    - "&fAuthors: &e{author}"
    - "&fVersion: &e{version}"
    - ""
    - "&bLeft click &fto download"
    - "&bRight click &fto get the source code"
    - "&bMiddle click &fto see the wiki"
```

---


## Predicate Menu

This is an arbitrary menu that serves as a switch that you can add some [Menus]({{% ref "menu/overview" %}}) and some [Requirements]({{% ref "requirement/overview" %}}) for each [Menu]({{% ref "menu/overview" %}}) to check before opening one of them.

## Format

```yaml
menu-settings:
  menu-type: predicate

  permission: bettergui.test

  command:
  - command1
  - command2
  ...

  argument-processor:
  - <argument-processor>
  - <argument-processor>

menu-name1:
  menu: <menu-file>
  argument: <args>
  requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

menu-name2:
  menu: <menu-file>
  argument: <args>
  requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

```

## Note

* `menu-settings`
  * `permission`: the required permission to open the menu.
  * `command`: the commands to open the menu.
  * `argument-processor`: the [Argument Processor]({{% ref "argument" %}}) to handle the arguments of the command to open the menu.

* `menu-name1`, `menu-name2`, etc.
  * `menu`: the file of the menu to open,
  * `argument`: the argument to pass when opening the menu. It's optional
  * `requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before opening the menu. If it's not set, the plugin will assume that the menu can always be opened.

* The plugin will check the requirement of each menus in the top-down order of the config. If it found a menu whose requirements are met, it would open that menu. Otherwise, nothing happened.

## Example

```yaml
# level-predicate.yml
menu-settings:
  menu-type: predicate
  command: level

level-5:
  menu: level-5.yml
  requirement:
    check-level:
      level:
        value: 5
        take: false

level-2:
  menu: level-2.yml
  requirement:
    check-level:
      level:
        value: 2
        take: false

level-0:
  menu: level-0.yml

# level-5.yml
menu-settings:
  title: "&aYou reached level 5!"

# level-2.yml
menu-settings:
  title: "&aYou reached level 2!"

# level-0.yml
menu-settings:
  title: "&cYou don't have enough levels!"
```

---




## Simple Menu

This is the default menu type of BetterGUI, represents a chest-like GUI.

## Format

```yaml
menu-settings:
  menu-type: simple # You don't need to set this type. It's the default value

  # The actions when the player opens the menu
  open-action:
  - action
  - action
  - action
  ...

  # The actions when the player closes the menu
  close-action:
  - action
  - action
  - action
  ...

  # The type of the display inventory
  # https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/InventoryType.html
  inventory-type: <inventory-type>
  #inventory: <inventory-type>

  # The rows <1-6> of the inventory if the type is CHEST
  rows: <1-6>

  # How frequently the menu will refresh itself
  auto-refresh: <ticks>
  #ticks: <ticks>

  # The requirement before the player can open the menu
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The requirement before the player can close the menu
  close-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The permission required to open the menu
  permission: bettergui.test

  # The command to open the menu
  command:
  - command1
  - command2
  ...

  # The title of the inventory
  title: <name>
  #name: <name>

  # Save the display to the cache for later use
  # This option is mainly used to fix a "self-open" issue when the player open the same menu
  cached: <true/false>

  # The creator to create the inventory. Mainly used to create custom inventories provided by addons.
  creator: default

  # The list of argument processors to process the arguments of the command to open the menu
  argument-processor:
  - <argument-processor>
  - <argument-processor>
 
  # The delay in milliseconds that a player can click the buttons of the menu
  click-delay: <millis>

# This is a special button. It will fill all empty slots of the inventory (You don't need to set this button)
default-button:
  <button-settings>

button1:
  <button-settings>
button2:
  <button-settings>
...
```

## Note

* `open-action`: the [Action]({{% ref "action/overview" %}}) when the menu is opened.
* `close-action`: the [Action]({{% ref "action/overview" %}}) when the menu is closed.
* `view-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before opening the menu. If it is not met, the menu will not be opened.
* `close-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before closing the menu. If it is not met, the menu will not be closed.
* `argument-processor`: the [Argument Processor]({{% ref "argument" %}}) to handle the arguments of the command to open the menu.

## Example

```yaml
menu-settings:
  name: '&c&lExample Menu'
  rows: 6
  command: menu
  auto-refresh: 5
  open-action:
    - "tell: &eYou opened the example menu"
  close-action:
    - "tell: &cYou closed the example menu"

default-icon:
  type: animated
  child:
    frame1:
      id:
        - RED_STAINED_GLASS_PANE
        - STAINED_GLASS_PANE:14
    frame2:
      id:
        - GREEN_STAINED_GLASS_PANE
        - STAINED_GLASS_PANE:13
    frame3:
      id:
        - BLUE_STAINED_GLASS_PANE
        - STAINED_GLASS_PANE:11

# Buttons
spawn-cmd:
  COMMAND: 'spawn'
  NAME: '&u/spawn'
  LORE:
    - 'It just executes /spawn'
    - 'as the player who clicked.'
  ID: ender_pearl
  POSITION-X: 1
  POSITION-Y: 2

durability-armor:
  NAME: '&aDamaged armor'
  LORE:
    - 'This armor is damaged.'
  ID: diamond helmet
  DAMAGE: 100
  POSITION-X: 2
  POSITION-Y: 2
```
---




---


## Addon Downloader

* This is a special menu that displays the available addons of BetterGUI.
* You can view the addons and read their wiki
* You can also download addons and they'll be installed automatically (Requires restarting the server after downloading to enable the addons)

## Format

```yaml
menu-settings:
  menu-type: addon

  # The name of the menu
  name: '&c&lAddon Downloader'

  # The rows of the menu
  rows: 3

  # The command to open the menu
  command:
    - addondownloader
    - addondl

  # The period in ticks to refresh the menu
  auto-refresh: 5

# The button for each addon
button:
  material:
    - LIGHT_BLUE_STAINED_GLASS_PANE
    - STAINED_GLASS_PANE:3
  name: "&f{name} &c- &4{status}"
  lore:
    - "&f{description}"
    - "&fAuthors: &e{author}"
    - "&fVersion: &e{version}"
    - ""
    - "&bLeft click &fto download"
    - "&bRight click &fto get the source code"
    - "&bMiddle click &fto see the wiki"
```
---




---


## Predicate Menu

This is an arbitrary menu that serves as a switch that you can add some [Menus]({{% ref "menu/overview" %}}) and some [Requirements]({{% ref "requirement/overview" %}}) for each [Menu]({{% ref "menu/overview" %}}) to check before opening one of them.

## Format

```yaml
menu-settings:
  menu-type: predicate

  permission: bettergui.test

  command:
  - command1
  - command2
  ...

  argument-processor:
  - <argument-processor>
  - <argument-processor>

menu-name1:
  menu: <menu-file>
  argument: <args>
  requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

menu-name2:
  menu: <menu-file>
  argument: <args>
  requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

```

## Note

* `menu-settings`
  * `permission`: the required permission to open the menu.
  * `command`: the commands to open the menu.
  * `argument-processor`: the [Argument Processor]({{% ref "argument" %}}) to handle the arguments of the command to open the menu.

* `menu-name1`, `menu-name2`, etc.
  * `menu`: the file of the menu to open,
  * `argument`: the argument to pass when opening the menu. It's optional
  * `requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before opening the menu. If it's not set, the plugin will assume that the menu can always be opened.

* The plugin will check the requirement of each menus in the top-down order of the config. If it found a menu whose requirements are met, it would open that menu. Otherwise, nothing happened.

## Example

```yaml
# level-predicate.yml
menu-settings:
  menu-type: predicate
  command: level

level-5:
  menu: level-5.yml
  requirement:
    check-level:
      level:
        value: 5
        take: false

level-2:
  menu: level-2.yml
  requirement:
    check-level:
      level:
        value: 2
        take: false

level-0:
  menu: level-0.yml

# level-5.yml
menu-settings:
  title: "&aYou reached level 5!"

# level-2.yml
menu-settings:
  title: "&aYou reached level 2!"

# level-0.yml
menu-settings:
  title: "&cYou don't have enough levels!"
```
---




---



# Button

The visible unit of a [Menu]({{% ref "../menu" %}}) that provides a display button the user can interact & do actions when clicked.
---



## Overview

* A button is what is shown in the menu.
* When the player clicks a button, some actions are executed.
* A button can also be updated.
* There are many built-in types of button (Check the sidebar). A developer can make his own button and register to the plugin.
* You can specify the type of button by setting the `type` option.

## Example
```yaml
simple-button: #
  slot: 1
  id: cobblestone
  name: "&bThis is a simple button"
  lore:
  - ""
  - "&fThis is a lore"
  action: "tell: &eYou clicked"
  close-on-click: true

animated-icon:
  slot: 2
  type: animated
  update: 5
  child:
    frame_icon1:
      name: "&cFrame 1"
      id: red_wool
      lore:
        - "This is part of an animated icon"
    frame_icon2:
      name: "&aFrame 2"
      id: green_wool
      lore:
        - "This is part of an animated icon"
    frame_icon3:
      name: "&bFrame 3"
      id: light_blue_wool
      lore:
        - "This is part of an animated icon"
```

---


## Slot

{{% notice style="tip" %}}
If you want to use [variables]({{% ref "misc/variable" %}}) in the slot or [add Math to the slot]({{% ref "addon/eval-extra" %}}), check out [MaskedGUI]({{% ref "addon/masked-gui" %}}) and its [Dynamic Slot]({{% ref "addon/masked-gui/dynamic-slot" %}})
{{% /notice %}}

Before talking about [Button]({{% ref "../overview" %}}), let's talk about Slot first.

Slot is a coordinate which is used to determine where the item will be placed in the menu. In **BetterGUI**, there are 2 ways to specify a slot:
- `position-x` and `position-y`
- `slot`

## `position-x` and `position-y`

If you are comfortable with the grid layout, you can set the slot by specifying the X and Y coordinates.

Here are all coordinates in a 9x6 grid:

[![Coordinate Table](coordinates-table.png)](https://filoghost.me/docs/chest-commands/attributes)

Example:

```yaml
position-x: 1
position-y: 1
```

## `slot`

This is the easiest way to specify a slot. You can use the slot number directly.

Here are all slots in a 9x6 grid:

[![Slot Table](slots-table.png)](https://www.spigotmc.org/threads/where-are-located-gui-slots.301647/)

Example:

```yaml
slot: 0
```

## Multiple Slots

You can also specify multiple slots for an item. This is useful if you want to create a button that takes up more than one slot.

```yaml
slot: 0, 1, 2, 3, 4, 5, 6, 7, 8
```

If you want to specify a range of slots, you can use the range format (`<first>-<last>`).

```yaml
slot: 0-8
```

If you want to go crazy and specify both a range and a list of slots, you can do that too.

```yaml
slot: 0-8, 9, 17, 18-26
```

---


## Empty Button

This is the simplest and useless button. This represents nothing.

## Format

```yaml
button-name:
  type: empty
```

---


## Dummy Button

This is a decorative button. You can only set the display item of the button through [Item Modifiers]({{% ref "modifier/overview" %}}).

## Format

```yaml
button-name:
  type: dummy
  modifier1: <value1>
  modifier2: <value2>
  modifier3: <value3>
  ...
```

## Example

```yaml
dummy-button:
  type: dummy
  id: STONE
  name: "&eThis is a dummy button"
```

---


## Air Button

This button represents the Air item, which the player can't see.

## Format

```yaml
button-name:
  type: air
  # command:
  action:
  - <action>
  - <action>
  - <action>
  ...
  close-on-click: <true/false>
```

## Note

* `action` (`command`): the [Action]({{% ref "action/overview" %}}) to be executed on clicked.
  * You can use [Click Type]({{% ref "misc/click" %}}) to set different [Actions]({{% ref "action/overview" %}}) for each type of click
* `close-on-click`: whether to close the menu on clicked.

## Example

```yaml
air-button:
  type: air
  command:
  - "tell: &aOh..."
  - "delay: 30"
  - "tell: &aUhhhh... Hello"
  close-on-click: true
```

---


## Null Button

This is similar to [Air Button]({{% ref "../air" %}}), but this button represents nothing.

## Format

```yaml
button-name:
  type: null
  # command:
  action:
  - <action>
  - <action>
  - <action>
  ...
  close-on-click: <true/false>
```

## Note

* The difference is that, while [Air Button]({{% ref "../air" %}}) overrides the display item and the actions of a slot, this button only overrides the actions of a slot.

## Example

```yaml
null-button:
  type: null
  command:
  - "tell: &aOh..."
  - "delay: 30"
  - "tell: &aUhhhh... Hello"
  close-on-click: true
```

---


## Simple Button

This is a combination of [Dummy Button]({{% ref "../dummy" %}}) and [Air Button]({{% ref "../air" %}}), so you can set both [Item Modifiers]({{% ref "modifier/overview" %}}) and [`action` (`command`) & `close-on-click`]({{% ref "../air" %}}#note).

## Format

```yaml
button-name:
  type: simple # You don't need to set this value. It's the default value
  modifier1: <value1>
  modifier2: <value2>
  modifier3: <value3>
  ...
  # command:
  action:
  - <action>
  - <action>
  - <action>
  ...
  close-on-click: <true/false>
```

## Example

```yaml
simple-button:
  id: cobblestone
  name: "&bThis is a simple button"
  lore:
  - ""
  - "&fThis is a lore"
  action: "tell: &eYou clicked"
  close-on-click: true
```

---


## Animated Button

This is a dynamic button which displays the frame buttons one-by-one.

## Format

```yaml
button-name:
  type: animated
  update: <ticks>
  shift: <number>
  reverse: <true/false>
  child:
    button1:
      <button-settings>
    button2:
      <button-settings>
    button3:
      <button-settings>
    ...
```

## Note

* `child`: the list of [Button]({{% ref "../overview" %}}) that serves as the frames of the animattion.
* `update`: the ticks between two frames.
* `shift`: the index of the starting frame.
  * If you set a positive value (`n`), the `n`-th frame will be the start frame.
  * If you set a negative value (`-n`), the `n`-th frame from the bottom will be the start frame.
* `reverse`: whether to flip the frames, so that the frames will go bottom-up.

## Example

```yaml
animated-icon:
  type: animated
  update: 5
  child:
    frame_icon1:
      name: "&cFrame 1"
      id: red_wool
      lore:
        - "This is part of an animated icon"
    frame_icon2:
      name: "&aFrame 2"
      id: green_wool
      lore:
        - "This is part of an animated icon"
    frame_icon3:
      name: "&bFrame 3"
      id: light_blue_wool
      lore:
        - "This is part of an animated icon"
```

---


## Predicate Button

This is a conditional button which displays the button if the requirements are met, or the fallback button otherwise.

## Format

```yaml
button-name:
  type: predicate
  button:
    <button-settings>
  fallback:
    <button-settings>
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...
  check-only-on-creation: <true/false>
  click-requirement:
    left:
      <requirement-set>
      <requirement-set>
      <requirement-set>
      ...
    right:
      <requirement-set>
      <requirement-set>
      <requirement-set>
      ...
    middle:
      <requirement-set>
      <requirement-set>
      <requirement-set>
      ...
    ...
    default:
      <requirement-set>
      <requirement-set>
      <requirement-set>
      ...
```

## Note

* `view-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before displaying the [Button]({{% ref "../overview" %}}).
* `button`: the [Button]({{% ref "../overview" %}}) to show if the `view-requirement` are met.
* `fallback`: the fallback [Button]({{% ref "../overview" %}}) to show if the `view-requirement` are not met.
* `click-requirement`: the pairs of [Click Type]({{% ref "misc/click" %}}) & [Requirement]({{% ref "requirement/overview" %}}) to check when the button is clicked.
* `check-only-on-creation`: whether to only check `view-requirement` when the menu is opened.

## Example

```yaml
permission:
  SLOT: 1
  type: predicate
  CLICK-REQUIREMENT:
    default:
      permission:
        PERMISSION: bettergui.test
        fail-command: 'tell: &cYou don''t have the correct permission!'
  button:
    COMMAND: 'tell: &a[v] You have the correct permission!'
    NAME: '&8Permission test'
    LORE:
      - 'To use this item, you need the'
      - 'permission "bettergui.test".'
      - 'Otherwise, a configurable error'
      - 'message will be displayed.'
    ID: iron bars
```

```yaml
level-view-requirement:
  type: predicate
  slot: 2
  button:
    id: exp_bottle
    name: "&cA exp bottle"
    lore:
      - "You will see this icon when the level is higher than 5"
  fallback:
    id: stone
    name: "&cA stone"
    lore:
      - "You will see this icon when the level is lower than 5"
  view-requirement:
    level:
      level: 5
```

---


## List Button

This is a conditional button which loops through the child buttons and check if a button can be displayed.

## Format

```yaml
button-name:
  type: list
  keep-current-index: <true/false>
  child:
    button1:
      <button-settings>
    button2:
      <button-settings>
    button3:
      <button-settings>
    ...
```

## Note

* `child`: the list of [Button]({{% ref "../overview" %}}). This button will loop through and display a button if it can be shown.
* `keep-current-index`: whether to only check when the player opens the menu.

## Example

```yaml
list-icon:
  type: list
  keep-current-index: false
  child:
    level_5:
      type: predicate
      button:
        id: grass
        name: "&aYou are in Level 5"
      view-requirement:
        level:
          level: 5
    level_3:
      type: predicate
      button:
        id: netherrack
        name: "&cYou are in Level 3"
      view-requirement:
        level:
          level: 3
    low_level:
      id: bedrock
      name: "&cYou are low level"
```

---


## Template Button

This is an arbitrary button that can be used as a template for various copies of the buttons with slightly different settings and/or values.

## Format

```yaml
button-name:
  type: template
  template: <name> # The name from template folder
  variable:
    <variable1>: <value1>
    <variable2>: <value2>
    ...
  <button-settings>
```

## Note

* `template`: the name of the button in the template folder
  * The template folder (located at `plugins/BetterGUI/template`) is basically a folder containing `yml` files defining common buttons to use in all menus
  * You can get the registered template buttons by using the command [`gettemplatebuttons`]({{% ref "basic/command" %}})
* `variable`: the variables to apply to the template button. This will help you to create many buttons with different attributes from one single template button.

## Example

### Using Template Button

* **Normal Case**
```yaml
# Not using template
button1:
  id: stone
  name: "&cThis is button"
  lore:
  - "This is a line"
  - "This is a 2 line"
  - "This is a 3 line"
  - "This is a 4 line"
  command: "tell: &cYou clicked"

button2:
  id: stone
  name: "&cThis is button"
  lore:
  - "This is a line"
  - "This is a 2 line"
  - "This is a 3 line"
  - "This is a 4 line"
  command: "tell: &cYou clicked this again"
```

* **Using Template Button**
```yaml
# Using template
button1:
  type: template
  template: test # The name from template folder
  command: "tell: &cYou clicked"
button2:
  type: template
  template: test # The name from template folder
  command: "tell: &cYou clicked this again"

# Template File
test:
  id: stone
  name: "&cThis is button"
  lore:
  - "This is a line"
  - "This is a 2 line"
  - "This is a 3 line"
  - "This is a 4 line"
```

### Use `variable` option
```yaml
# This will create 4 buttons with different XP amount. These buttons give XP to the player
test-xp-100:
  type: template
  template: test-xp
  variable:
    xp: 100

test-xp-200:
  type: template
  slot: 12
  template: test-xp
  variable:
    xp: 200

test-xp-300:
  type: template
  template: test-xp
  variable:
    xp: 300

test-xp-400:
  type: template
  template: test-xp
  variable:
    xp: 400

# Template File
test-xp:
  id: paper
  name: "&eGive &f{xp} XP"
  lore:
  - ""
  - "&fThis is a test template button"
  command: "console: xp {xp} {player}"

# Notice that the template button has {xp} in it. It will be replaced with the value from the variables of the button using this template button
```

---




## Slot

{{% notice style="tip" %}}
If you want to use [variables]({{% ref "misc/variable" %}}) in the slot or [add Math to the slot]({{% ref "addon/eval-extra" %}}), check out [MaskedGUI]({{% ref "addon/masked-gui" %}}) and its [Dynamic Slot]({{% ref "addon/masked-gui/dynamic-slot" %}})
{{% /notice %}}

Before talking about [Button]({{% ref "../overview" %}}), let's talk about Slot first.

Slot is a coordinate which is used to determine where the item will be placed in the menu. In **BetterGUI**, there are 2 ways to specify a slot:
- `position-x` and `position-y`
- `slot`

## `position-x` and `position-y`

If you are comfortable with the grid layout, you can set the slot by specifying the X and Y coordinates.

Here are all coordinates in a 9x6 grid:

[![Coordinate Table](coordinates-table.png)](https://filoghost.me/docs/chest-commands/attributes)

Example:

```yaml
position-x: 1
position-y: 1
```

## `slot`

This is the easiest way to specify a slot. You can use the slot number directly.

Here are all slots in a 9x6 grid:

[![Slot Table](slots-table.png)](https://www.spigotmc.org/threads/where-are-located-gui-slots.301647/)

Example:

```yaml
slot: 0
```

## Multiple Slots

You can also specify multiple slots for an item. This is useful if you want to create a button that takes up more than one slot.

```yaml
slot: 0, 1, 2, 3, 4, 5, 6, 7, 8
```

If you want to specify a range of slots, you can use the range format (`<first>-<last>`).

```yaml
slot: 0-8
```

If you want to go crazy and specify both a range and a list of slots, you can do that too.

```yaml
slot: 0-8, 9, 17, 18-26
```
---




---


## Empty Button

This is the simplest and useless button. This represents nothing.

## Format

```yaml
button-name:
  type: empty
```
---




---


## Dummy Button

This is a decorative button. You can only set the display item of the button through [Item Modifiers]({{% ref "modifier/overview" %}}).

## Format

```yaml
button-name:
  type: dummy
  modifier1: <value1>
  modifier2: <value2>
  modifier3: <value3>
  ...
```

## Example

```yaml
dummy-button:
  type: dummy
  id: STONE
  name: "&eThis is a dummy button"
```
---




---


## Air Button

This button represents the Air item, which the player can't see.

## Format

```yaml
button-name:
  type: air
  # command:
  action:
  - <action>
  - <action>
  - <action>
  ...
  close-on-click: <true/false>
```

## Note

* `action` (`command`): the [Action]({{% ref "action/overview" %}}) to be executed on clicked.
  * You can use [Click Type]({{% ref "misc/click" %}}) to set different [Actions]({{% ref "action/overview" %}}) for each type of click
* `close-on-click`: whether to close the menu on clicked.

## Example

```yaml
air-button:
  type: air
  command:
  - "tell: &aOh..."
  - "delay: 30"
  - "tell: &aUhhhh... Hello"
  close-on-click: true
```
---




---


## Null Button

This is similar to [Air Button]({{% ref "../air" %}}), but this button represents nothing.

## Format

```yaml
button-name:
  type: null
  # command:
  action:
  - <action>
  - <action>
  - <action>
  ...
  close-on-click: <true/false>
```

## Note

* The difference is that, while [Air Button]({{% ref "../air" %}}) overrides the display item and the actions of a slot, this button only overrides the actions of a slot.

## Example

```yaml
null-button:
  type: null
  command:
  - "tell: &aOh..."
  - "delay: 30"
  - "tell: &aUhhhh... Hello"
  close-on-click: true
```
---




---


## Simple Button

This is a combination of [Dummy Button]({{% ref "../dummy" %}}) and [Air Button]({{% ref "../air" %}}), so you can set both [Item Modifiers]({{% ref "modifier/overview" %}}) and [`action` (`command`) & `close-on-click`]({{% ref "../air" %}}#note).

## Format

```yaml
button-name:
  type: simple # You don't need to set this value. It's the default value
  modifier1: <value1>
  modifier2: <value2>
  modifier3: <value3>
  ...
  # command:
  action:
  - <action>
  - <action>
  - <action>
  ...
  close-on-click: <true/false>
```

## Example

```yaml
simple-button:
  id: cobblestone
  name: "&bThis is a simple button"
  lore:
  - ""
  - "&fThis is a lore"
  action: "tell: &eYou clicked"
  close-on-click: true
```
---




---


## Animated Button

This is a dynamic button which displays the frame buttons one-by-one.

## Format

```yaml
button-name:
  type: animated
  update: <ticks>
  shift: <number>
  reverse: <true/false>
  child:
    button1:
      <button-settings>
    button2:
      <button-settings>
    button3:
      <button-settings>
    ...
```

## Note

* `child`: the list of [Button]({{% ref "../overview" %}}) that serves as the frames of the animattion.
* `update`: the ticks between two frames.
* `shift`: the index of the starting frame.
  * If you set a positive value (`n`), the `n`-th frame will be the start frame.
  * If you set a negative value (`-n`), the `n`-th frame from the bottom will be the start frame.
* `reverse`: whether to flip the frames, so that the frames will go bottom-up.

## Example

```yaml
animated-icon:
  type: animated
  update: 5
  child:
    frame_icon1:
      name: "&cFrame 1"
      id: red_wool
      lore:
        - "This is part of an animated icon"
    frame_icon2:
      name: "&aFrame 2"
      id: green_wool
      lore:
        - "This is part of an animated icon"
    frame_icon3:
      name: "&bFrame 3"
      id: light_blue_wool
      lore:
        - "This is part of an animated icon"
```
---




---


## Predicate Button

This is a conditional button which displays the button if the requirements are met, or the fallback button otherwise.

## Format

```yaml
button-name:
  type: predicate
  button:
    <button-settings>
  fallback:
    <button-settings>
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...
  check-only-on-creation: <true/false>
  click-requirement:
    left:
      <requirement-set>
      <requirement-set>
      <requirement-set>
      ...
    right:
      <requirement-set>
      <requirement-set>
      <requirement-set>
      ...
    middle:
      <requirement-set>
      <requirement-set>
      <requirement-set>
      ...
    ...
    default:
      <requirement-set>
      <requirement-set>
      <requirement-set>
      ...
```

## Note

* `view-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before displaying the [Button]({{% ref "../overview" %}}).
* `button`: the [Button]({{% ref "../overview" %}}) to show if the `view-requirement` are met.
* `fallback`: the fallback [Button]({{% ref "../overview" %}}) to show if the `view-requirement` are not met.
* `click-requirement`: the pairs of [Click Type]({{% ref "misc/click" %}}) & [Requirement]({{% ref "requirement/overview" %}}) to check when the button is clicked.
* `check-only-on-creation`: whether to only check `view-requirement` when the menu is opened.

## Example

```yaml
permission:
  SLOT: 1
  type: predicate
  CLICK-REQUIREMENT:
    default:
      permission:
        PERMISSION: bettergui.test
        fail-command: 'tell: &cYou don''t have the correct permission!'
  button:
    COMMAND: 'tell: &a[v] You have the correct permission!'
    NAME: '&8Permission test'
    LORE:
      - 'To use this item, you need the'
      - 'permission "bettergui.test".'
      - 'Otherwise, a configurable error'
      - 'message will be displayed.'
    ID: iron bars
```

```yaml
level-view-requirement:
  type: predicate
  slot: 2
  button:
    id: exp_bottle
    name: "&cA exp bottle"
    lore:
      - "You will see this icon when the level is higher than 5"
  fallback:
    id: stone
    name: "&cA stone"
    lore:
      - "You will see this icon when the level is lower than 5"
  view-requirement:
    level:
      level: 5
```
---




---


## List Button

This is a conditional button which loops through the child buttons and check if a button can be displayed.

## Format

```yaml
button-name:
  type: list
  keep-current-index: <true/false>
  child:
    button1:
      <button-settings>
    button2:
      <button-settings>
    button3:
      <button-settings>
    ...
```

## Note

* `child`: the list of [Button]({{% ref "../overview" %}}). This button will loop through and display a button if it can be shown.
* `keep-current-index`: whether to only check when the player opens the menu.

## Example

```yaml
list-icon:
  type: list
  keep-current-index: false
  child:
    level_5:
      type: predicate
      button:
        id: grass
        name: "&aYou are in Level 5"
      view-requirement:
        level:
          level: 5
    level_3:
      type: predicate
      button:
        id: netherrack
        name: "&cYou are in Level 3"
      view-requirement:
        level:
          level: 3
    low_level:
      id: bedrock
      name: "&cYou are low level"
```
---




---


## Template Button

This is an arbitrary button that can be used as a template for various copies of the buttons with slightly different settings and/or values.

## Format

```yaml
button-name:
  type: template
  template: <name> # The name from template folder
  variable:
    <variable1>: <value1>
    <variable2>: <value2>
    ...
  <button-settings>
```

## Note

* `template`: the name of the button in the template folder
  * The template folder (located at `plugins/BetterGUI/template`) is basically a folder containing `yml` files defining common buttons to use in all menus
  * You can get the registered template buttons by using the command [`gettemplatebuttons`]({{% ref "basic/command" %}})
* `variable`: the variables to apply to the template button. This will help you to create many buttons with different attributes from one single template button.

## Example

### Using Template Button

* **Normal Case**
```yaml
# Not using template
button1:
  id: stone
  name: "&cThis is button"
  lore:
  - "This is a line"
  - "This is a 2 line"
  - "This is a 3 line"
  - "This is a 4 line"
  command: "tell: &cYou clicked"

button2:
  id: stone
  name: "&cThis is button"
  lore:
  - "This is a line"
  - "This is a 2 line"
  - "This is a 3 line"
  - "This is a 4 line"
  command: "tell: &cYou clicked this again"
```

* **Using Template Button**
```yaml
# Using template
button1:
  type: template
  template: test # The name from template folder
  command: "tell: &cYou clicked"
button2:
  type: template
  template: test # The name from template folder
  command: "tell: &cYou clicked this again"

# Template File
test:
  id: stone
  name: "&cThis is button"
  lore:
  - "This is a line"
  - "This is a 2 line"
  - "This is a 3 line"
  - "This is a 4 line"
```

### Use `variable` option
```yaml
# This will create 4 buttons with different XP amount. These buttons give XP to the player
test-xp-100:
  type: template
  template: test-xp
  variable:
    xp: 100

test-xp-200:
  type: template
  slot: 12
  template: test-xp
  variable:
    xp: 200

test-xp-300:
  type: template
  template: test-xp
  variable:
    xp: 300

test-xp-400:
  type: template
  template: test-xp
  variable:
    xp: 400

# Template File
test-xp:
  id: paper
  name: "&eGive &f{xp} XP"
  lore:
  - ""
  - "&fThis is a test template button"
  command: "console: xp {xp} {player}"

# Notice that the template button has {xp} in it. It will be replaced with the value from the variables of the button using this template button
```
---




---



# Action

The operation to be executed
---



## Overview

* Actions are used when you want to execute something on certain events (broadcast everyone when the player clicked the button, etc).
* There are many built-in types of actions (Check the sidebar). A developer can also create his own action and register to this plugin.

## Example
```yaml
hello:
  COMMAND: # Here are the actions
  - "tell: &eHello There"
  - "delay: 60"
  - "tell: &eHello Again"
  NAME: '&u&lHello Button'
  ID: stone
  POSITION-X: 1
  POSITION-Y: 1
```

---


## Player Executor

This action will execute the command as a player

## Format

* `<command>`
* `player: <command>`

## Note

* This is the default type of all actions, so you can specific the action without the prefix `player:`

## Example

* `spawn`
* `player: warp pvp`
* `player: me Hello World!`

---


## Console Executor

This action will execute the command as the console (terminal)

## Format

* `console: <command>`

## Example

* `console: say Hello {player}!`

---


## OP Executor

This action will execute the command as an operator (`/op`)

{{% notice warning %}}
This action will give the player OP `/op`, execute the `<command>` and then de-op the player. Since it uses `/op`, this action is considered "dangerous". A hacker can use a Crasher to exploit the action.
It's recommended to use [Permission Executor]({{% ref "../permission" %}}) instead.
{{% /notice %}}

## Format

* `op: <command>`

## Example

* `op: stop`

---


## Permission Executor

This action will give the permissions to the player, execute the command and then retrieve the permissions

## Format

* `permission(<permission>): <command>`
* `permission(<permission_1>, <permission_2>, <permission_3>): <command>`

## Example

* `permission(essentials.fly): fly`
* `permission(essentials.gamemode, essentials.gamemode.creative): gamemode 1`

---


## Open Menu

This action will open the specific menu.

## Format

* `open-menu: <menu_name>`
* `open: <menu_name>`
* `menu: <menu_name>`

## Example

* `open-menu: example.yml`
* `open: pvp.yml`
* `menu: test.yml`

{{% notice style="note" %}}
You can bypass open requirements of the menu by adding `bypassChecks` to the action.
For example: `open(bypassChecks): pvp.yml`
{{% /notice %}}

---


## Update Menu

This action will execute the update task of the current menu.

## Format

* `update-menu`
* `updatemenu`

---


## Back Menu

This action will send the player to his previous menu, or close the current menu if there is no previous menu.

## Format

* `back-menu`
* `backmenu`

{{% notice style="note" %}}
You can bypass open requirements of the menu by adding `bypassChecks` to the action.
For example: `backmenu(bypassChecks)`
{{% /notice %}}

---


## Close Menu

This action will close the current menu.

## Format

* `close-menu`
* `closemenu`

---


## Broadcast Message

This action will send the message to every online players

## Format

* `broadcast: <message>`

## Example

* `broadcast: Hello`

---


## Tell Message

This action will send the message to the player.

## Format

* `tell: <message>`

## Example

* `tell: You there?`

---


## Play Sound

This action will send the sound to the player.

## Format

* `sound: <sound>, [volume], [pitch]`
* `sound: <sound> [volume] [pitch]`
* `raw-sound: <sound>, [volume], [pitch]`
* `raw-sound: <sound> [volume] [pitch]`

## Note

* `<sound>` supports Minecraft's sound name, so it also supports custom sounds from Resource Pack. If the `<sound>` can not be found, the action is simply ignored.
* You can specify the `[volume]` and the `[pitch]` of the `<sound>`. Those are optional.

## Example

* `sound: BLOCK_NOTE_BLOCK_PLING`
* `sound: BLOCK_NOTE_BLOCK_PLING 1 2`

---


## Delay

This action will delay the action flow in the specific ticks (20 ticks = 1 second)

## Format

* `delay: <ticks>`

## Example

* `delay: 20`
* `delay: 100`

---




## Player Executor

This action will execute the command as a player

## Format

* `<command>`
* `player: <command>`

## Note

* This is the default type of all actions, so you can specific the action without the prefix `player:`

## Example

* `spawn`
* `player: warp pvp`
* `player: me Hello World!`
---




---


## Console Executor

This action will execute the command as the console (terminal)

## Format

* `console: <command>`

## Example

* `console: say Hello {player}!`
---




---


## OP Executor

This action will execute the command as an operator (`/op`)

{{% notice warning %}}
This action will give the player OP `/op`, execute the `<command>` and then de-op the player. Since it uses `/op`, this action is considered "dangerous". A hacker can use a Crasher to exploit the action.
It's recommended to use [Permission Executor]({{% ref "../permission" %}}) instead.
{{% /notice %}}

## Format

* `op: <command>`

## Example

* `op: stop`
---




---


## Permission Executor

This action will give the permissions to the player, execute the command and then retrieve the permissions

## Format

* `permission(<permission>): <command>`
* `permission(<permission_1>, <permission_2>, <permission_3>): <command>`

## Example

* `permission(essentials.fly): fly`
* `permission(essentials.gamemode, essentials.gamemode.creative): gamemode 1`
---




---


## Open Menu

This action will open the specific menu.

## Format

* `open-menu: <menu_name>`
* `open: <menu_name>`
* `menu: <menu_name>`

## Example

* `open-menu: example.yml`
* `open: pvp.yml`
* `menu: test.yml`

{{% notice style="note" %}}
You can bypass open requirements of the menu by adding `bypassChecks` to the action.
For example: `open(bypassChecks): pvp.yml`
{{% /notice %}}
---




---


## Update Menu

This action will execute the update task of the current menu.

## Format

* `update-menu`
* `updatemenu`
---




---


## Back Menu

This action will send the player to his previous menu, or close the current menu if there is no previous menu.

## Format

* `back-menu`
* `backmenu`

{{% notice style="note" %}}
You can bypass open requirements of the menu by adding `bypassChecks` to the action.
For example: `backmenu(bypassChecks)`
{{% /notice %}}
---




---


## Close Menu

This action will close the current menu.

## Format

* `close-menu`
* `closemenu`
---




---


## Broadcast Message

This action will send the message to every online players

## Format

* `broadcast: <message>`

## Example

* `broadcast: Hello`
---




---


## Tell Message

This action will send the message to the player.

## Format

* `tell: <message>`

## Example

* `tell: You there?`
---




---


## Play Sound

This action will send the sound to the player.

## Format

* `sound: <sound>, [volume], [pitch]`
* `sound: <sound> [volume] [pitch]`
* `raw-sound: <sound>, [volume], [pitch]`
* `raw-sound: <sound> [volume] [pitch]`

## Note

* `<sound>` supports Minecraft's sound name, so it also supports custom sounds from Resource Pack. If the `<sound>` can not be found, the action is simply ignored.
* You can specify the `[volume]` and the `[pitch]` of the `<sound>`. Those are optional.

## Example

* `sound: BLOCK_NOTE_BLOCK_PLING`
* `sound: BLOCK_NOTE_BLOCK_PLING 1 2`
---




---


## Delay

This action will delay the action flow in the specific ticks (20 ticks = 1 second)

## Format

* `delay: <ticks>`

## Example

* `delay: 20`
* `delay: 100`
---




---



# Requirement

The criteria to check before doing actions.
---



## Overview

* Requirement is one of the interesting parts of the plugin.
* It is used when you want to check if the player meets some sort of requirements before doing anything (Check the level before opening the menu, etc).
* There are many built-in types of requirements (Check the sidebar). A developer can also make his own requirement type and register it to the plugin.

{{% notice info %}}
What you see in the examples & set in your [Menu]({{% ref "menu/overview" %}}) is actually [**Requirement Set**]({{% ref "set" %}}).

Make sure to check [**Requirement Set**]({{% ref "set" %}}) to understand how to correctly set requirements in your [Menu]({{% ref "menu/overview" %}}) (Particularly, how to set multiple requirements & set [Actions]({{% ref "action/overview" %}}) when the requirements are met / failed to met).
{{% /notice %}}

## Example

```yaml
permission-list:
  slot: 1
  type: predicate
  CLICK-REQUIREMENT: # Click Requirement
    default: # Click type
      we-permission: # The name of the Requirement set
        PERMISSION: # Here we are
        - bettergui.test
        - bettergui.test.1
        fail-command: "tell: &cYou don''t have the correct permission!"
  button:
    COMMAND: "tell: &a[v] You have the correct permission!"
    NAME: '&8Permission test'
    LORE:
      - 'To use this item, you need the'
      - 'required permissions.'
      - 'Otherwise, a configurable error'
      - 'message will be displayed.'
    ID: iron bars
```

---


## Requirement Set

* A requirement set is a set of requirements that the player are required to pass before doing actions.
* It consists of:
  * The [Requirements]({{% ref "../overview" %}}).
  * `success-action` (`success-command`): the [Action]({{% ref "action/overview" %}}) when the player passes all requirements.
  * `fail-action` (`fail-command`): the [Action]({{% ref "action/overview" %}}) when the player doesn't pass any of the requirements.
* You can set multiple sets of requirements.
  * The plugin will check for one set that the player meet its requirements. If none of the sets is matched, these are simply passed as failed and the actions will not be executed.

## Format

```yaml
requirement-set-name: # The name of the Requirement Set
  requirement-1: value-1 # The first requirement
  requirement-2: value-2 # The second requirement
  requirement-3: value-3 # The third requirement
  <requirement..>: <value..> # More requirements

  success-action: # The actions when the requirements are met
  - action1
  - action2
  - action3

  fail-action: # The actions when the requirements are not met
  - action1
  - action2
  - action3
```

## Example

```yaml
check-condition:
  slot: 1
  type: predicate
  CLICK-REQUIREMENT: # Click Requirement
    default: # Click type
      we-permission: # The name of the Requirement Set
        permission: # The permission requirement
        - bettergui.test
        - bettergui.test.1
        level: 10 # The level requirement
        fail-command: "tell: &cYou don''t meet the requirements!"
        success-command: "tell: &a[v] You passed the requirements!"
  button:
    NAME: '&8Requirement Test'
    LORE:
      - 'To use this item, you need to pass all requirements.'
      - 'Otherwise, a configurable error'
      - 'message will be displayed.'
    ID: iron bars
```

---


## Cooldown Requirement

The requirement to check if the player is not in a cooldown timer (seconds). After checking successfully, the cooldown timer will start for the player.

## Format

```yaml
cooldown: <seconds>
```

## Example

```yaml
cooldown:
  slot: 1
  type: predicate
  button:
    COMMAND: "tell: &e You will need to wait 10 seconds to click again"
    NAME: '&aCooldown'
    LORE:
      - 'This is a example of icon with cooldown'
    ID: paper
  click-requirement: # Click Requirement
    default: # Click type
      test-cooldown: # Requirement Set name
        cooldown: 10 # Here we are
      fail-command:
        - "tell: &cWait until the cooldown is finished"
```

---


## Level Requirement

The requirement to check if the level of the player is higher or equal to the specific level

## Format

```yaml
level: <level>
```
```yaml
level:
  value: <level>
  take: <true/false>
```

## Note

* You can specify the `take` value (`true` or `false`) to allow/disallow the plugin to take the level of the player alter checking successfully

## Example

```yaml
test-view-requirement:
  type: predicate
  slot: 1
  button:
    id: exp_bottle
    name: "&cA exp bottle"
    lore:
      - "You will see this icon when the level is higher than 5"
  view-requirement: # View Requirement
    level: # Requirement Set name
      level: 5 # Here we are
```
```yaml
test-click-requirement:
  type: predicate
  slot: 1
  button:
    id: exp_bottle
    name: "&cA level checker"
    command: "tell: &aYou reached level 5"
  click-requirement: # Click Requirement
    default: # Click type
      test-level: # Requirement Set name
        level: # Here we are
          value: 5
          take: true # Take the level
      fail-command:
        - "tell: &cTrain more"
```

---


## Permission Requirement

The requirement to check if the player has the specific permission

## Format

```yaml
permission: <permission>
```
```yaml
permission:
- <permission>
- <permission>
- <permission>
...
```

## Note

* You can add `-` before `<permission>` to indicate that the plugin should check if the player doesn't have the `<permission>`

## Example

```yaml
permission:
  slot: 1
  type: predicate
  CLICK-REQUIREMENT: # Click Requirement
    default: # Click type
      permission: # Requirement set name
        PERMISSION: bettergui.test # Here we are
        fail-command: "tell: &cYou don''t have the correct permission!"
  button:
    COMMAND: "tell: &a[v] You have the correct permission!"
    NAME: '&8Permission test'
    LORE:
      - 'To use this item, you need the'
      - 'permission "bettergui.test".'
      - 'Otherwise, a configurable error'
      - 'message will be displayed.'
    ID: iron bars
```
```yaml
permission-list:
  slot: 2
  type: predicate
  CLICK-REQUIREMENT: # Click Requirement
    default: # Click type
      permission: # Requirement set name
        PERMISSION: # Here we are
        - bettergui.test
        - bettergui.test.1
        fail-command: "tell: &cYou don''t have the correct permission!"
  button:
    COMMAND: "tell: &a[v] You have the correct permission!"
    NAME: '&8Permission test'
    LORE:
      - 'To use this item, you need the'
      - 'required permissions.'
      - 'Otherwise, a configurable error'
      - 'message will be displayed.'
    ID: iron bars
```

---


## Condition Requirement

The requirement to check on conditions & expressions (Mainly [Math extension](https://github.com/PlaceholderAPI/PlaceholderAPI/wiki/Placeholders#math))

{{% notice tip %}}
If you want more advanced expressions, check out [Eval Extra]({{% ref "addon/eval-extra" %}})
{{% /notice %}}

## Format

```yaml
condition: <condition>
```

## Note

* This requirement will check if `<condition>` is `true`, `yes`, `on` or `0`

## Example

```yaml
test-view-requirement:
  type: predicate
  slot: 1
  button:
    id: exp_bottle
    name: "&cA exp bottle"
    lore:
      - "You will see this icon when the level is 0"
  view-requirement: # View Requirement
    level: # Requirement Set name
      condition: "%math_{level} >= 0%" # Here we are
```

---


## Version Requirement

The requirement to check if the server is at a specific version or higher.

## Format

```yaml
version: <value>
```

## Note

* The `<value>` is the major part of the version of Minecraft.
  * `1.12.2` will be `12`
  * `1.18.2` will be `18`
  * `1.8.8` will be `8`

## Example

```yaml
test-xp:
  slot: 0
  id:
    - EXPERIENCE_BOTTLE
    - EXP_BOTTLE
  name: "&eGive &f10 XP"
  lore:
    - ""
    - "&fThis is a test template button"
    - "&fLevel: {level}"
  click-requirement:
    old-version:
      version: 13 # Check if the server is at 1.13.X
      success-action: "console: xp add {player} 10 points"
      fail-action: "console: xp 10 {player}"
```

---




## Requirement Set

* A requirement set is a set of requirements that the player are required to pass before doing actions.
* It consists of:
  * The [Requirements]({{% ref "../overview" %}}).
  * `success-action` (`success-command`): the [Action]({{% ref "action/overview" %}}) when the player passes all requirements.
  * `fail-action` (`fail-command`): the [Action]({{% ref "action/overview" %}}) when the player doesn't pass any of the requirements.
* You can set multiple sets of requirements.
  * The plugin will check for one set that the player meet its requirements. If none of the sets is matched, these are simply passed as failed and the actions will not be executed.

## Format

```yaml
requirement-set-name: # The name of the Requirement Set
  requirement-1: value-1 # The first requirement
  requirement-2: value-2 # The second requirement
  requirement-3: value-3 # The third requirement
  <requirement..>: <value..> # More requirements

  success-action: # The actions when the requirements are met
  - action1
  - action2
  - action3

  fail-action: # The actions when the requirements are not met
  - action1
  - action2
  - action3
```

## Example

```yaml
check-condition:
  slot: 1
  type: predicate
  CLICK-REQUIREMENT: # Click Requirement
    default: # Click type
      we-permission: # The name of the Requirement Set
        permission: # The permission requirement
        - bettergui.test
        - bettergui.test.1
        level: 10 # The level requirement
        fail-command: "tell: &cYou don''t meet the requirements!"
        success-command: "tell: &a[v] You passed the requirements!"
  button:
    NAME: '&8Requirement Test'
    LORE:
      - 'To use this item, you need to pass all requirements.'
      - 'Otherwise, a configurable error'
      - 'message will be displayed.'
    ID: iron bars
```
---




---


## Cooldown Requirement

The requirement to check if the player is not in a cooldown timer (seconds). After checking successfully, the cooldown timer will start for the player.

## Format

```yaml
cooldown: <seconds>
```

## Example

```yaml
cooldown:
  slot: 1
  type: predicate
  button:
    COMMAND: "tell: &e You will need to wait 10 seconds to click again"
    NAME: '&aCooldown'
    LORE:
      - 'This is a example of icon with cooldown'
    ID: paper
  click-requirement: # Click Requirement
    default: # Click type
      test-cooldown: # Requirement Set name
        cooldown: 10 # Here we are
      fail-command:
        - "tell: &cWait until the cooldown is finished"
```
---




---


## Level Requirement

The requirement to check if the level of the player is higher or equal to the specific level

## Format

```yaml
level: <level>
```
```yaml
level:
  value: <level>
  take: <true/false>
```

## Note

* You can specify the `take` value (`true` or `false`) to allow/disallow the plugin to take the level of the player alter checking successfully

## Example

```yaml
test-view-requirement:
  type: predicate
  slot: 1
  button:
    id: exp_bottle
    name: "&cA exp bottle"
    lore:
      - "You will see this icon when the level is higher than 5"
  view-requirement: # View Requirement
    level: # Requirement Set name
      level: 5 # Here we are
```
```yaml
test-click-requirement:
  type: predicate
  slot: 1
  button:
    id: exp_bottle
    name: "&cA level checker"
    command: "tell: &aYou reached level 5"
  click-requirement: # Click Requirement
    default: # Click type
      test-level: # Requirement Set name
        level: # Here we are
          value: 5
          take: true # Take the level
      fail-command:
        - "tell: &cTrain more"
```
---




---


## Permission Requirement

The requirement to check if the player has the specific permission

## Format

```yaml
permission: <permission>
```
```yaml
permission:
- <permission>
- <permission>
- <permission>
...
```

## Note

* You can add `-` before `<permission>` to indicate that the plugin should check if the player doesn't have the `<permission>`

## Example

```yaml
permission:
  slot: 1
  type: predicate
  CLICK-REQUIREMENT: # Click Requirement
    default: # Click type
      permission: # Requirement set name
        PERMISSION: bettergui.test # Here we are
        fail-command: "tell: &cYou don''t have the correct permission!"
  button:
    COMMAND: "tell: &a[v] You have the correct permission!"
    NAME: '&8Permission test'
    LORE:
      - 'To use this item, you need the'
      - 'permission "bettergui.test".'
      - 'Otherwise, a configurable error'
      - 'message will be displayed.'
    ID: iron bars
```
```yaml
permission-list:
  slot: 2
  type: predicate
  CLICK-REQUIREMENT: # Click Requirement
    default: # Click type
      permission: # Requirement set name
        PERMISSION: # Here we are
        - bettergui.test
        - bettergui.test.1
        fail-command: "tell: &cYou don''t have the correct permission!"
  button:
    COMMAND: "tell: &a[v] You have the correct permission!"
    NAME: '&8Permission test'
    LORE:
      - 'To use this item, you need the'
      - 'required permissions.'
      - 'Otherwise, a configurable error'
      - 'message will be displayed.'
    ID: iron bars
```
---




---


## Condition Requirement

The requirement to check on conditions & expressions (Mainly [Math extension](https://github.com/PlaceholderAPI/PlaceholderAPI/wiki/Placeholders#math))

{{% notice tip %}}
If you want more advanced expressions, check out [Eval Extra]({{% ref "addon/eval-extra" %}})
{{% /notice %}}

## Format

```yaml
condition: <condition>
```

## Note

* This requirement will check if `<condition>` is `true`, `yes`, `on` or `0`

## Example

```yaml
test-view-requirement:
  type: predicate
  slot: 1
  button:
    id: exp_bottle
    name: "&cA exp bottle"
    lore:
      - "You will see this icon when the level is 0"
  view-requirement: # View Requirement
    level: # Requirement Set name
      condition: "%math_{level} >= 0%" # Here we are
```
---




---


## Version Requirement

The requirement to check if the server is at a specific version or higher.

## Format

```yaml
version: <value>
```

## Note

* The `<value>` is the major part of the version of Minecraft.
  * `1.12.2` will be `12`
  * `1.18.2` will be `18`
  * `1.8.8` will be `8`

## Example

```yaml
test-xp:
  slot: 0
  id:
    - EXPERIENCE_BOTTLE
    - EXP_BOTTLE
  name: "&eGive &f10 XP"
  lore:
    - ""
    - "&fThis is a test template button"
    - "&fLevel: {level}"
  click-requirement:
    old-version:
      version: 13 # Check if the server is at 1.13.X
      success-action: "console: xp add {player} 10 points"
      fail-action: "console: xp 10 {player}"
```
---




---



# Item Modifier

The unit that changes the display item.
---



## Overview

* Item Modifier is the property of an item. It describes what the final item should be.
* There are a lot of built-in modifiers for items (Check the sidebar). A developer can also make his own modifier and register to the plugin.

## Example
```yaml
stone-button:
  slot: 1
  id: stone
  name: "&cThis is a stone button"
  lore:
  - "This is just a stone button"
  - "&uNothing special"
```

---


## Material

This modifier will set the material of the item.

## Format

```yaml
material: <material>
id: <material>
mat: <material>
```

## Note

* [List of Materials](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html).
* You can set multiple materials as a list for the plugin to check for one available material. This helps Setup Makers to support both old and new version of the material.

## Example

```yaml
stone-button:
  slot: 1
  id: stone
```
```yaml
player-head:
  slot: 2
  id:
  - player_head
  - skull_item:3
```

---


## Name

This modifier will set the display name of the item.

## Format

```yaml
name: "<name>"
```

## Example

```yaml
stone-button:
  slot: 1
  id: stone
  name: "&cThis is a stone button"
```

---


## Lore

This modifier will set the lore of the item.

## Format

```yaml
lore: <lore>
```
```yaml
lore:
- <lore>
- <lore>
- <lore>
...
```

## Example

```yaml
stone-button:
  slot: 1
  id: stone
  name: "&cThis is a stone button"
  lore:
  - "This is just a stone button"
  - "&uNothing special"
```

---


## Amount

This modifier will set the amount of the item.

## Format

```yaml
amount: <amount>
```

## Example

```yaml
stone-button:
  slot: 1
  id: stone
  amount: 10
  name: "&cThis is 10 stone buttons"
  lore:
  - "This is just 10 stone buttons"
  - "&uNothing special"
```

---


## Durability

This modifier will set the durability of the item.

## Format

```yaml
durability: <durability>
damage: <durability>
```

## Example

```yaml
durability-armor:
  NAME: '&aDamaged armor'
  LORE:
    - 'This armor is damaged.'
  ID: diamond helmet
  DAMAGE: 100
  POSITION-X: 1
  POSITION-Y: 1
```

---


## Enchantment

This modifier will add the enchants to the item.

## Format

```yaml
enchantment:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
```
```yaml
enchant:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
```
```yaml
enc:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
```

## Note

* [List of Enchantments](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/enchantments/Enchantment.html).
* You can set the `[level]` of the `<enchantment>`. It's optional.

## Example

```yaml
enchanted-sword:
  NAME: '&aEnchanted sword'
  LORE:
    - 'This sword is glowing.'
  ID: diamond_sword
  ENCHANTMENT:
    - "durability, 1"
  POSITION-X: 1
  POSITION-Y: 1
```

---


## Item Flag

This modifier will add the flags to the item.

## Format

```yaml
flag:
- <flag>
- <flag>
- <flag>
...
```
```yaml
item-flags:
- <flag>
- <flag>
- <flag>
...
```
```yaml
itemflag:
- <flag>
- <flag>
- <flag>
...
```
```yaml
itemflags:
- <flag>
- <flag>
- <flag>
...
```
```yaml
item-flag:
- <flag>
- <flag>
- <flag>
...
```

## Note

* [List of flags](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/inventory/ItemFlag.html).

## Example

```yaml
enchanted-sword-flag:
  NAME: '&aEnchanted sword'
  LORE:
    - 'This sword is glowing. (literally)'
  ID: diamond_sword
  ENCHANTMENT:
    - "durability, 1"
  FLAG:
    - HIDE_ENCHANTS
  POSITION-X: 1
  POSITION-Y: 1
```

---


## Potion Effect

This modifier will add the potion effects to the item.

## Format

```yaml
potion:
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
...
```
```yaml
effect:
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
...
```

## Note

* [List of Potion Effects](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/potion/PotionEffectType.html).
* You can set the `[duration]` and `[amplifier]` of the `<potion>` effect. These are optional.

## Example

```yaml
potion:
  position-x: 1
  position-y: 1
  name: "&bPotion"
  id: potion
  potion:
    - "SPEED"
    - "WEAKNESS, 30, 1"
```

---


## Skull

This modifier will set the skull of the item.

## Format

```yaml
skull: <skull>
head: <skull>
skull-owner: <skull-owner>
```

## Note

* `<skull>` accepts a player name, an UUID (unique id), a Base64 value, or a `texture.minecraft.net` URL

## Example

```yaml
skull:
  position-x: 1
  position-y: 1
  name: "&bSkull"
  id: player_head
  skull: "HSGamer"
  #skull: "7acc67dc-8b84-4f8d-b7ad-ec81e758f5a1"
  #skull: "http://textures.minecraft.net/texture/ffcdae586b52403b92b1857ee4331bac636af08bab92ba5750a54a83331a6353"
  #skull: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZTM1ODNkNTNlOWNhZjE3MGUwNWI1MTYxN2E2N2QxMzEwZDJkODExYTUxNTg4NjI5ODZjMTVlMjg2NzhhNTA1ZiJ9fX0="

per-player-skull:
  position-x: 2
  position-y: 1
  name: "&bPer Player Skulls"
  id: player_head
  skull: "{player}"
```

---


## NBT

This modifier will apply the NBT data to the item.

{{% notice warning %}}
This modifier will reset all item settings. Therefore, It's recommended to order the settings in the following pattern: `ID (Material)`, `NBT`, `other item settings`.
{{% /notice %}}

## Format

```yaml
nbt: <nbt>
nbt-data: <nbt>
```

## Example

```yaml
custom-model-chestplate:
  id: leather_chestplate
  nbt:
    CustomModelData: 104230
  #nbt: "{CustomModelData:104230}"
  name: "&aCustom Model Chestplate"
  lore:
    - "This is a custom model chestplate"
  position-x: 1
  position-y: 1

colored-leather-chestplate:
  id: leather_chestplate
  nbt:
    display:
      color: 16175144
  #nbt: "{display:{color:16175144}}"
  name: "&aColored Leather Chestplate"
  lore:
    - "This is a colored leather chestplate"
  position-x: 2
  position-y: 1
```

## Item Component

In 1.20.5 and above, Mojang decided to replace NBT with their new Item Component.
To use Item Component, you can use its square-bracket format `[]` as the value to the modifier.

For example, for a typical `/give` command like this:
```
/give @s leather_helmet[dyed_color={rgb:456345,show_in_tooltip:false}]
```

You can take this part `[dyed_color={rgb:456345,show_in_tooltip:false}]` and use it in the modifier like this:

```yaml
nbt: "[dyed_color={rgb:456345,show_in_tooltip:false}]"
```

---




## Material

This modifier will set the material of the item.

## Format

```yaml
material: <material>
id: <material>
mat: <material>
```

## Note

* [List of Materials](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html).
* You can set multiple materials as a list for the plugin to check for one available material. This helps Setup Makers to support both old and new version of the material.

## Example

```yaml
stone-button:
  slot: 1
  id: stone
```
```yaml
player-head:
  slot: 2
  id:
  - player_head
  - skull_item:3
```
---




---


## Name

This modifier will set the display name of the item.

## Format

```yaml
name: "<name>"
```

## Example

```yaml
stone-button:
  slot: 1
  id: stone
  name: "&cThis is a stone button"
```
---




---


## Lore

This modifier will set the lore of the item.

## Format

```yaml
lore: <lore>
```
```yaml
lore:
- <lore>
- <lore>
- <lore>
...
```

## Example

```yaml
stone-button:
  slot: 1
  id: stone
  name: "&cThis is a stone button"
  lore:
  - "This is just a stone button"
  - "&uNothing special"
```
---




---


## Amount

This modifier will set the amount of the item.

## Format

```yaml
amount: <amount>
```

## Example

```yaml
stone-button:
  slot: 1
  id: stone
  amount: 10
  name: "&cThis is 10 stone buttons"
  lore:
  - "This is just 10 stone buttons"
  - "&uNothing special"
```
---




---


## Durability

This modifier will set the durability of the item.

## Format

```yaml
durability: <durability>
damage: <durability>
```

## Example

```yaml
durability-armor:
  NAME: '&aDamaged armor'
  LORE:
    - 'This armor is damaged.'
  ID: diamond helmet
  DAMAGE: 100
  POSITION-X: 1
  POSITION-Y: 1
```
---




---


## Enchantment

This modifier will add the enchants to the item.

## Format

```yaml
enchantment:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
```
```yaml
enchant:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
```
```yaml
enc:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
```

## Note

* [List of Enchantments](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/enchantments/Enchantment.html).
* You can set the `[level]` of the `<enchantment>`. It's optional.

## Example

```yaml
enchanted-sword:
  NAME: '&aEnchanted sword'
  LORE:
    - 'This sword is glowing.'
  ID: diamond_sword
  ENCHANTMENT:
    - "durability, 1"
  POSITION-X: 1
  POSITION-Y: 1
```
---




---


## Item Flag

This modifier will add the flags to the item.

## Format

```yaml
flag:
- <flag>
- <flag>
- <flag>
...
```
```yaml
item-flags:
- <flag>
- <flag>
- <flag>
...
```
```yaml
itemflag:
- <flag>
- <flag>
- <flag>
...
```
```yaml
itemflags:
- <flag>
- <flag>
- <flag>
...
```
```yaml
item-flag:
- <flag>
- <flag>
- <flag>
...
```

## Note

* [List of flags](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/inventory/ItemFlag.html).

## Example

```yaml
enchanted-sword-flag:
  NAME: '&aEnchanted sword'
  LORE:
    - 'This sword is glowing. (literally)'
  ID: diamond_sword
  ENCHANTMENT:
    - "durability, 1"
  FLAG:
    - HIDE_ENCHANTS
  POSITION-X: 1
  POSITION-Y: 1
```
---




---


## Potion Effect

This modifier will add the potion effects to the item.

## Format

```yaml
potion:
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
...
```
```yaml
effect:
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
...
```

## Note

* [List of Potion Effects](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/potion/PotionEffectType.html).
* You can set the `[duration]` and `[amplifier]` of the `<potion>` effect. These are optional.

## Example

```yaml
potion:
  position-x: 1
  position-y: 1
  name: "&bPotion"
  id: potion
  potion:
    - "SPEED"
    - "WEAKNESS, 30, 1"
```
---




---


## Skull

This modifier will set the skull of the item.

## Format

```yaml
skull: <skull>
head: <skull>
skull-owner: <skull-owner>
```

## Note

* `<skull>` accepts a player name, an UUID (unique id), a Base64 value, or a `texture.minecraft.net` URL

## Example

```yaml
skull:
  position-x: 1
  position-y: 1
  name: "&bSkull"
  id: player_head
  skull: "HSGamer"
  #skull: "7acc67dc-8b84-4f8d-b7ad-ec81e758f5a1"
  #skull: "http://textures.minecraft.net/texture/ffcdae586b52403b92b1857ee4331bac636af08bab92ba5750a54a83331a6353"
  #skull: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZTM1ODNkNTNlOWNhZjE3MGUwNWI1MTYxN2E2N2QxMzEwZDJkODExYTUxNTg4NjI5ODZjMTVlMjg2NzhhNTA1ZiJ9fX0="

per-player-skull:
  position-x: 2
  position-y: 1
  name: "&bPer Player Skulls"
  id: player_head
  skull: "{player}"
```
---




---


## NBT

This modifier will apply the NBT data to the item.

{{% notice warning %}}
This modifier will reset all item settings. Therefore, It's recommended to order the settings in the following pattern: `ID (Material)`, `NBT`, `other item settings`.
{{% /notice %}}

## Format

```yaml
nbt: <nbt>
nbt-data: <nbt>
```

## Example

```yaml
custom-model-chestplate:
  id: leather_chestplate
  nbt:
    CustomModelData: 104230
  #nbt: "{CustomModelData:104230}"
  name: "&aCustom Model Chestplate"
  lore:
    - "This is a custom model chestplate"
  position-x: 1
  position-y: 1

colored-leather-chestplate:
  id: leather_chestplate
  nbt:
    display:
      color: 16175144
  #nbt: "{display:{color:16175144}}"
  name: "&aColored Leather Chestplate"
  lore:
    - "This is a colored leather chestplate"
  position-x: 2
  position-y: 1
```

## Item Component

In 1.20.5 and above, Mojang decided to replace NBT with their new Item Component.
To use Item Component, you can use its square-bracket format `[]` as the value to the modifier.

For example, for a typical `/give` command like this:
```
/give @s leather_helmet[dyed_color={rgb:456345,show_in_tooltip:false}]
```

You can take this part `[dyed_color={rgb:456345,show_in_tooltip:false}]` and use it in the modifier like this:

```yaml
nbt: "[dyed_color={rgb:456345,show_in_tooltip:false}]"
```
---




---



# Argument Processor

The unit that handles the arguments of a [Menu]({{% ref "menu" %}}).

{{% notice info %}}
Some menus support **multiple** argument processors. The argument processors are executed in the order they are specified in the setting.
{{% /notice %}}
---



## Overview

* Argument Processor is a special unit that handles the arguments of a menu, mainly from [Open Menu Command]({{% ref "basic/command" %}}) and [Open Menu Action]({{% ref "action/menu-open" %}})
* The arguments are splitted and handled by multiple processors in the configured order.
* The processors are specified in the `argument-processor` section of the `menu-settings`.
* There are many built-in types of processors (Check the sidebar). A developer can also create his own processor and register to this plugin.

## Example
```yaml
menu-settings:
  command: testargs
  argument-processor:
    hello:
      length: 2
      suggest:
      - Hello you
      - Welcome back
      action: "tell: &cHello is required"
    message:
      take-remaining: true
      suggest:
      - HSGamer
      - Minecraft World
      action: "tell: &cMessage is required"

button:
  slot: 0
  id: stone
  name: "&bTest Arguments"
  lore:
  - "{arg_hello}, {arg_message}"
```

## Variable
* Each processor provide its own variable to be used in the menu.
* The format: `{arg_<processor_name>}`
* For example: `{arg_hello}`, `{arg_message}`

---


## Store Argument

This is a processor to store the arguments and provide them as [Variables]({{% ref "misc/variable" %}})

## Format

```yaml
menu-settings:
  argument-processor: # Add the processor to the menu
    <name>:
      type: store # Not needed as it's the default type
      action:
      - action
      - action
      - action
      - action
      invalid-action:
      - action
      - action
      - action
      length: <number>
      take-remaining: <true/false>
      suggest:
      - string1
      - string2
      - string3
      check-suggest: <true/false>
```

## Note

* `length`: the required length of the argument
* `take-remaining`: whether to take all remaining arguments
* `suggest`: the list of suggestions when the player uses tab-completion
* `check-suggest`: whether to check the argument against the `suggest` list
* `action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument length is not enough
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument is invalid

## Example

```yaml
menu-settings:
  command: testargs
  argument-processor:
    hello:
      length: 2
      suggest:
      - Hello you
      - Welcome back
      action: "tell: &cHello is required"
    message:
      take-remaining: true
      suggest:
      - HSGamer
      - Minecraft World
      action: "tell: &cMessage is required"

button:
  slot: 0
  id: stone
  name: "&bTest Arguments"
  lore:
  - "{arg_hello}, {arg_message}"
```

---


## Player Argument

This is a processor to handle the argument for Player Name

## Format

```yaml
menu-settings:
  argument-processor: # Add the processor to the menu
    <name>:
      type: player
      action:
      - action
      - action
      - action
      - action
      invalid-action:
      - action
      - action
      - action
      online-only: <true/false>
```

## Note

* `online-only`: whether to check if the player is online. If `true`, then only the online players are given to the suggestion list
* `action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument length is not enough
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument is invalid

## Targeted Variables

You can fetch the [Variable]({{% ref "misc/variable" %}}) for the target player argument by using this format:
```
{arg_<processor_name>_<variable_name>}
```
For PlaceholderAPI's placeholders, use this format:
```
{arg_<processor_name>_papi_<placeholder_without_brackets>}
```
For example (given that your argument processor name is `target`):
- `{level}` will be `{arg_target_level}`
- `{uuid}` will be `{arg_target_uuid}`
- `%player_gamemode%` will be `{arg_target_papi_player_gamemode}`

## Example

```yaml
menu-settings:
  command: confirmteleport
  argument-processor:
    player:
      type: player
      action: "tell: &cPlayer is required"
    target:
      type: player
      action: "tell: &cTarget is required"

button:
  slot: 0
  id: ender_pearl
  name: "&bTeleport to {arg_target}"
  lore:
    - ""
    - "&7&lTarget Info"
    - "&7- &fName: &e{arg_target}"
    - "&7- &fUUID: &e{arg_target_uuid}"
    - "&7- &fLocation: &e{arg_target_world} {arg_target_x} {arg_target_y} {arg_target_z}"
    - "&7- &fTarget PlaceholderAPI: &e{arg_target_papi_player_gamemode}"
    - ""
  command: "console: tp {arg_player} {arg_target}"
```

---


## Number Argument

This is a processor to handle the numeric argument

## Format

```yaml
menu-settings:
  argument-processor: # Add the processor to the menu
    <name>:
      type: number
      action:
      - action
      - action
      - action
      - action
      invalid-action:
      - action
      - action
      - action
      suggest:
      - 0
      - 1
      - 2
```

## Note

* `suggest`: the list of suggestions when the player uses tab-completion
* `action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument length is not enough
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument is invalid

## Example

```yaml
menu-settings:
  command: giveapple
  argument-processor:
    amount:
      type: number
      action: "tell: &cAmount is required"

button:
  slot: 0
  id: apple
  name: "&bGive apple"
  command: "console: give {player} apple {arg_amount}"
```

---


## Decimal Argument

This is a processor to handle the decimal argument

## Format

```yaml
menu-settings:
  argument-processor: # Add the processor to the menu
    <name>:
      type: decimal
      action:
      - action
      - action
      - action
      - action
      invalid-action:
      - action
      - action
      - action
      suggest:
      - 0
      - 1
      - 2
```

## Note

* `suggest`: the list of suggestions when the player uses tab-completion
* `action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument length is not enough
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument is invalid

## Example

```yaml
menu-settings:
  command: teleportcoords
  argument-processor:
    x:
      type: decimal
      action: "tell: &cX is required"
    y:
      type: decimal
      action: "tell: &cY is required"
    z:
      type: decimal
      action: "tell: &cZ is required"

button:
  slot: 0
  id: ender_pearl
  name: "&bTeleport"
  command: "console: tp {player} {arg_x} {arg_y} {arg_z}"
```

---


## Material Argument

This is a processor to handle the argument of Material

## Format

```yaml
menu-settings:
  argument-processor: # Add the processor to the menu
    <name>:
      type: material
      action:
      - action
      - action
      - action
      - action
      invalid-action:
      - action
      - action
      - action
```

## Note

* `action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument length is not enough
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument is invalid

## Example

```yaml
menu-settings:
  command: materialview
  argument-processor:
    material:
      type: material
      action: "tell: &cMaterial is required"

button:
  slot: 0
  id: "{arg_material}"
  name: "&bMaterial"
```

---


## Entity Argument

This is a processor to handle the argument of Entity

## Format

```yaml
menu-settings:
  argument-processor: # Add the processor to the menu
    <name>:
      type: entity
      action:
      - action
      - action
      - action
      - action
      invalid-action:
      - action
      - action
      - action
```

## Note

* `action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument length is not enough
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument is invalid

## Example

```yaml
menu-settings:
  command: spawnentity
  argument-processor:
    entity:
      type: entity
      action: "tell: &cEntity is required"

button:
  slot: 0
  id: "egg"
  name: "&bSpawn Entity"
  command: "op: spawn {arg_entity}"
```

---




## Store Argument

This is a processor to store the arguments and provide them as [Variables]({{% ref "misc/variable" %}})

## Format

```yaml
menu-settings:
  argument-processor: # Add the processor to the menu
    <name>:
      type: store # Not needed as it's the default type
      action:
      - action
      - action
      - action
      - action
      invalid-action:
      - action
      - action
      - action
      length: <number>
      take-remaining: <true/false>
      suggest:
      - string1
      - string2
      - string3
      check-suggest: <true/false>
```

## Note

* `length`: the required length of the argument
* `take-remaining`: whether to take all remaining arguments
* `suggest`: the list of suggestions when the player uses tab-completion
* `check-suggest`: whether to check the argument against the `suggest` list
* `action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument length is not enough
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument is invalid

## Example

```yaml
menu-settings:
  command: testargs
  argument-processor:
    hello:
      length: 2
      suggest:
      - Hello you
      - Welcome back
      action: "tell: &cHello is required"
    message:
      take-remaining: true
      suggest:
      - HSGamer
      - Minecraft World
      action: "tell: &cMessage is required"

button:
  slot: 0
  id: stone
  name: "&bTest Arguments"
  lore:
  - "{arg_hello}, {arg_message}"
```
---




---


## Player Argument

This is a processor to handle the argument for Player Name

## Format

```yaml
menu-settings:
  argument-processor: # Add the processor to the menu
    <name>:
      type: player
      action:
      - action
      - action
      - action
      - action
      invalid-action:
      - action
      - action
      - action
      online-only: <true/false>
```

## Note

* `online-only`: whether to check if the player is online. If `true`, then only the online players are given to the suggestion list
* `action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument length is not enough
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument is invalid

## Targeted Variables

You can fetch the [Variable]({{% ref "misc/variable" %}}) for the target player argument by using this format:
```
{arg_<processor_name>_<variable_name>}
```
For PlaceholderAPI's placeholders, use this format:
```
{arg_<processor_name>_papi_<placeholder_without_brackets>}
```
For example (given that your argument processor name is `target`):
- `{level}` will be `{arg_target_level}`
- `{uuid}` will be `{arg_target_uuid}`
- `%player_gamemode%` will be `{arg_target_papi_player_gamemode}`

## Example

```yaml
menu-settings:
  command: confirmteleport
  argument-processor:
    player:
      type: player
      action: "tell: &cPlayer is required"
    target:
      type: player
      action: "tell: &cTarget is required"

button:
  slot: 0
  id: ender_pearl
  name: "&bTeleport to {arg_target}"
  lore:
    - ""
    - "&7&lTarget Info"
    - "&7- &fName: &e{arg_target}"
    - "&7- &fUUID: &e{arg_target_uuid}"
    - "&7- &fLocation: &e{arg_target_world} {arg_target_x} {arg_target_y} {arg_target_z}"
    - "&7- &fTarget PlaceholderAPI: &e{arg_target_papi_player_gamemode}"
    - ""
  command: "console: tp {arg_player} {arg_target}"
```
---




---


## Number Argument

This is a processor to handle the numeric argument

## Format

```yaml
menu-settings:
  argument-processor: # Add the processor to the menu
    <name>:
      type: number
      action:
      - action
      - action
      - action
      - action
      invalid-action:
      - action
      - action
      - action
      suggest:
      - 0
      - 1
      - 2
```

## Note

* `suggest`: the list of suggestions when the player uses tab-completion
* `action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument length is not enough
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument is invalid

## Example

```yaml
menu-settings:
  command: giveapple
  argument-processor:
    amount:
      type: number
      action: "tell: &cAmount is required"

button:
  slot: 0
  id: apple
  name: "&bGive apple"
  command: "console: give {player} apple {arg_amount}"
```
---




---


## Decimal Argument

This is a processor to handle the decimal argument

## Format

```yaml
menu-settings:
  argument-processor: # Add the processor to the menu
    <name>:
      type: decimal
      action:
      - action
      - action
      - action
      - action
      invalid-action:
      - action
      - action
      - action
      suggest:
      - 0
      - 1
      - 2
```

## Note

* `suggest`: the list of suggestions when the player uses tab-completion
* `action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument length is not enough
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument is invalid

## Example

```yaml
menu-settings:
  command: teleportcoords
  argument-processor:
    x:
      type: decimal
      action: "tell: &cX is required"
    y:
      type: decimal
      action: "tell: &cY is required"
    z:
      type: decimal
      action: "tell: &cZ is required"

button:
  slot: 0
  id: ender_pearl
  name: "&bTeleport"
  command: "console: tp {player} {arg_x} {arg_y} {arg_z}"
```
---




---


## Material Argument

This is a processor to handle the argument of Material

## Format

```yaml
menu-settings:
  argument-processor: # Add the processor to the menu
    <name>:
      type: material
      action:
      - action
      - action
      - action
      - action
      invalid-action:
      - action
      - action
      - action
```

## Note

* `action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument length is not enough
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument is invalid

## Example

```yaml
menu-settings:
  command: materialview
  argument-processor:
    material:
      type: material
      action: "tell: &cMaterial is required"

button:
  slot: 0
  id: "{arg_material}"
  name: "&bMaterial"
```
---




---


## Entity Argument

This is a processor to handle the argument of Entity

## Format

```yaml
menu-settings:
  argument-processor: # Add the processor to the menu
    <name>:
      type: entity
      action:
      - action
      - action
      - action
      - action
      invalid-action:
      - action
      - action
      - action
```

## Note

* `action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument length is not enough
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) to be called when the argument is invalid

## Example

```yaml
menu-settings:
  command: spawnentity
  argument-processor:
    entity:
      type: entity
      action: "tell: &cEntity is required"

button:
  slot: 0
  id: "egg"
  name: "&bSpawn Entity"
  command: "op: spawn {arg_entity}"
```
---




---



# Miscellaneous

Less important but interesting topics.
---



## Variable

* Variable (or sometimes Placeholder) is a special string that will be replaced to a value that is relative to the player.
* Variables can be seen as the string inside curly brackets `{}`. We will see some of these variables in the next section.
* You can use [`/getvariables`]({{% ref "basic/command" %}}) to get the list of registered variables
* You can use variables in your text by putting them in curly brackets. For example, `Hello {player}!` will say hello to the player, with `{player}` replaced to the player's name.

## Built-ins

* `{player}` returns the player's name
* `{uuid}` returns the unique id of the player
* `{online}` returns the number of online players
* `{max_players}` returns the max capacity of players in the server
* `{world}` returns the current world of the player
* `{world_env}` returns the environment of the current world of the player
* `{x}` returns the current X position of the player
* `{y}` returns the current Y position of the player
* `{z}` returns the current Z position of the player
* `{bed_world}` returns the current world of the player's bed
* `{bed_world_env}` returns the environment of the current world of the player's bed
* `{bed_x}` returns the current X position of the player's bed
* `{bed_y}` returns the current Y position of the player's bed
* `{bed_z}` returns the current Z position of the player's bed
* `{exp}` returns the experiences (XP) of the player
* `{level}` returns the level of the player
* `{exp_to_level}` returns the required XP to go to the next level
* `{food_level}` returns the food level of the player
* `{ip}` returns the IP address of the player
* `{biome}` returns the current biome in the player's current location
* `{ping}` returns the latency of the player's connection
* `{random_<i>}` or `{random_<i1>:<i2>}` returns a random number from 0 to `<i>`, or from `<i1>` to `<i2>`

## Menu variables

* There are variables are generated by the menu.
  * You can use [`/getvariables <menu>`]({{% ref "basic/command" %}}) to get the list of registered variables for the specific menu
* To use variables from another menu: `{menu_<menu_name>.yml_<variable>`
  * Example: If you use [Store Argument Processor]({{% ref "argument/store" %}}) in a menu called `test.yml` and want to use `{merged_args}` in other menus, you can use `{menu_test.yml_merged_args}`

## [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/)

* You can use placeholders from [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) in your text.
* You can also use variables from BetterGUI to other plugins via [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/)
  * The format for this is `%bettergui_<variable>%` (`<variable>` is a variable without the curly brackets `{}`)
  * For example, this is the placeholder to use `{player}` in other plugins: `%bettergui_player%`

---


## Message Color

## Basic Color

* Some options that accepts a string can also support colors in that string
* You can use colors to "colorize" the string. If you have been using other plugins that interact with messages and texts, you may be familiar with some color characters (`&c`, `&b`, etc) or a combination of color and transformation (`&c&l`, `&b&o&l`, etc).
* [Color codes](https://minecraft.tools/en/color-code.php)
* You can use `&u` to get the random color for the text

## HEX Color

* After the 5.0 update, BetterGUI now supports HEX color (the thing with 3 Red Green Blue values) in texts and messages.
* You can use it by using the HEX format `&#rrggbb` (`rr`, `gg` and `bb` are the value of the red, green and blue channel of the color, from `00` to `FF`)
* For example, `&#FF0000` represents the red color. `&#FF0000Hello World!` will return the red `Hello World!`
* [HEX Color](https://www.google.com/search?q=Hex+color)

---


## Click Type

* You may notice, in the example menu, there are some weird values in `command` (`action`) and `click-requirement`.
* What are those `left`, `right`, `middle` and `default`?
* Those are called Click Type. It indicates the different behaviors of the button on different click types (left-click, right-click, middle-click, etc).
* [List of Click Type](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/ClickType.html)
* Along with the click types, you can set a `default` click type, whose behaviors will be set on all available click types.

## In `action`

```yaml
COMMAND:
  LEFT: "tell: &cYou left-clicked"
  RIGHT: "tell: &cYou right-clicked"
  MIDDLE: "tell: &cYou middle-clicked"
  # Default for every click types
  DEFAULT:
    - "tell: &cUnknown click type"
    - "tell: Left, Right, Middle only"
```

## In `click-requirement`

```yaml
click-requirement:
  left:
    test:
      cooldown: 10
  right:
    test:
      cooldown: 20
  middle:
    test:
      cooldown: 30
  default:
    test:
      cooldown: 40
    fail-command:
      - "tell: &cCalm down"
```

## `NUMBER_KEY` with number key

* **The format**: `NUMBER_KEY_<0-8>`
* You can set the `NUMBER_KEY` click type with a number key (from `0` to `8`, specify the `1` to `9` number key)
* This requires [`use-modern-click-type`]({{% ref "basic/config" %}}) to be enabled

---




## Variable

* Variable (or sometimes Placeholder) is a special string that will be replaced to a value that is relative to the player.
* Variables can be seen as the string inside curly brackets `{}`. We will see some of these variables in the next section.
* You can use [`/getvariables`]({{% ref "basic/command" %}}) to get the list of registered variables
* You can use variables in your text by putting them in curly brackets. For example, `Hello {player}!` will say hello to the player, with `{player}` replaced to the player's name.

## Built-ins

* `{player}` returns the player's name
* `{uuid}` returns the unique id of the player
* `{online}` returns the number of online players
* `{max_players}` returns the max capacity of players in the server
* `{world}` returns the current world of the player
* `{world_env}` returns the environment of the current world of the player
* `{x}` returns the current X position of the player
* `{y}` returns the current Y position of the player
* `{z}` returns the current Z position of the player
* `{bed_world}` returns the current world of the player's bed
* `{bed_world_env}` returns the environment of the current world of the player's bed
* `{bed_x}` returns the current X position of the player's bed
* `{bed_y}` returns the current Y position of the player's bed
* `{bed_z}` returns the current Z position of the player's bed
* `{exp}` returns the experiences (XP) of the player
* `{level}` returns the level of the player
* `{exp_to_level}` returns the required XP to go to the next level
* `{food_level}` returns the food level of the player
* `{ip}` returns the IP address of the player
* `{biome}` returns the current biome in the player's current location
* `{ping}` returns the latency of the player's connection
* `{random_<i>}` or `{random_<i1>:<i2>}` returns a random number from 0 to `<i>`, or from `<i1>` to `<i2>`

## Menu variables

* There are variables are generated by the menu.
  * You can use [`/getvariables <menu>`]({{% ref "basic/command" %}}) to get the list of registered variables for the specific menu
* To use variables from another menu: `{menu_<menu_name>.yml_<variable>`
  * Example: If you use [Store Argument Processor]({{% ref "argument/store" %}}) in a menu called `test.yml` and want to use `{merged_args}` in other menus, you can use `{menu_test.yml_merged_args}`

## [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/)

* You can use placeholders from [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) in your text.
* You can also use variables from BetterGUI to other plugins via [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/)
  * The format for this is `%bettergui_<variable>%` (`<variable>` is a variable without the curly brackets `{}`)
  * For example, this is the placeholder to use `{player}` in other plugins: `%bettergui_player%`
---




---


## Message Color

## Basic Color

* Some options that accepts a string can also support colors in that string
* You can use colors to "colorize" the string. If you have been using other plugins that interact with messages and texts, you may be familiar with some color characters (`&c`, `&b`, etc) or a combination of color and transformation (`&c&l`, `&b&o&l`, etc).
* [Color codes](https://minecraft.tools/en/color-code.php)
* You can use `&u` to get the random color for the text

## HEX Color

* After the 5.0 update, BetterGUI now supports HEX color (the thing with 3 Red Green Blue values) in texts and messages.
* You can use it by using the HEX format `&#rrggbb` (`rr`, `gg` and `bb` are the value of the red, green and blue channel of the color, from `00` to `FF`)
* For example, `&#FF0000` represents the red color. `&#FF0000Hello World!` will return the red `Hello World!`
* [HEX Color](https://www.google.com/search?q=Hex+color)
---




---


## Click Type

* You may notice, in the example menu, there are some weird values in `command` (`action`) and `click-requirement`.
* What are those `left`, `right`, `middle` and `default`?
* Those are called Click Type. It indicates the different behaviors of the button on different click types (left-click, right-click, middle-click, etc).
* [List of Click Type](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/ClickType.html)
* Along with the click types, you can set a `default` click type, whose behaviors will be set on all available click types.

## In `action`

```yaml
COMMAND:
  LEFT: "tell: &cYou left-clicked"
  RIGHT: "tell: &cYou right-clicked"
  MIDDLE: "tell: &cYou middle-clicked"
  # Default for every click types
  DEFAULT:
    - "tell: &cUnknown click type"
    - "tell: Left, Right, Middle only"
```

## In `click-requirement`

```yaml
click-requirement:
  left:
    test:
      cooldown: 10
  right:
    test:
      cooldown: 20
  middle:
    test:
      cooldown: 30
  default:
    test:
      cooldown: 40
    fail-command:
      - "tell: &cCalm down"
```

## `NUMBER_KEY` with number key

* **The format**: `NUMBER_KEY_<0-8>`
* You can set the `NUMBER_KEY` click type with a number key (from `0` to `8`, specify the `1` to `9` number key)
* This requires [`use-modern-click-type`]({{% ref "basic/config" %}}) to be enabled
---




---



# Addon

The extension that adds more features to the main plugin.
---



## Advanced Cooldown

{{% button href="https://github.com/BetterGUI-MC/AdvancedCooldown/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/AdvancedCooldown/" style="green" icon="download" %}}Download{{% /button %}}

## Config.yml
```yaml
# Format:
# <name>: <value>
#
# Example:
# simple-cooldown: 100
simple-cooldown: 100
cooldown-10000: 10000
cooldown-999: 999
```

## Variable
> `<name>` is the cooldown name from the `config.yml`
* `advanced_cooldown_<name>`
* `advanced_cooldown_<name>_s` or `advanced_cooldown_<name>_seconds`
* `advanced_cooldown_<name>_m` or `advanced_cooldown_<name>_minutes`
* `advanced_cooldown_<name>_h` or `advanced_cooldown_<name>_hours`
* `advanced_cooldown_<name>_format_<time-format>`
    * Example Format: `advanced_cooldown_<name>_format_HH:mm:ss`

## Requirement

### Format
```yaml
advanced-cooldown: <name>
```

### Description
* This requirement will check if the player is not in a cooldown timer named `<name>`.
* After checking the requirement, the addon will start the cooldown timer for the player.

### Example
```yaml
advanced-cooldown:
  slot: 1
  id: clock
  name: "&cAdvanced Cooldown"
  command:
    - "tell: &aHello"
  click-requirement:
    left:
      test:
        advanced-cooldown: "simple-cooldown" # from config.yml
      fail-command:
        - "tell: &cYou need to wait {advanced_cooldown_simple-cooldown_s} seconds"
    right:
      test:
        advanced-cooldown: "cooldown-10000" # from config.yml
      fail-command:
        - "tell: &cYou need to wait {advanced_cooldown_cooldown-10000_s} seconds"
    middle:
      test:
        advanced-cooldown: "cooldown-999" # from config.yml
      fail-command:
        - "tell: &cYou need to wait {advanced_cooldown_cooldown-999_s} seconds"
```

## Time Format

| character | duration element |
| --- | --- |
| y | years |
| M | months |
| d | days |
| H | hours |
| m | minutes |
| s | seconds |
| S | milliseconds |

* Example:
    * `HH:mm:ss`: show hours, minutes and seconds
    * `YY:MM:dd HH:mm:ss`: show years, months, days, hours, minutes and seconds

---


## Alternative Command Listener

{{% button href="https://github.com/BetterGUI-MC/AlternativeCommandListener/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/AlternativeCommandListener/" style="green" icon="download" %}}Download{{% /button %}}

This addon adds an alternative feature for menu commands to solve the "duplicated command" issue.

## Config.yml

```yaml
# The list of ignored commands
ignored-commands:
- warp test

# Ignore case-sensitive when checking commands
case-insensitive: true

# Should we ignore the commands in ignored-commands
# If set to false, the plugin will do the opposite (override the commands in ignored-commands)
should-ignore: true
```

---


## Anvil GUI

{{% button href="https://github.com/BetterGUI-MC/AnvilGUI/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/job/AnvilGUI/" style="green" icon="download" %}}Download{{% /button %}}

## Format
```yaml
# Settings
menu-settings:
  menu-type: anvil

  # The title of the menu
  title: <name>

  # The text to show when the player opens the menu
  text: <text>

  # The commands executed when the player clicks the result slot (the last slot)
  complete-action:
  - action
  - action
  ...

  # The commands executed when closing the menu
  close-action:
  - action
  - action
  ...

  # Whether the addon prevents the player from closing the menu
  prevent-close: <true/false>

  # The commands to open the menu
  command:
  - command1
  - command2
  ...

  # Whether the addon will clear the user's input when completed
  clear-input-on-complete: <true/false>

# Left Button
left-button:
  modifier1: <value1>
  modifier2: <value2>
  modifier3: <value3>
  ...

# Right Button
right-button:
  modifier1: <value1>
  modifier2: <value2>
  modifier3: <value3>
  ...

# Left Button (for simplier menu)
button:
  modifier1: <value1>
  modifier2: <value2>
  modifier3: <value3>
  ...
```

## Description
* This is a special menu type only for getting inputs.
* In this menu type, the addon only apply ONE icon.

## Note
* The `complete-action` and `close-action` use the [Action](../Action.md) value.
* The `left-button`, `right-button` and `button` use the [Button](../Button.md) value.
* The menu will register a [Menu Variable](../Variable.md#menu-variables) named `{anvil_input}` to get the player's input.

## Example
```yaml
menu-settings:
  menu-type: anvil
  command: testanvil
  title: "&cTest Anvil"
  text: "What is your name?"
  clear-input-on-complete: true
  complete-action:
  - "tell: &aHello, {anvil_input}"
  prevent-close: true
  close-action:
  - "tell: &cYou closed the menu"

button:
  id: paper
```

---


## ASCII-Placeholders

{{% button href="https://github.com/BetterGUI-MC/ASCII-Placeholders/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/ASCII-Placeholders/" style="green" icon="download" %}}Download{{% /button %}}

## Config.yml
```yaml
# This is the config for all static variables
# Format: {ascii_<name_of_variable>}
# Example: {ascii_<3}, {ascii_*}, {ascii_cross}, e.g.
#
# List of unicode symbols: http://www.fileformat.info/info/unicode/index.htm
<3: \u2764
"*": \u2605
"**": \u2739
"p": \u2022
"v": \u2714
"+": \u25C6
"++": \u2726
"x": \u2588
"/": \u258C
"cross": \u2720
"arrow_right": \u27A1
"arrow_left": \u2B05
"arrow_up": \u2B06
"arrow_down": \u2B07
```

## Variable
* `{ascii_<name>}` gets the value (symbol) from the `config.yml` at the key `<name>`

---


## BetterDialogs

{{% button href="https://github.com/BetterGUI-MC/BetterDialogs" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://www.spigotmc.org/resources/betterdialogs.127759/" style="green" icon="download" %}}Download{{% /button %}}

This is an addon for those who want to work with the new **Dialog System**, in **BetterGUI**'s style.

## Requirement

Your server must meet **one** of the following requirements:

- Is a **PaperMC** server in 1.21.7 or higher
- Is a **SpigotMC** server in 1.21.6 or higher (Make sure to use the latest build)
- Have installed [**PacketEvents**](https://www.spigotmc.org/resources/80279/)

### Limitation

- SpigotMC: Does not support Item Body
- PacketEvents: Item Body only displays the material and no components (See [the pull request](https://github.com/retrooper/packetevents/pull/1277))

## Getting Started

- Download the addon
- [Install the addon]({{% ref "basic/addon" %}})
- Start using it!

---


## BetterForms


{{% button href="https://github.com/BetterGUI-MC/BetterForms" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://www.spigotmc.org/resources/betterforms.115565/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice warning %}}
Depend: [Geyser](https://geysermc.org/download#geyser) or [Floodgate](https://geysermc.org/download#floodgate)
{{% /notice %}}

This is an addon for those who want to work with **Bedrock Forms**, in **BetterGUI**'s style.

## Get Started

{{% expand title="For Standalone Server" %}}
You can install just Geyser or both Geyser and Floodgate into your server
{{% /expand %}}

{{% expand title="For Proxied Server (BungeeCord, Velocity, etc.)" %}}
You have to install Floodgate into your backend server so that the addon knows whether a player is playing in Bedrock or Java
{{% /expand %}}

After downloading the addon and the required plugins, follow [this guide]({{% ref "basic/addon" %}}) to install the addon.

---


## Bungee Link

{{% button href="https://github.com/BetterGUI-MC/BungeeLink/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/BungeeLink/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice warning %}}
Depend: [BungeeCord](https://www.spigotmc.org/wiki/bungeecord/), [Velocity](https://papermc.io/software/velocity) or their forks

For [Velocity](https://papermc.io/software/velocity) and its fork, make sure to set `bungee-plugin-message-channel = true` in your `velocity.toml`
{{% /notice %}}

## Action

### Send To Server

#### Format
* `server: <server-name>`

#### Description
This action will send the player to the server `<server-name>`

#### Example
```yaml
send-to-pvp:
  slot: 1
  id: diamond sword
  name: "&c&lPVP"
  lore:
  - "&fGo to PVP Server"
  command: "server: pvp"
```

### Alert

#### Format
* `alert: <message>`

#### Description
This action will send `<message>` to all servers in the network

#### Example
```yaml
ping-everyone:
  slot: 1
  id: paper
  name: "&ePing @everyone"
  command: "alert: &b&l@everyone"
```

---


## Converter

{{% button href="https://github.com/BetterGUI-MC/Converter/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/Converter/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice note %}}
This is a work-in-progress. More features will be added soon.
{{% /notice %}}

{{% notice warning %}}
This addon does not guarantee to convert 100% of your menus, because the structure is usually different between menu plugins.

BetterGUI does not have conflict with other menus. Therefore, it's recommended to do a fresh start by making your next menu entirely in BetterGUI, then rework your old menus one-by-one in BetterGUI.
{{% /notice %}}

## Supported plugins

* [ChestCommands](https://dev.bukkit.org/projects/chest-commands)
* [DeluxeMenus](https://www.spigotmc.org/resources/deluxemenus.11734/)

## How to use

0. **Don't delete your old plugin**
1. [Download & Install the addon]({{% ref "basic/addon" %}})
2. Start & Join your server
3. Type `/convertmenu <plugin> [menu]`
  * If you don't set the `[menu]`, the addon will convert all menus from your old menu plugin.
4. The converted files will be in `plugins/BetterGUI/addon/Converter/<plugin>`

---


## Dynamic Title

{{% button href="https://github.com/BetterGUI-MC/DynamicTitle/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/DynamicTitle/" style="green" icon="download" %}}Download{{% /button %}}

## Description

This is an addon for your existing menus. This enables updating inventory titles.

## How to use

Set the `creator` option of the `menu-settings` to be `dynamic-title`

```yaml
menu-settings:
  name: '&u&lExample Menu'

  creator: "dynamic-title"
  # ...
```

## More settings

```yaml
menu-settings:
  name: '&u&lExample Menu'

  # The creator to enable Dynamic Title
  creator: "dynamic-title"

  # How often the title should update in ticks (20 ticks = 1 second)
  title-period: 5

  # The title template
  # The list of title "frames" that will be displayed in order (when the title refreshes)
  title-template:
  - "&u-"
  - "&u--"
  - "&u---"
  - "&u----"
  - "&u-----"
  - "%original%"
  - "&u-----"
  - "&u----"
  - "&u---"
  - "&u--"
  - "&u-"
  - ""
```

{{% notice warning %}}
Sometimes when you close the menu, the menu will not be closed. It's a known (and wont-fix) bug because of how the packet is sent. You may have to set the `title-period` higher to reduce the chance the bug occurs.
{{% /notice %}}

---


## Enchant Keyring

{{% button href="https://github.com/BetterGUI-MC/EnchantKeyring/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/EnchantKeyring/" style="green" icon="download" %}}Download{{% /button %}}

This addon adds an [Item Modifier]({{% ref "modifier/overview" %}}) similar to [Enchantment]({{% ref "modifier/enchantment" %}}) but it uses Minecraft's keys instead of Bukkit's ones. It is useful for those who use custom enchantment plugins and want to add these enchantments to the menu.

## Format

```yaml
enchant-key:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
```

## Note

* The `<enchantment>` use Minecraft's key in the format of `<name>:<key>` (Similar to the enchantment key you use in the `/enchant` command in Vanilla).
* You can set the `[level]` of the `<enchantment>`. It's optional.

## Example

```yaml
enchanted-sword:
  NAME: '&aEnchanted sword'
  LORE:
    - 'This sword is glowing.'
  ID: diamond_sword
  enchant-key:
    - "minecraft:unbreaking, 1"
  POSITION-X: 1
  POSITION-Y: 1
```

---


## Eval Extra

{{% button href="https://github.com/BetterGUI-MC/EvalExtra/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/EvalExtra/" style="green" icon="download" %}}Download{{% /button %}}

## Description
* This is an addon to apply math expressions in some settings of the menu
* With this, you can write advanced math in menu. Especially, this addon is useful to write advanced conditions in [Condition Requirement]({{% ref "requirement/condition" %}})

## Example
```yaml
stone:
  id: stone
  amount: "25 + 3"
```
```yaml
stone:
  id: stone
  amount: "FLOOR(SQRT(18))" # The amount will be the floor value of the square root of 18, which is 4
```
```yaml
test-view-requirement:
  type: predicate
  slot: 1
  button:
    id: exp_bottle
    name: "&cA exp bottle"
    lore:
      - "You will see this icon when the level is higher than 5"
  view-requirement:
    level:
      condition: "{level} > 5" # This will check if the player's level is higher than 5
```

## Operator
* The basic is the use of math operators in the expressions (`+`, `-`, `*`, `/`, etc)
* Examples:
```yaml
amount: "5 + 7" # The amount will be 11
```
```yaml
amount: "{level} % 64 + 1" # The amount will be from 1 to 64, based on the level
```
* Along with math operators, you can also use Boolean operators (`>`, `<`, `=`, `>=`, `<=`, etc) to compare values.
* Example:
```yaml
condition: "{level} > 5" # This will check if the player's level is higher than 5
```
* [Supported Operators](https://github.com/ezylang/EvalEx/tree/2.x#supported-operators)

## Function
* Functions are the process of "input to output", take the input and returns the corresponding output.
* [Functions](https://github.com/ezylang/EvalEx/tree/2.x#supported-functions)
* Example:
```yaml
amount: "FLOOR(SQRT(18))" # The amount will be the floor value of the square root of 18, which is 4
```

### String Functions
* This addon also accepts comparing strings with String Functions
* It includes:
  * `STRCT("this", "is")` check if `is` is in `this` (`this` contains `is`)
  * `STREDW("String", "ing")` check if `String` ends with `ing`
  * `STREQ("str1", "str1")` check if `str1` equals `str1`
  * `STREQIC("str1", "str1")` check if `str1` equals `str1` (case-insensitive)
  * `STRLEN("Hello World")` get the length of `Hello World`
  * `STRMP("String", "String-?")` check if `String` matches the RegExr pattern `String-?`
  * `STRSTW("String", "Str")` check if `String` starts with `Str`

## Skip the Evaluation
* If you want to skip your string from evaluation for some reason, put `[skip-eval]` before your string
  * Example: If you want to skip `1 + 1`, put `[skip-eval]` like this `[skip-eval] 1 + 1`

## Variable

You can evaluate an expression as a variable by using the variable `{eval_<expression>}`

For example:
* `{eval_1 + 2}`
* `{eval_{level} * 100}`
* `{eval_FLOOR(SQRT(18))}`

---


## ExterHeads

{{% button href="https://github.com/BetterGUI-MC/ExterHeads/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/ExterHeads/" style="green" icon="download" %}}Download{{% /button %}}

This addon adds [Item Modifiers]({{% ref "modifier/overview" %}}) to get heads from popular head plugins.

## [Head Database](https://www.spigotmc.org/resources/head-database.14280/)

### Format

```yaml
head-database: <head-id>
head-db: <head-id>
hdb: <head-id>
```

### Example

```yaml
head-item:
  hdb: 1
  name: "&cHead Database"
  lore:
  - ""
  - "&7This is a head item from Head Database"
```

## [TheSilentPro's HeadDB](https://www.spigotmc.org/resources/headdb.84967/)

### Format

```yaml
tsp-head: <head-id>
tsp-head-name: <head-name>
```

### Example

```yaml
head-item:
  tsp-head: 1
  name: "&cHeadDB"
  lore:
  - ""
  - "&7This is a head item from HeadDB"
```

## [zHead](https://www.spigotmc.org/resources/zhead-database-plugin-for-heads.115717/)

### Format

```yaml
zhead: <head-id>
```

### Example

```yaml
head-item:
  zhead: 1
  name: "&czHead"
  lore:
  - ""
  - "&7This is a head item from zHead"
```

## [Skulls](https://www.spigotmc.org/resources/skulls-the-ultimate-head-database.90098/)

### Format

```yaml
skulls: <head-id>
```

### Example

```yaml
head-item:
  skulls: 1
  name: "&cSkulls"
  lore:
  - ""
  - "&7This is a head item from Skulls"
```

---


## Item Gotcha

{{% button href="https://github.com/BetterGUI-MC/ItemGotcha/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/ItemGotcha/" style="green" icon="download" %}}Download{{% /button %}}

## Config.yml
```yaml
stone:
  id: STONE
  amount: 32

advanced_stone:
  id: STONE
  amount: "32"
  name: "&c{player}'s Stone"
  lore:
    - "A dummy Stone"
    - ''
    - "&kYes, it's very dummy and stupid"
```

### Create an item
* The config should be easy if you are familiar with [**Button**]({{% ref "button/overview" %}})
  and, particularly, [**Dummy Button**]({{% ref "button/dummy" %}})
* Yes, you can think of the `config.yml` as a Menu setup, but with [**dummy buttons**]({{% ref "button/dummy" %}})
* Therefore, if you want to make an item, you can set it up in the `config.yml` as how you did in your menu (Name,
  Material, Lore, etc)

## Command
| Command | Permission | Description |
| --- | --- | --- |
| `giveitem <item_name>` | bettergui.items | Give `<item_name>` to the player |

## Action

### Format
* `give: <item>`
* `give: <item>, <amount>`
* `give: <material>, <amount>`

### Description
This action will give the player the `<item>` (specified in the `config.yml`) or
  the [`<material>`](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html) with the `<amount>`

### Example
```yaml
give-stone:
  slot: 1
  id: stone
  name: "&cGive me stone"
  command: "give: stone"

give-advanced-stone:
  slot: 2
  id: stone
  name: "&cGive me advanced stone"
  command: "give: advanced_stone"

give-kits:
  slot: 3
  id: diamond sword
  name: "&cGive kits"
  command:
  - "give: DIAMOND_SWORD"
  - "give: STONE, 10"
```

## Requirement

### Format
```yaml
item: <item>
```
```yaml
item:
  value: <item>
  take: <true/false>
```
```yaml
item: <item>, [amount]
```
```yaml
item:
  value: <item>, [amount]
  take: <true/false>
```

### Description
* This requirement will check if the player has the `<item>` (specified in the `config.yml`) in his inventory
* You can set the `amount` value to specify the amount of `<item>` the requirement should check
* You can set the `take` value (`true` or `false`) to allow/disallow the plugin to take the items of the player alter checking successfully

### Example
```yaml
take-stone:
  slot: 1
  type: predicate
  button:
    id: stone
    name: "&cTake Stone"
  click-requirement:
    left:
      take-one: # Take one stone
        item: "stone"
    right:
      take-ten: # Take ten stone
        item: "stone, 10"
    middle:
      take-multi: # Take 10 stone and 1 cobblestone
        item:
          value:
            - "stone, 10"
            - "cobblestone"
          take: true
    default:
      check-stone: # Check (not take) if the player has 20 stone
        item:
          value:
            - "stone, 20"
          take: false
```

---


## ItemBridge Hook

{{% button href="https://github.com/BetterGUI-MC/ItemBridgeHook" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/ItemBridgeHook/" style="green" icon="download" %}}Download{{% /button %}}

This addons add support for some plugins that generate custom items, through [UniItem](https://github.com/ProjectUnified/UniItem)

{{% notice warning %}}
The item modifier is order-sensitive. You have to set it before other modifiers.
{{% /notice %}}

## Format

All the Item Modifiers to get items from these item plugins are in the format

```yaml
<type>: <id>
```

Where `<type>` is the type of the item plugin, and `<id>` is the id of the item

You can check the available `<type>` here: [Supported Plugins](https://github.com/ProjectUnified/UniItem#supported-plugins)

## Example

### [ItemBridge](https://polymart.org/product/4/)

```yaml
test-itembridge:
  slot: 0
  itembridge: "minecraft:stone"
  name: "&bItemBridge"
```

### [ItemsAdder](https://www.spigotmc.org/resources/73355/)

```yaml
test-itemsadder:
  slot: 0
  ia: "iasurvival:ruby_block"
  name: "&bItemsAdder"
```

### [Oraxen](https://www.spigotmc.org/resources/72448/)

```yaml
test-oraxen:
  slot: 0
  oraxen: "onyx_axe"
  name: "&bOraxen"
```

### [Nexo](https://polymart.org/product/6901/)

```yaml
test-nexo:
  slot: 0
  nexo: "my_item"
  name: "&bNexo"
```

---


## MaskedGUI

{{% button href="https://github.com/BetterGUI-MC/MaskedGUI" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://www.spigotmc.org/resources/maskedgui.107475/" style="green" icon="download" %}}Download{{% /button %}}

This is an addon for your existing menus. It introduces new advanced features to make more complex menus and allows for more possibilities, while keeping the same level of simplicity if you are familiar with **BetterGUI**.

Some possible menus you can make with this addon are:
- [A menu with a welcome animation](https://youtu.be/g6r73BCpMU4)
- [Frame-by-frame animation](https://youtu.be/9cmGYL6BTdY)
- [Progress bar](https://youtu.be/txd07psA3NM)
- [Pagination](https://youtu.be/iajNu8t9JnQ)
- _And more!_

## Get Started

After downloading, follow [this guide]({{% ref "basic/addon" %}}) to install the addon.

To start using the addon in your menu, simply set `menu-type` of `menu-settings` to `masked`.

```yaml
menu-settings:
  menu-type: masked
  name: '&c&lExample Menu'
  rows: 6
  ...
```

---


## Meta Play

{{% button href="https://github.com/BetterGUI-MC/MetaPlay" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/MetaPlay/" style="green" icon="download" %}}Download{{% /button %}}

## Description

This addon adds a new variable to get and set metadata of players. This can be used to store data for the player.

## Variable

* `{meta_<key>}` gets the value from the metadata of the player at the key `<key>`
* `{meta_number_<key>}` gets the value from the metadata of the player at the key `<key>` and converts it to a number

## Action

* `mete(<key>): <value>` sets the value of the metadata of the player at the key `<key>` to `<value>`
* `meta(<key>, number): <value>` sets the value of the metadata of the player at the key `<key>` to `<value>` as a number
* `meta(<key>)` removes the value of the metadata of the player at the key `<key>`

Note: In `<value>` you can use the variable `{value}` to get the previous value of the metadata.

## Example

```yaml
T:
  id: diamond
  name: "&b&lMeta: &f{meta_number_diamond_count}"
  command:
    left: "meta(diamond_count, number): {value} + 1" # Requires EvalExtra to use expressions
    right: "meta(diamond_count): 0"
```

---


## PaperSpec

{{% button href="https://github.com/BetterGUI-MC/PaperSpec/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/PaperSpec/" style="green" icon="download" %}}Download{{% /button %}}

## Description
This addon add functions that only work on [PaperMC](https://papermc.io/) and its forks.

{{% notice warning %}}
Requirement: _Paper 1.19.4 or newer is required for this addon to work._
{{% /notice %}}

## Menu Settings

### Menu Title

Set the `creator` option of the `menu-settings` to be `mini-title`.

Then you can use [MiniMessage formatting](https://docs.adventure.kyori.net/minimessage/index.html) for the inventory title.

```yaml
menu-settings:
  name: '<red><b>A inventory title generated by MiniMessage'

  creator: "mini-title"
  # ...
```

## Item Modifiers

### Skull Modifier

#### Format
```yaml
paper-skull: <skull>
paper-head: <skull>
skull$: <skull>
head$: <skull>
```

#### Description
* This modifier will set the `<skull>` of the item
* `<skull>` accepts a player name or an UUID (unique id)

#### Example
```yaml
skull:
  position-x: 1
  position-y: 1
  name: "&bSkull"
  id: player_head
  paper-skull: "HSGamer"
  # paper-skull: "7acc67dc-8b84-4f8d-b7ad-ec81e758f5a1"

per-player-skull:
  position-x: 2
  position-y: 1
  name: "&bPer Player Skulls"
  id: player_head
  paper-skull: "{player}"
```

### DisplayName & Lore Modifiers

#### Format
```yaml
mini-name: <minimessage formatting text>
mini-lore:
- <minimessage formatting text>
- <minimessage formatting text>
- ...
```

#### Description
You can use [MiniMessage formatting](https://docs.adventure.kyori.net/minimessage/index.html) for the name and lore of your menu items. Just make sure you use the new format above instead of the original `name` and `lore` modifiers.

There are aliases for the modifiers. You can also use:

1. `name$` for the `mini-name` modifier
2. `lore$` for the `mini-lore` modifier

Note that the legacy color codes (`&c`, `&3`) does not work in the new format.

#### Example
```yaml
minimessage:
  position-x: 1
  position-y: 1
  mini-name: "<rainbow>Rainbow Name"
  mini-lore:
    - "<b>Bold text"
    - "<aqua>Simple color!"
    - "<#00ff00>R G B color!"
    - "<gradient:green:blue>Gradient color!"
    - "<transition:#00ff00:#ff0000:0>Transition color!"
    - "<font:myfont:custom_font>Uses a custom font from a resource pack"
    - "<lang:block.minecraft.diamond_block> <- this is a translatable text"
```

### Action

> `<type>`: The type of the component (`json`, `minimessage`, `legacy`)

* `paper-tell(<type>): <text>`: send the component text to the player
* `paper-broadcast(<type>): <text>`: send the component text to all players
* `paper-tell(<type>, bar): <text>`: send the component text as an action bar to the player
* `paper-broadcast(<type>, bar): <text>`: send the component text as an action bar to all players

## [MiniPlaceholders](https://modrinth.com/plugin/miniplaceholders) support

[MiniPlaceholders](https://modrinth.com/plugin/miniplaceholders) is supported in all settings that involve [MiniMessage formatting](https://docs.adventure.kyori.net/minimessage/index.html)

### Example

```yaml
mini-tps:
  position-x: 1
  position-y: 1
  mini-name: "<rainbow>TPS"
  mini-lore:
    - "<white><b>1m: <green><server_tps_1>" # <server_tps_1> is a MiniPlaceholders placeholder
    - "<white><b>5m: <green><server_tps_5>" # <server_tps_5> is a MiniPlaceholders placeholder
```

---


## PlayerPoints Bridge

{{% button href="https://github.com/BetterGUI-MC/PlayerPointsBridge/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/PlayerPointsBridge/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice warning %}}
Depend: [PlayerPoints](https://www.spigotmc.org/resources/playerpoints.80745/)
{{% /notice %}}

## Variable
* `{points}` gets the points the player having

## Action

### Format
* `give-point: <point>`

### Description
This action gives `<point>` to the player

### Example
```yaml
give-point:
  slot: 1
  id: emerald
  name: "&cGive points"
  command: "give-point: 10"
```

## Requirement

### Format
```yaml
point: <value>
```
```yaml
point:
  value: <value>
  take: <true/false>
```

### Description
* This requirement checks if the player has at least `<value>` points
* You can set the `take` value (`true` or `false`) to allow/disallow the plugin to take the points of the player alter checking successfully

### Example
```yaml
check-points:
  slot: 1
  id: emerald
  name: "&cTake Points"
  click-requirement:
    left:
      take-point: # Take 10 points
        point: 10
    right:
      check-point: # Check if the players has 10 points
        point:
          value: 10
          take: false
        success-action: "tell: &a You have enough points"
        fail-action: "tell: &a You don't have enough points"
```

---


## Switch Icon

{{% button href="https://github.com/BetterGUI-MC/SwitchIcon/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/SwitchIcon/" style="green" icon="download" %}}Download{{% /button %}}

## Format
```yaml
button-name:
  type: switch
  child:
    button1:
      <button-settings>
    button2:
      <button-settings>
    button3:
      <button-settings>
    ...
```

## Description
This is a button that changes everytime the user clicks

## Example
```yaml
switch-icon:
  type: switch
  child:
    frame_icon1:
      name: "&cFrame 1"
      id: red_wool
    frame_icon2:
      name: "&aFrame 2"
      id: green_wool
    frame_icon3:
      name: "&bFrame 3"
      id: light_blue_wool
```

---


## TokenManager Bridge

{{% button href="https://github.com/BetterGUI-MC/TokenManagerBridge/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/TokenManagerBridge/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice warning %}}
Depend: [TokenManager](https://www.spigotmc.org/resources/tokenmanager.8610/)
{{% /notice %}}

## Variable
* `{tokens}` gets the tokens the player having

## Action

### Format
* `give-token: <token>`

### Description
This action gives `<token>` to the player

### Example
```yaml
give-token:
  slot: 1
  id: emerald
  name: "&cGive tokens"
  command: "give-token: 10"
```

## Requirement

### Format
```yaml
token: <value>
```
```yaml
token:
  value: <value>
  take: <true/false>
```

### Description
* This requirement checks if the player has at least `<value>` tokens
* You can set the `take` value (`true` or `false`) to allow/disallow the plugin to take the tokens of the player alter checking successfully

### Example
```yaml
check-tokens:
  slot: 1
  id: emerald
  name: "&cTake tokens"
  click-requirement:
    left:
      take-token: # Take 10 tokens
        token: 10
    right:
      check-token: # Check if the players has 10 tokens
        token:
          value: 10
          take: false
        success-action: "tell: &a You have enough tokens"
        fail-action: "tell: &a You don't have enough tokens"
```

---


## Trade Mart

{{% button href="https://github.com/BetterGUI-MC/TradeMart/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/TradeMart/" style="green" icon="download" %}}Download{{% /button %}}

## Description

This is an addon to add Villager-like GUI for item trading.

## Format

```yaml
menu-settings:
  menu-type: trade

  # The actions when the player opens the menu
  open-action:
  - action
  - action
  - action
  ...

  # The actions when the player closes the menu
  close-action:
  - action
  - action
  - action
  ...

  # The requirement before the player can open the menu
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The requirement before the player can close the menu
  close-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The permission required to open the menu
  permission: bettergui.test

  # The command to open the menu
  command:
  - command1
  - command2
  ...

  # The title of the inventory
  title: <name>
  #name: <name>

  # The list of argument processors to process the arguments of the command to open the menu
  argument-processor:
  - <argument-processor>
  - <argument-processor>

trade-name1:
  item1:
    <button-settings>
  item2:
    <button-settings>
  result:
    <button-settings>

trade-name2:
  item1:
    <button-settings>
  item2:
    <button-settings>
  result:
    <button-settings>
...
```

## Note

* `open-action`: the [Action]({{% ref "action/overview" %}}) when the menu is opened.
* `close-action`: the [Action]({{% ref "action/overview" %}}) when the menu is closed.
* `view-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before opening the menu. If it is not met, the menu will not be opened.
* `close-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before closing the menu. If it is not met, the menu will not be closed.
* `argument-processor`: the [Argument Processor]({{% ref "argument" %}}) to handle the arguments of the command to open the menu.

## Trade

```yaml
trade-name:
  item1:
    <button-settings>
  item2:
    <button-settings>
  result:
    <button-settings>
  max-uses: <number>
```

* `item1`: The first item to trade. REQUIRED
* `item2`: The second item to trade. OPTIONAL
* `result`: The result item. REQUIRED
* `max-uses`: The maximum uses of a trade. OPTIONAL

## Example

```yaml
menu-settings:
  menu-type: trade
  title: "&c&lTest Trade"
  command: trade

trade1:
  item:
    id: diamond
  item2:
    id: redstone
  result:
    id: piston

trade2:
  item:
    id: diamond_block
    amount: 64
  result:
    id: paper
    name: "&b&lRich Cerificate"

trade3:
  item:
    id: paper
    name: "&b&lRich Cerificate"
  item2:
    id: emerald
    amount: 64
  result:
    id: paper
    name: "&a&lVillage Cerificate"
    lore:
    - ""
    - "&7Signed by {player}"
```

---


## Vault Bridge

{{% button href="https://github.com/BetterGUI-MC/VaultBridge/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/VaultBridge/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice warning %}}
Depend: [Vault](https://www.spigotmc.org/resources/vault.34315/)
{{% /notice %}}

## Variable
* `{money}` gets the money the player having
* `{money_formatted}` gets the money the player having (formatted)
* `{group}` gets the group the player is currently in

## Action

### Format
* `give-money: <money>`

### Description
This action gives `<money>` to the player

### Example
```yaml
give-money:
  slot: 1
  id: emerald
  name: "&cGive money"
  command: "give-money: 10"
```

## Requirement

### Money

#### Format
```yaml
money: <value>
```
```yaml
money:
  value: <value>
  take: <true/false>
```

#### Description
* This requirement checks if the money the player having is at least `<value>`
* You can set the `take` value (`true` or `false`) to allow/disallow the plugin to take the money of the player alter checking successfully

#### Example
```yaml
check-money:
  slot: 1
  id: emerald
  name: "&cTake money"
  click-requirement:
    left:
      take-money: # Take 10 money
        money: 10
    right:
      check-money: # Check if the players has 10 money
        money:
          value: 10
          take: false
        success-action: "tell: &a You have enough money"
        fail-action: "tell: &a You don't have enough money"
```

### Group

#### Format
```yaml
group: <name>
```

#### Decription
This requirement checks if the player is in the group `<name>`

#### Example
```yaml
check-group:
  slot: 1
  id: stone
  name: "&cStone Group"
  click-requirement:
    default:
      stone-group: # Check if the player is in the "stone" group
        group: stone
        success-action: "tell: &aYou are welcome"
        fail-action: "tell: &cGet out of here"
```

---


## World and Region

{{% button href="https://github.com/BetterGUI-MC/World-And-Region/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/World%20And%20Region/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice warning %}}
Depend: [WorldGuard](https://dev.bukkit.org/projects/worldguard) (for Region & Flag)
{{% /notice %}}

## Variable
* `{region}` gets the name of the region the user standing on
* `{flag_<flag_name>}` gets the status of the flag `<flag_name>` at the region the user standing on

## Requirement

### World

#### Format
```yaml
world: <world_name>
```
```yaml
world:
- <world_name>
- <world_name>
```

#### Description
This requirement checks if the player is at the world `<world_name>`

### Region

#### Format
```yaml
region: <region_name>
```
```yaml
region:
- <region_name>
- <region_name>
```

#### Description
This requirement checks if the player is at the region `<region_name>`

### Region Owner

#### Format
```yaml
region-owner: <region_name>
```
```yaml
region-owner:
- <region_name>
- <region_name>
```

#### Description
This requirement checks if the player is the owner of the region `<region_name>`

### Region User

#### Format
```yaml
region-user: <region_name>
```
```yaml
region-user:
- <region_name>
- <region_name>
```

#### Description
This requirement checks if the player is the user of the region `<region_name>`

### Flag

#### Format
```yaml
flag:
  flag1: <value1>
  flag2: <value2>
  flag3: <value3>
  ...
```

#### Description
This requirement checks if the status of the `flag` at the region the player standing on matches the `value`

---


## XCross

{{% button href="https://github.com/BetterGUI-MC/XCross/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/XCross/" style="green" icon="download" %}}Download{{% /button %}}

## Description
This addon integrates [XSeries](https://github.com/CryptoMorin/XSeries) so that you can use version-independent values in some item modifiers & actions.

## Item Modifier

### Material Modifier

#### Format
```yaml
xmaterial: <material>
xid: <material>
xmat: <material>
```

#### Description
* This modifier will set the `<material>` of the item

#### Example
```yaml
stone-button:
  slot: 1
  xid: stone
```
```yaml
player-head:
  slot: 2
  xid: player_head
```

### Enchantment Modifier

#### Format
```yaml
xenchantment:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
```
```yaml
xenchant:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
```
```yaml
xenc:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
```

#### Description
* This modifier will add the `<enchantment>`s to the item
* You can set the `[level]` of the `<enchantment>`. It's optional.

#### Example
```yaml
enchanted-sword:
  NAME: '&aEnchanted sword'
  LORE:
    - 'This sword is glowing.'
  ID: diamond_sword
  XENCHANTMENT:
    - "durability, 1"
  POSITION-X: 1
  POSITION-Y: 1
```

### Potion Effect Modifier

#### Format
```yaml
xpotion:
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
...
```
```yaml
xeffect:
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
...
```

#### Description
* This modifier will add the `<potion>` effect to the item.
* You can set the `[duration]` and `[amplifier]` of the `<potion>` effect. These are optional.

#### Example
```yaml
potion:
  position-x: 1
  position-y: 1
  name: "&bPotion"
  id: potion
  xpotion:
    - "SPEED"
    - "WEAKNESS, 30, 1"
```

### Skull Modifier

#### Format
```yaml
xskull: <skull>
xhead: <skull>
```

#### Description
* This modifier will set the `<skull>` of the item
* `<skull>` accepts a player name, an UUID (unique id), an Base64 value, or a `texture.minecraft.net` URL

#### Example
```yaml
skull:
  position-x: 1
  position-y: 1
  name: "&bSkull"
  id: player_head
  xskull: "HSGamer"
  #xskull: "7acc67dc-8b84-4f8d-b7ad-ec81e758f5a1"
  #xskull: "http://textures.minecraft.net/texture/ffcdae586b52403b92b1857ee4331bac636af08bab92ba5750a54a83331a6353"
  #xskull: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZmZjZGFlNTg2YjUyNDAzYjkyYjE4NTdlZTQzMzFiYWM2MzZhZjA4YmFiOTJiYTU3NTBhNTRhODMzMzFhNjM1MyJ9fX0="

per-player-skull:
  position-x: 2
  position-y: 1
  name: "&bPer Player Skulls"
  id: player_head
  xskull: "{player}"
```

## Action

### Play Sound

#### Format
* `xsound: <sound>, [volume], [pitch]`
* `xsound: <sound> [volume] [pitch]`

#### Description
* This action will send the `<sound>` to the player
* You can specify the `[volume]` and the `[pitch]` of the `<sound>`. Those are optional

#### Example
* `xsound: BLOCK_NOTE_BLOCK_PLING`
* `xsound: BLOCK_NOTE_BLOCK_PLING 1 2`

---




## Advanced Cooldown

{{% button href="https://github.com/BetterGUI-MC/AdvancedCooldown/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/AdvancedCooldown/" style="green" icon="download" %}}Download{{% /button %}}

## Config.yml
```yaml
# Format:
# <name>: <value>
#
# Example:
# simple-cooldown: 100
simple-cooldown: 100
cooldown-10000: 10000
cooldown-999: 999
```

## Variable
> `<name>` is the cooldown name from the `config.yml`
* `advanced_cooldown_<name>`
* `advanced_cooldown_<name>_s` or `advanced_cooldown_<name>_seconds`
* `advanced_cooldown_<name>_m` or `advanced_cooldown_<name>_minutes`
* `advanced_cooldown_<name>_h` or `advanced_cooldown_<name>_hours`
* `advanced_cooldown_<name>_format_<time-format>`
    * Example Format: `advanced_cooldown_<name>_format_HH:mm:ss`

## Requirement

### Format
```yaml
advanced-cooldown: <name>
```

### Description
* This requirement will check if the player is not in a cooldown timer named `<name>`.
* After checking the requirement, the addon will start the cooldown timer for the player.

### Example
```yaml
advanced-cooldown:
  slot: 1
  id: clock
  name: "&cAdvanced Cooldown"
  command:
    - "tell: &aHello"
  click-requirement:
    left:
      test:
        advanced-cooldown: "simple-cooldown" # from config.yml
      fail-command:
        - "tell: &cYou need to wait {advanced_cooldown_simple-cooldown_s} seconds"
    right:
      test:
        advanced-cooldown: "cooldown-10000" # from config.yml
      fail-command:
        - "tell: &cYou need to wait {advanced_cooldown_cooldown-10000_s} seconds"
    middle:
      test:
        advanced-cooldown: "cooldown-999" # from config.yml
      fail-command:
        - "tell: &cYou need to wait {advanced_cooldown_cooldown-999_s} seconds"
```

## Time Format

| character | duration element |
| --- | --- |
| y | years |
| M | months |
| d | days |
| H | hours |
| m | minutes |
| s | seconds |
| S | milliseconds |

* Example:
    * `HH:mm:ss`: show hours, minutes and seconds
    * `YY:MM:dd HH:mm:ss`: show years, months, days, hours, minutes and seconds
---




---


## Alternative Command Listener

{{% button href="https://github.com/BetterGUI-MC/AlternativeCommandListener/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/AlternativeCommandListener/" style="green" icon="download" %}}Download{{% /button %}}

This addon adds an alternative feature for menu commands to solve the "duplicated command" issue.

## Config.yml

```yaml
# The list of ignored commands
ignored-commands:
- warp test

# Ignore case-sensitive when checking commands
case-insensitive: true

# Should we ignore the commands in ignored-commands
# If set to false, the plugin will do the opposite (override the commands in ignored-commands)
should-ignore: true
```
---




---


## Anvil GUI

{{% button href="https://github.com/BetterGUI-MC/AnvilGUI/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/job/AnvilGUI/" style="green" icon="download" %}}Download{{% /button %}}

## Format
```yaml
# Settings
menu-settings:
  menu-type: anvil

  # The title of the menu
  title: <name>

  # The text to show when the player opens the menu
  text: <text>

  # The commands executed when the player clicks the result slot (the last slot)
  complete-action:
  - action
  - action
  ...

  # The commands executed when closing the menu
  close-action:
  - action
  - action
  ...

  # Whether the addon prevents the player from closing the menu
  prevent-close: <true/false>

  # The commands to open the menu
  command:
  - command1
  - command2
  ...

  # Whether the addon will clear the user's input when completed
  clear-input-on-complete: <true/false>

# Left Button
left-button:
  modifier1: <value1>
  modifier2: <value2>
  modifier3: <value3>
  ...

# Right Button
right-button:
  modifier1: <value1>
  modifier2: <value2>
  modifier3: <value3>
  ...

# Left Button (for simplier menu)
button:
  modifier1: <value1>
  modifier2: <value2>
  modifier3: <value3>
  ...
```

## Description
* This is a special menu type only for getting inputs.
* In this menu type, the addon only apply ONE icon.

## Note
* The `complete-action` and `close-action` use the [Action](../Action.md) value.
* The `left-button`, `right-button` and `button` use the [Button](../Button.md) value.
* The menu will register a [Menu Variable](../Variable.md#menu-variables) named `{anvil_input}` to get the player's input.

## Example
```yaml
menu-settings:
  menu-type: anvil
  command: testanvil
  title: "&cTest Anvil"
  text: "What is your name?"
  clear-input-on-complete: true
  complete-action:
  - "tell: &aHello, {anvil_input}"
  prevent-close: true
  close-action:
  - "tell: &cYou closed the menu"

button:
  id: paper
```
---




---


## ASCII-Placeholders

{{% button href="https://github.com/BetterGUI-MC/ASCII-Placeholders/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/ASCII-Placeholders/" style="green" icon="download" %}}Download{{% /button %}}

## Config.yml
```yaml
# This is the config for all static variables
# Format: {ascii_<name_of_variable>}
# Example: {ascii_<3}, {ascii_*}, {ascii_cross}, e.g.
#
# List of unicode symbols: http://www.fileformat.info/info/unicode/index.htm
<3: \u2764
"*": \u2605
"**": \u2739
"p": \u2022
"v": \u2714
"+": \u25C6
"++": \u2726
"x": \u2588
"/": \u258C
"cross": \u2720
"arrow_right": \u27A1
"arrow_left": \u2B05
"arrow_up": \u2B06
"arrow_down": \u2B07
```

## Variable
* `{ascii_<name>}` gets the value (symbol) from the `config.yml` at the key `<name>`
---




---


## BetterDialogs

{{% button href="https://github.com/BetterGUI-MC/BetterDialogs" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://www.spigotmc.org/resources/betterdialogs.127759/" style="green" icon="download" %}}Download{{% /button %}}

This is an addon for those who want to work with the new **Dialog System**, in **BetterGUI**'s style.

## Requirement

Your server must meet **one** of the following requirements:

- Is a **PaperMC** server in 1.21.7 or higher
- Is a **SpigotMC** server in 1.21.6 or higher (Make sure to use the latest build)
- Have installed [**PacketEvents**](https://www.spigotmc.org/resources/80279/)

### Limitation

- SpigotMC: Does not support Item Body
- PacketEvents: Item Body only displays the material and no components (See [the pull request](https://github.com/retrooper/packetevents/pull/1277))

## Getting Started

- Download the addon
- [Install the addon]({{% ref "basic/addon" %}})
- Start using it!
---



### Menu

## Format

```yaml
menu-settings:
  # The menu type of the dialog
  menu-type: action-dialog

  # The title of the dialog
  title: "Dialog Title"

  # Whether the menu will be closed when the player clicks a button
  can-close-with-action: true

  # The action to perform after the player clicks a button
  after-action: CLOSE

  # The actions when the player opens the dialog
  open-action:
  - action
  - action
  - action

  # The requirement before the player can open the dialog
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The permission required to open the dialog
  permission: bettergui.test

  # The command to open the dialog
  command:
  - command1
  - command2
  ...

  # The list of argument processors to process the arguments of the command to open the dialog
  argument-processor:
    <argument-processor>
    <argument-processor>
```

## Menu Settings

### `menu-type`

The type of the dialog

Available values:
- `confirmation-dialog`: A confirmation dialog with 2 buttons
- `action-dialog`: A dialog with multiple buttons
- `notice-dialog`: A notice dialog with a single button
- `server-links-dialog`: A dialog used to display server link

```yaml
menu-settings:
  menu-type: server-links-dialog
```

```yaml
menu-settings:
  menu-type: confirmation-dialog
```

### `can-close-with-action`

Whether the menu will be closed when the player clicks a button

Available values:
- `true`: The menu will be closed when the player clicks a button
- `false`: The menu will not be closed when the player clicks a button

```yaml
menu-settings:
  menu-type: confirmation-dialog
  can-close-with-action: true
```

### `after-action`

The action to perform after the player clicks a button

Available values:
- `CLOSE`: Close the menu
- `NONE`: Do nothing
- `WAIT_FOR_RESPONSE`: Wait for the server's response

```yaml
menu-settings:
  menu-type: confirmation-dialog
  after-action: CLOSE
```

```yaml
menu-settings:
  menu-type: confirmation-dialog
  after-action: NONE
```

### `columns`

The number of columns in the dialog

Only works when the `menu-type` is `action-dialog` or `server-links-dialog`

```yaml
menu-settings:
  menu-type: action-dialog
  columns: 3
```

### `button-width`

The width of the buttons in the dialog

Only works when the `menu-type` is `server-links-dialog`

```yaml
menu-settings:
  menu-type: server-links-dialog
  button-width: 10
```

## Example

```yaml
menu-settings:
  menu-type: confirmation-dialog
  title: "&c&lTest Dialog for &e&lBetterDialogs"
  command: testconfirmdialog

welcome:
  text: "&7Hello, &e{player}"
  width: 100

text-body:
  text: "&fThis is a demo for for &e&lBetterDialogs"

item:
  type: item
  material: DIAMOND_SWORD
  name: "&e&lDiamond Sword"
  lore:
    - "&7This is a diamond sword."
    - "&7It's very sharp."
    - "&b&lClick to open the dialog."
  enchant:
    - "durability, 1"
  description:
    text: "&7This is a diamond sword. It's very sharp."

name:
  type: input
  label: "&aEnter your name"
  initial: "{player}"

male:
  type: "boolean"
  label: "&6Are you male?"
  on-true: "Male"
  on-false: "Female"

number:
  type: number
  label: "&bChoose a number"
  start: 0
  end: 100
  step: 1
  initial: 50

select:
  type: select
  label: "&cWhat do you prefer?"
  options:
    tea: "&eTea"
    coffee: "&eCoffee"
    water: "&eWater"
  initial: "tea"

yes:
  type: action
  label: "&e&lYes"
  command:
    - "tell: &eName: &f{dialog_name}"
    - "tell: &eGender: &f{dialog_male}"
    - "tell: &eNumber: &f{dialog_number}"
    - "tell: &eSelection: &f{dialog_select:display} &7({dialog_select})"

no:
  type: action
  label: "&c&lNo"
  command: "tell: &cNevermind"
```

![example](example.png)

> [!NOTE]
> The lines below `menu-settings` are called `Component`. Those are the pieces of the body of the dialog.
> Continue to the next section for more information about the dialog components.

---


### Component

Documentation of the various components of a dialog

---


### Adventure Component

For some components that display Text (label, title, etc.), there are variants that can be used for advanced purposes.

This page will provide the possible ways to use the Adventure Component.

## MiniMessage

> Support: PaperMC

You can use MiniMessage to format text in your components by wrapping the key option in either the prefix `mini-` or the postfix `$`. For example:
- `title` will be `mini-title` or `title$`
- `label` will be `mini-label` or `label$`

```yaml
name:
  type: text
  text$: "Hello <rainbow>world</rainbow>, isn't <blue><u><click:open_url:'https://docs.advntr.dev/minimessage'>MiniMessage</click></u></blue> fun?"
```

### MiniPlaceholders

You can use the placeholders provided by MiniPlaceholders to display dynamic information in your components.

```yaml
ping:
  type: text
  text$: "<player_name>: <player_ping>"
```

## JSON

> Support: PaperMC, PacketEvents

You can use JSON to format text in your components by wrapping the key option in either the prefix `json-`. For example:
- `title` will be `json-title`
- `label` will be `json-label`

```yaml
json:
  type: text
  json-text: '["",{"text":"Welcome "},{"text":"to","italic":true},{"text":" BetterDialogs","bold":true,"color":"yellow"}]'
```

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

name:
  type: text
  text$: "Hello <rainbow>world</rainbow>, isn't <blue><u><click:open_url:'https://docs.advntr.dev/minimessage'>MiniMessage</click></u></blue> fun?"

ping:
  type: text
  text$: "<player_name>: <player_ping>"

json:
  type: text
  json-text: '["",{"text":"Welcome "},{"text":"to","italic":true},{"text":" BetterDialogs","bold":true,"color":"yellow"}]'
```

![Example](example.png)

---




### Menu

## Format

```yaml
menu-settings:
  # The menu type of the dialog
  menu-type: action-dialog

  # The title of the dialog
  title: "Dialog Title"

  # Whether the menu will be closed when the player clicks a button
  can-close-with-action: true

  # The action to perform after the player clicks a button
  after-action: CLOSE

  # The actions when the player opens the dialog
  open-action:
  - action
  - action
  - action

  # The requirement before the player can open the dialog
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The permission required to open the dialog
  permission: bettergui.test

  # The command to open the dialog
  command:
  - command1
  - command2
  ...

  # The list of argument processors to process the arguments of the command to open the dialog
  argument-processor:
    <argument-processor>
    <argument-processor>
```

## Menu Settings

### `menu-type`

The type of the dialog

Available values:
- `confirmation-dialog`: A confirmation dialog with 2 buttons
- `action-dialog`: A dialog with multiple buttons
- `notice-dialog`: A notice dialog with a single button
- `server-links-dialog`: A dialog used to display server link

```yaml
menu-settings:
  menu-type: server-links-dialog
```

```yaml
menu-settings:
  menu-type: confirmation-dialog
```

### `can-close-with-action`

Whether the menu will be closed when the player clicks a button

Available values:
- `true`: The menu will be closed when the player clicks a button
- `false`: The menu will not be closed when the player clicks a button

```yaml
menu-settings:
  menu-type: confirmation-dialog
  can-close-with-action: true
```

### `after-action`

The action to perform after the player clicks a button

Available values:
- `CLOSE`: Close the menu
- `NONE`: Do nothing
- `WAIT_FOR_RESPONSE`: Wait for the server's response

```yaml
menu-settings:
  menu-type: confirmation-dialog
  after-action: CLOSE
```

```yaml
menu-settings:
  menu-type: confirmation-dialog
  after-action: NONE
```

### `columns`

The number of columns in the dialog

Only works when the `menu-type` is `action-dialog` or `server-links-dialog`

```yaml
menu-settings:
  menu-type: action-dialog
  columns: 3
```

### `button-width`

The width of the buttons in the dialog

Only works when the `menu-type` is `server-links-dialog`

```yaml
menu-settings:
  menu-type: server-links-dialog
  button-width: 10
```

## Example

```yaml
menu-settings:
  menu-type: confirmation-dialog
  title: "&c&lTest Dialog for &e&lBetterDialogs"
  command: testconfirmdialog

welcome:
  text: "&7Hello, &e{player}"
  width: 100

text-body:
  text: "&fThis is a demo for for &e&lBetterDialogs"

item:
  type: item
  material: DIAMOND_SWORD
  name: "&e&lDiamond Sword"
  lore:
    - "&7This is a diamond sword."
    - "&7It's very sharp."
    - "&b&lClick to open the dialog."
  enchant:
    - "durability, 1"
  description:
    text: "&7This is a diamond sword. It's very sharp."

name:
  type: input
  label: "&aEnter your name"
  initial: "{player}"

male:
  type: "boolean"
  label: "&6Are you male?"
  on-true: "Male"
  on-false: "Female"

number:
  type: number
  label: "&bChoose a number"
  start: 0
  end: 100
  step: 1
  initial: 50

select:
  type: select
  label: "&cWhat do you prefer?"
  options:
    tea: "&eTea"
    coffee: "&eCoffee"
    water: "&eWater"
  initial: "tea"

yes:
  type: action
  label: "&e&lYes"
  command:
    - "tell: &eName: &f{dialog_name}"
    - "tell: &eGender: &f{dialog_male}"
    - "tell: &eNumber: &f{dialog_number}"
    - "tell: &eSelection: &f{dialog_select:display} &7({dialog_select})"

no:
  type: action
  label: "&c&lNo"
  command: "tell: &cNevermind"
```

![example](example.png)

> [!NOTE]
> The lines below `menu-settings` are called `Component`. Those are the pieces of the body of the dialog.
> Continue to the next section for more information about the dialog components.
---




---


### Component

Documentation of the various components of a dialog
---



#### Text

This is a component to display text content.

## Format

```yaml
text-component-name:
  # The type of the component.
  type: text
  # The text to display.
  text: "Hello, world!"
  # The width of the component in pixels.
  # Optional and defaults to 150.
  width: 150
```

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

show-name:
  type: text
  text: "&e&lHello, &b{player}&r!"

show-info:
  type: text
  text: "&e&lWelcome to our server!"
```

![Example](example.png)

---


#### Item

This is a component to display an item in a dialog, with an optional text description.

## Format

```yaml
item-component-name:
  type: item

  # The description of the item
  # Optional. If not provided, the item will not have a description.
  description:
    # The text to display as the description of the item.
    text: "Item description"
    # The width of the description text in pixels.
    width: 150

  # Whether to show decorations
  show-decorations: true

  # Whether to show tooltip when hovering over the item.
  show-tooltip: true

  # The width of the item in pixels.
  width: 150

  # The height of the item in pixels.
  height: 150

  # The Item modifiers
  modifier1: value1
  modifier2: value2
  modifier3: value3
```

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

one-item:
  type: item
  description:
    text: "&bThis is a stone"
    width: 500

  id: stone
  name: "Stone"
  lore:
    - "A simple stone"
    - "Used for building"

item-no-description:
  type: item
  id: cobblestone
  name: "Cobblestone"
  lore:
    - "A simple stone"
    - "Used for building"
```

![Example](example.png)

---


#### Input

This is a component for inputs from the player. It allows the player to interact with the dialog and provide user input so that the dialog can send the information to the server.

The next sections will provide more information about each type of input component.

## Get Input Value

For each input, you can retrieve the value using the `{dialog_<name>}` variable, where `<name>` is the name of the input component.

For example, if you have an dialog with an input component like this:

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

name:
  type: input
  label: "Name"

hello:
  type: action
  command: "tell: &b&lHello, &f&l{dialog_name}"
```

You can retrieve the value of the `name` component using the `{dialog_name}` variable, as shown in the `hello` action.

---


#### Action

This is a button component, one that can be used to perform an action when clicked.

## Common Format

```yaml
action-name:
  # The label of the button
  label: "Click me!"

  # The tooltip of the button
  # If the tooltip is not provided, there will be no tooltip
  tooltip: "This is a tooltip"

  # The width of the button
  # If the width is not provided, it will default to 150
  width: 150
```

## Button Types

### Copy To Clipboard

This button copies the specified text to the clipboard.

#### Format

```yaml
action-name:
  # The type of the button
  type: copy

  # The text to copy to the clipboard
  text: "Hello, world!"
```

#### Example

```yaml
copy-command:
  type: copy
  label: "Click here to copy a command"
  tooltip: "Copy the command to your clipboard"
  text: "/kill {player}"
```

### Open URL

This button will prompt the player to open a URL.

#### Format

```yaml
action-name:
  # The type of the button
  type: url

  # The URL to open
  url: "https://example.com"
```

#### Example

```yaml
open-url:
  type: url
  label: "Click here to open a URL"
  tooltip: "Open a URL in your browser"
  url: "https://bettergui-mc.github.io/Docs/"
```

### Suggest Command

This button will suggest a command to the player.

#### Format

```yaml
action-name:
  # The type of the button
  type: suggest

  # The command to suggest
  command: "/kill {player}"
```

#### Example

```yaml
suggest-command:
  type: suggest
  label: "Click here to suggest a command"
  tooltip: "Suggest a command to your player"
  command: "/kill {player}"
```

### Run Command

This button will control the player to execute a command.

#### Format

```yaml
action-name:
  # The type of the button
  type: run

  # The command to execute
  command: "/kill {player}"
```

#### Example

```yaml
run-command:
  type: run
  label: "Click here to run a command"
  tooltip: "Run a command on your player"
  command: "/kill {player}"
```

### Custom Action

This button will execute custom actions on the server.

#### Format

```yaml
action-name:
  # The type of the button
  type: action

  # The list of actions to execute
  command:
  - action1
  - action2

  # The requirement to check when clicking the button
  click-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
```

Check [Action]({{% ref "action/overview" %}}) for more information about the available actions in `command`.

Check [Requirement]({{% ref "requirement/overview" %}}) for more information about the available requirements in `click-requirement`.

### Example

```yaml
action-custom:
  type: action
  label: "Click here to execute custom actions"
  tooltip: "Execute custom actions on your player"
  command:
  - "tell: &aYou met the requirement"
  - "tell: &aHere is your reward"
  - "console: give {player} diamond 64"
  click-requirement:
    check-level:
      level:
        value: 10
        take: false
      fail-action: "tell: &cYou don't have enough level"
```

## Full Example

```yaml
menu-settings:
  menu-type: action-dialog
  title: "Example Dialog"
  command: exampledialog

copy-command:
  type: copy
  label: "Click here to copy a command"
  text: "/kill {player}"

open-url:
  type: url
  label: "Click here to open a URL"
  tooltip: "Open a URL in your browser"
  url: "https://bettergui-mc.github.io/Docs/"

suggest-command:
  type: suggest
  label: "Click here to suggest a command"
  tooltip: "Suggest a command to your player"
  command: "/kill {player}"

run-command:
  type: run
  label: "Click here to run a command"
  tooltip: "Run a command on your player"
  command: "/kill {player}"

action-custom:
  type: action
  label: "Click here to execute custom actions"
  tooltip: "Execute custom actions on your player"
  command:
    - "tell: &aYou met the requirement"
    - "tell: &aHere is your reward"
    - "console: give {player} diamond 64"
  click-requirement:
    check-level:
      level:
        value: 10
        take: false
      fail-action: "tell: &cYou don't have enough level"
```

![Example](example.png)

---




#### Text

This is a component to display text content.

## Format

```yaml
text-component-name:
  # The type of the component.
  type: text
  # The text to display.
  text: "Hello, world!"
  # The width of the component in pixels.
  # Optional and defaults to 150.
  width: 150
```

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

show-name:
  type: text
  text: "&e&lHello, &b{player}&r!"

show-info:
  type: text
  text: "&e&lWelcome to our server!"
```

![Example](example.png)
---




---


#### Item

This is a component to display an item in a dialog, with an optional text description.

## Format

```yaml
item-component-name:
  type: item

  # The description of the item
  # Optional. If not provided, the item will not have a description.
  description:
    # The text to display as the description of the item.
    text: "Item description"
    # The width of the description text in pixels.
    width: 150

  # Whether to show decorations
  show-decorations: true

  # Whether to show tooltip when hovering over the item.
  show-tooltip: true

  # The width of the item in pixels.
  width: 150

  # The height of the item in pixels.
  height: 150

  # The Item modifiers
  modifier1: value1
  modifier2: value2
  modifier3: value3
```

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

one-item:
  type: item
  description:
    text: "&bThis is a stone"
    width: 500

  id: stone
  name: "Stone"
  lore:
    - "A simple stone"
    - "Used for building"

item-no-description:
  type: item
  id: cobblestone
  name: "Cobblestone"
  lore:
    - "A simple stone"
    - "Used for building"
```

![Example](example.png)
---




---


#### Input

This is a component for inputs from the player. It allows the player to interact with the dialog and provide user input so that the dialog can send the information to the server.

The next sections will provide more information about each type of input component.

## Get Input Value

For each input, you can retrieve the value using the `{dialog_<name>}` variable, where `<name>` is the name of the input component.

For example, if you have an dialog with an input component like this:

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

name:
  type: input
  label: "Name"

hello:
  type: action
  command: "tell: &b&lHello, &f&l{dialog_name}"
```

You can retrieve the value of the `name` component using the `{dialog_name}` variable, as shown in the `hello` action.
---



##### Text

This is an input component that allows players to enter text.

## Format

```yaml
text-input-name:
  # The type of the input component.
  type: input

  # The label of the input component.
  # If not provided, the label will be hidden.
  label: "Text Input"

  # The width of the input component.
  # If not provided, the width will be 200px.
  width: 200

  # The initial value of the input component.
  # If not provided, the initial value will be empty.
  initial: "Hello World"

  # The maximum length of the input component.
  # If not provided, the length will be 32.
  max-length: 32

  # The maximum number of lines the input component can have.
  # Optional.
  max-lines: 5

  # The height of the input component.
  # Optional.
  height: 100
```

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

name:
  type: input
  label: "Name"

hello:
  type: action
  command: "tell: &b&lHello, &f&l{dialog_name}"
```

![Example](example.png)

---


##### Checkbox

This is an input component that allows players to check a box.

## Format

```yaml
checkbox-input-name:
  # The type of the input component
  type: checkbox

  # The label of the input component
  label: Checkbox Label

  # The initial state of the checkbox
  # If not specified, the checkbox will be unchecked by default
  initial: false

  # The value of the checkbox when checked
  # If not specified, the value will be "true"
  on-true: "Checked"

  # The value of the checkbox when unchecked
  # If not specified, the value will be "false"
  on-false: "Unchecked"
```

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

gender:
  type: checkbox
  label: "Are you male?"
  on-true: "Male"
  on-false: "Female"

hello:
  type: action
  command: "tell: &b&lYour gender is &f&l{dialog_gender}"
```

![Example](example.png)

---


##### Slider

This is an input component that allows players to select a value within a specified range using a slider.

## Format

```yaml
slider-input-component:
  # The type of the input component.
  type: slider

  # The label for the input component.
  label: "Slider Label"

  # The format for the label.
  # If not specified, the label will be displayed as is.
  label-format: "options.generic_value"

  # The start value of the slider.
  start: 0

  # The end value of the slider.
  end: 100

  # The step value of the slider.
  # If not specified, the step will be calculated automatically based on the range.
  step: 1

  # The initial value of the slider.
  # If not specified, the initial value will be at the start of the range.
  initial: 50
```

## Value Format

You can define the display format for the slider value when using the variable by following the variable format `{dialog_<variable_name>:<format>}`

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

age:
  type: slider
  label: "Age"
  start: 0
  end: 100
  step: 1
  initial: 18

hello:
  type: action
  command:
    - "tell: &b&lYour age is &f&l{dialog_age}"
    - "tell: &b&lYour age is &f&l{dialog_age:000}"
```

![Example](example.png)

---


##### Select

This is an input component that allows the player to select an option from a list.

## Format

```yaml
select-input-name:
  # The type of the input component.
  type: select

  # The label of the input component.
  # If not specified, the label will be hidden
  label: "Select an option"

  # The width of the input component.
  # If not specified, the width will be 200 pixels.
  width: 200

  # The available options for the input component.
  # Each option is a key-value pair, where the key is the option's value and the value is the option's label.
  options:
    option1: "Option 1"
    option2: "Option 2"
    option3: "Option 3"

  # The key of the initial option for the input component.
  # If not specified, the first option will be selected by default.
  initial: option1
```

## Variable

When you use the `{dialog_<name>}` variable, it will return the key of the selected option.

If you want to get the label of the selected option, you can use the `{dialog_<name>:display}` variable.

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

experience:
  type: select
  label: "&eYour Experience with the game"
  width: 300
  options:
    beginner: "&aBeginner"
    intermediate: "&eIntermediate"
    advanced: "&6Advanced"
    expert: "&cExpert"
  initial: beginner

hello:
  type: action
  command:
    - "tell: &bYour selected experience is &f{dialog_experience}"
    - "tell: &bYour selected experience is &f{dialog_experience:display}"
```

![Example](example.png)

---




##### Text

This is an input component that allows players to enter text.

## Format

```yaml
text-input-name:
  # The type of the input component.
  type: input

  # The label of the input component.
  # If not provided, the label will be hidden.
  label: "Text Input"

  # The width of the input component.
  # If not provided, the width will be 200px.
  width: 200

  # The initial value of the input component.
  # If not provided, the initial value will be empty.
  initial: "Hello World"

  # The maximum length of the input component.
  # If not provided, the length will be 32.
  max-length: 32

  # The maximum number of lines the input component can have.
  # Optional.
  max-lines: 5

  # The height of the input component.
  # Optional.
  height: 100
```

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

name:
  type: input
  label: "Name"

hello:
  type: action
  command: "tell: &b&lHello, &f&l{dialog_name}"
```

![Example](example.png)
---




---


##### Checkbox

This is an input component that allows players to check a box.

## Format

```yaml
checkbox-input-name:
  # The type of the input component
  type: checkbox

  # The label of the input component
  label: Checkbox Label

  # The initial state of the checkbox
  # If not specified, the checkbox will be unchecked by default
  initial: false

  # The value of the checkbox when checked
  # If not specified, the value will be "true"
  on-true: "Checked"

  # The value of the checkbox when unchecked
  # If not specified, the value will be "false"
  on-false: "Unchecked"
```

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

gender:
  type: checkbox
  label: "Are you male?"
  on-true: "Male"
  on-false: "Female"

hello:
  type: action
  command: "tell: &b&lYour gender is &f&l{dialog_gender}"
```

![Example](example.png)
---




---


##### Slider

This is an input component that allows players to select a value within a specified range using a slider.

## Format

```yaml
slider-input-component:
  # The type of the input component.
  type: slider

  # The label for the input component.
  label: "Slider Label"

  # The format for the label.
  # If not specified, the label will be displayed as is.
  label-format: "options.generic_value"

  # The start value of the slider.
  start: 0

  # The end value of the slider.
  end: 100

  # The step value of the slider.
  # If not specified, the step will be calculated automatically based on the range.
  step: 1

  # The initial value of the slider.
  # If not specified, the initial value will be at the start of the range.
  initial: 50
```

## Value Format

You can define the display format for the slider value when using the variable by following the variable format `{dialog_<variable_name>:<format>}`

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

age:
  type: slider
  label: "Age"
  start: 0
  end: 100
  step: 1
  initial: 18

hello:
  type: action
  command:
    - "tell: &b&lYour age is &f&l{dialog_age}"
    - "tell: &b&lYour age is &f&l{dialog_age:000}"
```

![Example](example.png)
---




---


##### Select

This is an input component that allows the player to select an option from a list.

## Format

```yaml
select-input-name:
  # The type of the input component.
  type: select

  # The label of the input component.
  # If not specified, the label will be hidden
  label: "Select an option"

  # The width of the input component.
  # If not specified, the width will be 200 pixels.
  width: 200

  # The available options for the input component.
  # Each option is a key-value pair, where the key is the option's value and the value is the option's label.
  options:
    option1: "Option 1"
    option2: "Option 2"
    option3: "Option 3"

  # The key of the initial option for the input component.
  # If not specified, the first option will be selected by default.
  initial: option1
```

## Variable

When you use the `{dialog_<name>}` variable, it will return the key of the selected option.

If you want to get the label of the selected option, you can use the `{dialog_<name>:display}` variable.

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

experience:
  type: select
  label: "&eYour Experience with the game"
  width: 300
  options:
    beginner: "&aBeginner"
    intermediate: "&eIntermediate"
    advanced: "&6Advanced"
    expert: "&cExpert"
  initial: beginner

hello:
  type: action
  command:
    - "tell: &bYour selected experience is &f{dialog_experience}"
    - "tell: &bYour selected experience is &f{dialog_experience:display}"
```

![Example](example.png)
---




---


#### Action

This is a button component, one that can be used to perform an action when clicked.

## Common Format

```yaml
action-name:
  # The label of the button
  label: "Click me!"

  # The tooltip of the button
  # If the tooltip is not provided, there will be no tooltip
  tooltip: "This is a tooltip"

  # The width of the button
  # If the width is not provided, it will default to 150
  width: 150
```

## Button Types

### Copy To Clipboard

This button copies the specified text to the clipboard.

#### Format

```yaml
action-name:
  # The type of the button
  type: copy

  # The text to copy to the clipboard
  text: "Hello, world!"
```

#### Example

```yaml
copy-command:
  type: copy
  label: "Click here to copy a command"
  tooltip: "Copy the command to your clipboard"
  text: "/kill {player}"
```

### Open URL

This button will prompt the player to open a URL.

#### Format

```yaml
action-name:
  # The type of the button
  type: url

  # The URL to open
  url: "https://example.com"
```

#### Example

```yaml
open-url:
  type: url
  label: "Click here to open a URL"
  tooltip: "Open a URL in your browser"
  url: "https://bettergui-mc.github.io/Docs/"
```

### Suggest Command

This button will suggest a command to the player.

#### Format

```yaml
action-name:
  # The type of the button
  type: suggest

  # The command to suggest
  command: "/kill {player}"
```

#### Example

```yaml
suggest-command:
  type: suggest
  label: "Click here to suggest a command"
  tooltip: "Suggest a command to your player"
  command: "/kill {player}"
```

### Run Command

This button will control the player to execute a command.

#### Format

```yaml
action-name:
  # The type of the button
  type: run

  # The command to execute
  command: "/kill {player}"
```

#### Example

```yaml
run-command:
  type: run
  label: "Click here to run a command"
  tooltip: "Run a command on your player"
  command: "/kill {player}"
```

### Custom Action

This button will execute custom actions on the server.

#### Format

```yaml
action-name:
  # The type of the button
  type: action

  # The list of actions to execute
  command:
  - action1
  - action2

  # The requirement to check when clicking the button
  click-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
```

Check [Action]({{% ref "action/overview" %}}) for more information about the available actions in `command`.

Check [Requirement]({{% ref "requirement/overview" %}}) for more information about the available requirements in `click-requirement`.

### Example

```yaml
action-custom:
  type: action
  label: "Click here to execute custom actions"
  tooltip: "Execute custom actions on your player"
  command:
  - "tell: &aYou met the requirement"
  - "tell: &aHere is your reward"
  - "console: give {player} diamond 64"
  click-requirement:
    check-level:
      level:
        value: 10
        take: false
      fail-action: "tell: &cYou don't have enough level"
```

## Full Example

```yaml
menu-settings:
  menu-type: action-dialog
  title: "Example Dialog"
  command: exampledialog

copy-command:
  type: copy
  label: "Click here to copy a command"
  text: "/kill {player}"

open-url:
  type: url
  label: "Click here to open a URL"
  tooltip: "Open a URL in your browser"
  url: "https://bettergui-mc.github.io/Docs/"

suggest-command:
  type: suggest
  label: "Click here to suggest a command"
  tooltip: "Suggest a command to your player"
  command: "/kill {player}"

run-command:
  type: run
  label: "Click here to run a command"
  tooltip: "Run a command on your player"
  command: "/kill {player}"

action-custom:
  type: action
  label: "Click here to execute custom actions"
  tooltip: "Execute custom actions on your player"
  command:
    - "tell: &aYou met the requirement"
    - "tell: &aHere is your reward"
    - "console: give {player} diamond 64"
  click-requirement:
    check-level:
      level:
        value: 10
        take: false
      fail-action: "tell: &cYou don't have enough level"
```

![Example](example.png)
---




---


### Adventure Component

For some components that display Text (label, title, etc.), there are variants that can be used for advanced purposes.

This page will provide the possible ways to use the Adventure Component.

## MiniMessage

> Support: PaperMC

You can use MiniMessage to format text in your components by wrapping the key option in either the prefix `mini-` or the postfix `$`. For example:
- `title` will be `mini-title` or `title$`
- `label` will be `mini-label` or `label$`

```yaml
name:
  type: text
  text$: "Hello <rainbow>world</rainbow>, isn't <blue><u><click:open_url:'https://docs.advntr.dev/minimessage'>MiniMessage</click></u></blue> fun?"
```

### MiniPlaceholders

You can use the placeholders provided by MiniPlaceholders to display dynamic information in your components.

```yaml
ping:
  type: text
  text$: "<player_name>: <player_ping>"
```

## JSON

> Support: PaperMC, PacketEvents

You can use JSON to format text in your components by wrapping the key option in either the prefix `json-`. For example:
- `title` will be `json-title`
- `label` will be `json-label`

```yaml
json:
  type: text
  json-text: '["",{"text":"Welcome "},{"text":"to","italic":true},{"text":" BetterDialogs","bold":true,"color":"yellow"}]'
```

## Example

```yaml
menu-settings:
  menu-type: notice-dialog
  title: "Example Dialog"
  command: exampledialog

name:
  type: text
  text$: "Hello <rainbow>world</rainbow>, isn't <blue><u><click:open_url:'https://docs.advntr.dev/minimessage'>MiniMessage</click></u></blue> fun?"

ping:
  type: text
  text$: "<player_name>: <player_ping>"

json:
  type: text
  json-text: '["",{"text":"Welcome "},{"text":"to","italic":true},{"text":" BetterDialogs","bold":true,"color":"yellow"}]'
```

![Example](example.png)
---




---


## BetterForms


{{% button href="https://github.com/BetterGUI-MC/BetterForms" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://www.spigotmc.org/resources/betterforms.115565/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice warning %}}
Depend: [Geyser](https://geysermc.org/download#geyser) or [Floodgate](https://geysermc.org/download#floodgate)
{{% /notice %}}

This is an addon for those who want to work with **Bedrock Forms**, in **BetterGUI**'s style.

## Get Started

{{% expand title="For Standalone Server" %}}
You can install just Geyser or both Geyser and Floodgate into your server
{{% /expand %}}

{{% expand title="For Proxied Server (BungeeCord, Velocity, etc.)" %}}
You have to install Floodgate into your backend server so that the addon knows whether a player is playing in Bedrock or Java
{{% /expand %}}

After downloading the addon and the required plugins, follow [this guide]({{% ref "basic/addon" %}}) to install the addon.
---



### Modal Form

This is a simple form with 2 buttons.

## Format

```yaml
menu-settings:
  menu-type: modal-form

  # The title of the form
  title: <name>

  # The content of the form
  content: <content>

  # The actions when the player opens the form
  open-action:
  - action
  - action
  - action
  ...

  # The actions when the player closes the form
  close-action:
  - action
  - action
  - action
  ...

  # The actions when the player does something invalid in the form
  invalid-action:
  - action
  - action
  - action
  ...

  # The actions when the player is not a Bedrock player
  java-action:
  - action
  - action
  - action
  ...

  # The requirement before the player can open the form
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The permission required to open the form
  permission: bettergui.test

  # The command to open the form
  command:
  - command1
  - command2
  ...

  # The list of argument processors to process the arguments of the command to open the form
  argument-processor:
    <argument-processor>
    <argument-processor>

# The first button
button1:
  # The text of the button
  text: <text>

  # The actions when clicking the button
  action:
  - action
  - action
  - action
  ...

  # The requirement to check when clicking the button
  click-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

# The second button
button2:
  # The text of the button
  text: <text>

  # The actions when clicking the button
  action:
  - action
  - action
  - action
  ...

  # The requirement to check when clicking the button
  click-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...
```

## Note

### Menu Settings

* `open-action`: the [Action]({{% ref "action/overview" %}}) when the menu is opened.
* `close-action`: the [Action]({{% ref "action/overview" %}}) when the menu is closed.
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) when the player does something invalid.
* `java-action`: the [Action]({{% ref "action/overview" %}}) when the player is not a Bedrock player.
* `view-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before opening the menu. If it is not met, the menu will not be opened.
* `argument-processor`: the [Argument Processor]({{% ref "argument" %}}) to handle the arguments of the command to open the menu.

### Button

* `action`: the [Action]({{% ref "action/overview" %}}) when the button is clicked.
* `click-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check when the button is clicked. If it is not met, the `action` will not be executed.

## Example

```yaml
menu-settings:
  menu-type: modal-form
  command: modalform
  title: "Modal Form"
  content: "&eAre you beautiful, &f{player} &e?"

  open-action: "tell: &eYou opened the form"
  close-action: "tell: &cYou closed the form"
  java-action: "tell: &cYou can't open this form because you're not a Bedrock player"

yes:
  text: "&b&lYes"
  click-requirement:
    check-level:
      level:
        value: 10
        take: false
      success-action: "tell: &eThanks for paticipating the form"
      fail-action: "tell: &eImprove yourself..."

no:
  text: "&bNo"
  action: "tell: &aIt's fine, you're beautiful as always"
```

![Example 1](example1.png)

---


### Simple Form

This is a form with a list of buttons.

## Format

```yaml
menu-settings:
  menu-type: simple-form

  # The title of the form
  title: <name>

  # The actions when the player opens the form
  open-action:
  - action
  - action
  - action
  ...

  # The actions when the player closes the form
  close-action:
  - action
  - action
  - action
  ...

  # The actions when the player does something invalid in the form
  invalid-action:
  - action
  - action
  - action
  ...

  # The actions when the player is not a Bedrock player
  java-action:
  - action
  - action
  - action
  ...

  # The requirement before the player can open the form
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The permission required to open the form
  permission: bettergui.test

  # The command to open the form
  command:
  - command1
  - command2
  ...

  # The list of argument processors to process the arguments of the command to open the form
  argument-processor:
    <argument-processor>
    <argument-processor>

# The button
button1:
  # The text of the button
  text: <text>

  # The actions when clicking the button
  action:
  - action
  - action
  - action
  ...

  # The requirement to check when clicking the button
  click-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The path to the image
  path: <path>

  # The URL to the image
  url: <url>

button2:
  ...

button3:
  ...
```

## Note

### Menu Settings

* `open-action`: the [Action]({{% ref "action/overview" %}}) when the menu is opened.
* `close-action`: the [Action]({{% ref "action/overview" %}}) when the menu is closed.
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) when the player does something invalid.
* `java-action`: the [Action]({{% ref "action/overview" %}}) when the player is not a Bedrock player.
* `view-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before opening the menu. If it is not met, the menu will not be opened.
* `argument-processor`: the [Argument Processor]({{% ref "argument" %}}) to handle the arguments of the command to open the menu.

### Button

* `action`: the [Action]({{% ref "action/overview" %}}) when the button is clicked.
* `click-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check when the button is clicked. If it is not met, the `action` will not be executed.
* `path`: the path to the image displayed in the button. The `path` is mostly for texture packs
* `url`: the URL to the image displayed in the button.

## Example

```yaml
menu-settings:
  menu-type: simple-form
  command: simpleform
  title: "&4&lInfo Form"

profile:
  text: "&cHSGamer"
  url: "https://raw.githubusercontent.com/HSGamer/hsgamer.github.io/main/static/android-chrome-256x256.png"
  command: "tell: &eLink: &fhttps://hsgamer.me/"

bettergui:
  text: "&cBetterGUI"
  url: "https://raw.githubusercontent.com/BetterGUI-MC/.github/main/images/logo.png"
  command: "tell: &eLink: &fhttps://bettergui-mc.github.io/Docs/"
```

![Example 1](example1.png)

---


### Custom Form

This is a complex form with a list of input components.

## Format

### Menu

```yaml
menu-settings:
  menu-type: custom-form

  # The title of the form
  title: <name>

  # The actions when the player opens the form
  open-action:
  - action
  - action
  - action
  ...

  # The actions when the player closes the form
  close-action:
  - action
  - action
  - action
  ...

  # The actions when the player does something invalid in the form
  invalid-action:
  - action
  - action
  - action
  ...

  # The actions when the player is not a Bedrock player
  java-action:
  - action
  - action
  - action
  ...

  # The requirement before the player can open the form
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The permission required to open the form
  permission: bettergui.test

  # The command to open the form
  command:
  - command1
  - command2
  ...

  # The list of argument processors to process the arguments of the command to open the form
  argument-processor:
    <argument-processor>
    <argument-processor>

# The components
component1:
  <setting>

component2:
  <setting>

component3:
  <setting>
```

### Component

#### Label

```yaml
component:
  type: label

  # The component text
  text: <text>
```

#### Input

```yaml
component:
  type: input

  # The component text
  text: <text>

  # The placeholder when there is no value in the input
  placeholder: <placeholder>

  # The default text
  default: <text>
```

#### Dropdown

```yaml
component:
  type: dropdown

  # The component text
  text: <text>

  # The options
  option:
  - text1
  - text2
  - text3
  ...

  # The index of the option to choose as the default option
  default: <index>
```

#### Slider

```yaml
component:
  type: slider

  # The component text
  text: <text>

  # The minimum value
  min: <value>

  # The maximum value
  max: <value>

  # The step
  step: <value>

  # The default value
  default: <value>
```

#### Step Slider

```yaml
component:
  type: step

  # The component text
  text: <text>

  # The options
  option: 
  - text1
  - text2
  - text3
  ...

  # The index of the option to choose as the default option
  default: <index>
```

#### Switch

```yaml
component:
  type: switch

  # The component text
  text: <text>

  # The default value
  default: <true/false>
```

#### Submit Button

```yaml
button1:
  type: submit

  # The component text
  text: <text>

  # The actions when clicking the button
  action:
  - action
  - action
  - action
  ...

  # The requirement to check when clicking the button
  click-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...
```

## Note

### Menu Settings

* `open-action`: the [Action]({{% ref "action/overview" %}}) when the menu is opened.
* `close-action`: the [Action]({{% ref "action/overview" %}}) when the menu is closed.
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) when the player does something invalid.
* `java-action`: the [Action]({{% ref "action/overview" %}}) when the player is not a Bedrock player.
* `view-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before opening the menu. If it is not met, the menu will not be opened.
* `argument-processor`: the [Argument Processor]({{% ref "argument" %}}) to handle the arguments of the command to open the menu.

### Component

* `action`: the [Action]({{% ref "action/overview" %}}) when the button is clicked.
* `click-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check when the button is clicked. If it is not met, the `action` will not be executed.

### Variable

You can get the value of the component by using the format `{form_<component>}`, where `<component>` is the name of the component in the config. For example, use `{form_username}` to get the value of the component named `username`.

## Example

```yaml
menu-settings:
  menu-type: custom-form
  command: customform
  title: "&4&lRegister Form"

user-label:
  type: label
  text: User Details

username:
  type: input
  text: "Username"
  placeholder: "Your username here..."
  default: "{player}"

password:
  type: input
  text: "Password"
  placeholder: "Yout password here..."

remember:
  type: switch
  text: "Remember"

personal-label:
  type: label
  text: Personal Details

gender:
  type: dropdown
  text: Gender
  option:
  - "Male"
  - "Female"
  - "Other..."
  default: 0

age:
  type: slider
  text: Age
  min: 0
  max: 100
  step: 1
  default: 1

happiness:
  type: step
  text: Happiness
  option:
  - Sad
  - Normal
  - Happy
  - Feeling Lucky
  default: 1

submit:
  type: submit
  action:
  - "tell: &eUsername: &f{form_username}"
  - "tell: &ePassword: &f{form_password}"
  - "tell: &eGender: &f{form_gender}"
  - "tell: &eAge: &f{form_age}"
  - "tell: &eHappiness: &f{form_happiness}"
  click-requirement:
    remember-check:
      condition: "{form_remember}"
      fail-action: "tell: &cYour form is lost..."
```

![Example 1](example1.png)
![Example 2](example2.png)

---


### View Requirement

You can use `view-requirement` to any component so that it will only be shown in the form if the player meets the [Requirement]({{% ref "requirement/overview" %}}).

## Example

```yml
menu-settings:
  menu-type: modal-form
  command: modalform
  title: "Modal Form"
  content: "&eAre you beautiful, &f{player} &e?"

  open-action: "tell: &eYou opened the form"
  close-action: "tell: &cYou closed the form"
  java-action: "tell: &cYou can't open this form because you're not a Bedrock player"

yes:
  text: "&b&lYes"
  click-requirement:
    check-level:
      level:
        value: 10
        take: false
      success-action: "tell: &eThanks for paticipating the form"
      fail-action: "tell: &eImprove yourself..."

no:
  text: "&bNo"
  action: "tell: &aIt's fine, you're beautiful as always"
  view-requirement: # Only show this component if the player meets the following requirement
    check-level: # Check if the level of the player is higher than or equal to 10
      level:
        value: 10
        take: false
```

---




### Modal Form

This is a simple form with 2 buttons.

## Format

```yaml
menu-settings:
  menu-type: modal-form

  # The title of the form
  title: <name>

  # The content of the form
  content: <content>

  # The actions when the player opens the form
  open-action:
  - action
  - action
  - action
  ...

  # The actions when the player closes the form
  close-action:
  - action
  - action
  - action
  ...

  # The actions when the player does something invalid in the form
  invalid-action:
  - action
  - action
  - action
  ...

  # The actions when the player is not a Bedrock player
  java-action:
  - action
  - action
  - action
  ...

  # The requirement before the player can open the form
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The permission required to open the form
  permission: bettergui.test

  # The command to open the form
  command:
  - command1
  - command2
  ...

  # The list of argument processors to process the arguments of the command to open the form
  argument-processor:
    <argument-processor>
    <argument-processor>

# The first button
button1:
  # The text of the button
  text: <text>

  # The actions when clicking the button
  action:
  - action
  - action
  - action
  ...

  # The requirement to check when clicking the button
  click-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

# The second button
button2:
  # The text of the button
  text: <text>

  # The actions when clicking the button
  action:
  - action
  - action
  - action
  ...

  # The requirement to check when clicking the button
  click-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...
```

## Note

### Menu Settings

* `open-action`: the [Action]({{% ref "action/overview" %}}) when the menu is opened.
* `close-action`: the [Action]({{% ref "action/overview" %}}) when the menu is closed.
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) when the player does something invalid.
* `java-action`: the [Action]({{% ref "action/overview" %}}) when the player is not a Bedrock player.
* `view-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before opening the menu. If it is not met, the menu will not be opened.
* `argument-processor`: the [Argument Processor]({{% ref "argument" %}}) to handle the arguments of the command to open the menu.

### Button

* `action`: the [Action]({{% ref "action/overview" %}}) when the button is clicked.
* `click-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check when the button is clicked. If it is not met, the `action` will not be executed.

## Example

```yaml
menu-settings:
  menu-type: modal-form
  command: modalform
  title: "Modal Form"
  content: "&eAre you beautiful, &f{player} &e?"

  open-action: "tell: &eYou opened the form"
  close-action: "tell: &cYou closed the form"
  java-action: "tell: &cYou can't open this form because you're not a Bedrock player"

yes:
  text: "&b&lYes"
  click-requirement:
    check-level:
      level:
        value: 10
        take: false
      success-action: "tell: &eThanks for paticipating the form"
      fail-action: "tell: &eImprove yourself..."

no:
  text: "&bNo"
  action: "tell: &aIt's fine, you're beautiful as always"
```

![Example 1](example1.png)
---




---


### Simple Form

This is a form with a list of buttons.

## Format

```yaml
menu-settings:
  menu-type: simple-form

  # The title of the form
  title: <name>

  # The actions when the player opens the form
  open-action:
  - action
  - action
  - action
  ...

  # The actions when the player closes the form
  close-action:
  - action
  - action
  - action
  ...

  # The actions when the player does something invalid in the form
  invalid-action:
  - action
  - action
  - action
  ...

  # The actions when the player is not a Bedrock player
  java-action:
  - action
  - action
  - action
  ...

  # The requirement before the player can open the form
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The permission required to open the form
  permission: bettergui.test

  # The command to open the form
  command:
  - command1
  - command2
  ...

  # The list of argument processors to process the arguments of the command to open the form
  argument-processor:
    <argument-processor>
    <argument-processor>

# The button
button1:
  # The text of the button
  text: <text>

  # The actions when clicking the button
  action:
  - action
  - action
  - action
  ...

  # The requirement to check when clicking the button
  click-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The path to the image
  path: <path>

  # The URL to the image
  url: <url>

button2:
  ...

button3:
  ...
```

## Note

### Menu Settings

* `open-action`: the [Action]({{% ref "action/overview" %}}) when the menu is opened.
* `close-action`: the [Action]({{% ref "action/overview" %}}) when the menu is closed.
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) when the player does something invalid.
* `java-action`: the [Action]({{% ref "action/overview" %}}) when the player is not a Bedrock player.
* `view-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before opening the menu. If it is not met, the menu will not be opened.
* `argument-processor`: the [Argument Processor]({{% ref "argument" %}}) to handle the arguments of the command to open the menu.

### Button

* `action`: the [Action]({{% ref "action/overview" %}}) when the button is clicked.
* `click-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check when the button is clicked. If it is not met, the `action` will not be executed.
* `path`: the path to the image displayed in the button. The `path` is mostly for texture packs
* `url`: the URL to the image displayed in the button.

## Example

```yaml
menu-settings:
  menu-type: simple-form
  command: simpleform
  title: "&4&lInfo Form"

profile:
  text: "&cHSGamer"
  url: "https://raw.githubusercontent.com/HSGamer/hsgamer.github.io/main/static/android-chrome-256x256.png"
  command: "tell: &eLink: &fhttps://hsgamer.me/"

bettergui:
  text: "&cBetterGUI"
  url: "https://raw.githubusercontent.com/BetterGUI-MC/.github/main/images/logo.png"
  command: "tell: &eLink: &fhttps://bettergui-mc.github.io/Docs/"
```

![Example 1](example1.png)
---




---


### Custom Form

This is a complex form with a list of input components.

## Format

### Menu

```yaml
menu-settings:
  menu-type: custom-form

  # The title of the form
  title: <name>

  # The actions when the player opens the form
  open-action:
  - action
  - action
  - action
  ...

  # The actions when the player closes the form
  close-action:
  - action
  - action
  - action
  ...

  # The actions when the player does something invalid in the form
  invalid-action:
  - action
  - action
  - action
  ...

  # The actions when the player is not a Bedrock player
  java-action:
  - action
  - action
  - action
  ...

  # The requirement before the player can open the form
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The permission required to open the form
  permission: bettergui.test

  # The command to open the form
  command:
  - command1
  - command2
  ...

  # The list of argument processors to process the arguments of the command to open the form
  argument-processor:
    <argument-processor>
    <argument-processor>

# The components
component1:
  <setting>

component2:
  <setting>

component3:
  <setting>
```

### Component

#### Label

```yaml
component:
  type: label

  # The component text
  text: <text>
```

#### Input

```yaml
component:
  type: input

  # The component text
  text: <text>

  # The placeholder when there is no value in the input
  placeholder: <placeholder>

  # The default text
  default: <text>
```

#### Dropdown

```yaml
component:
  type: dropdown

  # The component text
  text: <text>

  # The options
  option:
  - text1
  - text2
  - text3
  ...

  # The index of the option to choose as the default option
  default: <index>
```

#### Slider

```yaml
component:
  type: slider

  # The component text
  text: <text>

  # The minimum value
  min: <value>

  # The maximum value
  max: <value>

  # The step
  step: <value>

  # The default value
  default: <value>
```

#### Step Slider

```yaml
component:
  type: step

  # The component text
  text: <text>

  # The options
  option: 
  - text1
  - text2
  - text3
  ...

  # The index of the option to choose as the default option
  default: <index>
```

#### Switch

```yaml
component:
  type: switch

  # The component text
  text: <text>

  # The default value
  default: <true/false>
```

#### Submit Button

```yaml
button1:
  type: submit

  # The component text
  text: <text>

  # The actions when clicking the button
  action:
  - action
  - action
  - action
  ...

  # The requirement to check when clicking the button
  click-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...
```

## Note

### Menu Settings

* `open-action`: the [Action]({{% ref "action/overview" %}}) when the menu is opened.
* `close-action`: the [Action]({{% ref "action/overview" %}}) when the menu is closed.
* `invalid-action`: the [Action]({{% ref "action/overview" %}}) when the player does something invalid.
* `java-action`: the [Action]({{% ref "action/overview" %}}) when the player is not a Bedrock player.
* `view-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before opening the menu. If it is not met, the menu will not be opened.
* `argument-processor`: the [Argument Processor]({{% ref "argument" %}}) to handle the arguments of the command to open the menu.

### Component

* `action`: the [Action]({{% ref "action/overview" %}}) when the button is clicked.
* `click-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check when the button is clicked. If it is not met, the `action` will not be executed.

### Variable

You can get the value of the component by using the format `{form_<component>}`, where `<component>` is the name of the component in the config. For example, use `{form_username}` to get the value of the component named `username`.

## Example

```yaml
menu-settings:
  menu-type: custom-form
  command: customform
  title: "&4&lRegister Form"

user-label:
  type: label
  text: User Details

username:
  type: input
  text: "Username"
  placeholder: "Your username here..."
  default: "{player}"

password:
  type: input
  text: "Password"
  placeholder: "Yout password here..."

remember:
  type: switch
  text: "Remember"

personal-label:
  type: label
  text: Personal Details

gender:
  type: dropdown
  text: Gender
  option:
  - "Male"
  - "Female"
  - "Other..."
  default: 0

age:
  type: slider
  text: Age
  min: 0
  max: 100
  step: 1
  default: 1

happiness:
  type: step
  text: Happiness
  option:
  - Sad
  - Normal
  - Happy
  - Feeling Lucky
  default: 1

submit:
  type: submit
  action:
  - "tell: &eUsername: &f{form_username}"
  - "tell: &ePassword: &f{form_password}"
  - "tell: &eGender: &f{form_gender}"
  - "tell: &eAge: &f{form_age}"
  - "tell: &eHappiness: &f{form_happiness}"
  click-requirement:
    remember-check:
      condition: "{form_remember}"
      fail-action: "tell: &cYour form is lost..."
```

![Example 1](example1.png)
![Example 2](example2.png)
---




---


### View Requirement

You can use `view-requirement` to any component so that it will only be shown in the form if the player meets the [Requirement]({{% ref "requirement/overview" %}}).

## Example

```yml
menu-settings:
  menu-type: modal-form
  command: modalform
  title: "Modal Form"
  content: "&eAre you beautiful, &f{player} &e?"

  open-action: "tell: &eYou opened the form"
  close-action: "tell: &cYou closed the form"
  java-action: "tell: &cYou can't open this form because you're not a Bedrock player"

yes:
  text: "&b&lYes"
  click-requirement:
    check-level:
      level:
        value: 10
        take: false
      success-action: "tell: &eThanks for paticipating the form"
      fail-action: "tell: &eImprove yourself..."

no:
  text: "&bNo"
  action: "tell: &aIt's fine, you're beautiful as always"
  view-requirement: # Only show this component if the player meets the following requirement
    check-level: # Check if the level of the player is higher than or equal to 10
      level:
        value: 10
        take: false
```
---




---


## Bungee Link

{{% button href="https://github.com/BetterGUI-MC/BungeeLink/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/BungeeLink/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice warning %}}
Depend: [BungeeCord](https://www.spigotmc.org/wiki/bungeecord/), [Velocity](https://papermc.io/software/velocity) or their forks

For [Velocity](https://papermc.io/software/velocity) and its fork, make sure to set `bungee-plugin-message-channel = true` in your `velocity.toml`
{{% /notice %}}

## Action

### Send To Server

#### Format
* `server: <server-name>`

#### Description
This action will send the player to the server `<server-name>`

#### Example
```yaml
send-to-pvp:
  slot: 1
  id: diamond sword
  name: "&c&lPVP"
  lore:
  - "&fGo to PVP Server"
  command: "server: pvp"
```

### Alert

#### Format
* `alert: <message>`

#### Description
This action will send `<message>` to all servers in the network

#### Example
```yaml
ping-everyone:
  slot: 1
  id: paper
  name: "&ePing @everyone"
  command: "alert: &b&l@everyone"
```
---




---


## Converter

{{% button href="https://github.com/BetterGUI-MC/Converter/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/Converter/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice note %}}
This is a work-in-progress. More features will be added soon.
{{% /notice %}}

{{% notice warning %}}
This addon does not guarantee to convert 100% of your menus, because the structure is usually different between menu plugins.

BetterGUI does not have conflict with other menus. Therefore, it's recommended to do a fresh start by making your next menu entirely in BetterGUI, then rework your old menus one-by-one in BetterGUI.
{{% /notice %}}

## Supported plugins

* [ChestCommands](https://dev.bukkit.org/projects/chest-commands)
* [DeluxeMenus](https://www.spigotmc.org/resources/deluxemenus.11734/)

## How to use

0. **Don't delete your old plugin**
1. [Download & Install the addon]({{% ref "basic/addon" %}})
2. Start & Join your server
3. Type `/convertmenu <plugin> [menu]`
  * If you don't set the `[menu]`, the addon will convert all menus from your old menu plugin.
4. The converted files will be in `plugins/BetterGUI/addon/Converter/<plugin>`
---




---


## Dynamic Title

{{% button href="https://github.com/BetterGUI-MC/DynamicTitle/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/DynamicTitle/" style="green" icon="download" %}}Download{{% /button %}}

## Description

This is an addon for your existing menus. This enables updating inventory titles.

## How to use

Set the `creator` option of the `menu-settings` to be `dynamic-title`

```yaml
menu-settings:
  name: '&u&lExample Menu'

  creator: "dynamic-title"
  # ...
```

## More settings

```yaml
menu-settings:
  name: '&u&lExample Menu'

  # The creator to enable Dynamic Title
  creator: "dynamic-title"

  # How often the title should update in ticks (20 ticks = 1 second)
  title-period: 5

  # The title template
  # The list of title "frames" that will be displayed in order (when the title refreshes)
  title-template:
  - "&u-"
  - "&u--"
  - "&u---"
  - "&u----"
  - "&u-----"
  - "%original%"
  - "&u-----"
  - "&u----"
  - "&u---"
  - "&u--"
  - "&u-"
  - ""
```

{{% notice warning %}}
Sometimes when you close the menu, the menu will not be closed. It's a known (and wont-fix) bug because of how the packet is sent. You may have to set the `title-period` higher to reduce the chance the bug occurs.
{{% /notice %}}
---




---


## Enchant Keyring

{{% button href="https://github.com/BetterGUI-MC/EnchantKeyring/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/EnchantKeyring/" style="green" icon="download" %}}Download{{% /button %}}

This addon adds an [Item Modifier]({{% ref "modifier/overview" %}}) similar to [Enchantment]({{% ref "modifier/enchantment" %}}) but it uses Minecraft's keys instead of Bukkit's ones. It is useful for those who use custom enchantment plugins and want to add these enchantments to the menu.

## Format

```yaml
enchant-key:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
```

## Note

* The `<enchantment>` use Minecraft's key in the format of `<name>:<key>` (Similar to the enchantment key you use in the `/enchant` command in Vanilla).
* You can set the `[level]` of the `<enchantment>`. It's optional.

## Example

```yaml
enchanted-sword:
  NAME: '&aEnchanted sword'
  LORE:
    - 'This sword is glowing.'
  ID: diamond_sword
  enchant-key:
    - "minecraft:unbreaking, 1"
  POSITION-X: 1
  POSITION-Y: 1
```
---




---


## Eval Extra

{{% button href="https://github.com/BetterGUI-MC/EvalExtra/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/EvalExtra/" style="green" icon="download" %}}Download{{% /button %}}

## Description
* This is an addon to apply math expressions in some settings of the menu
* With this, you can write advanced math in menu. Especially, this addon is useful to write advanced conditions in [Condition Requirement]({{% ref "requirement/condition" %}})

## Example
```yaml
stone:
  id: stone
  amount: "25 + 3"
```
```yaml
stone:
  id: stone
  amount: "FLOOR(SQRT(18))" # The amount will be the floor value of the square root of 18, which is 4
```
```yaml
test-view-requirement:
  type: predicate
  slot: 1
  button:
    id: exp_bottle
    name: "&cA exp bottle"
    lore:
      - "You will see this icon when the level is higher than 5"
  view-requirement:
    level:
      condition: "{level} > 5" # This will check if the player's level is higher than 5
```

## Operator
* The basic is the use of math operators in the expressions (`+`, `-`, `*`, `/`, etc)
* Examples:
```yaml
amount: "5 + 7" # The amount will be 11
```
```yaml
amount: "{level} % 64 + 1" # The amount will be from 1 to 64, based on the level
```
* Along with math operators, you can also use Boolean operators (`>`, `<`, `=`, `>=`, `<=`, etc) to compare values.
* Example:
```yaml
condition: "{level} > 5" # This will check if the player's level is higher than 5
```
* [Supported Operators](https://github.com/ezylang/EvalEx/tree/2.x#supported-operators)

## Function
* Functions are the process of "input to output", take the input and returns the corresponding output.
* [Functions](https://github.com/ezylang/EvalEx/tree/2.x#supported-functions)
* Example:
```yaml
amount: "FLOOR(SQRT(18))" # The amount will be the floor value of the square root of 18, which is 4
```

### String Functions
* This addon also accepts comparing strings with String Functions
* It includes:
  * `STRCT("this", "is")` check if `is` is in `this` (`this` contains `is`)
  * `STREDW("String", "ing")` check if `String` ends with `ing`
  * `STREQ("str1", "str1")` check if `str1` equals `str1`
  * `STREQIC("str1", "str1")` check if `str1` equals `str1` (case-insensitive)
  * `STRLEN("Hello World")` get the length of `Hello World`
  * `STRMP("String", "String-?")` check if `String` matches the RegExr pattern `String-?`
  * `STRSTW("String", "Str")` check if `String` starts with `Str`

## Skip the Evaluation
* If you want to skip your string from evaluation for some reason, put `[skip-eval]` before your string
  * Example: If you want to skip `1 + 1`, put `[skip-eval]` like this `[skip-eval] 1 + 1`

## Variable

You can evaluate an expression as a variable by using the variable `{eval_<expression>}`

For example:
* `{eval_1 + 2}`
* `{eval_{level} * 100}`
* `{eval_FLOOR(SQRT(18))}`
---




---


## ExterHeads

{{% button href="https://github.com/BetterGUI-MC/ExterHeads/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/ExterHeads/" style="green" icon="download" %}}Download{{% /button %}}

This addon adds [Item Modifiers]({{% ref "modifier/overview" %}}) to get heads from popular head plugins.

## [Head Database](https://www.spigotmc.org/resources/head-database.14280/)

### Format

```yaml
head-database: <head-id>
head-db: <head-id>
hdb: <head-id>
```

### Example

```yaml
head-item:
  hdb: 1
  name: "&cHead Database"
  lore:
  - ""
  - "&7This is a head item from Head Database"
```

## [TheSilentPro's HeadDB](https://www.spigotmc.org/resources/headdb.84967/)

### Format

```yaml
tsp-head: <head-id>
tsp-head-name: <head-name>
```

### Example

```yaml
head-item:
  tsp-head: 1
  name: "&cHeadDB"
  lore:
  - ""
  - "&7This is a head item from HeadDB"
```

## [zHead](https://www.spigotmc.org/resources/zhead-database-plugin-for-heads.115717/)

### Format

```yaml
zhead: <head-id>
```

### Example

```yaml
head-item:
  zhead: 1
  name: "&czHead"
  lore:
  - ""
  - "&7This is a head item from zHead"
```

## [Skulls](https://www.spigotmc.org/resources/skulls-the-ultimate-head-database.90098/)

### Format

```yaml
skulls: <head-id>
```

### Example

```yaml
head-item:
  skulls: 1
  name: "&cSkulls"
  lore:
  - ""
  - "&7This is a head item from Skulls"
```
---




---


## Item Gotcha

{{% button href="https://github.com/BetterGUI-MC/ItemGotcha/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/ItemGotcha/" style="green" icon="download" %}}Download{{% /button %}}

## Config.yml
```yaml
stone:
  id: STONE
  amount: 32

advanced_stone:
  id: STONE
  amount: "32"
  name: "&c{player}'s Stone"
  lore:
    - "A dummy Stone"
    - ''
    - "&kYes, it's very dummy and stupid"
```

### Create an item
* The config should be easy if you are familiar with [**Button**]({{% ref "button/overview" %}})
  and, particularly, [**Dummy Button**]({{% ref "button/dummy" %}})
* Yes, you can think of the `config.yml` as a Menu setup, but with [**dummy buttons**]({{% ref "button/dummy" %}})
* Therefore, if you want to make an item, you can set it up in the `config.yml` as how you did in your menu (Name,
  Material, Lore, etc)

## Command
| Command | Permission | Description |
| --- | --- | --- |
| `giveitem <item_name>` | bettergui.items | Give `<item_name>` to the player |

## Action

### Format
* `give: <item>`
* `give: <item>, <amount>`
* `give: <material>, <amount>`

### Description
This action will give the player the `<item>` (specified in the `config.yml`) or
  the [`<material>`](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html) with the `<amount>`

### Example
```yaml
give-stone:
  slot: 1
  id: stone
  name: "&cGive me stone"
  command: "give: stone"

give-advanced-stone:
  slot: 2
  id: stone
  name: "&cGive me advanced stone"
  command: "give: advanced_stone"

give-kits:
  slot: 3
  id: diamond sword
  name: "&cGive kits"
  command:
  - "give: DIAMOND_SWORD"
  - "give: STONE, 10"
```

## Requirement

### Format
```yaml
item: <item>
```
```yaml
item:
  value: <item>
  take: <true/false>
```
```yaml
item: <item>, [amount]
```
```yaml
item:
  value: <item>, [amount]
  take: <true/false>
```

### Description
* This requirement will check if the player has the `<item>` (specified in the `config.yml`) in his inventory
* You can set the `amount` value to specify the amount of `<item>` the requirement should check
* You can set the `take` value (`true` or `false`) to allow/disallow the plugin to take the items of the player alter checking successfully

### Example
```yaml
take-stone:
  slot: 1
  type: predicate
  button:
    id: stone
    name: "&cTake Stone"
  click-requirement:
    left:
      take-one: # Take one stone
        item: "stone"
    right:
      take-ten: # Take ten stone
        item: "stone, 10"
    middle:
      take-multi: # Take 10 stone and 1 cobblestone
        item:
          value:
            - "stone, 10"
            - "cobblestone"
          take: true
    default:
      check-stone: # Check (not take) if the player has 20 stone
        item:
          value:
            - "stone, 20"
          take: false
```
---




---


## ItemBridge Hook

{{% button href="https://github.com/BetterGUI-MC/ItemBridgeHook" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/ItemBridgeHook/" style="green" icon="download" %}}Download{{% /button %}}

This addons add support for some plugins that generate custom items, through [UniItem](https://github.com/ProjectUnified/UniItem)

{{% notice warning %}}
The item modifier is order-sensitive. You have to set it before other modifiers.
{{% /notice %}}

## Format

All the Item Modifiers to get items from these item plugins are in the format

```yaml
<type>: <id>
```

Where `<type>` is the type of the item plugin, and `<id>` is the id of the item

You can check the available `<type>` here: [Supported Plugins](https://github.com/ProjectUnified/UniItem#supported-plugins)

## Example

### [ItemBridge](https://polymart.org/product/4/)

```yaml
test-itembridge:
  slot: 0
  itembridge: "minecraft:stone"
  name: "&bItemBridge"
```

### [ItemsAdder](https://www.spigotmc.org/resources/73355/)

```yaml
test-itemsadder:
  slot: 0
  ia: "iasurvival:ruby_block"
  name: "&bItemsAdder"
```

### [Oraxen](https://www.spigotmc.org/resources/72448/)

```yaml
test-oraxen:
  slot: 0
  oraxen: "onyx_axe"
  name: "&bOraxen"
```

### [Nexo](https://polymart.org/product/6901/)

```yaml
test-nexo:
  slot: 0
  nexo: "my_item"
  name: "&bNexo"
```
---




---


## MaskedGUI

{{% button href="https://github.com/BetterGUI-MC/MaskedGUI" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://www.spigotmc.org/resources/maskedgui.107475/" style="green" icon="download" %}}Download{{% /button %}}

This is an addon for your existing menus. It introduces new advanced features to make more complex menus and allows for more possibilities, while keeping the same level of simplicity if you are familiar with **BetterGUI**.

Some possible menus you can make with this addon are:
- [A menu with a welcome animation](https://youtu.be/g6r73BCpMU4)
- [Frame-by-frame animation](https://youtu.be/9cmGYL6BTdY)
- [Progress bar](https://youtu.be/txd07psA3NM)
- [Pagination](https://youtu.be/iajNu8t9JnQ)
- _And more!_

## Get Started

After downloading, follow [this guide]({{% ref "basic/addon" %}}) to install the addon.

To start using the addon in your menu, simply set `menu-type` of `menu-settings` to `masked`.

```yaml
menu-settings:
  menu-type: masked
  name: '&c&lExample Menu'
  rows: 6
  ...
```
---



### Slot Grid

Let's extend the concept of [Slot]({{% ref "button/slot" %}}) to add more features to it.

Start with this simple menu

```yaml
menu-settings:
  menu-type: masked
  command: demo
  title: "&c&lDemo"
  rows: 6

demo-slot:
  slot: 0-53
  id: emerald
```

![Slot Demo 1](slot-demo1.png)

You can see that I have set the `slot` to `0-53` which means that the `demo-slot` will be applied to all slots in the menu.

What if I want to use `slot` to specify a grid of slots, like a 3x3 grid in the middle of the menu?

Here is where I'll introduce a new format for `slot` called **Slot Grid**.

```yaml
slot: <x1>-<y1>-<x2>-<y2>
```

`<x1>` and `<y1>` are the coordinates of the top-left corner of the grid.

`<x2>` and `<y2>` are the coordinates of the bottom-right corner of the grid.

For example, I can replicate the previous menu by using `slot: 1-1-9-6`.

```yaml
demo-slot:
  slot: 1-1-9-6
  id: emerald
```

Or I can make a 3x3 grid in the middle of the menu by using `slot: 4-2-6-4`.

```yaml
demo-slot:
  slot: 4-2-6-4
  id: emerald
```

![Slot Demo 2](slot-demo2.png)

Cool, right? But what if I want only the outer border of the grid?

You can put `-o` at the end of the `slot` to specify that you want the outer border of the grid.

```yaml
demo-slot:
  slot: 1-1-9-6-o
  id: emerald
```

![Slot Demo 3](slot-demo3.png)

---


### Dynamic Slot

If you want to control the [Slot]({{% ref "button/slot" %}}) interactively (i.e. use [variables]({{% ref "misc/variable" %}}) in the slot, [add Math to the slot]({{% ref "addon/eval-extra" %}})), you can use `dynamic-slot` instead of the traditional `slot`

## Example

```yaml
level-slot:
  dynamic-slot: "{level} % 9" # Slot depends on the level of the player
  id: red_stained_glass_pane
  name: "&cDynamic Button"
  lore:
    - "&fLevel: {level}"

# Button to give XP
give-xp:
  slot: 9-17
  id:
    - EXPERIENCE_BOTTLE
    - EXP_BOTTLE
  name: "&eGive &f10 XP"
  lore:
    - "&fLevel: {level}"
  click-requirement:
    old-version:
      version: 13 # Check if the server is at 1.13.X
      success-action: "console: xp add {player} 10 points"
      fail-action: "console: xp 10 {player}"
```

![Dynamic Slot Demo 1](dynamic-slot-demo1.gif)

---


### Mask

This is a new component in which you can specify the logic on how the [Buttons]({{% ref "button/overview" %}}) are displayed. This creates new possibilities to make more creative menus from your crazy ideas.

You can use this to make a simple menu

<iframe width="560" height="315" src="https://www.youtube.com/embed/sJhsBfklfOE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

... or a more complex menu

<iframe width="560" height="315" src="https://www.youtube.com/embed/g6r73BCpMU4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

## Built-in

* [Simple Mask]({{% ref "simple" %}})
* [Multi-Slot Mask]({{% ref "multi-slot" %}})
* [Pattern Mask]({{% ref "pattern" %}})
* [Progress Mask]({{% ref "progress" %}})
* [Hybrid Mask]({{% ref "hybrid" %}})
* [Animated Mask]({{% ref "animated" %}})
* [One-Time Animated Mask]({{% ref "one-time-animated" %}})
* [Predicate Mask]({{% ref "predicate" %}})
* [List Mask]({{% ref "list" %}})
* [Button Paginated Mask]({{% ref "button-paginated" %}})
* [Sequence Paginated Mask]({{% ref "sequence-paginated" %}})
* [Mask Paginated Mask]({{% ref "mask-paginated" %}})
* [Template Mask]({{% ref "template" %}})
* [Player List Mask]({{% ref "player-list" %}})
* [Value List Mask]({{% ref "value-list" %}})
* [Key-Value List Mask]({{% ref "key-value-list" %}})
* [Filtered Button Paginated Mask]({{% ref "filtered-button-paginated" %}})

---




### Slot Grid

Let's extend the concept of [Slot]({{% ref "button/slot" %}}) to add more features to it.

Start with this simple menu

```yaml
menu-settings:
  menu-type: masked
  command: demo
  title: "&c&lDemo"
  rows: 6

demo-slot:
  slot: 0-53
  id: emerald
```

![Slot Demo 1](slot-demo1.png)

You can see that I have set the `slot` to `0-53` which means that the `demo-slot` will be applied to all slots in the menu.

What if I want to use `slot` to specify a grid of slots, like a 3x3 grid in the middle of the menu?

Here is where I'll introduce a new format for `slot` called **Slot Grid**.

```yaml
slot: <x1>-<y1>-<x2>-<y2>
```

`<x1>` and `<y1>` are the coordinates of the top-left corner of the grid.

`<x2>` and `<y2>` are the coordinates of the bottom-right corner of the grid.

For example, I can replicate the previous menu by using `slot: 1-1-9-6`.

```yaml
demo-slot:
  slot: 1-1-9-6
  id: emerald
```

Or I can make a 3x3 grid in the middle of the menu by using `slot: 4-2-6-4`.

```yaml
demo-slot:
  slot: 4-2-6-4
  id: emerald
```

![Slot Demo 2](slot-demo2.png)

Cool, right? But what if I want only the outer border of the grid?

You can put `-o` at the end of the `slot` to specify that you want the outer border of the grid.

```yaml
demo-slot:
  slot: 1-1-9-6-o
  id: emerald
```

![Slot Demo 3](slot-demo3.png)
---




---


### Dynamic Slot

If you want to control the [Slot]({{% ref "button/slot" %}}) interactively (i.e. use [variables]({{% ref "misc/variable" %}}) in the slot, [add Math to the slot]({{% ref "addon/eval-extra" %}})), you can use `dynamic-slot` instead of the traditional `slot`

## Example

```yaml
level-slot:
  dynamic-slot: "{level} % 9" # Slot depends on the level of the player
  id: red_stained_glass_pane
  name: "&cDynamic Button"
  lore:
    - "&fLevel: {level}"

# Button to give XP
give-xp:
  slot: 9-17
  id:
    - EXPERIENCE_BOTTLE
    - EXP_BOTTLE
  name: "&eGive &f10 XP"
  lore:
    - "&fLevel: {level}"
  click-requirement:
    old-version:
      version: 13 # Check if the server is at 1.13.X
      success-action: "console: xp add {player} 10 points"
      fail-action: "console: xp 10 {player}"
```

![Dynamic Slot Demo 1](dynamic-slot-demo1.gif)
---




---


### Mask

This is a new component in which you can specify the logic on how the [Buttons]({{% ref "button/overview" %}}) are displayed. This creates new possibilities to make more creative menus from your crazy ideas.

You can use this to make a simple menu

<iframe width="560" height="315" src="https://www.youtube.com/embed/sJhsBfklfOE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

... or a more complex menu

<iframe width="560" height="315" src="https://www.youtube.com/embed/g6r73BCpMU4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

## Built-in

* [Simple Mask]({{% ref "simple" %}})
* [Multi-Slot Mask]({{% ref "multi-slot" %}})
* [Pattern Mask]({{% ref "pattern" %}})
* [Progress Mask]({{% ref "progress" %}})
* [Hybrid Mask]({{% ref "hybrid" %}})
* [Animated Mask]({{% ref "animated" %}})
* [One-Time Animated Mask]({{% ref "one-time-animated" %}})
* [Predicate Mask]({{% ref "predicate" %}})
* [List Mask]({{% ref "list" %}})
* [Button Paginated Mask]({{% ref "button-paginated" %}})
* [Sequence Paginated Mask]({{% ref "sequence-paginated" %}})
* [Mask Paginated Mask]({{% ref "mask-paginated" %}})
* [Template Mask]({{% ref "template" %}})
* [Player List Mask]({{% ref "player-list" %}})
* [Value List Mask]({{% ref "value-list" %}})
* [Key-Value List Mask]({{% ref "key-value-list" %}})
* [Filtered Button Paginated Mask]({{% ref "filtered-button-paginated" %}})
---



#### Simple Mask

This is the default mask if you don't specify any mask. That means that all [Buttons]({{% ref "button/overview" %}}) are Simple Mask by default.

```yaml
multi-slot:
  mask: simple # You can omit this line. It's the default mask.
  slot: 0-8,45,46,47-52
  type: animated
  update: 10
  child:
    frame1:
      name: ' '
      id:
        - black stained glass pane
        - STAINED_GLASS_PANE:15
    frame2:
      name: ' '
      id:
        - gray stained glass pane
        - STAINED_GLASS_PANE:7
    frame3:
      name: ' '
      id:
        - white stained glass pane
        - STAINED_GLASS_PANE
```

---


#### Multi-Slot Mask

It's the same as the [Simple Mask]({{% ref "../simple" %}}) but there is a special feature when you add multiple [Buttons]({{% ref "button/overview" %}}).

## Format

```yaml
mask-name:
  mask: multislot
  slot: <slot>
  child:
    button-name-1:
      <button-settings>
    button-name-2:
      <button-settings>
    ...
```

## Example

```yaml
demo-slot:
  mask: multislot
  slot: 1-1-9-6
  child:
    emerald-button:
      id: emerald
      name: "&a&lEmerald"
```

![MultiSlot 1](multislot-1.png)

```yaml
demo-slot:
  mask: multislot
  slot: 1-1-9-6
  child:
    emerald-button:
      id: emerald
      name: "&a&lEmerald"
    diamond-button:
      id: diamond
      name: "&b&lDiamond"
```

![MultiSlot 2](multislot-2.png)

```yaml
demo-slot:
  mask: multislot
  slot: 1-1-9-6
  child:
    emerald-button:
      id: emerald
      name: "&a&lEmerald"
    diamond-button:
      id: diamond
      name: "&b&lDiamond"
    redstone-button:
      id: redstone
      name: "&c&lRedstone"
```

![MultiSlot 3](multislot-3.png)

You may now understand what is the special feature of this mask. This mask will loop through the [`child` buttons]({{% ref "button/overview" %}}) and display them for each slot in the `slot` section.

---


#### Pattern Mask

It is a mask that allows you to create a pattern of buttons. The [Buttons]({{% ref "button/overview" %}}) are elements that can be used to draw on a grid-like pattern.

## Format

```yaml
mask-name:
  mask: pattern
  pattern:
    - "xxxxxxxxx"
    - "x       x"
    - "x       x"
    - "x       x"
    - "xxxxxxxxx"
  child:
    button-name-1:
      <button-settings>
    button-name-2:
      <button-settings>
    ...
```

## Note

* `pattern`: The pattern that will be drawn. The pattern is a list of strings. Each string represents a row of the pattern. The length of each string must be the same. The character in the string represents the button that will be drawn on that position. The character must be unique.
* The name of each button in the `child` section is the character that is used to draw on the pattern. The character must be unique.

## Example

```yaml
demo-slot:
  mask: pattern
  pattern:
    - "xxxxxxxxx"
    - "x       x"
    - "x       x"
    - "x       x"
    - "x       x"
    - "xxxxxxxxx"
  child:
    x:
      id: emerald
      name: "&a&lEmerald"
```

![Pattern 1](pattern-1.png)

```yaml
demo-slot:
  mask: pattern
  pattern:
    - "xxxxxxxxx"
    - "x       x"
    - "x 1 1 1 x"
    - "x  2 2  x"
    - "x       x"
    - "xxxxxxxxx"
  child:
    x:
      id: black_stained_glass_pane
      name: "&r"
    ' ':
      id: gray_stained_glass_pane
      name: "&r"
    1:
      id: emerald
      name: "&a&lEmerald"
    2:
      id: diamond
      name: "&b&lDiamond"
```

![Pattern 2](pattern-2.png)

---


#### Progress Mask

It is a mask that shows the progress of the player. It is useful for showing the progress of the player in a quest or a game.

## Format

```yaml
mask-name:
  mask: progress
  slot: <slot>
  current: <current-value>
  max: <max-value>
  current-button:
    <button-settings>
  max-button:
    <button-settings>
```

## Note

* `current`: The current value of the progress. It can be a number or a placeholder.
* `max`: The max value of the progress. It can be a number or a placeholder.
* `current-button`: The [Button]({{% ref "button/overview" %}}) that represents the filled part of the progress.
* `max-button`: The [Button]({{% ref "button/overview" %}}) that represents the empty part of the progress.

## Example

```yaml
demo-slot:
  mask: progress
  current: "{level}"
  max: 45
  slot: 1-1-9-5
  current-button:
    id: green_stained_glass_pane
    name: "&a&lCurrent: &e{level}"
  max-button:
    id: red_stained_glass_pane
    name: "&c&lMax: &e45"
```

![Progress 1](progress-1.gif)

Don't worry about the weird last row. I'll explain it later.

---


#### Hybrid Mask

This mask is a combination of multiple masks. It is useful for grouping masks for better organization.

## Format

```yaml
mask-name:
  mask: hybrid
  child:
    mask-1:
      <mask-settings>
    mask-2:
      <mask-settings>
    ...
```

## Example

```yaml
demo-slot:
  mask: hybrid
  child:
    mask-1:
      slot: 1-1-9-5
      id: green_stained_glass_pane
      name: "&a&lMask 1"
    mask-2:
      slot: 1-6-9-6
      id: red_stained_glass_pane
      name: "&c&lMask 2"
```

![Hybrid 1](hybrid-1.gif)

```yaml
demo-slot:
  mask: hybrid
  child:
    progress-level:
      mask: progress
      current: "{level}"
      max: 45
      slot: 1-1-9-5
      current-button:
        id: green_stained_glass_pane
        name: "&a&lCurrent: &e{level}"
      max-button:
        id: red_stained_glass_pane
        name: "&c&lMax: &e45"
    give-xp:
      slot: "1-6-9-6"
      id:
        - EXPERIENCE_BOTTLE
        - EXP_BOTTLE
      name: "&eGive &f10 XP"
      lore:
        - ""
        - "&fLevel: {level}"
      click-requirement:
        old-version:
          version: 13
          success-action: "console: xp add {player} 10 points"
          fail-action: "console: xp 10 {player}"
```

![Hybrid 2](hybrid-2.gif)

To explain what was missed in the example of [Progress Mask]({{% ref "../progress" %}}), the last row is the [Simple Mask]({{% ref "../simple" %}}) that gives the player 10 XP. I used the Hybrid Mask to group the Progress Mask and the Simple Mask together.

---


#### Animated Mask

Similar to [Animated Button]({{% ref "button/animated" %}}), this mask iterates through a list of masks and displays them in a sequence to create an animation.

## Format

```yaml
mask-name:
  mask: animated
  update: <ticks>
  child:
    mask-1:
      <mask-settings>
    mask-2:
      <mask-settings>
    ...
```

## Note

* `update`: The number of ticks between each frame.

## Example

```yaml
demo-slot:
  mask: animated
  update: 5
  child:
    frame1:
      slot: 0-53
      id: red_stained_glass_pane
      name: "&c&lFrame 1"
    frame2:
      slot: 0-53
      id: green_stained_glass_pane
      name: "&a&lFrame 2"
    frame3:
      slot: 0-53
      id: blue_stained_glass_pane
      name: "&9&lFrame 3"
```

![Animated 1](animated-1.gif)

```yaml
demo-slot:
  mask: animated
  update: 5
  child:
    frame1:
      slot: 0-8
      id: black_stained_glass_pane
      name: "&c&lFrame 1"
    frame2:
      slot: 9-17
      id: black_stained_glass_pane
      name: "&c&lFrame 2"
    frame3:
      slot: 18-26
      id: black_stained_glass_pane
      name: "&c&lFrame 3"
    frame4:
      slot: 27-35
      id: black_stained_glass_pane
      name: "&c&lFrame 4"
    frame5:
      slot: 36-44
      id: black_stained_glass_pane
      name: "&c&lFrame 5"
    frame6:
      slot: 45-53
      id: black_stained_glass_pane
      name: "&c&lFrame 6"
```

![Animated 2](animated-2.gif)

```yaml
demo-slot:
  mask: animated
  update: 5
  child:
    frame1:
      slot: 1-1-9-6
      mask: multislot
      child:
        button1:
          id: red_stained_glass_pane
          name: "&r"
        button2:
          id: black_stained_glass_pane
          name: "&r"
    frame2:
      slot: 1-1-9-6
      mask: multislot
      child:
        button1:
          id: black_stained_glass_pane
          name: "&r"
        button2:
          id: red_stained_glass_pane
          name: "&r"
```

![Animated 3](animated-3.gif)

---


#### One-Time Animated Mask

This is a special type of [Animated Mask]({{% ref "../animated" %}}) that only plays once. It will not loop back to the first frame after it reaches the last frame.

## Format

```yaml
mask-name:
  mask: animated
  update: <ticks>
  async: <true/false>
  keep-last: <true/false>
  child:
    mask-1:
      <mask-settings>
    mask-2:
      <mask-settings>
    ...
```

## Note

* `keep-last`: Whether the last frame will be kept after the animation is finished. The default value is `false`.

## Example

```yaml
demo-slot:
  mask: one-time-animated
  update: 5
  child:
    frame1:
      slot: 0-8
      id: black_stained_glass_pane
      name: "&c&lFrame 1"
    frame2:
      slot: 9-17
      id: black_stained_glass_pane
      name: "&c&lFrame 2"
    frame3:
      slot: 18-26
      id: black_stained_glass_pane
      name: "&c&lFrame 3"
    frame4:
      slot: 27-35
      id: black_stained_glass_pane
      name: "&c&lFrame 4"
    frame5:
      slot: 36-44
      id: black_stained_glass_pane
      name: "&c&lFrame 5"
    frame6:
      slot: 45-53
      id: black_stained_glass_pane
      name: "&c&lFrame 6"
```

![One-Time Animated 1](one-time-animated-1.gif)

---


#### Predicate Mask

This is a conditional mask. It will show the mask if the requirement is met. If not, it will show the fallback mask.

## Format

```yaml
mask-name:
  mask: predicate
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...
  check-only-on-creation: <true/false>
  success:
    <mask-settings>
  fallback:
    <mask-settings>
```

## Note

* `success`: The [Mask]({{% ref "./.." %}}) that will be shown if the `view-requirement` is met. If you don't set it, the mask will be empty.
* `fallback`: The [Mask]({{% ref "./.." %}}) that will be shown if the `view-requirement` is not met. If you don't set it, the mask will be empty.
* `view-requirement`: The [Requirement]({{% ref "requirement/overview" %}}) that must be met for the `success` mask to be shown.
* `check-only-on-creation`: If this value is set to `true`, the plugin will only check the `view-requirement` when the player opens the menu.

## Example

```yaml
demo-slot:
  mask: predicate
  view-requirement:
    test-level:
      level:
        value: 10
        take: false
  success:
    mask: pattern
    pattern:
      - "...xxx..."
      - "..x...x.."
      - "..x...x.."
      - "..x...x.."
      - "...xxx..."
    child:
      x:
        id: green_stained_glass_pane
        name: "&a&lSuccess"
  fallback:
    mask: pattern
    pattern:
      - "..x...x.."
      - "...x.x..."
      - "....x...."
      - "...x.x..."
      - "..x...x.."
    child:
      x:
        id: red_stained_glass_pane
        name: "&c&lFail"
```

![Predicate 1](predicate-1.gif)

---


#### List Mask

This is a conditional mask that loops through a list of masks and display a mask if it can be shown.

It can be used with [Predicate Mask]({{% ref "../predicate" %}}) to make more complex checks.

## Format

```yaml
mask-name:
  mask: list
  child:
    mask1:
      <mask-settings>
    mask2:
      <mask-settings>
    ...
```

## Example

```yaml
demo-slot:
  mask: list
  child:
    level-10:
      mask: predicate
      view-requirement:
        test-level:
          level:
            value: 10
            take: false
      success:
        mask: pattern
        pattern:
          - "..x..xxx."
          - ".xx..x.x."
          - "..x..x.x."
          - "..x..x.x."
          - ".xxx.xxx."
        child:
          x:
            id: green_stained_glass_pane
            name: "&a&lYou have reached level 10!"
    level-5:
      mask: predicate
      view-requirement:
        test-level:
          level:
            value: 5
            take: false
      success:
        mask: pattern
        pattern:
          - "...xxx..."
          - "...x....."
          - "...xxx..."
          - ".....x..."
          - "...xxx..."
        child:
          x:
            id: green_stained_glass_pane
            name: "&a&lYou have reached level 5!"
    level-0:
      mask: pattern
      pattern:
        - "...xxx..."
        - "...x.x..."
        - "...x.x..."
        - "...x.x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&c&lFail"
```

![List 1](list-1.gif)

---


#### Button Paginated Mask

This is a mask that allows you to paginate [Buttons]({{% ref "button/overview" %}}). This is useful when you have a lot of buttons and you want to split them into multiple pages.

## Format

```yaml
mask-name:
  mask: button-paginated
  slot: <slot>
  cycle: <true/false>
  signal: <signal>
  child:
    button-1:
      <button-settings>
    button-2:
      <button-settings>
    ...
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Example

```yaml
# The paginated mask
demo-slot:
  mask: button-paginated
  slot: 1-7
  cycle: false
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  child:
    button1:
      id: red_stained_glass_pane
      name: "&c&lButton 1"
    button2:
      id: green_stained_glass_pane
      name: "&a&lButton 2"
    button3:
      id: blue_stained_glass_pane
      name: "&9&lButton 3"
    button4:
      id: yellow_stained_glass_pane
      name: "&e&lButton 4"
    button5:
      id: purple_stained_glass_pane
      name: "&5&lButton 5"
    button6:
      id: orange_stained_glass_pane
      name: "&6&lButton 6"
    button7:
      id: pink_stained_glass_pane
      name: "&d&lButton 7"
    button8:
      id: black_stained_glass_pane
      name: "&0&lButton 8"
    button9:
      id: white_stained_glass_pane
      name: "&f&lButton 9"
    button10:
      id: gray_stained_glass_pane
      name: "&7&lButton 10"
    button11:
      id: light_gray_stained_glass_pane
      name: "&8&lButton 11"

# The button to go to the previous page
previous-button:
  slot: 0
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 8
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page
```

![Button Paginated 1](button-paginated-1.gif)

---


#### Sequence Paginated Mask

This is the same as the [Button Paginated Mask]({{% ref "../button-paginated" %}}). The only difference is that this mask assumes each button as a page, so it will "shift" the buttons to the left or right depending on the page.

## Format

```yaml
mask-name:
  mask: sequence-paginated
  slot: <slot>
  cycle: <true/false>
  signal: <signal>
  child:
    button-1:
      <button-settings>
    button-2:
      <button-settings>
    ...
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Example

```yaml
# The paginated mask
demo-slot:
  mask: sequence-paginated
  slot: 1-7
  cycle: false
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  child:
    button1:
      id: red_stained_glass_pane
      name: "&c&lButton 1"
    button2:
      id: green_stained_glass_pane
      name: "&a&lButton 2"
    button3:
      id: blue_stained_glass_pane
      name: "&9&lButton 3"
    button4:
      id: yellow_stained_glass_pane
      name: "&e&lButton 4"
    button5:
      id: purple_stained_glass_pane
      name: "&5&lButton 5"
    button6:
      id: orange_stained_glass_pane
      name: "&6&lButton 6"
    button7:
      id: pink_stained_glass_pane
      name: "&d&lButton 7"
    button8:
      id: black_stained_glass_pane
      name: "&0&lButton 8"
    button9:
      id: white_stained_glass_pane
      name: "&f&lButton 9"
    button10:
      id: gray_stained_glass_pane
      name: "&7&lButton 10"
    button11:
      id: light_gray_stained_glass_pane
      name: "&8&lButton 11"

# The button to go to the previous page
previous-button:
  slot: 0
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 8
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page
```

![Sequence Paginated 1](sequence-paginated-1.gif)

---


#### Mask Paginated Mask

Unlike [Button Paginated Mask]({{% ref "../button-paginated" %}}), this mask paginates [Masks]({{% ref "./.." %}}) instead of [Buttons]({{% ref "button/overview" %}}).

## Format

```yaml
mask-name:
  mask: mask-paginated
  cycle: <true/false>
  signal: <signal>
  child:
    mask-1:
      <mask-settings>
    mask-2:
      <mask-settings>
    ...
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Example

```yaml
# The paginated mask
demo-slot:
  mask: mask-paginated
  cycle: false
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  child:
    0:
      mask: pattern
      pattern:
        - "...xxx..."
        - "...x.x..."
        - "...x.x..."
        - "...x.x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&c&l0"
    1:
      mask: pattern
      pattern:
        - "....x...."
        - "...xx...."
        - "....x...."
        - "....x...."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&a&l1"
    2:
      mask: pattern
      pattern:
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
        - "...x....."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&b&l2"
    3:
      mask: pattern
      pattern:
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&d&l3"
    4:
      mask: pattern
      pattern:
        - "...x.x..."
        - "...x.x..."
        - "...xxx..."
        - ".....x..."
        - ".....x..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&e&l4"
    5:
      mask: pattern
      pattern:
        - "...xxx..."
        - "...x....."
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&f&l5"

# The button to go to the previous page
previous-button:
  slot: 18
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 26
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page
```

![Mask Paginated](mask-paginated-1.gif)

---


#### Template Mask

While you are creating menus with masks, you may find yourself repeating the same mask settings over and over again. This is where the template mask comes in handy. It allows you to create a template mask and use it in other masks.

## Format

```yaml
mask-name:
  mask: template
  template: <name> # The name from template folder
  variable:
    <variable1>: <value1>
    <variable2>: <value2>
    ...
  <mask-settings>
```

## Template Folder

The template folder (located at `plugins/BetterGUI/addon/MaskedGUI/template`) is a folder containing `yml` files defining common masks to use in all menus. That means you can create a template mask by simply creating a `yml` file in the template folder, add the common mask settings, and use it in other masks.

## Note

* `variable`: The variable is a way to pass values to the template mask. Check out [Use `variable` option]({{% ref "button/template" %}}#use-variable-option) for more information.

## Example

```yaml
# Template File
test-pattern:
  mask: pattern
  button:
    "*":
      id: purple_stained_glass_pane
      name: "&b&lBody"
    "x":
      id: red_stained_glass_pane
      name: "&c&lTarget"
    "#":
      id: pink_stained_glass_pane
      name: "&a&lHead"
```

```yaml
demo-slot:
  mask: animated
  update: 3
  child:
    1:
      mask: template
      template: test-pattern
      pattern:
      - "......x.."
      - "........."
      - "........."
    2:
      mask: template
      template: test-pattern
      pattern:
      - "......x.."
      - "........."
      - "#........"
    3:
      mask: template
      template: test-pattern
      pattern:
      - "......x.."
      - "........."
      - "*#......."
    4:
      mask: template
      template: test-pattern
      pattern:
      - "......x.."
      - "........."
      - "**#......"
    5:
      mask: template
      template: test-pattern
      pattern:
      - "......x.."
      - "..#......"
      - "***......"
    6:
      mask: template
      template: test-pattern
      pattern:
      - "..#...x.."
      - "..*......"
      - ".**......"
    7:
      mask: template
      template: test-pattern
      pattern:
      - "..*#..x.."
      - "..*......"
      - "..*......"
    8:
      mask: template
      template: test-pattern
      pattern:
      - "..**#.x.."
      - "..*......"
      - "........."
    9:
      mask: template
      template: test-pattern
      pattern:
      - "..***#x.."
      - "........."
      - "........."
    10:
      mask: template
      template: test-pattern
      pattern:
      - "..****#.."
      - "........."
      - "........."
    11:
      mask: template
      template: test-pattern
      pattern:
      - "...****.."
      - "......#.."
      - "........."
    12:
      mask: template
      template: test-pattern
      pattern:
      - "....***.."
      - "......*.."
      - "......#.."
    13:
      mask: template
      template: test-pattern
      pattern:
      - ".....**.."
      - "......*.."
      - "......*#."
    14:
      mask: template
      template: test-pattern
      pattern:
      - "......*.."
      - "......*.."
      - "......**#"
    15:
      mask: template
      template: test-pattern
      pattern:
      - "........."
      - "......*.."
      - "......***"
    16:
      mask: template
      template: test-pattern
      pattern:
      - "........."
      - "........."
      - "......***"
    17:
      mask: template
      template: test-pattern
      pattern:
      - "........."
      - "........."
      - ".......**"
    18:
      mask: template
      template: test-pattern
      pattern:
      - "........."
      - "........."
      - "........*"
    19:
      mask: template
      template: test-pattern
      pattern:
      - "........."
      - "........."
      - "........."
```

![Template 1](template-1.gif)

---


#### Switch Mask

This mask allows you to store a list of masks. Then you can make it switch to a specific mask from that list.

## Format

```yaml
mask-name:
  mask: hybrid
  signal: <signal>
  default: <mask-name>
  child:
    mask-1:
      <mask-settings>
    mask-2:
      <mask-settings>
    ...
```

## Note

* `signal`: The signal name used by actions to switch the mask.
* `default`: The name of the mask from the `child` section used as a default mask. If it's not set, the default mask will be empty.

## Action

* `set-mask(<signal>): <mask>`: Switch the mask to `<mask>`

## Example

```yaml
demo-slot:
  mask: switch
  signal: demo-page-signal # This is the signal name used by actions to switch the mask.
  default: 0 # The default mask name
  child:
    0:
      mask: pattern
      pattern:
        - "...xxx..."
        - "...x.x..."
        - "...x.x..."
        - "...x.x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&c&l0"
    1:
      mask: pattern
      pattern:
        - "....x...."
        - "...xx...."
        - "....x...."
        - "....x...."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&a&l1"
    2:
      mask: pattern
      pattern:
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
        - "...x....."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&b&l2"
    3:
      mask: pattern
      pattern:
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&d&l3"
    4:
      mask: pattern
      pattern:
        - "...x.x..."
        - "...x.x..."
        - "...xxx..."
        - ".....x..."
        - ".....x..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&e&l4"
    5:
      mask: pattern
      pattern:
        - "...xxx..."
        - "...x....."
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&f&l5"

button-1:
  slot: 47
  name: "&e&l1"
  id: arrow
  command: "set-mask(demo-page-signal): 1"

button-2:
  slot: 48
  name: "&e&l2"
  id: arrow
  command: "set-mask(demo-page-signal): 2"

button-3:
  slot: 49
  name: "&e&l3"
  id: arrow
  command: "set-mask(demo-page-signal): 3"

button-4:
  slot: 50
  name: "&e&l4"
  id: arrow
  command: "set-mask(demo-page-signal): 4"

button-5:
  slot: 51
  name: "&e&l5"
  id: arrow
  command: "set-mask(demo-page-signal): 5"
```

![Switch 1](switch-1.gif)

---


#### Player List Mask

This mask is similar to [Button Paginated Mask]({{% ref "../button-paginated" %}}). The only difference is that this mask will fetch all online players and display each of them as a [Button]({{% ref "button/overview" %}}).

## Format

```yaml
mask-name:
  mask: player-list
  slot: <slot>
  cycle: <true/false>
  signal: <signal>
  view-self: <true/false>
  view-offline: <true/false>
  player-update: 20
  viewer-update: 0
  player-condition:
  - condition1
  - condition2
  - condition3
  viewer-condition:
  - condition1
  - condition2
  - condition3
  button:
    <button-settings>
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.
* `view-self`: Whether the mask will display the player that opens then menu.
* `view-offline`: Whether the mask will display all offline players instead of just online ones.
* `player-condition`: The list of [Condition Requirement]({{% ref "requirement/condition" %}}) that the player must meet to appear in the list.
* `viewer-condition`: The list of [Condition Requirement]({{% ref "requirement/condition" %}}) that the viewer must meet to see the player's button.
* The difference between `player-condition` and `viewer-condition` is that the `player-condition` will be checked for each online players to gather the list of "passed" players to display in the menu, while `viewer-condition` will be checked between the viewer (who opens the menu) and the player in the "passed" players to determine if the viewer can see the player in the menu.
* `button`: The [Button]({{% ref "button/overview" %}}) to be displayed for each players.
* `player-update`: The ticks to wait before the player list is refreshed.
* `viewer-update`: The ticks to wait before the "passed" player list from the viewer view is refreshed.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Player Variable

* It's possible to define variables for each players in the list in `player-condition` and `button`
* To do that, the mask introduces 2 new variables:
  * `{current_player_<variable_name>}` to fetch the variable `<variable_name>` of the target player
    * Example:
      * `{player}` -> `{current_player}`
      * `{ping}` -> `{current_player_ping}`
      * `{exp_to_level}` -> `{current_player_exp_to_level}`
  * `{current_player_papi_<placeholder_name>}` to fetch the PlaceholderAPI's placeholder `<placeholder_name>` of the target player

## Example

```yaml
demo-slot:
  mask: player-list
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  slot: 2-1-8-1
  view-self: true
  button:
    id: player_head
    skull: "{current_player}"
    name: "&c{current_player}"
    lore:
    - "&eX: &f{current_player_x}"
    - "&eY: &f{current_player_y}"
    - "&eZ: &f{current_player_z}"
    command: "console: tp {player} {current_player}"
    close-on-click: true

# The button to go to the previous page
previous-button:
  slot: 0
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 8
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page
```

![Player List 1](player-list-1.gif)

---


#### Value List Mask

This mask is similar to [Button Paginated Mask]({{% ref "../button-paginated" %}}), but you can specify a list of values and display each of them as a [Button]({{% ref "button/overview" %}}).

## Format

```yaml
mask-name:
  mask: value-list
  slot: <slot>
  cycle: <true/false>
  signal: <signal>
  value-update: 20
  viewer-update: 0
  viewer-condition:
  - condition1
  - condition2
  - condition3
  value:
  - value1
  - value2
  - value3
  button:
    <button-settings>
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.
* `viewer-condition`: The list of [Condition Requirement]({{% ref "requirement/condition" %}}) that the viewer must meet to see the button.
* `value`: The list of values
* `button`: The [Button]({{% ref "button/overview" %}}) to be displayed for each values.
* `value-update`: The ticks to wait before the value list is refreshed.
* `viewer-update`: The ticks to wait before the "passed" value list from the viewer view is refreshed.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Variable

* On `button`, you can get the current value from the `value` list by using the variable `{current_value}`

## Example

```yaml
# The paginated mask
demo-slot:
  mask: value-list
  slot: 1-7
  cycle: false
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  value:
  - red_stained_glass_pane
  - green_stained_glass_pane
  - blue_stained_glass_pane
  - yellow_stained_glass_pane
  - purple_stained_glass_pane
  - orange_stained_glass_pane
  - pink_stained_glass_pane
  - black_stained_glass_pane
  - white_stained_glass_pane
  - gray_stained_glass_pane
  - light_gray_stained_glass_pane
  button:
    id: "{current_value}"
    name: "&c&lButton"

# The button to go to the previous page
previous-button:
  slot: 0
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 8
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page
```

![Value List 1](value-list-1.gif)

---


#### Key-Value List Mask

This mask is similar to [Button Paginated Mask]({{% ref "../button-paginated" %}}), but you can specify a list of map-like values and display each of them as a [Button]({{% ref "button/overview" %}}).

## Format

```yaml
mask-name:
  mask: key-value-list
  slot: <slot>
  cycle: <true/false>
  signal: <signal>
  value-update: 20
  viewer-update: 0
  viewer-condition:
  - condition1
  - condition2
  - condition3
  value:
  - key1: value1
    key2: value2
    key3: value3
  - key1: value11
    key2: value12
    key3: value13
  - key1: value21
    key2: value22
    key3: value23
  button:
    <button-settings>
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.
* `viewer-condition`: The list of [Condition Requirement]({{% ref "requirement/condition" %}}) that the viewer must meet to see the button.
* `value`: The list of map-like values
* `button`: The [Button]({{% ref "button/overview" %}}) to be displayed for each values.
* `value-update`: The ticks to wait before the value list is refreshed.
* `viewer-update`: The ticks to wait before the "passed" value list from the viewer view is refreshed.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Variable

* On `button`, you can use a key to get the value from the `value` list by using the variable `{key_<name>}`
* For examples: With this `value` list
```yaml
value:
- material: red_stained_glass_pane
  name: "Button 1"
- material: green_stained_glass_pane
  name: "Button 2"
```
  * You can use `{key_material}` to get the `material` part of the value
  * You can use `{key_name}` to get the `name` part of the value

## Example

```yaml
# The paginated mask
demo-slot:
  mask: key-value-list
  slot: 1-7
  cycle: false
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  value:
  - material: red_stained_glass_pane
    name: Button 1
  - material: green_stained_glass_pane
    name: Button 2
  - material: blue_stained_glass_pane
    name: Button 3
  - material: yellow_stained_glass_pane
    name: Button 4
  - material: purple_stained_glass_pane
    name: Button 5
  - material: orange_stained_glass_pane
    name: Button 6
  - material: pink_stained_glass_pane
    name: Button 7
  - material: black_stained_glass_pane
    name: Button 8
  - material: white_stained_glass_pane
    name: Button 9
  - material: gray_stained_glass_pane
    name: Button 10
  - material: light_gray_stained_glass_pane
    name: Button 11
  button:
    id: "{key_material}"
    name: "&c&l{key_name}"

# The button to go to the previous page
previous-button:
  slot: 0
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 8
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page
```

![Key Value List 1](key-value-list-1.gif)

---


#### Filtered Button Paginated Mask

This mask is similar to [Button Paginated Mask]({{% ref "../button-paginated" %}}), but you can filter out the buttons with specific requirements.

## Format

```yaml
mask-name:
  mask: filtered-button-paginated
  slot: <slot>
  cycle: <true/false>
  signal: <signal>
  update: 20
  child:
    button-1:
      <button-settings>
      filter-requirement:
        <requirement-set>
        <requirement-set>
        <requirement-set>
        ...

    button-2:
      <button-settings>
      filter-requirement:
        <requirement-set>
        <requirement-set>
        <requirement-set>
        ...

    button-3:
      <button-settings>
      filter-requirement:
        <requirement-set>
        <requirement-set>
        <requirement-set>
        ...
    ...
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.
* `update`: The ticks to wait before the mask is refreshed.
* You can use `filter-requirement` on the button to remove it from the list if the player doesn't meet the requirements.
  * It's similar to `view-requirement`, but the difference is that, while buttons with `view-requirement` will leave an empty button on the list, those with `filter-requirement` will be removed from the list if the player doesn't meet the requirements.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Example

```yaml
# The paginated mask
demo-slot:
  mask: filtered-button-paginated
  slot: 1-7
  cycle: false
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  child:
    button1:
      id: red_stained_glass_pane
      name: "&c&lButton 1"
      filter-requirement:
        test-level:
          level:
            value: 1
            take: false
    button2:
      id: green_stained_glass_pane
      name: "&a&lButton 2"
      filter-requirement:
        test-level:
          level:
            value: 2
            take: false
    button3:
      id: blue_stained_glass_pane
      name: "&9&lButton 3"
      filter-requirement:
        test-level:
          level:
            value: 4
            take: false
    button4:
      id: yellow_stained_glass_pane
      name: "&e&lButton 4"
      filter-requirement:
        test-level:
          level:
            value: 5
            take: false
    button5:
      id: purple_stained_glass_pane
      name: "&5&lButton 5"
      filter-requirement:
        test-level:
          level:
            value: 6
            take: false
    button6:
      id: orange_stained_glass_pane
      name: "&6&lButton 6"
      filter-requirement:
        test-level:
          level:
            value: 10
            take: false
    button7:
      id: pink_stained_glass_pane
      name: "&d&lButton 7"
      filter-requirement:
        test-level:
          level:
            value: 11
            take: false
    button8:
      id: black_stained_glass_pane
      name: "&0&lButton 8"
      filter-requirement:
        test-level:
          level:
            value: 11
            take: false
    button9:
      id: white_stained_glass_pane
      name: "&f&lButton 9"
      filter-requirement:
        test-level:
          level:
            value: 11
            take: false
    button10:
      id: gray_stained_glass_pane
      name: "&7&lButton 10"
      filter-requirement:
        test-level:
          level:
            value: 12
            take: false
    button11:
      id: light_gray_stained_glass_pane
      name: "&8&lButton 11"
      filter-requirement:
        test-level:
          level:
            value: 12
            take: false

# The button to go to the previous page
previous-button:
  slot: 0
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 8
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page

# Button to give XP
give-xp:
  slot: 9-17
  id:
    - EXPERIENCE_BOTTLE
    - EXP_BOTTLE
  name: "&eGive &f10 XP"
  lore:
    - ""
    - "&fLevel: {level}"
  click-requirement:
    old-version:
      version: 13 # Check if the server is at 1.13.X
      success-action: "console: xp add {player} 10 points"
      fail-action: "console: xp 10 {player}"
```

![Filtered Button Paginated 1](filtered-button-paginated-1.gif)

---




#### Simple Mask

This is the default mask if you don't specify any mask. That means that all [Buttons]({{% ref "button/overview" %}}) are Simple Mask by default.

```yaml
multi-slot:
  mask: simple # You can omit this line. It's the default mask.
  slot: 0-8,45,46,47-52
  type: animated
  update: 10
  child:
    frame1:
      name: ' '
      id:
        - black stained glass pane
        - STAINED_GLASS_PANE:15
    frame2:
      name: ' '
      id:
        - gray stained glass pane
        - STAINED_GLASS_PANE:7
    frame3:
      name: ' '
      id:
        - white stained glass pane
        - STAINED_GLASS_PANE
```
---




---


#### Multi-Slot Mask

It's the same as the [Simple Mask]({{% ref "../simple" %}}) but there is a special feature when you add multiple [Buttons]({{% ref "button/overview" %}}).

## Format

```yaml
mask-name:
  mask: multislot
  slot: <slot>
  child:
    button-name-1:
      <button-settings>
    button-name-2:
      <button-settings>
    ...
```

## Example

```yaml
demo-slot:
  mask: multislot
  slot: 1-1-9-6
  child:
    emerald-button:
      id: emerald
      name: "&a&lEmerald"
```

![MultiSlot 1](multislot-1.png)

```yaml
demo-slot:
  mask: multislot
  slot: 1-1-9-6
  child:
    emerald-button:
      id: emerald
      name: "&a&lEmerald"
    diamond-button:
      id: diamond
      name: "&b&lDiamond"
```

![MultiSlot 2](multislot-2.png)

```yaml
demo-slot:
  mask: multislot
  slot: 1-1-9-6
  child:
    emerald-button:
      id: emerald
      name: "&a&lEmerald"
    diamond-button:
      id: diamond
      name: "&b&lDiamond"
    redstone-button:
      id: redstone
      name: "&c&lRedstone"
```

![MultiSlot 3](multislot-3.png)

You may now understand what is the special feature of this mask. This mask will loop through the [`child` buttons]({{% ref "button/overview" %}}) and display them for each slot in the `slot` section.
---




---


#### Pattern Mask

It is a mask that allows you to create a pattern of buttons. The [Buttons]({{% ref "button/overview" %}}) are elements that can be used to draw on a grid-like pattern.

## Format

```yaml
mask-name:
  mask: pattern
  pattern:
    - "xxxxxxxxx"
    - "x       x"
    - "x       x"
    - "x       x"
    - "xxxxxxxxx"
  child:
    button-name-1:
      <button-settings>
    button-name-2:
      <button-settings>
    ...
```

## Note

* `pattern`: The pattern that will be drawn. The pattern is a list of strings. Each string represents a row of the pattern. The length of each string must be the same. The character in the string represents the button that will be drawn on that position. The character must be unique.
* The name of each button in the `child` section is the character that is used to draw on the pattern. The character must be unique.

## Example

```yaml
demo-slot:
  mask: pattern
  pattern:
    - "xxxxxxxxx"
    - "x       x"
    - "x       x"
    - "x       x"
    - "x       x"
    - "xxxxxxxxx"
  child:
    x:
      id: emerald
      name: "&a&lEmerald"
```

![Pattern 1](pattern-1.png)

```yaml
demo-slot:
  mask: pattern
  pattern:
    - "xxxxxxxxx"
    - "x       x"
    - "x 1 1 1 x"
    - "x  2 2  x"
    - "x       x"
    - "xxxxxxxxx"
  child:
    x:
      id: black_stained_glass_pane
      name: "&r"
    ' ':
      id: gray_stained_glass_pane
      name: "&r"
    1:
      id: emerald
      name: "&a&lEmerald"
    2:
      id: diamond
      name: "&b&lDiamond"
```

![Pattern 2](pattern-2.png)
---




---


#### Progress Mask

It is a mask that shows the progress of the player. It is useful for showing the progress of the player in a quest or a game.

## Format

```yaml
mask-name:
  mask: progress
  slot: <slot>
  current: <current-value>
  max: <max-value>
  current-button:
    <button-settings>
  max-button:
    <button-settings>
```

## Note

* `current`: The current value of the progress. It can be a number or a placeholder.
* `max`: The max value of the progress. It can be a number or a placeholder.
* `current-button`: The [Button]({{% ref "button/overview" %}}) that represents the filled part of the progress.
* `max-button`: The [Button]({{% ref "button/overview" %}}) that represents the empty part of the progress.

## Example

```yaml
demo-slot:
  mask: progress
  current: "{level}"
  max: 45
  slot: 1-1-9-5
  current-button:
    id: green_stained_glass_pane
    name: "&a&lCurrent: &e{level}"
  max-button:
    id: red_stained_glass_pane
    name: "&c&lMax: &e45"
```

![Progress 1](progress-1.gif)

Don't worry about the weird last row. I'll explain it later.
---




---


#### Hybrid Mask

This mask is a combination of multiple masks. It is useful for grouping masks for better organization.

## Format

```yaml
mask-name:
  mask: hybrid
  child:
    mask-1:
      <mask-settings>
    mask-2:
      <mask-settings>
    ...
```

## Example

```yaml
demo-slot:
  mask: hybrid
  child:
    mask-1:
      slot: 1-1-9-5
      id: green_stained_glass_pane
      name: "&a&lMask 1"
    mask-2:
      slot: 1-6-9-6
      id: red_stained_glass_pane
      name: "&c&lMask 2"
```

![Hybrid 1](hybrid-1.gif)

```yaml
demo-slot:
  mask: hybrid
  child:
    progress-level:
      mask: progress
      current: "{level}"
      max: 45
      slot: 1-1-9-5
      current-button:
        id: green_stained_glass_pane
        name: "&a&lCurrent: &e{level}"
      max-button:
        id: red_stained_glass_pane
        name: "&c&lMax: &e45"
    give-xp:
      slot: "1-6-9-6"
      id:
        - EXPERIENCE_BOTTLE
        - EXP_BOTTLE
      name: "&eGive &f10 XP"
      lore:
        - ""
        - "&fLevel: {level}"
      click-requirement:
        old-version:
          version: 13
          success-action: "console: xp add {player} 10 points"
          fail-action: "console: xp 10 {player}"
```

![Hybrid 2](hybrid-2.gif)

To explain what was missed in the example of [Progress Mask]({{% ref "../progress" %}}), the last row is the [Simple Mask]({{% ref "../simple" %}}) that gives the player 10 XP. I used the Hybrid Mask to group the Progress Mask and the Simple Mask together.
---




---


#### Animated Mask

Similar to [Animated Button]({{% ref "button/animated" %}}), this mask iterates through a list of masks and displays them in a sequence to create an animation.

## Format

```yaml
mask-name:
  mask: animated
  update: <ticks>
  child:
    mask-1:
      <mask-settings>
    mask-2:
      <mask-settings>
    ...
```

## Note

* `update`: The number of ticks between each frame.

## Example

```yaml
demo-slot:
  mask: animated
  update: 5
  child:
    frame1:
      slot: 0-53
      id: red_stained_glass_pane
      name: "&c&lFrame 1"
    frame2:
      slot: 0-53
      id: green_stained_glass_pane
      name: "&a&lFrame 2"
    frame3:
      slot: 0-53
      id: blue_stained_glass_pane
      name: "&9&lFrame 3"
```

![Animated 1](animated-1.gif)

```yaml
demo-slot:
  mask: animated
  update: 5
  child:
    frame1:
      slot: 0-8
      id: black_stained_glass_pane
      name: "&c&lFrame 1"
    frame2:
      slot: 9-17
      id: black_stained_glass_pane
      name: "&c&lFrame 2"
    frame3:
      slot: 18-26
      id: black_stained_glass_pane
      name: "&c&lFrame 3"
    frame4:
      slot: 27-35
      id: black_stained_glass_pane
      name: "&c&lFrame 4"
    frame5:
      slot: 36-44
      id: black_stained_glass_pane
      name: "&c&lFrame 5"
    frame6:
      slot: 45-53
      id: black_stained_glass_pane
      name: "&c&lFrame 6"
```

![Animated 2](animated-2.gif)

```yaml
demo-slot:
  mask: animated
  update: 5
  child:
    frame1:
      slot: 1-1-9-6
      mask: multislot
      child:
        button1:
          id: red_stained_glass_pane
          name: "&r"
        button2:
          id: black_stained_glass_pane
          name: "&r"
    frame2:
      slot: 1-1-9-6
      mask: multislot
      child:
        button1:
          id: black_stained_glass_pane
          name: "&r"
        button2:
          id: red_stained_glass_pane
          name: "&r"
```

![Animated 3](animated-3.gif)
---




---


#### One-Time Animated Mask

This is a special type of [Animated Mask]({{% ref "../animated" %}}) that only plays once. It will not loop back to the first frame after it reaches the last frame.

## Format

```yaml
mask-name:
  mask: animated
  update: <ticks>
  async: <true/false>
  keep-last: <true/false>
  child:
    mask-1:
      <mask-settings>
    mask-2:
      <mask-settings>
    ...
```

## Note

* `keep-last`: Whether the last frame will be kept after the animation is finished. The default value is `false`.

## Example

```yaml
demo-slot:
  mask: one-time-animated
  update: 5
  child:
    frame1:
      slot: 0-8
      id: black_stained_glass_pane
      name: "&c&lFrame 1"
    frame2:
      slot: 9-17
      id: black_stained_glass_pane
      name: "&c&lFrame 2"
    frame3:
      slot: 18-26
      id: black_stained_glass_pane
      name: "&c&lFrame 3"
    frame4:
      slot: 27-35
      id: black_stained_glass_pane
      name: "&c&lFrame 4"
    frame5:
      slot: 36-44
      id: black_stained_glass_pane
      name: "&c&lFrame 5"
    frame6:
      slot: 45-53
      id: black_stained_glass_pane
      name: "&c&lFrame 6"
```

![One-Time Animated 1](one-time-animated-1.gif)
---




---


#### Predicate Mask

This is a conditional mask. It will show the mask if the requirement is met. If not, it will show the fallback mask.

## Format

```yaml
mask-name:
  mask: predicate
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...
  check-only-on-creation: <true/false>
  success:
    <mask-settings>
  fallback:
    <mask-settings>
```

## Note

* `success`: The [Mask]({{% ref "./.." %}}) that will be shown if the `view-requirement` is met. If you don't set it, the mask will be empty.
* `fallback`: The [Mask]({{% ref "./.." %}}) that will be shown if the `view-requirement` is not met. If you don't set it, the mask will be empty.
* `view-requirement`: The [Requirement]({{% ref "requirement/overview" %}}) that must be met for the `success` mask to be shown.
* `check-only-on-creation`: If this value is set to `true`, the plugin will only check the `view-requirement` when the player opens the menu.

## Example

```yaml
demo-slot:
  mask: predicate
  view-requirement:
    test-level:
      level:
        value: 10
        take: false
  success:
    mask: pattern
    pattern:
      - "...xxx..."
      - "..x...x.."
      - "..x...x.."
      - "..x...x.."
      - "...xxx..."
    child:
      x:
        id: green_stained_glass_pane
        name: "&a&lSuccess"
  fallback:
    mask: pattern
    pattern:
      - "..x...x.."
      - "...x.x..."
      - "....x...."
      - "...x.x..."
      - "..x...x.."
    child:
      x:
        id: red_stained_glass_pane
        name: "&c&lFail"
```

![Predicate 1](predicate-1.gif)
---




---


#### List Mask

This is a conditional mask that loops through a list of masks and display a mask if it can be shown.

It can be used with [Predicate Mask]({{% ref "../predicate" %}}) to make more complex checks.

## Format

```yaml
mask-name:
  mask: list
  child:
    mask1:
      <mask-settings>
    mask2:
      <mask-settings>
    ...
```

## Example

```yaml
demo-slot:
  mask: list
  child:
    level-10:
      mask: predicate
      view-requirement:
        test-level:
          level:
            value: 10
            take: false
      success:
        mask: pattern
        pattern:
          - "..x..xxx."
          - ".xx..x.x."
          - "..x..x.x."
          - "..x..x.x."
          - ".xxx.xxx."
        child:
          x:
            id: green_stained_glass_pane
            name: "&a&lYou have reached level 10!"
    level-5:
      mask: predicate
      view-requirement:
        test-level:
          level:
            value: 5
            take: false
      success:
        mask: pattern
        pattern:
          - "...xxx..."
          - "...x....."
          - "...xxx..."
          - ".....x..."
          - "...xxx..."
        child:
          x:
            id: green_stained_glass_pane
            name: "&a&lYou have reached level 5!"
    level-0:
      mask: pattern
      pattern:
        - "...xxx..."
        - "...x.x..."
        - "...x.x..."
        - "...x.x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&c&lFail"
```

![List 1](list-1.gif)
---




---


#### Button Paginated Mask

This is a mask that allows you to paginate [Buttons]({{% ref "button/overview" %}}). This is useful when you have a lot of buttons and you want to split them into multiple pages.

## Format

```yaml
mask-name:
  mask: button-paginated
  slot: <slot>
  cycle: <true/false>
  signal: <signal>
  child:
    button-1:
      <button-settings>
    button-2:
      <button-settings>
    ...
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Example

```yaml
# The paginated mask
demo-slot:
  mask: button-paginated
  slot: 1-7
  cycle: false
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  child:
    button1:
      id: red_stained_glass_pane
      name: "&c&lButton 1"
    button2:
      id: green_stained_glass_pane
      name: "&a&lButton 2"
    button3:
      id: blue_stained_glass_pane
      name: "&9&lButton 3"
    button4:
      id: yellow_stained_glass_pane
      name: "&e&lButton 4"
    button5:
      id: purple_stained_glass_pane
      name: "&5&lButton 5"
    button6:
      id: orange_stained_glass_pane
      name: "&6&lButton 6"
    button7:
      id: pink_stained_glass_pane
      name: "&d&lButton 7"
    button8:
      id: black_stained_glass_pane
      name: "&0&lButton 8"
    button9:
      id: white_stained_glass_pane
      name: "&f&lButton 9"
    button10:
      id: gray_stained_glass_pane
      name: "&7&lButton 10"
    button11:
      id: light_gray_stained_glass_pane
      name: "&8&lButton 11"

# The button to go to the previous page
previous-button:
  slot: 0
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 8
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page
```

![Button Paginated 1](button-paginated-1.gif)
---




---


#### Sequence Paginated Mask

This is the same as the [Button Paginated Mask]({{% ref "../button-paginated" %}}). The only difference is that this mask assumes each button as a page, so it will "shift" the buttons to the left or right depending on the page.

## Format

```yaml
mask-name:
  mask: sequence-paginated
  slot: <slot>
  cycle: <true/false>
  signal: <signal>
  child:
    button-1:
      <button-settings>
    button-2:
      <button-settings>
    ...
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Example

```yaml
# The paginated mask
demo-slot:
  mask: sequence-paginated
  slot: 1-7
  cycle: false
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  child:
    button1:
      id: red_stained_glass_pane
      name: "&c&lButton 1"
    button2:
      id: green_stained_glass_pane
      name: "&a&lButton 2"
    button3:
      id: blue_stained_glass_pane
      name: "&9&lButton 3"
    button4:
      id: yellow_stained_glass_pane
      name: "&e&lButton 4"
    button5:
      id: purple_stained_glass_pane
      name: "&5&lButton 5"
    button6:
      id: orange_stained_glass_pane
      name: "&6&lButton 6"
    button7:
      id: pink_stained_glass_pane
      name: "&d&lButton 7"
    button8:
      id: black_stained_glass_pane
      name: "&0&lButton 8"
    button9:
      id: white_stained_glass_pane
      name: "&f&lButton 9"
    button10:
      id: gray_stained_glass_pane
      name: "&7&lButton 10"
    button11:
      id: light_gray_stained_glass_pane
      name: "&8&lButton 11"

# The button to go to the previous page
previous-button:
  slot: 0
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 8
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page
```

![Sequence Paginated 1](sequence-paginated-1.gif)
---




---


#### Mask Paginated Mask

Unlike [Button Paginated Mask]({{% ref "../button-paginated" %}}), this mask paginates [Masks]({{% ref "./.." %}}) instead of [Buttons]({{% ref "button/overview" %}}).

## Format

```yaml
mask-name:
  mask: mask-paginated
  cycle: <true/false>
  signal: <signal>
  child:
    mask-1:
      <mask-settings>
    mask-2:
      <mask-settings>
    ...
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Example

```yaml
# The paginated mask
demo-slot:
  mask: mask-paginated
  cycle: false
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  child:
    0:
      mask: pattern
      pattern:
        - "...xxx..."
        - "...x.x..."
        - "...x.x..."
        - "...x.x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&c&l0"
    1:
      mask: pattern
      pattern:
        - "....x...."
        - "...xx...."
        - "....x...."
        - "....x...."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&a&l1"
    2:
      mask: pattern
      pattern:
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
        - "...x....."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&b&l2"
    3:
      mask: pattern
      pattern:
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&d&l3"
    4:
      mask: pattern
      pattern:
        - "...x.x..."
        - "...x.x..."
        - "...xxx..."
        - ".....x..."
        - ".....x..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&e&l4"
    5:
      mask: pattern
      pattern:
        - "...xxx..."
        - "...x....."
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&f&l5"

# The button to go to the previous page
previous-button:
  slot: 18
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 26
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page
```

![Mask Paginated](mask-paginated-1.gif)
---




---


#### Template Mask

While you are creating menus with masks, you may find yourself repeating the same mask settings over and over again. This is where the template mask comes in handy. It allows you to create a template mask and use it in other masks.

## Format

```yaml
mask-name:
  mask: template
  template: <name> # The name from template folder
  variable:
    <variable1>: <value1>
    <variable2>: <value2>
    ...
  <mask-settings>
```

## Template Folder

The template folder (located at `plugins/BetterGUI/addon/MaskedGUI/template`) is a folder containing `yml` files defining common masks to use in all menus. That means you can create a template mask by simply creating a `yml` file in the template folder, add the common mask settings, and use it in other masks.

## Note

* `variable`: The variable is a way to pass values to the template mask. Check out [Use `variable` option]({{% ref "button/template" %}}#use-variable-option) for more information.

## Example

```yaml
# Template File
test-pattern:
  mask: pattern
  button:
    "*":
      id: purple_stained_glass_pane
      name: "&b&lBody"
    "x":
      id: red_stained_glass_pane
      name: "&c&lTarget"
    "#":
      id: pink_stained_glass_pane
      name: "&a&lHead"
```

```yaml
demo-slot:
  mask: animated
  update: 3
  child:
    1:
      mask: template
      template: test-pattern
      pattern:
      - "......x.."
      - "........."
      - "........."
    2:
      mask: template
      template: test-pattern
      pattern:
      - "......x.."
      - "........."
      - "#........"
    3:
      mask: template
      template: test-pattern
      pattern:
      - "......x.."
      - "........."
      - "*#......."
    4:
      mask: template
      template: test-pattern
      pattern:
      - "......x.."
      - "........."
      - "**#......"
    5:
      mask: template
      template: test-pattern
      pattern:
      - "......x.."
      - "..#......"
      - "***......"
    6:
      mask: template
      template: test-pattern
      pattern:
      - "..#...x.."
      - "..*......"
      - ".**......"
    7:
      mask: template
      template: test-pattern
      pattern:
      - "..*#..x.."
      - "..*......"
      - "..*......"
    8:
      mask: template
      template: test-pattern
      pattern:
      - "..**#.x.."
      - "..*......"
      - "........."
    9:
      mask: template
      template: test-pattern
      pattern:
      - "..***#x.."
      - "........."
      - "........."
    10:
      mask: template
      template: test-pattern
      pattern:
      - "..****#.."
      - "........."
      - "........."
    11:
      mask: template
      template: test-pattern
      pattern:
      - "...****.."
      - "......#.."
      - "........."
    12:
      mask: template
      template: test-pattern
      pattern:
      - "....***.."
      - "......*.."
      - "......#.."
    13:
      mask: template
      template: test-pattern
      pattern:
      - ".....**.."
      - "......*.."
      - "......*#."
    14:
      mask: template
      template: test-pattern
      pattern:
      - "......*.."
      - "......*.."
      - "......**#"
    15:
      mask: template
      template: test-pattern
      pattern:
      - "........."
      - "......*.."
      - "......***"
    16:
      mask: template
      template: test-pattern
      pattern:
      - "........."
      - "........."
      - "......***"
    17:
      mask: template
      template: test-pattern
      pattern:
      - "........."
      - "........."
      - ".......**"
    18:
      mask: template
      template: test-pattern
      pattern:
      - "........."
      - "........."
      - "........*"
    19:
      mask: template
      template: test-pattern
      pattern:
      - "........."
      - "........."
      - "........."
```

![Template 1](template-1.gif)
---




---


#### Switch Mask

This mask allows you to store a list of masks. Then you can make it switch to a specific mask from that list.

## Format

```yaml
mask-name:
  mask: hybrid
  signal: <signal>
  default: <mask-name>
  child:
    mask-1:
      <mask-settings>
    mask-2:
      <mask-settings>
    ...
```

## Note

* `signal`: The signal name used by actions to switch the mask.
* `default`: The name of the mask from the `child` section used as a default mask. If it's not set, the default mask will be empty.

## Action

* `set-mask(<signal>): <mask>`: Switch the mask to `<mask>`

## Example

```yaml
demo-slot:
  mask: switch
  signal: demo-page-signal # This is the signal name used by actions to switch the mask.
  default: 0 # The default mask name
  child:
    0:
      mask: pattern
      pattern:
        - "...xxx..."
        - "...x.x..."
        - "...x.x..."
        - "...x.x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&c&l0"
    1:
      mask: pattern
      pattern:
        - "....x...."
        - "...xx...."
        - "....x...."
        - "....x...."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&a&l1"
    2:
      mask: pattern
      pattern:
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
        - "...x....."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&b&l2"
    3:
      mask: pattern
      pattern:
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&d&l3"
    4:
      mask: pattern
      pattern:
        - "...x.x..."
        - "...x.x..."
        - "...xxx..."
        - ".....x..."
        - ".....x..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&e&l4"
    5:
      mask: pattern
      pattern:
        - "...xxx..."
        - "...x....."
        - "...xxx..."
        - ".....x..."
        - "...xxx..."
      child:
        x:
          id: red_stained_glass_pane
          name: "&f&l5"

button-1:
  slot: 47
  name: "&e&l1"
  id: arrow
  command: "set-mask(demo-page-signal): 1"

button-2:
  slot: 48
  name: "&e&l2"
  id: arrow
  command: "set-mask(demo-page-signal): 2"

button-3:
  slot: 49
  name: "&e&l3"
  id: arrow
  command: "set-mask(demo-page-signal): 3"

button-4:
  slot: 50
  name: "&e&l4"
  id: arrow
  command: "set-mask(demo-page-signal): 4"

button-5:
  slot: 51
  name: "&e&l5"
  id: arrow
  command: "set-mask(demo-page-signal): 5"
```

![Switch 1](switch-1.gif)
---




---


#### Player List Mask

This mask is similar to [Button Paginated Mask]({{% ref "../button-paginated" %}}). The only difference is that this mask will fetch all online players and display each of them as a [Button]({{% ref "button/overview" %}}).

## Format

```yaml
mask-name:
  mask: player-list
  slot: <slot>
  cycle: <true/false>
  signal: <signal>
  view-self: <true/false>
  view-offline: <true/false>
  player-update: 20
  viewer-update: 0
  player-condition:
  - condition1
  - condition2
  - condition3
  viewer-condition:
  - condition1
  - condition2
  - condition3
  button:
    <button-settings>
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.
* `view-self`: Whether the mask will display the player that opens then menu.
* `view-offline`: Whether the mask will display all offline players instead of just online ones.
* `player-condition`: The list of [Condition Requirement]({{% ref "requirement/condition" %}}) that the player must meet to appear in the list.
* `viewer-condition`: The list of [Condition Requirement]({{% ref "requirement/condition" %}}) that the viewer must meet to see the player's button.
* The difference between `player-condition` and `viewer-condition` is that the `player-condition` will be checked for each online players to gather the list of "passed" players to display in the menu, while `viewer-condition` will be checked between the viewer (who opens the menu) and the player in the "passed" players to determine if the viewer can see the player in the menu.
* `button`: The [Button]({{% ref "button/overview" %}}) to be displayed for each players.
* `player-update`: The ticks to wait before the player list is refreshed.
* `viewer-update`: The ticks to wait before the "passed" player list from the viewer view is refreshed.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Player Variable

* It's possible to define variables for each players in the list in `player-condition` and `button`
* To do that, the mask introduces 2 new variables:
  * `{current_player_<variable_name>}` to fetch the variable `<variable_name>` of the target player
    * Example:
      * `{player}` -> `{current_player}`
      * `{ping}` -> `{current_player_ping}`
      * `{exp_to_level}` -> `{current_player_exp_to_level}`
  * `{current_player_papi_<placeholder_name>}` to fetch the PlaceholderAPI's placeholder `<placeholder_name>` of the target player

## Example

```yaml
demo-slot:
  mask: player-list
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  slot: 2-1-8-1
  view-self: true
  button:
    id: player_head
    skull: "{current_player}"
    name: "&c{current_player}"
    lore:
    - "&eX: &f{current_player_x}"
    - "&eY: &f{current_player_y}"
    - "&eZ: &f{current_player_z}"
    command: "console: tp {player} {current_player}"
    close-on-click: true

# The button to go to the previous page
previous-button:
  slot: 0
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 8
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page
```

![Player List 1](player-list-1.gif)
---




---


#### Value List Mask

This mask is similar to [Button Paginated Mask]({{% ref "../button-paginated" %}}), but you can specify a list of values and display each of them as a [Button]({{% ref "button/overview" %}}).

## Format

```yaml
mask-name:
  mask: value-list
  slot: <slot>
  cycle: <true/false>
  signal: <signal>
  value-update: 20
  viewer-update: 0
  viewer-condition:
  - condition1
  - condition2
  - condition3
  value:
  - value1
  - value2
  - value3
  button:
    <button-settings>
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.
* `viewer-condition`: The list of [Condition Requirement]({{% ref "requirement/condition" %}}) that the viewer must meet to see the button.
* `value`: The list of values
* `button`: The [Button]({{% ref "button/overview" %}}) to be displayed for each values.
* `value-update`: The ticks to wait before the value list is refreshed.
* `viewer-update`: The ticks to wait before the "passed" value list from the viewer view is refreshed.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Variable

* On `button`, you can get the current value from the `value` list by using the variable `{current_value}`

## Example

```yaml
# The paginated mask
demo-slot:
  mask: value-list
  slot: 1-7
  cycle: false
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  value:
  - red_stained_glass_pane
  - green_stained_glass_pane
  - blue_stained_glass_pane
  - yellow_stained_glass_pane
  - purple_stained_glass_pane
  - orange_stained_glass_pane
  - pink_stained_glass_pane
  - black_stained_glass_pane
  - white_stained_glass_pane
  - gray_stained_glass_pane
  - light_gray_stained_glass_pane
  button:
    id: "{current_value}"
    name: "&c&lButton"

# The button to go to the previous page
previous-button:
  slot: 0
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 8
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page
```

![Value List 1](value-list-1.gif)
---




---


#### Key-Value List Mask

This mask is similar to [Button Paginated Mask]({{% ref "../button-paginated" %}}), but you can specify a list of map-like values and display each of them as a [Button]({{% ref "button/overview" %}}).

## Format

```yaml
mask-name:
  mask: key-value-list
  slot: <slot>
  cycle: <true/false>
  signal: <signal>
  value-update: 20
  viewer-update: 0
  viewer-condition:
  - condition1
  - condition2
  - condition3
  value:
  - key1: value1
    key2: value2
    key3: value3
  - key1: value11
    key2: value12
    key3: value13
  - key1: value21
    key2: value22
    key3: value23
  button:
    <button-settings>
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.
* `viewer-condition`: The list of [Condition Requirement]({{% ref "requirement/condition" %}}) that the viewer must meet to see the button.
* `value`: The list of map-like values
* `button`: The [Button]({{% ref "button/overview" %}}) to be displayed for each values.
* `value-update`: The ticks to wait before the value list is refreshed.
* `viewer-update`: The ticks to wait before the "passed" value list from the viewer view is refreshed.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Variable

* On `button`, you can use a key to get the value from the `value` list by using the variable `{key_<name>}`
* For examples: With this `value` list
```yaml
value:
- material: red_stained_glass_pane
  name: "Button 1"
- material: green_stained_glass_pane
  name: "Button 2"
```
  * You can use `{key_material}` to get the `material` part of the value
  * You can use `{key_name}` to get the `name` part of the value

## Example

```yaml
# The paginated mask
demo-slot:
  mask: key-value-list
  slot: 1-7
  cycle: false
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  value:
  - material: red_stained_glass_pane
    name: Button 1
  - material: green_stained_glass_pane
    name: Button 2
  - material: blue_stained_glass_pane
    name: Button 3
  - material: yellow_stained_glass_pane
    name: Button 4
  - material: purple_stained_glass_pane
    name: Button 5
  - material: orange_stained_glass_pane
    name: Button 6
  - material: pink_stained_glass_pane
    name: Button 7
  - material: black_stained_glass_pane
    name: Button 8
  - material: white_stained_glass_pane
    name: Button 9
  - material: gray_stained_glass_pane
    name: Button 10
  - material: light_gray_stained_glass_pane
    name: Button 11
  button:
    id: "{key_material}"
    name: "&c&l{key_name}"

# The button to go to the previous page
previous-button:
  slot: 0
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 8
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page
```

![Key Value List 1](key-value-list-1.gif)
---




---


#### Filtered Button Paginated Mask

This mask is similar to [Button Paginated Mask]({{% ref "../button-paginated" %}}), but you can filter out the buttons with specific requirements.

## Format

```yaml
mask-name:
  mask: filtered-button-paginated
  slot: <slot>
  cycle: <true/false>
  signal: <signal>
  update: 20
  child:
    button-1:
      <button-settings>
      filter-requirement:
        <requirement-set>
        <requirement-set>
        <requirement-set>
        ...

    button-2:
      <button-settings>
      filter-requirement:
        <requirement-set>
        <requirement-set>
        <requirement-set>
        ...

    button-3:
      <button-settings>
      filter-requirement:
        <requirement-set>
        <requirement-set>
        <requirement-set>
        ...
    ...
```

## Note

* `cycle`: Whether the buttons should cycle when you reach the end of the page. If this is set to `true`, then when you reach the end of the page, it will go back to the first page. If this is set to `false`, then when you reach the end of the page, it will stop at the last page.
* `signal`: The signal name used by actions to change the page.
* `update`: The ticks to wait before the mask is refreshed.
* You can use `filter-requirement` on the button to remove it from the list if the player doesn't meet the requirements.
  * It's similar to `view-requirement`, but the difference is that, while buttons with `view-requirement` will leave an empty button on the list, those with `filter-requirement` will be removed from the list if the player doesn't meet the requirements.

## Action

* `next-page: <signal>`: Changes the page to the next page.
* `previous-page: <signal>`: Changes the page to the previous page.
* `set-page(<signal>): <page>`: Changes the page to `<page>`.

## Example

```yaml
# The paginated mask
demo-slot:
  mask: filtered-button-paginated
  slot: 1-7
  cycle: false
  signal: demo-page-signal # This is the signal name used by actions to change the page.
  child:
    button1:
      id: red_stained_glass_pane
      name: "&c&lButton 1"
      filter-requirement:
        test-level:
          level:
            value: 1
            take: false
    button2:
      id: green_stained_glass_pane
      name: "&a&lButton 2"
      filter-requirement:
        test-level:
          level:
            value: 2
            take: false
    button3:
      id: blue_stained_glass_pane
      name: "&9&lButton 3"
      filter-requirement:
        test-level:
          level:
            value: 4
            take: false
    button4:
      id: yellow_stained_glass_pane
      name: "&e&lButton 4"
      filter-requirement:
        test-level:
          level:
            value: 5
            take: false
    button5:
      id: purple_stained_glass_pane
      name: "&5&lButton 5"
      filter-requirement:
        test-level:
          level:
            value: 6
            take: false
    button6:
      id: orange_stained_glass_pane
      name: "&6&lButton 6"
      filter-requirement:
        test-level:
          level:
            value: 10
            take: false
    button7:
      id: pink_stained_glass_pane
      name: "&d&lButton 7"
      filter-requirement:
        test-level:
          level:
            value: 11
            take: false
    button8:
      id: black_stained_glass_pane
      name: "&0&lButton 8"
      filter-requirement:
        test-level:
          level:
            value: 11
            take: false
    button9:
      id: white_stained_glass_pane
      name: "&f&lButton 9"
      filter-requirement:
        test-level:
          level:
            value: 11
            take: false
    button10:
      id: gray_stained_glass_pane
      name: "&7&lButton 10"
      filter-requirement:
        test-level:
          level:
            value: 12
            take: false
    button11:
      id: light_gray_stained_glass_pane
      name: "&8&lButton 11"
      filter-requirement:
        test-level:
          level:
            value: 12
            take: false

# The button to go to the previous page
previous-button:
  slot: 0
  id: arrow
  name: "&c&lPrevious"
  command: "previous-page: demo-page-signal" # The action to change the page

# The button to go to the next page
next-button:
  slot: 8
  id: arrow
  name: "&a&lNext"
  command: "next-page: demo-page-signal" # The action to change the page

# Button to give XP
give-xp:
  slot: 9-17
  id:
    - EXPERIENCE_BOTTLE
    - EXP_BOTTLE
  name: "&eGive &f10 XP"
  lore:
    - ""
    - "&fLevel: {level}"
  click-requirement:
    old-version:
      version: 13 # Check if the server is at 1.13.X
      success-action: "console: xp add {player} 10 points"
      fail-action: "console: xp 10 {player}"
```

![Filtered Button Paginated 1](filtered-button-paginated-1.gif)
---




---


## Meta Play

{{% button href="https://github.com/BetterGUI-MC/MetaPlay" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/MetaPlay/" style="green" icon="download" %}}Download{{% /button %}}

## Description

This addon adds a new variable to get and set metadata of players. This can be used to store data for the player.

## Variable

* `{meta_<key>}` gets the value from the metadata of the player at the key `<key>`
* `{meta_number_<key>}` gets the value from the metadata of the player at the key `<key>` and converts it to a number

## Action

* `mete(<key>): <value>` sets the value of the metadata of the player at the key `<key>` to `<value>`
* `meta(<key>, number): <value>` sets the value of the metadata of the player at the key `<key>` to `<value>` as a number
* `meta(<key>)` removes the value of the metadata of the player at the key `<key>`

Note: In `<value>` you can use the variable `{value}` to get the previous value of the metadata.

## Example

```yaml
T:
  id: diamond
  name: "&b&lMeta: &f{meta_number_diamond_count}"
  command:
    left: "meta(diamond_count, number): {value} + 1" # Requires EvalExtra to use expressions
    right: "meta(diamond_count): 0"
```
---




---


## PaperSpec

{{% button href="https://github.com/BetterGUI-MC/PaperSpec/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/PaperSpec/" style="green" icon="download" %}}Download{{% /button %}}

## Description
This addon add functions that only work on [PaperMC](https://papermc.io/) and its forks.

{{% notice warning %}}
Requirement: _Paper 1.19.4 or newer is required for this addon to work._
{{% /notice %}}

## Menu Settings

### Menu Title

Set the `creator` option of the `menu-settings` to be `mini-title`.

Then you can use [MiniMessage formatting](https://docs.adventure.kyori.net/minimessage/index.html) for the inventory title.

```yaml
menu-settings:
  name: '<red><b>A inventory title generated by MiniMessage'

  creator: "mini-title"
  # ...
```

## Item Modifiers

### Skull Modifier

#### Format
```yaml
paper-skull: <skull>
paper-head: <skull>
skull$: <skull>
head$: <skull>
```

#### Description
* This modifier will set the `<skull>` of the item
* `<skull>` accepts a player name or an UUID (unique id)

#### Example
```yaml
skull:
  position-x: 1
  position-y: 1
  name: "&bSkull"
  id: player_head
  paper-skull: "HSGamer"
  # paper-skull: "7acc67dc-8b84-4f8d-b7ad-ec81e758f5a1"

per-player-skull:
  position-x: 2
  position-y: 1
  name: "&bPer Player Skulls"
  id: player_head
  paper-skull: "{player}"
```

### DisplayName & Lore Modifiers

#### Format
```yaml
mini-name: <minimessage formatting text>
mini-lore:
- <minimessage formatting text>
- <minimessage formatting text>
- ...
```

#### Description
You can use [MiniMessage formatting](https://docs.adventure.kyori.net/minimessage/index.html) for the name and lore of your menu items. Just make sure you use the new format above instead of the original `name` and `lore` modifiers.

There are aliases for the modifiers. You can also use:

1. `name$` for the `mini-name` modifier
2. `lore$` for the `mini-lore` modifier

Note that the legacy color codes (`&c`, `&3`) does not work in the new format.

#### Example
```yaml
minimessage:
  position-x: 1
  position-y: 1
  mini-name: "<rainbow>Rainbow Name"
  mini-lore:
    - "<b>Bold text"
    - "<aqua>Simple color!"
    - "<#00ff00>R G B color!"
    - "<gradient:green:blue>Gradient color!"
    - "<transition:#00ff00:#ff0000:0>Transition color!"
    - "<font:myfont:custom_font>Uses a custom font from a resource pack"
    - "<lang:block.minecraft.diamond_block> <- this is a translatable text"
```

### Action

> `<type>`: The type of the component (`json`, `minimessage`, `legacy`)

* `paper-tell(<type>): <text>`: send the component text to the player
* `paper-broadcast(<type>): <text>`: send the component text to all players
* `paper-tell(<type>, bar): <text>`: send the component text as an action bar to the player
* `paper-broadcast(<type>, bar): <text>`: send the component text as an action bar to all players

## [MiniPlaceholders](https://modrinth.com/plugin/miniplaceholders) support

[MiniPlaceholders](https://modrinth.com/plugin/miniplaceholders) is supported in all settings that involve [MiniMessage formatting](https://docs.adventure.kyori.net/minimessage/index.html)

### Example

```yaml
mini-tps:
  position-x: 1
  position-y: 1
  mini-name: "<rainbow>TPS"
  mini-lore:
    - "<white><b>1m: <green><server_tps_1>" # <server_tps_1> is a MiniPlaceholders placeholder
    - "<white><b>5m: <green><server_tps_5>" # <server_tps_5> is a MiniPlaceholders placeholder
```
---




---


## PlayerPoints Bridge

{{% button href="https://github.com/BetterGUI-MC/PlayerPointsBridge/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/PlayerPointsBridge/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice warning %}}
Depend: [PlayerPoints](https://www.spigotmc.org/resources/playerpoints.80745/)
{{% /notice %}}

## Variable
* `{points}` gets the points the player having

## Action

### Format
* `give-point: <point>`

### Description
This action gives `<point>` to the player

### Example
```yaml
give-point:
  slot: 1
  id: emerald
  name: "&cGive points"
  command: "give-point: 10"
```

## Requirement

### Format
```yaml
point: <value>
```
```yaml
point:
  value: <value>
  take: <true/false>
```

### Description
* This requirement checks if the player has at least `<value>` points
* You can set the `take` value (`true` or `false`) to allow/disallow the plugin to take the points of the player alter checking successfully

### Example
```yaml
check-points:
  slot: 1
  id: emerald
  name: "&cTake Points"
  click-requirement:
    left:
      take-point: # Take 10 points
        point: 10
    right:
      check-point: # Check if the players has 10 points
        point:
          value: 10
          take: false
        success-action: "tell: &a You have enough points"
        fail-action: "tell: &a You don't have enough points"
```
---




---


## Switch Icon

{{% button href="https://github.com/BetterGUI-MC/SwitchIcon/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/SwitchIcon/" style="green" icon="download" %}}Download{{% /button %}}

## Format
```yaml
button-name:
  type: switch
  child:
    button1:
      <button-settings>
    button2:
      <button-settings>
    button3:
      <button-settings>
    ...
```

## Description
This is a button that changes everytime the user clicks

## Example
```yaml
switch-icon:
  type: switch
  child:
    frame_icon1:
      name: "&cFrame 1"
      id: red_wool
    frame_icon2:
      name: "&aFrame 2"
      id: green_wool
    frame_icon3:
      name: "&bFrame 3"
      id: light_blue_wool
```
---




---


## TokenManager Bridge

{{% button href="https://github.com/BetterGUI-MC/TokenManagerBridge/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/TokenManagerBridge/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice warning %}}
Depend: [TokenManager](https://www.spigotmc.org/resources/tokenmanager.8610/)
{{% /notice %}}

## Variable
* `{tokens}` gets the tokens the player having

## Action

### Format
* `give-token: <token>`

### Description
This action gives `<token>` to the player

### Example
```yaml
give-token:
  slot: 1
  id: emerald
  name: "&cGive tokens"
  command: "give-token: 10"
```

## Requirement

### Format
```yaml
token: <value>
```
```yaml
token:
  value: <value>
  take: <true/false>
```

### Description
* This requirement checks if the player has at least `<value>` tokens
* You can set the `take` value (`true` or `false`) to allow/disallow the plugin to take the tokens of the player alter checking successfully

### Example
```yaml
check-tokens:
  slot: 1
  id: emerald
  name: "&cTake tokens"
  click-requirement:
    left:
      take-token: # Take 10 tokens
        token: 10
    right:
      check-token: # Check if the players has 10 tokens
        token:
          value: 10
          take: false
        success-action: "tell: &a You have enough tokens"
        fail-action: "tell: &a You don't have enough tokens"
```
---




---


## Trade Mart

{{% button href="https://github.com/BetterGUI-MC/TradeMart/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/TradeMart/" style="green" icon="download" %}}Download{{% /button %}}

## Description

This is an addon to add Villager-like GUI for item trading.

## Format

```yaml
menu-settings:
  menu-type: trade

  # The actions when the player opens the menu
  open-action:
  - action
  - action
  - action
  ...

  # The actions when the player closes the menu
  close-action:
  - action
  - action
  - action
  ...

  # The requirement before the player can open the menu
  view-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The requirement before the player can close the menu
  close-requirement:
    <requirement-set>
    <requirement-set>
    <requirement-set>
    ...

  # The permission required to open the menu
  permission: bettergui.test

  # The command to open the menu
  command:
  - command1
  - command2
  ...

  # The title of the inventory
  title: <name>
  #name: <name>

  # The list of argument processors to process the arguments of the command to open the menu
  argument-processor:
  - <argument-processor>
  - <argument-processor>

trade-name1:
  item1:
    <button-settings>
  item2:
    <button-settings>
  result:
    <button-settings>

trade-name2:
  item1:
    <button-settings>
  item2:
    <button-settings>
  result:
    <button-settings>
...
```

## Note

* `open-action`: the [Action]({{% ref "action/overview" %}}) when the menu is opened.
* `close-action`: the [Action]({{% ref "action/overview" %}}) when the menu is closed.
* `view-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before opening the menu. If it is not met, the menu will not be opened.
* `close-requirement`: the [Requirement]({{% ref "requirement/overview" %}}) to check before closing the menu. If it is not met, the menu will not be closed.
* `argument-processor`: the [Argument Processor]({{% ref "argument" %}}) to handle the arguments of the command to open the menu.

## Trade

```yaml
trade-name:
  item1:
    <button-settings>
  item2:
    <button-settings>
  result:
    <button-settings>
  max-uses: <number>
```

* `item1`: The first item to trade. REQUIRED
* `item2`: The second item to trade. OPTIONAL
* `result`: The result item. REQUIRED
* `max-uses`: The maximum uses of a trade. OPTIONAL

## Example

```yaml
menu-settings:
  menu-type: trade
  title: "&c&lTest Trade"
  command: trade

trade1:
  item:
    id: diamond
  item2:
    id: redstone
  result:
    id: piston

trade2:
  item:
    id: diamond_block
    amount: 64
  result:
    id: paper
    name: "&b&lRich Cerificate"

trade3:
  item:
    id: paper
    name: "&b&lRich Cerificate"
  item2:
    id: emerald
    amount: 64
  result:
    id: paper
    name: "&a&lVillage Cerificate"
    lore:
    - ""
    - "&7Signed by {player}"
```
---




---


## Vault Bridge

{{% button href="https://github.com/BetterGUI-MC/VaultBridge/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/VaultBridge/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice warning %}}
Depend: [Vault](https://www.spigotmc.org/resources/vault.34315/)
{{% /notice %}}

## Variable
* `{money}` gets the money the player having
* `{money_formatted}` gets the money the player having (formatted)
* `{group}` gets the group the player is currently in

## Action

### Format
* `give-money: <money>`

### Description
This action gives `<money>` to the player

### Example
```yaml
give-money:
  slot: 1
  id: emerald
  name: "&cGive money"
  command: "give-money: 10"
```

## Requirement

### Money

#### Format
```yaml
money: <value>
```
```yaml
money:
  value: <value>
  take: <true/false>
```

#### Description
* This requirement checks if the money the player having is at least `<value>`
* You can set the `take` value (`true` or `false`) to allow/disallow the plugin to take the money of the player alter checking successfully

#### Example
```yaml
check-money:
  slot: 1
  id: emerald
  name: "&cTake money"
  click-requirement:
    left:
      take-money: # Take 10 money
        money: 10
    right:
      check-money: # Check if the players has 10 money
        money:
          value: 10
          take: false
        success-action: "tell: &a You have enough money"
        fail-action: "tell: &a You don't have enough money"
```

### Group

#### Format
```yaml
group: <name>
```

#### Decription
This requirement checks if the player is in the group `<name>`

#### Example
```yaml
check-group:
  slot: 1
  id: stone
  name: "&cStone Group"
  click-requirement:
    default:
      stone-group: # Check if the player is in the "stone" group
        group: stone
        success-action: "tell: &aYou are welcome"
        fail-action: "tell: &cGet out of here"
```
---




---


## World and Region

{{% button href="https://github.com/BetterGUI-MC/World-And-Region/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/World%20And%20Region/" style="green" icon="download" %}}Download{{% /button %}}

{{% notice warning %}}
Depend: [WorldGuard](https://dev.bukkit.org/projects/worldguard) (for Region & Flag)
{{% /notice %}}

## Variable
* `{region}` gets the name of the region the user standing on
* `{flag_<flag_name>}` gets the status of the flag `<flag_name>` at the region the user standing on

## Requirement

### World

#### Format
```yaml
world: <world_name>
```
```yaml
world:
- <world_name>
- <world_name>
```

#### Description
This requirement checks if the player is at the world `<world_name>`

### Region

#### Format
```yaml
region: <region_name>
```
```yaml
region:
- <region_name>
- <region_name>
```

#### Description
This requirement checks if the player is at the region `<region_name>`

### Region Owner

#### Format
```yaml
region-owner: <region_name>
```
```yaml
region-owner:
- <region_name>
- <region_name>
```

#### Description
This requirement checks if the player is the owner of the region `<region_name>`

### Region User

#### Format
```yaml
region-user: <region_name>
```
```yaml
region-user:
- <region_name>
- <region_name>
```

#### Description
This requirement checks if the player is the user of the region `<region_name>`

### Flag

#### Format
```yaml
flag:
  flag1: <value1>
  flag2: <value2>
  flag3: <value3>
  ...
```

#### Description
This requirement checks if the status of the `flag` at the region the player standing on matches the `value`
---




---


## XCross

{{% button href="https://github.com/BetterGUI-MC/XCross/" style="gray" icon="code" %}}Code{{% /button %}} {{% button href="https://ci.codemc.io/job/BetterGUI-MC/view/Addon/job/XCross/" style="green" icon="download" %}}Download{{% /button %}}

## Description
This addon integrates [XSeries](https://github.com/CryptoMorin/XSeries) so that you can use version-independent values in some item modifiers & actions.

## Item Modifier

### Material Modifier

#### Format
```yaml
xmaterial: <material>
xid: <material>
xmat: <material>
```

#### Description
* This modifier will set the `<material>` of the item

#### Example
```yaml
stone-button:
  slot: 1
  xid: stone
```
```yaml
player-head:
  slot: 2
  xid: player_head
```

### Enchantment Modifier

#### Format
```yaml
xenchantment:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
```
```yaml
xenchant:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
```
```yaml
xenc:
- <enchantment>, [level]
- <enchantment>, [level]
- <enchantment>, [level]
...
```

#### Description
* This modifier will add the `<enchantment>`s to the item
* You can set the `[level]` of the `<enchantment>`. It's optional.

#### Example
```yaml
enchanted-sword:
  NAME: '&aEnchanted sword'
  LORE:
    - 'This sword is glowing.'
  ID: diamond_sword
  XENCHANTMENT:
    - "durability, 1"
  POSITION-X: 1
  POSITION-Y: 1
```

### Potion Effect Modifier

#### Format
```yaml
xpotion:
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
...
```
```yaml
xeffect:
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
- <potion>, [duration], [amplifier]
...
```

#### Description
* This modifier will add the `<potion>` effect to the item.
* You can set the `[duration]` and `[amplifier]` of the `<potion>` effect. These are optional.

#### Example
```yaml
potion:
  position-x: 1
  position-y: 1
  name: "&bPotion"
  id: potion
  xpotion:
    - "SPEED"
    - "WEAKNESS, 30, 1"
```

### Skull Modifier

#### Format
```yaml
xskull: <skull>
xhead: <skull>
```

#### Description
* This modifier will set the `<skull>` of the item
* `<skull>` accepts a player name, an UUID (unique id), an Base64 value, or a `texture.minecraft.net` URL

#### Example
```yaml
skull:
  position-x: 1
  position-y: 1
  name: "&bSkull"
  id: player_head
  xskull: "HSGamer"
  #xskull: "7acc67dc-8b84-4f8d-b7ad-ec81e758f5a1"
  #xskull: "http://textures.minecraft.net/texture/ffcdae586b52403b92b1857ee4331bac636af08bab92ba5750a54a83331a6353"
  #xskull: "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvZmZjZGFlNTg2YjUyNDAzYjkyYjE4NTdlZTQzMzFiYWM2MzZhZjA4YmFiOTJiYTU3NTBhNTRhODMzMzFhNjM1MyJ9fX0="

per-player-skull:
  position-x: 2
  position-y: 1
  name: "&bPer Player Skulls"
  id: player_head
  xskull: "{player}"
```

## Action

### Play Sound

#### Format
* `xsound: <sound>, [volume], [pitch]`
* `xsound: <sound> [volume] [pitch]`

#### Description
* This action will send the `<sound>` to the player
* You can specify the `[volume]` and the `[pitch]` of the `<sound>`. Those are optional

#### Example
* `xsound: BLOCK_NOTE_BLOCK_PLING`
* `xsound: BLOCK_NOTE_BLOCK_PLING 1 2`
---




---



# Contribute

Tutorials on how to contribute to the project.
---