GUI Contents 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

Each GUI may contain one or more visual elements (contents) for aesthetics or functional purposes. The goal of this page is to illustrate how objects and their utilities can be implemented via a configuration file.

Say, for example, we want to define the content displayed on the first slot of the GUI. What we can do is specify a list of objects under the contents section:

gui:
  contents:
    '0': # The slot of the GUI, where zero is the first one.
      - # ...

Note that we are using a dash (-) to indicate that we may specify more than one content. This becomes useful when dealing with fallback contents in case a certain priority or requirement is not met.

Having said that, a content can be defined in the item section just as shown in the item configuration page:

gui:
  contents:
    '0':
      - item:
          material: stone_sword
          amount: 1
          durability: 1337
          display-name: "Strong sword"
          lore: []
          enchantments: []
          item-flags: []
          unbreakable: false
          custom-model-data: 1
        type: ITEM

NOTE: as of right now, specifying the type is useless, as there is only one implementation of GUI contents, but more might be implemented in the future.

This is the most basic configuration for a content, but more elements can be added to further customize the behavior of the object. We will go through each option one by one to analyze them deeply and understand their meaning:

Table of contents
Requirements
Priorities
Sound
Actions
Variables

Requirements

As the name suggests, specifying the requirement option will declare if the viewer can see the said content or not. If the user does not meet the specified requirements, they will not be able to visualize the object, and might see a fallback item instead.

At the time of writing this guide, requirements can be of two types:

• PERMISSION_REQUIREMENT, a string that represents a Minecraft permission. If the player does not have the said permission, they will be refused;

  requirements:
    type: PERMISSION_REQUIREMENT
    content: "bukkit.command.version"

• developer-defined, an apparently random combination of numbers and letters which should not be touched (only the developer has control over it).

Priorities

The priority option allows specifying which content will be shown first, in case two or more are specified for the same slot. This is useful mainly during configuration and testing phases, but it can also be used in conjunction with the requirements of the contents.

Say two contents with requirements are specified, and the viewer has both the requirements. Stating the priority of the objects will help the GUI to understand which one should be displayed and which one should be hidden.

The priority is a natural number (positive non-decimal), where the higher will be privileged over the others.

gui:
  contents:
    '0':
      - item: {}
        priority: 10
        type: ITEM

Sound

The sound option can be specified as previously described and represents the sound that will be played when the user clicks on the content.

Actions

The action option allows defining the behavior of the content upon interacting (clicking) with it. An action can be defined with its type and its content, and there are three types of actions:

• GUI_ITEM_COMMAND: requires a command to be specified in the content section;

  click-action:
    type: GUI_ITEM_COMMAND
    content: "say Hello"

• GUI_ITEM_CLOSE: closes the current GUI (the content can be not declared);

  click-action:
    type: GUI_ITEM_CLOSE

• developer-defined: in this case, there will usually be a strange name as the type, and the content will be an apparently random combination of numbers and letters. This means that the developer defined a customized action for the interaction with the content, that cannot be edited by the user.

Variables

Similarly to what happens for GUIs, also contents accept variables that can be declared in this section. They will be then replaced upon displaying the full content:

gui:
  contents:
    '0':
      - item:
          material: stone_sword
          amount: 1
          durability: 1337
          display-name: "<name>"
        variables: 
          name: "Strong sword"
        type: ITEM

To view the default variables, please check out the Glossary.