Init

content/ui-systems/windows.en.md

@@ -0,0 +1,174 @@
+---
+title: Windows
+type: docs
+weight: 3
+---
+
+Windows are UI panels for displaying and managing inventory containers, crafting interfaces, and other item-based interactions.
+
+**Package:** `com.hypixel.hytale.server.core.entity.entities.player.windows`
+
+## Window Types
+
+| Type | Description |
+|------|-------------|
+| `WindowType.Container` | Standard inventory/container view |
+| `WindowType.PocketCrafting` | Small crafting grid (2x2) |
+| `WindowType.BasicCrafting` | Basic crafting table (3x3) |
+| `WindowType.DiagramCrafting` | Diagram-based crafting |
+| `WindowType.StructuralCrafting` | Structural/building crafting |
+| `WindowType.Processing` | Processing/smelting interface |
+| `WindowType.Memories` | Memories storage interface |
+
+## Window Manager
+
+Each player has a `WindowManager` that handles open windows:
+
+```java
+Player player = ...;
+WindowManager windowManager = player.getWindowManager();
+```
+
+## Window Classes
+
+### ContainerWindow
+
+For standard container interfaces:
+
+```java
+import com.hypixel.hytale.server.core.entity.entities.player.windows.ContainerWindow;
+import com.hypixel.hytale.server.core.inventory.container.ItemContainer;
+
+// Open a container window - takes just the ItemContainer
+ContainerWindow window = new ContainerWindow(itemContainer);
+```
+
+{{< callout type="info" >}}
+`ContainerWindow` automatically uses `WindowType.Container`. The window ID is assigned internally.
+{{< /callout >}}
+
+### BlockWindow
+
+`BlockWindow` is an abstract class for block-based containers. It's typically used through built-in interactions rather than instantiated directly.
+
+```java
+// BlockWindow is abstract - used internally by block interactions
+// Constructor: BlockWindow(WindowType, x, y, z, rotationIndex, BlockType)
+```
+
+### ItemStackContainerWindow
+
+For ItemStack-based containers:
+
+```java
+import com.hypixel.hytale.server.core.entity.entities.player.windows.ItemStackContainerWindow;
+import com.hypixel.hytale.server.core.inventory.container.ItemStackItemContainer;
+
+// Takes an ItemStackItemContainer
+ItemStackContainerWindow window = new ItemStackContainerWindow(itemStackItemContainer);
+```
+
+## Opening Windows
+
+Use `PageManager.setPageWithWindows()` or `openCustomPageWithWindows()`:
+
+```java
+Player player = ...;
+PageManager pageManager = player.getPageManager();
+Ref<EntityStore> ref = player.getReference();
+Store<EntityStore> store = ref.getStore();
+
+// Open page with inventory windows
+ContainerWindow chestWindow = new ContainerWindow(chestContainer);
+
+boolean success = pageManager.setPageWithWindows(
+    ref, store,
+    Page.None,  // or Page.Bench, Page.Inventory, etc.
+    true,       // canCloseThroughInteraction
+    chestWindow
+);
+```
+
+## With Custom Pages
+
+Combine windows with custom UI pages:
+
+```java
+// Custom crafting UI with windows
+CraftingPage craftingPage = new CraftingPage(player.getPlayerRef());
+ContainerWindow inputWindow = new ContainerWindow(1, WindowType.BasicCrafting, inputContainer);
+ContainerWindow outputWindow = new ContainerWindow(2, WindowType.Container, outputContainer);
+
+pageManager.openCustomPageWithWindows(
+    ref, store,
+    craftingPage,
+    inputWindow,
+    outputWindow
+);
+```
+
+## Window Events
+
+Windows interact with the inventory system. Handle inventory changes through the appropriate events and handlers.
+
+## Practical Example
+
+### Chest Container UI
+
+```java
+public void openChest(Player player, ItemContainer chestContainer) {
+    PageManager pageManager = player.getPageManager();
+    Ref<EntityStore> ref = player.getReference();
+    Store<EntityStore> store = ref.getStore();
+
+    ContainerWindow window = new ContainerWindow(chestContainer);
+
+    pageManager.setPageWithWindows(
+        ref, store,
+        Page.Bench,  // Use Bench page for container UI
+        true,        // Allow closing via interaction
+        window
+    );
+}
+```
+
+### Opening Multiple Windows
+
+```java
+public void openCraftingUI(Player player, ItemContainer inputContainer,
+                           ItemContainer outputContainer) {
+    PageManager pageManager = player.getPageManager();
+    Ref<EntityStore> ref = player.getReference();
+    Store<EntityStore> store = ref.getStore();
+
+    // Create multiple windows
+    ContainerWindow inputWindow = new ContainerWindow(inputContainer);
+    ContainerWindow outputWindow = new ContainerWindow(outputContainer);
+
+    pageManager.setPageWithWindows(
+        ref, store,
+        Page.Bench,
+        true,
+        inputWindow,
+        outputWindow
+    );
+}
+```
+
+{{< callout type="info" >}}
+**Note:** `BlockWindow` is abstract and used internally by block interactions. For custom crafting UIs, use `ContainerWindow` with your own containers.
+{{< /callout >}}
+
+## Best Practices
+
+{{< callout type="info" >}}
+**Window Guidelines:**
+- Use unique window IDs for each open window
+- Match `WindowType` to the intended interface
+- Clean up containers when windows are closed
+- Use `canCloseThroughInteraction` appropriately
+{{< /callout >}}
+
+{{< callout type="warning" >}}
+**Important:** Windows are tied to container state. Ensure containers persist for the duration the window is open.
+{{< /callout >}}