162 lines
3.8 KiB
Markdown
162 lines
3.8 KiB
Markdown
---
|
|
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
|