UltimateUI guide

Example Usages

Example uses of the API for UltimateUI.

On this page, you will find example uses of UltimateUI API. Below are examples showing how the API can be used in your plugin.

Core Access#

Access the API singleton and check its availability before running your logic.

java

if (UltimateUIAPI.isAvailable()) {
    UltimateUIAPI api = UltimateUIAPI.get();
}

Opening UIs#

Open full-screen menus or HUD overlays for single players or groups.

java

UltimateUIAPI api = UltimateUIAPI.get();

// Single Player

api.openGui(player, "main_menu");
api.openGui(player, "intro_anim", true); // autoClose enabled
api.openGuiHud(player, "stats_overlay");

// Bulk Opening (Multiple Players)

List❮Player❯ team = getTeamPlayers();
api.openGui(team, "victory_screen", false, true); // hudMode: false, autoClose: true

Building UIs in Code#

Create a complete page programmatically with UiBuilder, then save it and open it — the page is written to pages/.yml and behaves like a hand-authored one. See the Building UIs page for the full method reference.

java

UltimateUIAPI api = UltimateUIAPI.get();

UiBuilder builder = api.createGui("daily_rewards")
    .screenSize(1920, 1080)
    .addBlock("background", 660, 240, 600, 600, "#101418")
    .addText("title", "<bold>Daily Rewards</bold>", 760, 280, 400, 48, "#ffd966")
    .addItem("reward_icon", "DIAMOND", 910, 460, 100, 100);

api.openGui(player, builder);             // save + open as a cursor menu
// api.openGuiHud(player, builder, true); // or as an auto-closing HUD overlay

Closing UIs#

Close all active interfaces or specific pages for players.

java

// Close everything for one player

UltimateUIAPI.get().closeGui(player);

// Close a specific page for a group of players

List❮Player❯ competitors = getPlayers();
int closedCount = UltimateUIAPI.get().closeGui(competitors, "lobby_timer");

Checking Current UI#

Check whether the player currently has any UI open.

java

public void checkUi(Player player, String uiName) {
    if (UltimateUIAPI.get().isGuiOpen(player, uiName)) {
        player.sendMessage("§aYes");
    } else {
        player.sendMessage("§cNo");
    }
}

if (UltimateUIAPI.get().isGuiOpen(player)) {
    player.sendMessage("§aSuccess!");
}

Session & State#

Check if a player has a GUI open and retrieve detailed session snapshots.

java

boolean active = UltimateUIAPI.get().isGuiOpen(player);
String currentGui = UltimateUIAPI.get().getOpenGuiName(player);

UiSession session = UltimateUIAPI.get().getSession(player);
if (session != null) {
    boolean isHud = session.isHudMode();
    boolean willAutoClose = session.isAutoClose();
}

Asset Management#

Verify and list available GUI configurations stored on the disk.

java

boolean exists = UltimateUIAPI.get().guiExists("example_ui");
List‹String› allGuis = UltimateUIAPI.get().listGuis();

Interaction Handling (Events)#

Handle player clicks on UI elements via the Java Event API.

java

@EventHandler
public void onUiClick(UltimateUIBlockClickEvent event) {
    if (event.getBlockId().equals("confirm_button")) {
        event.getPlayer().sendMessage("Action confirmed!");
        event.setCancelled(true); // Blocks the YAML runtime action
    }
}

Updating Elements#

Modify UI properties in real-time while a player has an active session.

java

UltimateUIAPI api = UltimateUIAPI.get();

// Update text
api.setElementText(player, "text1", "Hello world!");
api.setElementColor(player, "text1", "#00ff88");

// Change block size and pos
api.setElementPosition(player, "block1", 120.0, 48.0);
api.setElementScale(player, "block1", 280.0, 36.0);

// Change item
api.setElementItem(player, "item1", "DIAMOND");
api.setElementItem(player, "profile_head", "PLAYER_HEAD:Notch");

// Modifying properties via paths
api.setElementValue(player, "text1", "opacity", 180);
api.setElementValue(player, "text1", "style.bold", true);
api.setElementValue(player, "text1", "rotation", 45.0);

Category	Property Paths	ValueType
Transform	`x`, `y`, `width`, `height`, `rotation`, `layer`, `depth`	`Number`
Visuals	`text`, `unicode`, `color`, `opacity`, `text-wrap`	`String/Number`
Visibility	`visibility.visible`, `visibility.placeholder`	`Boolean`
Alignment	`align`, `anchor`, `hud.aligned`	`String/Boolean`
Items	`item.material`, `custom_model_data`, `enchants`, `glowing`	`String/Number/Boolean`
Pivot	`pivot.x`, `pivot.y`, `pivot.normalized`, `pivot.mode`	`Number/Boolean`
Rounding	`rounding` (small, regular, etc.), `rounding.unicode`, `rounding.unicode.[corner]`, `rounding.[corner].[x/y]`	`String`