your-plugin/
  src/main/resources/
    manifest.json                    # Must have "IncludesAssetPack": true
    Common/
      UI/
        Custom/
          MyPage.ui                  # Your custom UI files go here
          MyHud.ui
          ListItem.ui

$C = "../Common.ui";

$C.@PageOverlay {}                    // Dark background overlay

$C.@Container {
  Anchor: (Width: 600, Height: 400);
  
  #Title {
    $C.@Title { @Text = %page.title; }
  }
  
  #Content {
    LayoutMode: Top;
    
    Label #ValueLabel { Text: ""; }   // ID for code access
    
    $C.@TextButton #ActionBtn {
      @Text = %page.action;
    }
  }
}

$C.@BackButton {}

Window (abstract)
├── ContainerWindow                  # Simple item container (implements ItemContainerWindow)
├── ItemStackContainerWindow         # Container tied to an ItemStack (implements ItemContainerWindow)
├── FieldCraftingWindow              # Pocket/inventory crafting (WindowType.PocketCrafting)
├── MemoriesWindow                   # Memories/achievements display (WindowType.Memories)
└── BlockWindow (abstract)           # Tied to a block in the world (implements ValidatedWindow)
    ├── ContainerBlockWindow         # Container tied to a block (implements ItemContainerWindow)
    └── BenchWindow (abstract)       # Crafting bench base (implements MaterialContainerWindow)
        ├── ProcessingBenchWindow    # Furnace-like processing (implements ItemContainerWindow)
        └── CraftingWindow (abstract)
            ├── SimpleCraftingWindow       # Basic workbench crafting (implements MaterialContainerWindow)
            ├── DiagramCraftingWindow      # Blueprint/anvil crafting (implements ItemContainerWindow)
            └── StructuralCraftingWindow   # Block transformation crafting (implements ItemContainerWindow)

Server: openWindow(window) -> OpenWindow packet (ID 200) -> Client: Render UI
Client: User Action -> SendWindowAction packet (ID 203) -> Server: handleAction()
Server: invalidate() -> updateWindows() -> UpdateWindow packet (ID 201) -> Client: Refresh UI
Server: closeWindow() -> CloseWindow packet (ID 202) -> Client: Close UI

@Override
public JsonObject getData() {
    JsonObject data = new JsonObject();
    data.addProperty("type", windowType.ordinal());
    data.addProperty("title", "My Window");
    data.addProperty("customProperty", someValue);
    return data;
}

package com.example.myplugin.windows;

import com.google.gson.JsonObject;
import com.hypixel.hytale.server.core.entity.entities.player.windows.Window;
import com.hypixel.hytale.protocol.packets.window.WindowType;
import com.hypixel.hytale.protocol.packets.window.WindowAction;
import com.hypixel.hytale.component.Ref;
import com.hypixel.hytale.component.Store;
import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;

public class CustomWindow extends Window {
    
    private final JsonObject windowData = new JsonObject();
    
    public CustomWindow() {
        super(WindowType.Container);
        // Initialize window data
        windowData.addProperty("title", "Custom Window");
    }
    
    @Override
    public JsonObject getData() {
        // Return data to send to client (serialized as JSON)
        return windowData;
    }
    
    @Override
    protected boolean onOpen0() {
        // Called when window opens
        // Return false to cancel opening
        return true;
    }
    
    @Override
    protected void onClose0() {
        // Called when window closes - cleanup here
    }
    
    @Override
    public void handleAction(Ref<EntityStore> ref, Store<EntityStore> store, WindowAction action) {
        // Handle window actions from client
        // Default implementation is no-op
    }
}

import com.hypixel.hytale.component.Ref;
import com.hypixel.hytale.component.Store;
import com.hypixel.hytale.server.core.command.system.CommandContext;
import com.hypixel.hytale.server.core.command.system.basecommands.AbstractPlayerCommand;
import com.hypixel.hytale.server.core.entity.entities.Player;
import com.hypixel.hytale.server.core.entity.entities.player.windows.WindowManager;
import com.hypixel.hytale.server.core.universe.PlayerRef;
import com.hypixel.hytale.server.core.universe.world.World;
import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;
import com.hypixel.hytale.protocol.packets.window.OpenWindow;
import javax.annotation.Nonnull;

public class StorageCommand extends AbstractPlayerCommand {
    
    public StorageCommand() {
        super("storage", "Open storage window");
    }
    
