Configurable GUIs
ObliviateInvs can manage your YAML configuration files to load GUIs. It is super useful for creating user-friendly plugins. Just to let you know, that carrying GUI codes to configuration files comes with some issues and restrictions. Because you have to support complex items like fireworks, books, etc. Also, your icons may need complex behavior and graphics.
ObliviateInvs solves these issues and breaks these restrictions. Also, we provided rich configuration stuff that came to our mind.
Copy the code blocks in steps 1,2,3.
Specify your menu configuration section/file to the API.
It's called a 'default table' because you can specify different configuration files for each GUI.
public class Test extends JavaPlugin {
@Override
public void onEnable() {
new InventoryAPI(this).init();
ConfigurableGuiCache.resetCaches(); //not obligatory but recommended at configuration reload methods.
GuiConfigurationTable.setDefaultConfigurationTable(new GuiConfigurationTable(getConfig()));
}
}Extend ConfigurableGui class. This class extends the Gui class. You cannot set the title and size of configurable GUIs in the constructor. These attributes are automatically set on init. If you want to override them, you can use setTitle, setSize methods after super() call.
The second parameter is the id of the GUI. This id will be used in configuration sections. If you want to change the section name but you don't want to change id of the GUI, then override getSectionPath() method.
public class ConfigurableTestGUI extends ConfigurableGui {
public ConfigurableTestGUI(Player player) {
super(player, "example-configurable-gui");
}
}Put icons on your GUI. Icons are split into two. Functional and Dysfunctional.
Dysfunctional icons are completely configuration file based and independent of any extra in-build code. You can add custom dysfunctional icons only using the config. For example, filler items.
Functional icons are executable icons. You must program these icons in-build.
Note: ObliviateInvs caches serialized itemstacks as itemstack (not as configuration section). Feel relaxed about using getIcon() or addConfigIcon() methods very often.
Passing names of functional icons is not required but if you don't, obliviate-invs will put these icons as dysfunctional until your addConfigIcon method overrides them. If you do not put the functional icons in some cases, this behavior may cause some misunderstanding for users.
@Override
public void onOpen(InventoryOpenEvent event) {
putDysfunctionalIcons("functional-test-icon"); // passing functional icons' names are recommended
addConfigIcon("functional-test-icon").onClick(e -> {
player.sendMessage("You clicked");
});
}example-configurable-gui:
title: 'Custom Title'
row: 5
icons:
filler-item:
material: BLACK_STAINED_GLASS_PANE
display-name: '&a'
slot: 0-8
functional-test-icon:
material: DIAMOND_BOOTS
display-name: '&aGem'
slot: 4
enchantments:
- 'DEPTH_STRIDER:1'
item-flags:
#- 'HIDE_ENCHANTS'
- '*'You must specify the sections below in your config file.
example-configurable-gui:
title: 'Custom Title'
row: 5
icons:
functional-test-icon:
material: DIAMOND_BOOTS
slot: 4
Also, you can get dysfunctional icons using:
List<DysfunctionalIcon> = super.getDysfunctionalIcons()GUI Configuration Tables define your GUI config and their section names. For example, imagine that you want to make different configuration files for each gui thennnn you have to make different gui configuration tables for each gui. Also, GUI configuration files define section names too.
new MyConfigurableGui(player, "gui-id", new GuiConfigurationTable(getConfig())).open();example-configurable-gui:
title: 'Custom Title'
row: 5
icons:
functional-test-icon:
material: DIAMOND_BOOTS
slot: 4new GuiConfigurationTable(myMenuConfig).setMaterialSectionName("type");Changes the 'material' section name to 'type' for GUIs in myMenuConfig.
example-configurable-gui:
title: 'Custom Title'
row: 5
icons:
functional-test-icon:
type: DIAMOND_BOOTS #<----
slot: 4Sometimes developers need to edit itemstacks before they are added to the GUI. For example, you may want to apply skin to player heads.
Example:
addConfigIcon("any-icon", item -> {
if (!(item.hasItemMeta() && item.getItemMeta() instanceof SkullMeta meta)) return item;
meta.setOwningPlayer(Bukkit.getOfflinePlayer(player.getUniqueId()));
item.setItemMeta(meta);
return item;
}).onClick(e -> {
//handle click event
});Sometimes you may need to deserialize itemstacks manually. obliviate-invs uses mc.obliviate.inventory.configurable.util.ItemStackSerializer.class to deserialize.
ItemStack item = ItemStackSerializer.deserializeItemStack(section, guiConfigurationTable);This method deserializes a configuration as an itemstack. This method parses item type, name, lore, amount, durability, enchantment, item flags, custom model data and unbreakability. However, this method does not parse placeholders because this type of itemstack must be raw to caching itemstacks and applying placeholders at runtime.
PlaceholderUtil placeholderUtil = new PlaceholderUtil().add("{any_placeholder}", textValueOfThePlaceholder);
ItemStackSerializer.applyPlaceholdersToItemStack(item, placeholderUtil);example-root-section:
item:section variable defines example-root-section.item.
ItemStackSerializer.serializeItemStack(item, section);example-root-section:
item:
material: STONE
display-name: 'a stone'Some item stacks have complex metadata. For example; potions, banners, fireworks, enchanted books, written books, and skulls. ItemStack Serializer of obliviate-invs is not designed for these metadatas but it does a favor for developers. The serializer is called Bukkit's own serializer methods.
item1:
material: DIAMOND_CHESTPLATE
item2:
bukkit-serializing: true
item:
==: org.bukkit.inventory.ItemStack
type: ENCHANTED_BOOK
meta:
==: ItemMeta
meta-type: ENCHANTED
stored-enchants:
PROTECTION_PROJECTILE: 4- item1 is a simple diamond chestplate. It doesn't have any metadata.
- item2 is an enchanted book. Enchantment books have custom NBTs for storing enchantments. So, the serializer is called Bukkit's serializer.
Defines title text of the Gui.
title: 'Select a game to play'
Defines row amount of the GUI.
row: 5
Defines slot of the icon. If the icon is a dysfunctional icon, you can specify multiple slot.
Examples:
slot: 5
Dysfunctional Icon only:
slot: 1,3,5
slot: 1-5 (represents 1,2,3,4,5)
Defines type of the icon
Examples:
material: STONE
Defines the name of the icon.
Examples:
display-name: 'Gem'
Defines description of the icon.
Examples:
lore:
- 'line 1'
- 'line 2'Defines amount of the icon.
Examples:
amount: 5
Defines enchantments of the icon. (supports enchanted books)
Examples:
enchantments:
- 'PROTECTION:2'
- 'UNBREAKING:5'Defines custom model data of the icon. (only supports 1.14+ servers)
Examples:
custom-model-data: 500
defines durability/damage of the icon.
Examples:
durability: 30
Defines the icon is unbreakable or not. (only supports 1.11+ servers)
Examples:
unbreakable: true
Defines item flags of the icon. You can hide additional informations from the item. '*' wildcard is allowed.
Examples:
item-flags:
- '*'item-flags:
- 'HIDE_ENCHANTS'Defines the icon should glow or not. If the icon is enchanted glow section does not matter. This section adds an enchantment and hides using item flags.
Examples:
glow: true