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
      - item: {}
        priority: 0
        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.

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);
• 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