    @Override
    protected void execute(
        @Nonnull CommandContext context,
        @Nonnull Store<EntityStore> store,
        @Nonnull Ref<EntityStore> ref,
        @Nonnull PlayerRef playerRef,
        @Nonnull World world
    ) {
        world.execute(() -> {
            Player player = store.getComponent(ref, Player.getComponentType());
            StorageWindow window = new StorageWindow();
            
            // Open via WindowManager
            WindowManager windowManager = player.getWindowManager();
            OpenWindow packet = windowManager.openWindow(window);
            
            if (packet != null) {
                // Window opened successfully - packet is sent automatically
                context.sendSuccess("Window opened!");
            } else {
                // Opening was cancelled (onOpen0() returned false)
                context.sendError("Failed to open window");
            }
        });
    }
}

public void updateData(String newValue) {
    windowData.addProperty("value", newValue);
    invalidate(); // Mark for update
}

// For full rebuild (client re-renders entire window)
public void requireRebuild() {
    setNeedRebuild();
    invalidate();
}

// Get player's window manager
WindowManager windowManager = player.getWindowManager();

// Open a window (returns OpenWindow packet or null if cancelled)
OpenWindow packet = windowManager.openWindow(new MyWindow());

// Open multiple windows atomically (all or none)
List<OpenWindow> packets = windowManager.openWindows(window1, window2);

// Get window by ID
Window window = windowManager.getWindow(windowId);

// Get all open windows
List<Window> windows = windowManager.getWindows();

// Update a specific window (sends UpdateWindow packet)
windowManager.updateWindow(window);

// Update all dirty windows
windowManager.updateWindows();

// Validate all ValidatedWindow instances (closes invalid ones)
windowManager.validateWindows();

// Close a specific window
windowManager.closeWindow(windowId);

// Close all windows
windowManager.closeAllWindows();

// Mark a window as changed
windowManager.markWindowChanged(windowId);

public class CustomChestWindow extends BlockWindow implements ItemContainerWindow {
    
    private final SimpleItemContainer itemContainer;
    private final JsonObject windowData = new JsonObject();
    
    public CustomChestWindow(int x, int y, int z, int rotationIndex, BlockType blockType) {
        super(WindowType.Container, x, y, z, rotationIndex, blockType);
        this.itemContainer = new SimpleItemContainer(27); // 3 rows
        
        // Set max interaction distance (default: 7.0)
        setMaxDistance(7.0);
        
        // Initialize window data
        Item item = blockType.getItem();
        windowData.addProperty("blockItemId", item != null ? item.getId() : "");
    }
    
    @Override
    public JsonObject getData() {
        return windowData;
    }
    
    @Override
    public ItemContainer getItemContainer() {
        return itemContainer;
    }
    
    @Override
    protected boolean onOpen0() {
        // Load chest contents from block entity
        PlayerRef playerRef = getPlayerRef();
        Ref<EntityStore> ref = playerRef.getReference();
        Store<EntityStore> store = ref.getStore();
        World world = store.getExternalData().getWorld();
        
        // Load items from persistent storage
        loadItemsFromWorld(world);
        return true;
    }
    
    @Override
    protected void onClose0() {
        // Save chest contents
        saveItemsToWorld();
    }
}

@EventHandler
public void onBlockInteract(BlockInteractEvent event) {
    Player player = event.getPlayer();
    BlockPos pos = event.getBlockPos();
    Block block = event.getBlock();
    
    if (block.getType().getId().equals("my_mod:custom_chest")) {
        CustomChestWindow window = new CustomChestWindow(
            pos.x(), pos.y(), pos.z(),
            block.getRotationIndex(),
            block.getType()
        );
        player.getWindowManager().openWindow(window);
        event.setCancelled(true);
    }
}

public abstract class BenchWindow extends BlockWindow implements MaterialContainerWindow {
    protected final Bench bench;
    protected final BenchState benchState;
    protected final JsonObject windowData = new JsonObject();
    private MaterialExtraResourcesSection extraResourcesSection;
    
    // Window data includes:
    // - type: bench type ordinal
    // - id: bench ID string
    // - name: translation key
    // - blockItemId: item ID
    // - tierLevel: current tier level
    // - worldMemoriesLevel: world memories level
    // - progress: crafting progress (0.0 - 1.0)
    // - tierUpgradeProgress: tier upgrade progress
}

public class WorkbenchWindow extends SimpleCraftingWindow {
    
    public WorkbenchWindow(BenchState benchState) {
        super(benchState);
    }
    
