GUI For Developers

This section is dedicated to developers. If you are looking for the admins' 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 offer an easy to use, fast and reliable system to create and manage user menus. There are many types of GUIs available, which will be later introduced.

For now, we will focus on the common aspects for all of them.

Table of Contents
Contents
Title
Size
Movable Slots
Variables
Actions
Types

Contents

Assuming a GUI object is already been created, it can be populated using many contents. These describe the elements of the GUI, they can be user-defined and are interchangeable.

In particular, a GUI is divided into slots for which one can specify one or more contents that will be displayed accordingly based on certain criteria.

GUI gui;
Item first;
Item second;
/* ... */
// Second will be displayed as first
gui.setContents(0, ItemGUIContent.newInstance(first).setPriority(0))
        .setContents(0, ItemGUIContent.newInstance(second).setPriority(10));

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

Title

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

GUI gui;
/* ... */
gui.setTitle("&cSuper GUI");

Size

The size of the GUI represents how many slots are present in the GUI. It is defined upon creating the GUI, it is usually a number multiple of 9 and not higher than 54 (there are exceptions) and **cannot be changed after creating the GUI (unless a Resizable GUI is used).

Movable Slots

When adding a content to the GUI, by default they will be set as unmovable. This means that, upon interacting, the viewer will not be able to pick up the item and move it around. To change this, movable slots are introduced. A GUI can have one, some or all its slots set as movable (which will effectively convert it to an inventory).

GUI gui;
/* ... */
gui.setMovable(3, true).setMovable(7, false);
// In case every slot should be movable
gui.setAllMovable();

NOTE: even though it is specified per slots, the movable attribute is bound to the contents. This means that when a movable element is moved to a non-movable slot, it will retain its mobility. In other words, non-movable elements remain non-movable and viceversa.

Variables

Variables allow to define internal parameters in the GUI. This is extremely helpful for two reasons:

• to avoid repetition of strings and ease changing them (think of the server or player name, or even an event);
• to allow the developer to use dynamic values inside their GUIs. Think of a GUI that should change its title based on the player's name. This can be easily done thanks to the use of variables.

  public void openPlayerMoneyGUI(Viewer viewer, Player target) {
      GUI gui;
      /* ... */
      // The "<player>" string will be replaced with target's actual name
      gui.setTitle("<player>'s balance")
              .setVariable("player", target.getName())
              .open(viewer);
  }

This is also very helpful when working with 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

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: 1
    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: 1
    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
  # ...