# UI System

The Hytale server implements a server-authoritative UI system with two main subsystems: Pages (full-screen UI) and
Windows (inventory-style containers).

## Architecture Overview

```
UI System
├── Pages System - Full-screen UI (dialogs, menus, custom UIs)
│   ├── CustomUIPage - Base page class
│   ├── UICommandBuilder - DOM manipulation
│   └── UIEventBuilder - Event bindings
└── Windows System - Inventory-style containers
    ├── Window - Base window class
    └── WindowManager - Window lifecycle
```

## Page System

### Core Classes

| Class                        | Package                                                       | Description                             |
|------------------------------|---------------------------------------------------------------|-----------------------------------------|
| `CustomUIPage`               | `com.hypixel.hytale.server.core.entity.entities.player.pages` | Abstract base for all custom pages      |
| `BasicCustomUIPage`          | Same                                                          | Simple pages without event data parsing |
| `InteractiveCustomUIPage<T>` | Same                                                          | Pages with typed event handling         |
| `PageManager`                | Same                                                          | Manages page state for a player         |
| `UICommandBuilder`           | `com.hypixel.hytale.server.core.ui.builder`                   | Builds UI DOM commands                  |
| `UIEventBuilder`             | Same                                                          | Builds event bindings                   |

### Page Lifetime

```java
public enum CustomPageLifetime {
    CantClose(0),                           // User cannot close
    CanDismiss(1),                          // ESC key to dismiss
    CanDismissOrCloseThroughInteraction(2)  // Dismiss or click to close
}
```

### CustomUIPage Base Class

```java
public abstract class CustomUIPage {
    protected final PlayerRef playerRef;
    protected CustomPageLifetime lifetime;
    
    // Build the UI - called to construct the page
    public abstract void build(Ref<EntityStore> ref, UICommandBuilder cmd, 
                              UIEventBuilder events, Store<EntityStore> store);
    
    // Handle event data from client
    public void handleDataEvent(Ref<EntityStore> ref, Store<EntityStore> store, String rawData);
    
    // Rebuild entire page
    protected void rebuild();
    
    // Send partial update
    protected void sendUpdate(UICommandBuilder commandBuilder, boolean clear);
    
    // Close the page
    protected void close();
    
    // Called when page is dismissed by user
    public void onDismiss(Ref<EntityStore> ref, Store<EntityStore> store);
}
```

### InteractiveCustomUIPage<T>

For pages with typed event handling:

```java
public abstract class InteractiveCustomUIPage<T> extends CustomUIPage {
    protected final BuilderCodec<T> eventDataCodec;
    
    public InteractiveCustomUIPage(PlayerRef playerRef, CustomPageLifetime lifetime, 
                                   BuilderCodec<T> eventDataCodec) {
        super(playerRef, lifetime);
        this.eventDataCodec = eventDataCodec;
    }
    
    // Override this for type-safe event handling
    public void handleDataEvent(Ref<EntityStore> ref, Store<EntityStore> store, T data);
    
    // Send update with new event bindings
    protected void sendUpdate(UICommandBuilder cmd, UIEventBuilder events, boolean clear);
}
```

## UICommandBuilder

Builds commands to manipulate the UI DOM structure.

### Command Types

```java
public enum CustomUICommandType {
    Append(0),           // Append UI document
    AppendInline(1),     // Append inline XML
    InsertBefore(2),     // Insert before element
    InsertBeforeInline(3),
    Remove(4),           // Remove element
    Set(5),              // Set property value
    Clear(6)             // Clear children
}
```

### Methods

```java
UICommandBuilder cmd = new UICommandBuilder();

// Load UI documents
cmd.append("Pages/MyPage.ui");                    // Load to root
cmd.append("#Container", "Common/Button.ui");    // Append to selector

// Clear and remove
cmd.clear("#ItemList");                          // Clear children
cmd.remove("#OldElement");                       // Remove element

// Set property values
cmd.set("#Title.Text", "Hello World");           // String
cmd.set("#Counter.Value", 42);                   // Integer
cmd.set("#Progress.Value", 0.75f);               // Float
cmd.set("#Panel.Visible", true);                 // Boolean
cmd.set("#Label.Text", Message.translation("key")); // Localized

// Set with Value references
cmd.set("#Button.Style", Value.ref("Common/Button.ui", "ActiveStyle"));

// Set complex objects
cmd.setObject("#ItemSlot", itemGridSlot);        // Single object
cmd.set("#SlotList", itemGridSlotArray);         // Array
cmd.set("#DataList", itemList);                  // List

// Inline XML
cmd.appendInline("#Container", "<Panel Id='NewPanel'/>");
cmd.insertBefore("#Element", "Pages/Header.ui");
```

