Init

2026-01-20 20:33:59 +01:00
commit b16a40e431
583 changed files with 87339 additions and 0 deletions
--- a/content/ui-systems/ui-files.en.md
+++ b/content/ui-systems/ui-files.en.md
@@ -0,0 +1,161 @@
+---
+title: UI Files
+type: docs
+weight: 10
+---
+
+UI files (`.ui`) are Hytale's declarative markup language for defining user interfaces. They describe the structure, layout, and styling of UI elements that can be loaded by plugins via `UICommandBuilder.append()`.
+
+## File Location
+
+UI files are typically stored in the Assets directory:
+
+```
+Assets/
+  Common/UI/Custom/           # Server-side custom UI
+    Pages/                    # Custom page templates
+    Hud/                      # Custom HUD elements
+    Common.ui                 # Shared definitions
+    Sounds.ui                 # Sound definitions
+  Client/Interface/           # Client-side UI
+    InGame/Hud/               # HUD components
+    Common/                   # Common components
+    Common.ui                 # Client shared definitions
+```
+
+## Basic Structure
+
+A `.ui` file consists of variable definitions and widget declarations:
+
+```
+// Import external definitions
+$Common = "../Common.ui";
+
+// Define local variables
+@ButtonHeight = 44;
+@TextColor = #96a9be;
+
+// Define a widget tree
+Group #Container {
+  Anchor: (Width: 400, Height: 300);
+  Background: (Color: #000000(0.8));
+
+  Label #Title {
+    Text: "Hello World";
+    Style: (FontSize: 24, TextColor: @TextColor);
+  }
+}
+```
+
+## Loading UI Files from Plugins
+
+Use `UICommandBuilder.append()` to load a UI file:
+
+```java
+@Override
+public void build(Ref<EntityStore> ref, UICommandBuilder builder,
+                  UIEventBuilder events, Store<EntityStore> store) {
+    // Load the UI template (extension .ui is REQUIRED)
+    builder.append("Pages/MyPage.ui");
+
+    // Append to a specific element
+    builder.append("#ContentList", "Pages/ListItem.ui");
+
+    // Set dynamic values using selectors
+    builder.set("#Title", "Welcome, " + playerRef.getUsername());
+}
+```
+
+### Path Resolution
+
+The path is relative to `Common/UI/Custom/`. The `.ui` extension is **required**.
+
+| Path in `append()` | Resolved Location |
+|-------------------|-------------------|
+| `Pages/MyPage.ui` | `Common/UI/Custom/Pages/MyPage.ui` |
+| `Common.ui` | `Common/UI/Custom/Common.ui` |
+
+### For Java Plugins (Mods)
+
+When creating a Java plugin with custom UI, place your `.ui` files in the resources folder:
+
+```
+your-plugin/
+  src/main/
+    java/                           # Java source code
+    resources/
+      Common/UI/Custom/             # UI files go here
+        Pages/
+          MyPage.ui
+          MyButton.ui
+        Common.ui                   # Your shared definitions
+      plugin.json                   # Plugin manifest
+```
+
+Set `"IncludesAssetPack": true` in your `plugin.json` to enable asset loading:
+
+```json
+{
+  "Group": "MyGroup",
+  "Name": "MyPlugin",
+  "Version": "1.0.0",
+  "Main": "com.example.MyPlugin",
+  "IncludesAssetPack": true
+}
+```
+
+{{< callout type="info" >}}
+The server automatically looks for UI files in `Common/UI/Custom/` within your plugin's asset pack. This is why paths like `Pages/MyPage.ui` work without specifying the full path.
+{{< /callout >}}
+
+## Key Concepts
+
+### Variables
+
+Variables store reusable values:
+
+```
+@Height = 50;                           // Number
+@Color = #ff5500;                       // Color
+@Style = (FontSize: 16, RenderBold: true);  // Object
+```
+
+### Imports
+
+Import definitions from other files:
+
+```
+$Common = "Common.ui";                  // Import file
+$Common.@DefaultButtonStyle             // Reference imported variable
+```
+
+### Widget IDs
+
+Use `#` to assign IDs that can be targeted from Java:
+
+```
+Label #PlayerName {
+  Text: "Unknown";
+}
+```
+
+```java
+builder.set("#PlayerName", player.getUsername());
+```
+
+### Localization
+
+Use `%` prefix for translation keys:
+
+```
+Label {
+  Text: %server.ui.welcome.title;
+}
+```
+
+## Next Steps
+
+- [UI Syntax](ui-syntax) - Detailed syntax reference
+- [UI Widgets](ui-widgets) - Available widget types
+- [UI Properties](ui-properties) - Common properties
+- [UI Styles](ui-styles) - Styling system