GUIs

Each GUI uses an entire YAML file to parse its settings from the guis -> <lang> folder.
Unlike language files, they don't automatically add new options since they're 100% customizable.

Synchronizing GUIs

Since GUIs are edited individually for each language, syncing them after changing an option manually might be hard, you can take a look at this experimental option to sync GUIs.

How to read this documentation?

Main Options

title: Text # The title displayed above the GUI.
rows: Number ; 1 - 6 # The amount of rows that this GUI will have. The columns will have a fixed size of 9
type: Text # If no rows is specified, a type will be used. You can see all the types here:
           # https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/InventoryType.html
message: Text # Message that the player receives when this GUI opens.
disallow-creative: Boolean # Whether this GUI can be opened in creative mode or not.
interactable: [Number] or 'empty' # Interactable slots of this GUI. If it only contains one slot and that number is lower than zero,
            # then the list will act as a blacklist.
            # When set to "empty" all slots that don't have an option defined for them will be interactable. Meaning even if you did put
            # an item in one of these slots, that slot is no longer empty, but it's still "empty" in the sense that it has no option for that slot.

open-conditions:
  "A condition": "The message that gets sent if that condition is true"
  "Another condition": "The message that gets sent if that condition is true"

Item Options

These options are used under the item names which are under options entry of GUIs. Option names are really important for some GUIs. They define what an option does from the code. If an option name doesn't have any actions attached to it, it'll not do anything when clicked on. This is where conditional GUIs come to use.
All the text options in items support color codes and placeholders.
Some people might find the following information hard to understand. If you have a question for any options below, ask me.

For the general options used to create items which is even used outside of GUIs, refer to this documentation.

Other options that are specific to GUIs:

condition: Text # Refer to the section below for more information.
sound: Sound # The sound played when this item is clicked.
commands: [Command] # The commands executed when this item is clicked.
message: Text # The message sent to the player when this item is clicked.
interaction: GUIInteractionType # How should the plugin behave when a player interacts with this item in the GUI?

alias GUIInteractionType: for Text 
  DISALLOW  # The default interaction type. Doesn't allow the player to click on the item in any way.
  FREE      # The player can manipulate this slot freely. Take the item, and put new items in it.
  TAKE_ONLY # The player can only take the item that was put by the GUI from this slot.

# The position(s) of the item.
slot:   Number  ; 0 - 53 # See https://i.imgur.com/gK9plGo.png
slots: [Number] ; 0 - 53 # When this option is used, the same item will be placed in multiple slots.
posx:   Number  ; 1 - 9
posy:   Number  ; 1 - 6

perform-action: Boolean # If the option has special meaning, then when this option is set (it's intended to be set to "false" but any value works),
                        # then it'll act like other decorative option. Meaning when clicked on, it'll do nothing.

alias Sound:   for Text # https://github.com/CryptoMorin/KingdomsX/wiki/Config
alias Command: for Text # https://github.com/CryptoMorin/KingdomsX/wiki/Config

Conditional

GUI items use a simple logical-relational evaluator to change item appearance depending on a condition. You can define certain item properties by using condition option and putting each under a custom condition name. These conditions follow the general config conditions rules.

Example:

options:
  hello:

    # Options defined outside of conditional options are inherited. This only works for general options such as name, lore, material etc.
    # if a GUI defines special options for certain options, those will not be inherited.
    # So for example if the lore doesn't change in below situations,
    # you can write it here once instead of writing it twice or more.
    lore: "This option disables\nsomething somewhere"
   
    # Note that "activated" and "else" are just normal names that have no effects.
    # The last condition which is always used if none of the conditions above it were met, is named "else" most of the times.
    activated:
      condition: "kingdoms_members > 10 && kingdoms_members < 20"
      name: "&2Activated"
      material: GREEN_WOOL
    else: # You should use this name as well, it might be problematic in future versions.
      # Note that there's no "condition" option here. There is no need for us to use "%kingdoms_members% <= 10" here.
      # Omitting the condition will automatically default to always match.
      name: "&4Disabled"
      material: RED_WOOL

If you're looking for something similar, but for math equations, you should search for Conditional functions in the config section.

Custom UI

You can change the overall layout of each GUI by using ItemsAdder plugin. You can refer to this guide that explains how this works. You can use the placeholders inside the title option of each GUI.

If your GUI's image is a bit off (not centered on the screen), first try removing the offset completely. If it didn't work, try setting a high number to offset like -10 so you can see the title underneath. If the title has weird characters like □ or � that means you have to regenerate your pack. If that didn't work, try clearing your cache with /iacleancache command.

For chest-based GUIs, an offset of -8 is sufficient. Just use &f%img_offset_-8% at the beginning of your title to apply it, then add a placeholder for your custom GUI image (%img_<name>%) afterwards.

Note

Make sure you're using the latest version of ItemsAdder. The weird characters are usually caused by versions older than v3.3.0

Bedrock Forms

This section is dedicated to servers that use Geyser server software along with Floodgate. Minecraft's bedrock edition, allows additional GUI features that the Java edition doesn't have. The main GUI framework in Bedrock edition is called forms, while this type of GUI is more visually appealing, it does have some restrictions that the normal inventory GUI doesn't have.

Important

Note that Geyser server software is not officially supported. So any issues that occurs while using this server software that doesn't occur when using other officially supported server software (e.g. Spigot, Paper, etc) will most likely not be fixed. The forms GUI support is just an exception.

You can configure forms in the same GUI config file as previously explained. All form-related configurations are separate from the inventory options defined in the same file. All form options are configured below forms section of the config.

Form Types

Before configuring your GUI, you need to pick a form type. Each form type unfortunately has some restrictions and features that other form types do not have. This is configured in forms -> type option.

Simple Forms

forms:
  type: SIMPLE
  title: "My Form"
  body: "Click one of the buttons!"
  options:
    first-button:
      text: "First Button"
    second-button:
      text: "Second Button"
    third-button:
      text: "Third Button"

Supported Structures:

• Title
• Body Text
• Buttons

Modal Forms

This button is the same as simple forms, but for some reasons it only works if it has exactly 2 buttons. And these buttons cannot have images.

forms:
  type: MODAL
  title: "My Form"
  body: "Click one of the buttons!"
  options:
    first-button:
      text: "First Button"
    second-button:
      text: "Second Button"

Supported Structures:

• Title
• Body Text
• Buttons (Must be exactly 2 buttons, images not supported)

Custom Forms

forms:
  type: CUSTOM
  title: "My Form"
  body: "Click one of the buttons!"
  options:
    first-button:
      text: "First Button"
    second-button:
      text: "Second Button"

Supported Structures:

• Title
• Body Text
• Sliders
• Step Sliders
• Dropdowns
• Inputs
• Labels
• Toggles

Form Component Types

Writing...

Buttons

Sliders

Dropdowns

Inputs

Labels

Toggles