GUI For Server Admins

This section is dedicated to server admins. If you are looking for the developers' page, click here

Many of the fields referenced on this page might be or require platform-specific values. Check the glossary

GUIs are the main focus and the reason why this library has been created. They are graphical interfaces that can be manipulated via the configuration file to display proper content to the user. While there are different types of GUIs, most of them are similar and can be interchanged.

In this section, we will first look over the common options, then we will take a deeper look to the various types and their advantages.

Table of Contents
Contents
Title
Size
Movable Slots
Variables
Actions
Types

Contents

The main thing that one might be interested in is adding content in the GUI. Contents are elements on the page that can be interacted with and will display information to the viewer.

Since GUIs are divided in slots, for each, one or more content can be indicated. This is possible to allow fallback objects to show in case certain conditions are not met. So, for example, to add two contents on slot 0, it is possible to use a list:

gui:
  contents:
    '0':
      # First
      - item: {} 
        priority: 0
        type: ITEM
      # Second will be displayed as first
      - item: {}
        priority: 10
        type: ITEM

There is a full guide dedicated to contents that is highly advised to better understand how to properly configure this section.

Title

As the name suggests, the title is the name that will appear on top of the GUI. Colored names with the & character can be used.

gui:
  title: "&cSuper GUI"

Size

The size of the GUI is responsible for the number of slots in the page. Except for certain cases, this number has to be a multiple of 9 and not higher than 54.

gui:
  size: 45

Movable Slots

By default, each content added to the GUI will not be movable. This means that, upon interacting, the viewer will not be able to pick up the item and move it around. This behavior can be changed by specifying for which contents in the slots this should be allowed.

gui:
  movable-slots:
    - 3
    - 7

NOTE: this description only applies when first showing the GUI. Moving a movable object from a movable slot to a non-movable one, will not make it non-movable.

Variables

Variables are a special option of the GUIs that allow the configurator to define commonly used words or phrases inside the GUI. Say the configuration is something along the lines of:

gui:
  variables:
    name: "Super cool GUI"

What this means is that everytime the word <name> is present in the GUI (for example in the title, or in the contents names, lores, materials or anything else literal), it will be replaced with Super cool GUI.

This is useful both for server admins, for example, when setting the name of a server or to display the name of the player, but also for developers, that might use this technique for more advanced GUIs. To view the default variables, please check out the Glossary.

Actions

As the name suggests, actions are tasks executed in response to certain events happening. At the time of writing, there are four supported events:

• opening the GUI (open-gui-action);
• closing the GUI (close-gui-action);
• clicking outside the GUI (click-outside-action);
• closing the GUI because another one is being opened (change-gui-action);
• clicking on a content (check the dedicated section).

To define an action, you can specify one of the given keywords as a section, and declare its type and content:

gui:
  open-gui-action:
    type: GUI_COMMAND
    content: "say I opened the GUI!"

At the moment, only the type GUI_COMMAND (BI_GUI_COMMAND for change-gui-action) is allowed, that will force the viewer to execute the specified command.

Types

Now that we overlooked all the common features of the GUIs, we can focus on specific types with different uses.

Default

As the name suggests, this is the default type, which requires the size to be a multiple of 9 not higher than 54.

gui:
  type: DEFAULT

Resizable

Virtually the same as default, grants benefits only to the developer.

gui:
  type: RESIZABLE

Type

Defines a special GUI from one of the inventories already present in game. This is useful for creating custom anvils, workbenches, furnaces, hoppers and more. Check out the glossary to see all the available types.

gui:
  type: TYPE

Pageable

This is a special type of GUI that allows to create links among many interfaces. What this means is that it is possible to define one general GUI with common contents, title, size and type. Then, you can add as many pages as you'd like, and they will all have the previously defined values (unless overwritten). For example, it is possible to define a content just for the first page, one for the second and so on.

gui:
  type: PAGEABLE
  pages: 4
  # These settings apply to all the pages
  contents: {} # The common contents
  movable-slots: [] # The common movable slots
  variables:
    hello: "friend"
  size: 9
  gui-type: DEFAULT # The type of the GUIs, from the previously defined ones
  # Individual GUIs settings
  gui-pages:
    # Settings for the first page
    '0':
      title: "First page"
    # Settings for the second page; will override the previous variable
    '2':
      variables:
        hello: "world"
    # Settings for the third page
    '3':
      movable-slots:
        - 3

NOTE: in order to access the previous or the next page, two other options are available: next-page and previous-page. They require a number as the slot where they will be placed in, and a content:

gui:
  type: PAGEABLE
  # ...
  previous-page:
    slot: 3
    content:
      item:
        material: paper
        amount: 1
        durability: 0
        display-name: '&ePrevious Page'
        lore: []
        enchantments:
          - unbreaking:3
        item-flags:
          - hide_unbreakable
        unbreakable: false
        custom-model-data: 0
      priority: 0
      variables: {}
      type: ITEM
  next-page:
    slot: 5
    content:
      item:
        material: paper
        amount: 1
        durability: 0
        display-name: '&eNext Page'
        lore: []
        enchantments:
          - unbreaking:3
        item-flags:
          - hide_unbreakable
        unbreakable: false
        custom-model-data: 0
      priority: 0
      variables: {}
      type: ITEM

Data

Data GUIs are an extension of Pageable ones that help the developer display multiple information in GUIs in a simple and convenient way. They have the same configuration as Pageable, so for the server admin these types are basically the same.

gui:
  type: DATA
  pages: 4
  # ...