---
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