User Interface (UI)

1{
2    "Group": "com.example",
3    "Name": "my-plugin",
4    "Version": "1.0.0",
5    "Main": "com.example.myplugin.MyPlugin",
6    "IncludesAssetPack": true
7}

1// File location: Common/UI/Custom/Pages/MyMod_Page.ui
2// Java reference:
3builder.append("Pages/MyMod_Page.ui");  // ✓ Correct
4
5// NOT these:
6builder.append("Common/UI/Custom/Pages/MyMod_Page.ui");  // ✗ Wrong
7builder.append("Custom/Pages/MyMod_Page.ui");            // ✗ Wrong
8builder.append("MyMod_Page.ui");                         // ✗ Wrong

1import com.hypixel.hytale.server.core.entity.entities.player.pages.BasicCustomUIPage;
2import com.hypixel.hytale.server.core.ui.builder.UICommandBuilder;
3import com.hypixel.hytale.server.core.universe.PlayerRef;
4import com.hypixel.hytale.protocol.packets.interface_.CustomPageLifetime;
5
6public class WelcomePage extends BasicCustomUIPage {
7    
8    private final String playerName;
9    
10    public WelcomePage(PlayerRef playerRef, String playerName) {
11        super(playerRef, CustomPageLifetime.CanDismiss);
12        this.playerName = playerName;
13    }
14    
15    @Override
16    public void build(UICommandBuilder commands) {
17        // Path relative to Common/UI/Custom/
18        commands.append("Pages/MyMod_WelcomePage.ui");
19        
20        // Set dynamic values using element selectors
21        commands.set("#Title.Text", "Welcome!");
22        commands.set("#PlayerName.Text", playerName);
23        commands.set("#Badge.Visible", true);
24    }
25}

1$C = "../Common.ui";
2
3$C.@PageOverlay {
4
5  $C.@Container {
6    Anchor: (Width: 600, Height: 400);
7
8    #Title {
9      Group {
10        $C.@Title {
11          @Text = "Welcome Page";
12        }
13      }
14    }
15
16    #Content {
17      LayoutMode: Top;
18      Padding: (Full: 20);
19
20      Label #PlayerName {
21        Style: (FontSize: 18, TextColor: #ffffff);
22        Anchor: (Bottom: 10);
23      }
24
25      Group #Badge {
26        Visible: false;
27        // Badge content...
28      }
29
30      Button #CloseButton {
31        Anchor: (Width: 200, Height: 50);
32        Background: (Color: #d4a054);
33        Style: (
34          Hovered: (Background: #e8b868),
35          Pressed: (Background: #a67c3d)
36        );
37
38        Label {
39          Style: (FontSize: 14, RenderBold: true, TextColor: #000000);
40          Text: "Close";
41        }
42      }
43    }
44  }
45}
46
47$C.@BackButton {}

1import com.hypixel.hytale.server.core.entity.entities.player.pages.InteractiveCustomUIPage;
2import com.hypixel.hytale.server.core.ui.builder.*;
3import com.hypixel.hytale.protocol.packets.interface_.*;
4import com.hypixel.hytale.codec.builder.BuilderCodec;
5import com.hypixel.hytale.codec.KeyedCodec;
6import com.hypixel.hytale.codec.Codec;
7
8public class ShopPage extends InteractiveCustomUIPage {
9    
10    private int playerCoins;
11    
12    public ShopPage(PlayerRef playerRef, int coins) {
13        super(playerRef, CustomPageLifetime.CanDismiss, ShopEventData.CODEC);
14        this.playerCoins = coins;
15    }
16    
17    @Override
18    public void build(
19        Ref ref,
20        UICommandBuilder commands,
21        UIEventBuilder events,
22        Store store
23    ) {
24        commands.append("Pages/ShopPage.ui");
25        commands.set("#coins-display", playerCoins + " coins");
26        
27        // Bind button click event
28        events.addEventBinding(
29            CustomUIEventBindingType.Activating,
30            "#buy-button",
31            EventData.of("Action", "buy").append("ItemId", "sword_01")
32        );
33        
34        // Bind close button
35        events.addEventBinding(
36            CustomUIEventBindingType.Activating,
37            "#close-button",
38            EventData.of("Action", "close")
39        );
40    }
41    
42    @Override
43    public void handleDataEvent(
44        Ref ref,
45        Store store,
46        ShopEventData data
47    ) {
48        if ("buy".equals(data.action)) {
49            // Handle purchase
50            playerCoins -= 100;
51            
52            // Update UI dynamically
53            UICommandBuilder update = new UICommandBuilder();
54            update.set("#coins-display", playerCoins + " coins");
55            // sendUpdate(update); // Send update to client
56        } else if ("close".equals(data.action)) {
57            // Close the page
58            // close();
59        }
60    }
61    
62    // Event data codec for deserializing client events
63    public static class ShopEventData {
64        public static final BuilderCodec CODEC = 
65            BuilderCodec.builder(ShopEventData.class, ShopEventData::new)
66                .append(new KeyedCodec<>("Action", Codec.STRING),
67                    (d, v) -> d.action = v, d -> d.action).add()
68                .append(new KeyedCodec<>("ItemId", Codec.STRING),
69                    (d, v) -> d.itemId = v, d -> d.itemId).add()
70                .build();
71        
72        public String action;
73        public String itemId;
74    }
75}