### Selector Syntax

- `#ElementId` - Select by ID
- `#Parent #Child` - Descendant selector
- `#List[0]` - Index accessor (for lists)
- `#List[0] #Button` - Combined
- `#Element.Property` - Property accessor

## UIEventBuilder

Builds event bindings that trigger server callbacks.

### Event Binding Types

```java
public enum CustomUIEventBindingType {
    Activating(0),           // Click/press
    RightClicking(1),        // Right-click
    DoubleClicking(2),       // Double-click
    MouseEntered(3),         // Mouse enter
    MouseExited(4),          // Mouse leave
    ValueChanged(5),         // Input value changed
    ElementReordered(6),     // Drag reorder
    Validating(7),           // Input validation
    Dismissing(8),           // Page dismiss
    FocusGained(9),          // Element focused
    FocusLost(10),           // Element unfocused
    KeyDown(11),             // Key pressed
    MouseButtonReleased(12), // Mouse released
    SlotClicking(13),        // Inventory slot click
    SlotDoubleClicking(14),  // Slot double-click
    SlotMouseEntered(15),    // Slot hover enter
    SlotMouseExited(16),     // Slot hover exit
    DragCancelled(17),       // Drag cancelled
    Dropped(18),             // Item dropped
    SlotMouseDragCompleted(19),
    SlotMouseDragExited(20),
    SlotClickReleaseWhileDragging(21),
    SlotClickPressWhileDragging(22),
    SelectedTabChanged(23)   // Tab selection
}
```

### Methods

```java
UIEventBuilder events = new UIEventBuilder();

// Simple binding
events.addEventBinding(CustomUIEventBindingType.Activating, "#CloseButton");

// With event data
events.addEventBinding(CustomUIEventBindingType.Activating, "#SubmitButton",
    EventData.of("Action", "Submit"));

// Without interface lock (for non-blocking events)
events.addEventBinding(CustomUIEventBindingType.MouseEntered, "#HoverArea",
    EventData.of("Action", "Hover"), false);

// With value extraction from element
events.addEventBinding(CustomUIEventBindingType.ValueChanged, "#SearchInput",
    EventData.of("@Query", "#SearchInput.Value"), false);
```

### EventData

```java
// Simple key-value
EventData.of("Action", "Submit")

// Multiple values
new EventData()
    .append("Type", "Update")
    .append("Index", "5")

// Value extraction (@ prefix)
EventData.of("@Value", "#InputField.Value")     // Extract from element
EventData.of("@Selected", "#Dropdown.Selected") // Extract selection
```

## Value References

The `Value<T>` class references values either directly or from UI documents.

```java
// Direct value
Value<Integer> count = Value.of(42);
Value<String> text = Value.of("Hello");

// Reference from UI document
Value<String> style = Value.ref("Common/Button.ui", "ActiveStyle");
Value<Integer> border = Value.ref("Pages/Dialog.ui", "BorderWidth");
```

### Encoding Format

References are encoded in JSON as:

```json
{
    "$Document": "Common/Button.ui",
    "@Value": "ActiveStyle"
}
```

## UI Data Types

### PatchStyle (9-Patch Styling)

```java
public class PatchStyle {
    Value<String> texturePath;
    Value<Integer> border;
    Value<Integer> horizontalBorder;
    Value<Integer> verticalBorder;
    Value<String> color;
    Value<Area> area;
}
```

### Area

```java
public class Area {
    int x, y, width, height;
}
```

### Anchor

```java
public class Anchor {
    Value<Integer> left, right, top, bottom;
    Value<Integer> width, height;
    Value<Integer> minWidth, maxWidth;
    Value<Integer> full, horizontal, vertical;
}
```

### ItemGridSlot

