Documentation/content/ui-systems/ui-files.en.md at main

Files

2026-01-20 20:33:59 +01:00

3.8 KiB

Raw Permalink Blame History

title, type, weight

title	type	weight
UI Files	docs	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:

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

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

Use # to assign IDs that can be targeted from Java:

Label #PlayerName {
  Text: "Unknown";
}

builder.set("#PlayerName", player.getUsername());

Localization

Use % prefix for translation keys:

Label {
  Text: %server.ui.welcome.title;
}

Next Steps

UI Syntax - Detailed syntax reference
UI Widgets - Available widget types
UI Properties - Common properties
UI Styles - Styling system

3.8 KiB Raw Permalink Blame History