GUI Contents For Developers

This section is dedicated to developers. 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

In this guide, we will go over the creation and management of GUI contents, the elements that will be displayed upon opening the GUIs. The goal of this page is to teach the developer how they can create, manage interactions and special effects with these objects.

At the moment, only one implementation is present: ItemGUIContent. Since this class inherits from Item, its creation is very similar to one of them, thanks to the method chaining system:

ItemGUIContent.newInstance("stone_sword").setDisplayName("Strong sword").setDurability(1337);

This means that all the Item methods are available, and the content can be handled as such. One might even create an Item first, and then convert it to an ItemGUIContent using the copy(Class) method:

Item.newItem().setMaterial("dye").setDurability(4).setDisplayName("&9Custom Lapis Lazuli").copy(ItemGUIContent.class);

However, GUI contents allow further customization and more control over normal items. 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

The display of GUI contents can be controlled thanks to requirements. It is possible for certain elements to be hidden or replaced for users who do not meet some conditions. This can be done with the GUIContent#setViewRequirements(RequirementChecker) method in two ways:

• using PermissionRequirement: a special type of requirement that will check if the viewer has the specified Minecraft permission;

  ItemGUIContent.newInstance().setViewRequirements(new PermissionRequirement("bukkit.command.version"));
  // Or, short version
  ItemGUIContent.newInstance().setViewRequirements("bukkit.command.version");

• using RequirementChecker, a general functional interface that accepts a lambda function with the viewer as the parameter and requires a boolean to be returned.

  ItemGUIContent.newInstance().setViewRequirements(viewer -> viewer.getName().equals("Fulminazzo"));

Priorities

The priority allows defining which content should be displayed first in the case of a conflict. Being of type int, negative values are allowed, but natural numbers are to be preferred. The content with higher priority will be displayed first.

GUIContent content = ItemGUIContent.newInstance(); 
// ...
content.setPriority(10);

Sound

As the name of the method suggests, the developer can define a sound that will be played upon interacting (clicking) the content. The sound has to be of type Sound from the wrappers module.

GUIContent content = ItemGUIContent.newInstance(); 
// ...
content.setClickSound(new Sound("VILLAGER_HAPPY", 10.0F, 1.0F));

Actions

It is possible to define various actions upon interacting with the content, in addition to the already viewed click sound. At the time of writing, there are three types available:

• GUIItemCommand, will force the user to execute the given command;

  ItemGUIContent.newInstance().onClickItem(new GUIItemCommand("say Hello"));
  // Or, short version
  ItemGUIContent.newInstance().onClickItem("say Hello");

• GUIItemClose, will close the GUI;

  ItemGUIContent.newInstance().onClickItem(new GUIItemClose());
  // Or, short version
  ItemGUIContent.newInstance().onClickItemClose();

• GUIItemAction, a general functional interface that accepts a lambda function with the viewer, the gui and the content itself as the parameters.

  ItemGUIContent.newInstance().onClickItem((v, g, c) -> v.sendMessage("You clicked me!"));
  // Or, for commands only
  ItemGUIContent.newInstance().onClickItem("say I clicked on a content!");

NOTE: when serializing the content, it will NOT always be possible to translate lambda functions. Therefore, if the only action being executed is the forced execution of commands, string methods are to be preferred, in order to have a clean and minimal saving of the object.

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:

GUIContent content = ItemGUIContent.newInstance(); 
// ...
content.setVariable("name", "Strong sword");

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