1// Must run on world thread!
2player.getWorld().execute(() -> {
3    // Get required references
4    Ref entityRef = player.getReference();
5    Store store = player.getWorld().getEntityStore().getStore();
6    
7    // Create and open page
8    WelcomePage page = new WelcomePage(player.getPlayerRef(), player.getName());
9    player.getPageManager().openCustomPage(entityRef, store, page);
10});
11
12// Open a built-in page
13player.getPageManager().setPage(entityRef, store, Page.Inventory);
14
15// Open page with windows (e.g., container + custom UI)
16player.getPageManager().openCustomPageWithWindows(entityRef, store, myPage, myWindow);

1UICommandBuilder commands = new UICommandBuilder();
2
3// Layout commands - load/modify UI structure
4commands.append("Pages/MyPage.ui");              // Load UI document
5commands.append("#container", "Components/Item.ui"); // Append to element
6commands.appendInline("#container", "
");  // Append inline markup
7commands.insertBefore("#target", "Components/Header.ui");
8commands.remove("#old-element");                 // Remove element
9commands.clear("#container");                    // Clear all children
10
11// Value commands - set element values
12commands.set("#text", "Hello World");           // String
13commands.set("#count", 42);                     // int
14commands.set("#progress", 0.75f);               // float
15commands.set("#enabled", true);                 // boolean
16commands.setNull("#optional");                  // null value
17commands.setObject("#complex", myObject);       // Object (needs codec)

1UIEventBuilder events = new UIEventBuilder();
2
3// Simple event binding
4events.addEventBinding(
5    CustomUIEventBindingType.Activating,  // Event type
6    "#my-button"                          // Element selector
7);
8
9// Event with data
10events.addEventBinding(
11    CustomUIEventBindingType.Activating,
12    "#buy-btn",
13    EventData.of("Action", "buy").append("Id", "123")
14);
15
16// Non-locking event (UI stays responsive while processing)
17events.addEventBinding(
18    CustomUIEventBindingType.ValueChanged,
19    "#slider",
20    EventData.of("Type", "volume"),
21    false  // locksInterface = false
22);

1// Create event data (key-value pairs)
2EventData data = new EventData();
3data = data.append("Action", "submit");
4data = data.append("Quantity", "5");  // Note: values are strings
5
6// Or use static factory
7EventData data = EventData.of("Action", "buy")
8    .append("ItemId", "sword")
9    .append("Price", "100");

1import com.hypixel.hytale.server.core.entity.entities.player.hud.CustomUIHud;
2import com.hypixel.hytale.server.core.ui.builder.UICommandBuilder;
3
4public class BossHealthHud extends CustomUIHud {
5    
6    private String bossName;
7    private float healthPercent;
8    
9    public BossHealthHud(PlayerRef playerRef, String bossName) {
10        super(playerRef);
11        this.bossName = bossName;
12        this.healthPercent = 1.0f;
13    }
14    
15    // Called when HUD is first shown
16    // Override the build method to set up initial UI
17    
18    public void updateHealth(float percent) {
19        this.healthPercent = percent;
20        
21        UICommandBuilder update = new UICommandBuilder();
22        update.set("#health-fill", healthPercent);
23        update.set("#health-text", Math.round(healthPercent * 100) + "%");
24        
25        // false = don't clear existing HUD, just update
26        update(false, update);
27    }
28}

1HudManager hudManager = playerComponent.getHudManager();
2
3// Set custom HUD (replaces any existing)
4hudManager.setCustomHud(playerRef, new BossHealthHud(playerRef, "Dragon"));
5
6// Remove custom HUD
7hudManager.setCustomHud(playerRef, null);
8
9// Get current custom HUD
10CustomUIHud currentHud = hudManager.getCustomHud();
11
12// Reset to default HUD state
13hudManager.resetHud(playerRef);
14
15// Reset entire UI state
16hudManager.resetUserInterface(playerRef);

1// Show only specific components
2hudManager.setVisibleHudComponents(playerRef,
3    HudComponent.Hotbar,
4    HudComponent.Health,
5    HudComponent.Chat,
6    HudComponent.Reticle
7);
8
9// Show additional components
10hudManager.showHudComponents(playerRef,
11    HudComponent.Compass,
12    HudComponent.Stamina
13);
14
15// Hide specific components
16hudManager.hideHudComponents(playerRef,
17    HudComponent.KillFeed,
18    HudComponent.PlayerList
19);

1WindowManager windowManager = playerComponent.getWindowManager();
2
3// Open a window
4windowManager.openWindow(myWindow);
5
6// Open multiple windows
7windowManager.openWindows(window1, window2);
8
9// Get window by ID
10Window window = windowManager.getWindow(windowId);
11
12// Get all open windows
13List windows = windowManager.getWindows();
14
15// Update window data
16windowManager.updateWindow(myWindow);
17
18// Close window by ID
19windowManager.closeWindow(windowId);
20
21// Close all windows
22windowManager.closeAllWindows();

1import com.hypixel.hytale.server.core.entity.entities.player.windows.ContainerWindow;
2import com.hypixel.hytale.server.core.inventory.container.ItemContainer;
3
4// Create container window from an ItemContainer
5ItemContainer container = // ... get or create container
6ContainerWindow window = new ContainerWindow(container);
7
8// Register close event
9window.registerCloseEvent(event -> {
10    // Handle window close
11    getLogger().info("Container closed");
12});
13
14// Open the window
15windowManager.openWindow(window);

1import com.hypixel.hytale.server.core.ui.Value;
2
3// Direct value
4Value<String> directValue = Value.of("Hello");
5
6// Reference to another UI element's value
7Value refValue = Value.ref("OtherPage.ui", "#element.property");

1import com.hypixel.hytale.server.core.ui.Area;
2
3Area area = new Area()
4    .setX(10)
5    .setY(20)
6    .setWidth(100)
7    .setHeight(50);
8
9commands.set("#element.area", area);

1import com.hypixel.hytale.server.core.ui.Anchor;
2
3Anchor anchor = new Anchor();
4anchor.setLeft(Value.of(10));
5anchor.setTop(Value.of(20));
6anchor.setWidth(Value.of(200));
7anchor.setHeight(Value.of(100));
8
9// Or use shortcuts
10anchor.setFull(Value.of(0));        // Fill parent
11anchor.setHorizontal(Value.of(10)); // Horizontal margins
12anchor.setVertical(Value.of(10));   // Vertical margins

1import com.hypixel.hytale.server.core.ui.PatchStyle;
2
3PatchStyle style = new PatchStyle()
4    .setTexturePath(Value.of("textures/button.png"))
5    .setBorder(Value.of(4))
6    .setColor(Value.of("#FF0000"));
7
8commands.set("#button.background", style);

1import com.hypixel.hytale.server.core.ui.ItemGridSlot;
2
3ItemGridSlot slot = new ItemGridSlot(itemStack)
4    .setName("Magic Sword")
5    .setDescription("A powerful weapon")
6    .setActivatable(true)
7    .setItemIncompatible(false);
8
9commands.set("#inventory-slot-0", slot);

1import com.hypixel.hytale.server.core.ui.LocalizableString;
2
3// From raw string
4LocalizableString text = LocalizableString.fromString("Hello World");
5
6// From localization key (for translations)
7LocalizableString localized = LocalizableString.fromMessageId("ui.welcome.title");
8
9// With parameters
10Map<String, String> params = Map.of("player", playerName);
11LocalizableString withParams = LocalizableString.fromMessageId("ui.welcome.greeting", params);

1import com.hypixel.hytale.server.core.ui.DropdownEntryInfo;
2
3// For dropdown/select elements
4DropdownEntryInfo entry = new DropdownEntryInfo(
5    LocalizableString.fromString("Option 1"),
6    "value_1"  // Internal value
7);

1// Open built-in page
2pageManager.setPage(ref, store, Page.Inventory);
3
4// Close any page
5pageManager.setPage(ref, store, Page.None);

1import com.hypixel.hytale.server.core.entity.entities.player.pages.RespawnPage;
2
3// Built-in respawn screen
4RespawnPage respawnPage = new RespawnPage(
5    playerRef,
6    Message.raw("You Died"),     // Death message
7    true,                        // Allow respawn
8    deathItemLoss               // Item loss config
9);
10
11pageManager.openCustomPage(ref, store, respawnPage);

1import com.hypixel.hytale.server.core.entity.entities.player.pages.choices.*;
2
3// ChoiceElement represents a selectable option
4// Extend ChoiceBasePage for custom dialog pages
5// Use ChoiceInteraction for what happens when selected
6// Use ChoiceRequirement for conditions to show/enable options

1public class FullShopPage extends InteractiveCustomUIPage {
2    
3    private final List items;
4    private int coins;
5    
6    public FullShopPage(PlayerRef playerRef, List items, int coins) {
7        super(playerRef, CustomPageLifetime.CanDismiss, EventData.CODEC);
8        this.items = items;
9        this.coins = coins;
10    }
11    
12    @Override
13    public void build(Ref ref, UICommandBuilder cmd, 
14                      UIEventBuilder evt, Store store) {
15        
16        cmd.append("Pages/Shop.ui");
17        cmd.set("#coins", coins);
18        
19        for (int i = 0; i < items.size(); i++) {
20            ShopItem item = items.get(i);
21            
22            // Add item entry to list
23            cmd.append("#item-list", "Components/ShopItem.ui");
24            cmd.set("#item-" + i + "-name", item.name);
25            cmd.set("#item-" + i + "-price", item.price);
26            cmd.set("#item-" + i + "-icon", item.icon);
27            
28            // Bind buy button
29            evt.addEventBinding(
30                CustomUIEventBindingType.Activating,
31                "#item-" + i + "-buy",
32                EventData.of("Action", "buy")
33                    .append("index", String.valueOf(i))
34            );
35        }
36        
37        // Close button
38        evt.addEventBinding(
39            CustomUIEventBindingType.Activating,
40            "#close",
41            EventData.of("Action", "close")
42        );
43    }
44    
45    @Override
46    public void handleDataEvent(Ref ref, Store store, 
47                                EventData data) {
48        switch (data.action) {
49            case "buy":
50                int index = Integer.parseInt(data.index);
51                ShopItem item = items.get(index);
52                
53                if (coins >= item.price) {
54                    coins -= item.price;
55                    // Give item to player...
56                    
57                    // Update UI
58                    UICommandBuilder update = new UICommandBuilder();
59                    update.set("#coins", coins);
60                    // sendUpdate(update);
61                }
62                break;
63                
64            case "close":
65                // close();
66                break;
67        }
68    }
69    
70    public static class EventData {
71        public static final BuilderCodec CODEC = /* ... */;
72        public String action;
73        public String index;
74    }
75}

1public class QuestTrackerHud extends CustomUIHud {
2    
3    private List activeQuests;
4    
5    public void addQuest(Quest quest) {
6        activeQuests.add(quest);
7        refreshQuestList();
8    }
9    
10    public void updateQuestProgress(String questId, int progress) {
11        UICommandBuilder update = new UICommandBuilder();
12        update.set("#quest-" + questId + "-progress", progress);
13        update(false, update);
14    }
15    
16    public void completeQuest(String questId) {
17        UICommandBuilder update = new UICommandBuilder();
18        update.remove("#quest-" + questId);
19        update(false, update);
20    }
21    
22    private void refreshQuestList() {
23        UICommandBuilder update = new UICommandBuilder();
24        update.clear("#quest-list");
25        
26        for (Quest quest : activeQuests) {
27            update.append("#quest-list", "Components/QuestEntry.ui");
28            update.set("#quest-" + quest.id + "-name", quest.name);
29            update.set("#quest-" + quest.id + "-progress", quest.progress);
30        }
31        
32        update(false, update);
33    }
34}