```java
public class ItemGridSlot {
    ItemStack itemStack;
    Value<PatchStyle> background, overlay, icon;
    boolean isItemIncompatible;
    boolean isActivatable;
    boolean isItemUncraftable;
    boolean skipItemQualityBackground;
    String name, description;
}
```

### LocalizableString

```java
LocalizableString.fromString("Hello")              // Plain string
LocalizableString.fromMessageId("key")             // Translation key
LocalizableString.fromMessageId("key", Map.of("name", "Player"))  // With params
```

## Complete Page Example

```java
public class ShopPage extends InteractiveCustomUIPage<ShopPage.ShopEventData> {
    
    private final List<ShopItem> items;
    
    public ShopPage(PlayerRef playerRef, List<ShopItem> items) {
        super(playerRef, CustomPageLifetime.CanDismiss, ShopEventData.CODEC);
        this.items = items;
    }
    
    @Override
    public void build(Ref<EntityStore> ref, UICommandBuilder cmd, 
                     UIEventBuilder events, Store<EntityStore> store) {
        // Load main layout
        cmd.append("Pages/ShopPage.ui");
        
        // Set title
        cmd.set("#Title.Text", Message.translation("shop.title"));
        
        // Build item list
        cmd.clear("#ItemList");
        for (int i = 0; i < items.size(); i++) {
            ShopItem item = items.get(i);
            String selector = "#ItemList[" + i + "]";
            
            cmd.append("#ItemList", "Pages/ShopElementButton.ui");
            cmd.set(selector + " #Name.Text", item.getName());
            cmd.set(selector + " #Price.Text", String.valueOf(item.getPrice()));
            cmd.setObject(selector + " #Icon", item.toItemGridSlot());
            
            events.addEventBinding(
                CustomUIEventBindingType.Activating,
                selector,
                EventData.of("Action", "Buy").append("Index", String.valueOf(i)),
                false
            );
        }
        
        // Close button
        events.addEventBinding(CustomUIEventBindingType.Activating, "#CloseButton",
            EventData.of("Action", "Close"));
        
        // Search input
        events.addEventBinding(CustomUIEventBindingType.ValueChanged, "#SearchInput",
            EventData.of("Action", "Search").append("@Query", "#SearchInput.Value"),
            false);
    }
    
    @Override
    public void handleDataEvent(Ref<EntityStore> ref, Store<EntityStore> store, 
                               ShopEventData data) {
        switch (data.action) {
            case "Close" -> close();
            case "Buy" -> {
                if (data.index >= 0 && data.index < items.size()) {
                    buyItem(ref, store, items.get(data.index));
                    // Update UI
                    UICommandBuilder cmd = new UICommandBuilder();
                    cmd.set("#Balance.Text", getPlayerBalance(ref, store));
                    sendUpdate(cmd, false);
                }
            }
            case "Search" -> {
                filterItems(data.query);
                rebuild();
            }
        }
    }
    
    public static class ShopEventData {
        public static final BuilderCodec<ShopEventData> CODEC = BuilderCodec
            .builder(ShopEventData.class, ShopEventData::new)
            .addField(new KeyedCodec<>("Action", Codec.STRING), 
                (d, v) -> d.action = v, d -> d.action)
            .addField(new KeyedCodec<>("Index", Codec.INTEGER), 
                (d, v) -> d.index = v, d -> d.index)
            .addField(new KeyedCodec<>("Query", Codec.STRING), 
                (d, v) -> d.query = v, d -> d.query)
            .build();
        
        String action;
        int index = -1;
        String query;
    }
}
```

## PageManager

```java
Player player = ...;
PageManager pageManager = player.getPageManager();

// Open custom page
pageManager.openCustomPage(ref, store, new ShopPage(playerRef, items));

// Open built-in page
pageManager.setPage(ref, store, Page.Inventory);
pageManager.setPage(ref, store, Page.None);  // Close

// Open page with windows
pageManager.openCustomPageWithWindows(ref, store, customPage, window1, window2);

// Get current custom page
CustomUIPage current = pageManager.getCustomPage();
```

### Built-in Pages

```java
public enum Page {
    None(0),            // No page
    Bench(1),           // Crafting bench
    Inventory(2),       // Player inventory
    ToolsSettings(3),   // Builder tools
    Map(4),             // World map
    MachinimaEditor(5), // Machinima
    ContentCreation(6), // Content creation
    Custom(7)           // Custom server page
}
```

