v3 GUI System

⚠️ Usage ⚠️

The gui/menu feature is only available in spigot-jar.

TLDR

This wiki page will introduce a few GUI classes that are used in KamiMenu and/or PagedKamiMenu.
You should start here, then move onto the KamiMenu and PagedKamiMenu pages for more information.

MenuItem

KamiCommon has a MenuItem class that contains information about a given item for slot(s) of a menu.
It uses ItemSlot (see below) for slot management, click callbacks (see below), and IBuilder(s) for item management.
Note: Multiple item builders can be set for a single MenuItem, and the builderRotateTicks field will determine how fast it rotates between them.

MenuItem Click Sounds

MenuItem has the following methods to modify the click sound:

item.setClickSound(XSound.ITEM_GOAT_HORN_SOUND_0);
item.setClickVolume(1.0f);
item.setClickPitch(1.0f);

Click Interfaces

3 click interfaces exist, meant to provide access to common information at the time of click.
These are traditionally used with lambdas to provide code execution at a later time.

MenuClick

MenuClick provides a Player and ClickType in the callback.

MenuClick click = (player, clickType) -> {
    // your code here
};

MenuClickEvent

MenuClickEvent provides the Player, ClickType, and also the InventoryClickEvent in the callback.

MenuClickEvent click = (player, clickType, event) -> {
    // your code here
};

MenuClickPage

MenuClickPage provides the Player, ClickType, and the page number (for use with PagedKamiMenu) in the callback.

MenuClickPage click = (player, clickType, page) -> {
    // your code here, like opening a different page
};

ItemSlot

ItemSlot is an interface with two implementations: StaticItemSlot and LastRowItemSlot

StaticItemSlot

StaticItemSlot allows an item to be set in a specific set of slots.
It can be created with its constructors:

StaticItemSlot slot = new StaticItemSlot(0);
StaticItemSlot slot = new StaticItemSlot(0, 1, 2, 3, 4, 5, 6, 7, 8);
StaticItemSlot slot = new StaticItemSlot(List.of(0, 1, 2));

LastRowItemSlot

LastRowItemSlot allows an item to be set in the last row of the inventory, regardless of the inventory size.
It can be created with its constructors:

LastRowItemSlot slot = new LastRowItemSlot(0); // first slot in the last row
LastRowItemSlot slot = new LastRowItemSlot(4); // middle slot in the last row
LastRowItemSlot slot = new LastRowItemSlot(8); // last slot in the last row

IBuilderModifier

Items in KamiMenu are often modified by update tasks, which may include an IBuilder rotation or a developer-configured auto update.
To facilitate easy item management, IBuilderModifier provides a original copy of the IBuilder for modification each time it is updated. This interface can be used on a MenuItem, or with an ID through a Menu

KamiMenu myMenu = new KamiMenu("My Menu", 6);

// Use it through a MenuItem
// The modifier will be called each time the item needs to be updated
myMenu.addMenuItem(new ItemStack(Material.DIAMOND), 0).setModifier((builder) -> {
    // a basic example of updating the item data
    builder.setName("TimeStamp: " + System.currentTimeMillis());
    // This becomes really powerful when using the config loading system
    // Where this callback can be responsible for dynamically replacing placeholders
});


// Use it with the item ID system
myMenu.setModifier("MyItemId", (builder) -> {
    // modification code here
});

Auto Updating Items

Menu items in KamiCommon allow developers to configure an auto update interval. When configuring the auto-update, it sets the IBuilderModifier as the updater on the tick interval.

menu.setAutoUpdate("MyItemId", (builder) -> {
    // modification code here
}, 20); // 20 tick interval

menuItem.setAutoUpdate((builder) -> {
    // modification code here
}, 20); // 20 tick interval

NOTE: Using setAutoUpdate will set (therefore overriding) the modifier on the item. You should use EITHER setModifier OR setAutoUpdate, not both.

MenuSize

MenuSize is a wrapper class responsible for managing the type/size of an inventory.
It maintains EITHER a row count OR an InventoryType for the inventory.
You can pass your own MenuSize into the KamiMenu constructor, or use the default constructors for rows or inventory type.