GUI Framework

GUI Framework

EverNifeCore's GUI layer wraps triumph-gui with two additions: complex GUIs whose items can refresh themselves on a timer, and a layout system for describing menus in config. Everything starts from FCGuiFactory.

Creating a GUI

FCGuiFactory returns triumph-gui builders. The plain ones (simple, storage, paginated) are the stock triumph builders; the complex variants produce EverNifeCore's auto-updating GUIs:

import br.com.finalcraft.evernifecore.minecraft.gui.FCGuiFactory;
import br.com.finalcraft.evernifecore.minecraft.gui.custom.GuiComplex;

GuiComplex gui = FCGuiFactory.complex()
        .title("&8My Menu")
        .rows(3)
        .create();

gui.setItem(13, FCItemFactory.from(Material.DIAMOND)
        .displayName("&bClick me")
        .asGuiItem(event -> event.getWhoClicked().sendMessage("clicked!")));

gui.open(player);

Factory method	Returns
simple()	triumph SimpleBuilder (a plain Gui).
complex()	ComplexGuiBuilder -> GuiComplex (auto-updating).
storage()	triumph StorageBuilder.
paginated()	triumph PaginatedBuilder.
paginatedComplex()	PaginatedComplexGuiBuilder -> PaginatedGuiComplex.
from(Class<B>)	Any builder class, resolved to one of the above or reflectively constructed.

The builder surface is triumph-gui's: .title(String), .rows(int), .type(GuiType) (chest, hopper, dispenser, ...), .disableAllInteractions(), then .create(). A finished GUI opens with gui.open(player) and closes with gui.close(player).

Lifecycle

The lifecycle of a GUI is create -> populate -> open -> (update) -> close:

1. Create a GuiComplex (or paginated variant) from the factory.
2. Populate it with items - a GuiItem (static) or a GuiItemComplex (self-updating). Each item may carry a click action.
3. Open it for a player. triumph-gui registers the inventory and its click handlers.
4. Update happens automatically for complex GUIs (below), or on demand via gui.update() / gui.softUpdate().
5. Close unregisters the view.

Auto-updating items

A GuiComplex participates in a single global update task that ticks every ECSettings.DEFAULT_GUI_UPDATE_TIME ticks (default 2) and refreshes every open complex GUI. Two hooks let you drive live content:

Per-item - use a GuiItemComplex and give it an update callback. Each item honours its own interval:

import br.com.finalcraft.evernifecore.minecraft.gui.item.GuiItemComplex;

GuiItemComplex clock = FCItemFactory.from(Material.CLOCK)
        .displayName("&eLoading...")
        .asGuiItemComplex();

clock.setUpdateInterval(20); // ticks between refreshes for THIS item
clock.setOnItemUpdate(ctx -> ctx.updateItemStack(builder ->
        builder.displayName("&eNow: " + System.currentTimeMillis()).build()));

gui.setItem(11, clock);

setOnItemUpdate(Consumer<GuiItemComplex.Context>) receives a Context exposing the gui, the item and the viewing player, plus updateItemStack(Function<FCItemBuilder, ItemStack>) to rebuild the icon.

Per-GUI - gui.setOnGuiUpdate(BiConsumer<Player, GuiComplex>) runs on the global cadence for each viewer, for whole-menu refreshes. gui.softUpdate() forces every complex item to update immediately.

Paginated GUIs

PaginatedGuiComplex (from FCGuiFactory.paginatedComplex()) adds paged content on top of GuiComplex. You declare which slots hold page content, add the paginated items, then navigate:

import br.com.finalcraft.evernifecore.minecraft.gui.custom.PaginatedGuiComplex;

PaginatedGuiComplex gui = FCGuiFactory.paginatedComplex()
        .title("&8Warps")
        .rows(6)
        .create();

gui.addPageSlot(/* the content slots */ 10, 11, 12, 13, 14, 15, 16);
for (Warp warp : warps) {
    gui.addPaginatedItem(FCItemFactory.from(warp.icon()).asGuiItem(e -> warp.teleport(player)));
}

gui.open(player);          // renders page 0

Navigation:

Method	Effect
next() / previous()	Move one page; return false when there is no page in that direction.
setPageNum(int)	Jump to a page (does not redraw until update()).
getCurrentPageNum() / getTotalNumberOfPages()	Current page (0-indexed) and page count.
addPageSlot(int...) / addPageSlotAll()	Declare which inventory slots hold paginated content.
clearPaginatedItems() / clearPaginatedItemsAndUpdate()	Empty the paged content.

Fixed decorations (a border, a "next" button, a title icon) are added with the normal setItem; only the declared page slots cycle as pages change.

PlayerGui and layouts

PlayerGui<P extends IPlayerData, G extends BaseGui> pairs a viewer (and optionally their player data) with a GUI and adds open(), close(), back-navigation (open(previousGui) / getPreviousGui()), and a CompoundReplacer that resolves player-data and PlaceholderAPI placeholders in titles and lore. When a class implements IHasLayout, setupLayout(...) builds the menu from a config-defined LayoutBase - titles, rows and background icons come from the layout file, and PAPI integration is applied when the layout requests it. See Placeholders for the replacer side.

See also

• Items and NBT - asGuiItem / asGuiItemComplex produce the icons a GUI holds.
• Placeholders - the CompoundReplacer used by PlayerGui titles and lore.
• PlayerData and PDSections - PlayerGui can bind a player's data.