## Window System

### Window Base Class

```java
public abstract class Window {
    public abstract JsonObject getData();
    protected abstract boolean onOpen0();
    protected abstract void onClose0();
    
    public void handleAction(Ref<EntityStore> ref, Store<EntityStore> store, WindowAction action);
    public void close();
    public void invalidate();  // Mark for update
    public void registerCloseEvent(Consumer<Window> callback);
}
```

### Window Types

```java
public enum WindowType {
    Container(0),
    PocketCrafting(1),
    BasicCrafting(2),
    DiagramCrafting(3),
    StructuralCrafting(4),
    Processing(5),
    Memories(6)
}
```

### WindowManager

```java
WindowManager wm = player.getWindowManager();

// Open window
OpenWindow packet = wm.openWindow(myWindow);

// Open multiple
List<OpenWindow> packets = wm.openWindows(window1, window2);

// Close
wm.closeWindow(windowId);
wm.closeAllWindows();

// Update
wm.updateWindow(window);
wm.updateWindows();  // Update all dirty

// Get window
Window w = wm.getWindow(windowId);
```

## HUD System

The HUD is a persistent UI layer separate from pages.

### CustomHud Packet

```java
public class CustomHud implements Packet {
    boolean clear;
    CustomUICommand[] commands;
}
```

### HUD Components

```java
public enum HudComponent {
    Hotbar(0), StatusIcons(1), Reticle(2), Chat(3),
    Requests(4), Notifications(5), KillFeed(6), InputBindings(7),
    PlayerList(8), EventTitle(9), Compass(10), ObjectivePanel(11),
    PortalPanel(12), BuilderToolsLegend(13), Speedometer(14),
    UtilitySlotSelector(15), BlockVariantSelector(16),
    BuilderToolsMaterialSlotSelector(17), Stamina(18),
    AmmoIndicator(19), Health(20), Mana(21), Oxygen(22), Sleep(23)
}
```

## Protocol Packets

### Page Packets

| Packet            | ID  | Direction | Description       |
|-------------------|-----|-----------|-------------------|
| `SetPage`         | 216 | S->C      | Set built-in page |
| `CustomHud`       | 217 | S->C      | Update HUD        |
| `CustomPage`      | 218 | S->C      | Send custom page  |
| `CustomPageEvent` | 219 | C->S      | Page event        |

### Window Packets

| Packet             | ID  | Direction | Description    |
|--------------------|-----|-----------|----------------|
| `OpenWindow`       | 200 | S->C      | Open window    |
| `UpdateWindow`     | 201 | S->C      | Update window  |
| `CloseWindow`      | 202 | S->C      | Close window   |
| `ClientOpenWindow` | 203 | C->S      | Request window |
| `SendWindowAction` | 204 | C->S      | Window action  |

## Known UI Documents

| Path                       | Purpose             |
|----------------------------|---------------------|
| `Pages/DialogPage.ui`      | Dialog/conversation |
| `Pages/BarterPage.ui`      | Trading interface   |
| `Pages/ShopPage.ui`        | Shop interface      |
| `Pages/RespawnPage.ui`     | Death/respawn       |
| `Pages/ChangeModelPage.ui` | Model selection     |
| `Pages/WarpListPage.ui`    | Teleport list       |
| `Pages/CommandListPage.ui` | Command help        |
| `Pages/PluginListPage.ui`  | Plugin list         |
| `Common/TextButton.ui`     | Reusable button     |

## Best Practices

1. **Use InteractiveCustomUIPage<T>** - Provides type-safe event handling
2. **Define event data codec** - Create a proper BuilderCodec for your event data
3. **Use sendUpdate for partial updates** - Don't rebuild entire page for small changes
4. **Extract values with @ prefix** - Use `@PropertyName` syntax to extract element values
5. **Set locksInterface appropriately** - Use `false` for non-blocking events like hover
6. **Clear lists before rebuilding** - Always `cmd.clear()` before repopulating lists
7. **Handle dismiss** - Override `onDismiss()` for cleanup
8. **Use Value references** - Reference styles from UI documents for consistency