    @Override
    public void handleAction(Ref<EntityStore> ref, Store<EntityStore> store, WindowAction action) {
        if (action instanceof CraftRecipeAction craftAction) {
            String recipeId = craftAction.recipeId;
            int quantity = craftAction.quantity;
            // Handle crafting
            CraftingManager craftingManager = store.getComponent(ref, CraftingManager.getComponentType());
            craftSimpleItem(store, ref, craftingManager, craftAction);
        } else if (action instanceof TierUpgradeAction) {
            // Handle bench tier upgrade
            handleTierUpgrade(ref, store);
        }
    }
}

public class SmelterWindow extends ProcessingBenchWindow {
    
    public SmelterWindow(BenchState benchState) {
        super(benchState);
    }
    
    // ProcessingBenchWindow provides:
    // - setActive(boolean): toggle processing
    // - setProgress(float): update progress (0.0 - 1.0)
    // - setFuelTime(float): current fuel remaining
    // - setMaxFuel(int): maximum fuel capacity
    // - setProcessingSlots(Set<Short>): slots currently processing
    // - setProcessingFuelSlots(Set<Short>): fuel slots in use
    
    @Override
    public void handleAction(Ref<EntityStore> ref, Store<EntityStore> store, WindowAction action) {
        if (action instanceof SetActiveAction activeAction) {
            setActive(activeAction.state);
            invalidate();
        } else if (action instanceof TierUpgradeAction) {
            handleTierUpgrade(ref, store);
        }
    }
}

// Update progress with throttling (min 5% change or 500ms interval)
public void updateCraftingJob(float percent) {
    windowData.addProperty("progress", percent);
    checkProgressInvalidate(percent);
}

public void updateBenchUpgradeJob(float percent) {
    windowData.addProperty("tierUpgradeProgress", percent);
    checkProgressInvalidate(percent);
}

// On tier level change (requires full rebuild)
public void updateBenchTierLevel(int newValue) {
    windowData.addProperty("tierLevel", newValue);
    updateBenchUpgradeJob(0.0f);
    setNeedRebuild();
    invalidate();
}

public interface ItemContainerWindow {
    @Nonnull ItemContainer getItemContainer();
}

public class InventoryWindow extends Window implements ItemContainerWindow {
    
    private final SimpleItemContainer itemContainer;
    private final JsonObject windowData = new JsonObject();
    
    public InventoryWindow(int size) {
        super(WindowType.Container);
        this.itemContainer = new SimpleItemContainer(size);
        
        // Register change listener for automatic updates
        itemContainer.registerChangeEvent(EventPriority.NORMAL, event -> {
            invalidate();
        });
    }
    
    @Override
    public ItemContainer getItemContainer() {
        return itemContainer;
    }
    
    @Override
    public JsonObject getData() {
        return windowData;
    }
    
    @Override
    protected boolean onOpen0() {
        return true;
    }
    
    @Override
    protected void onClose0() {
        // Cleanup
    }
}

@Override
public void handleAction(Ref<EntityStore> ref, Store<EntityStore> store, WindowAction action) {
    if (action instanceof CraftRecipeAction craft) {
        handleCraft(craft.recipeId, craft.quantity);
    } else if (action instanceof SelectSlotAction select) {
        handleSlotSelect(select.slot);
    } else if (action instanceof SetActiveAction active) {
        handleActiveToggle(active.state);
    } else if (action instanceof SortItemsAction sort) {
        handleSort(sort.sortType);
    }
}

public enum SortType {
    Name(0),   // Sort by item translation key
    Type(1),   // Sort by item type (Weapon, Armor, Tool, Item, Special)
    Rarity(2); // Sort by quality value (reversed)
}

// Creating OpenWindow packet (done automatically by WindowManager)
OpenWindow packet = new OpenWindow(
    windowId,
    window.getType(),
    window.getData().toString(),  // JSON string
    itemContainerWindow != null ? itemContainerWindow.getItemContainer().toPacket() : null,
    materialContainerWindow != null ? materialContainerWindow.getExtraResourcesSection().toPacket() : null
);

public class MyPlugin extends JavaPlugin {
    
    @Override
    protected void setup() {
        // Register client-requestable window
        Window.CLIENT_REQUESTABLE_WINDOW_TYPES.put(
            WindowType.Memories,
            MemoriesWindow::new
        );
    }
}

// Handle client-requested window
@PacketHandler
public void onClientOpenWindow(ClientOpenWindow packet) {
    Supplier<? extends Window> supplier = Window.CLIENT_REQUESTABLE_WINDOW_TYPES.get(packet.type);
    if (supplier != null) {
        Window window = supplier.get();
        UpdateWindow updatePacket = windowManager.clientOpenWindow(window);
        if (updatePacket != null) {
            player.sendPacket(updatePacket);
        }
    }
}