UI File Reference

Hytale uses a declarative .ui file format for defining user interfaces. This guide covers the syntax, elements, and properties available.

API Reference

See full API: CustomUIPage | UICommandBuilder | UIEventBuilder

Concepts

Before reading this, familiarize yourself with Creating a Plugin.

File Syntax

Basic Structure

ElementType #ElementId {
  Property: value;
  Property: (SubProperty: value, SubProperty: value);

  ChildElement #ChildId {
    Property: value;
  }
}

Variables and Imports

// Import another .ui file as a variable
$C = "../Common.ui";
$Nav = "Nav/TopNavigationBar.ui";

// Define a constant
@MyConstant = 100;

// Define a style
@MyLabelStyle = LabelStyle(TextColor: #ffffff, FontSize: 16);

// Reference a template from an imported file
$C.@PageOverlay {
  // Content using the PageOverlay template from Common.ui
}

// Reference a named value from another file
$C.@DefaultScrollbarStyle

// Spread operator to inherit properties
@ExtendedStyle = LabelStyle(...@MyLabelStyle, RenderBold: true);

Template Syntax

• $Variable = "path/to/file.ui" - Import a file
• $Variable.@TemplateName - Use a template from imported file
• #ElementId - Assign an ID to an element (for selector access)
• @Name = value - Define a named constant or template
• ...@Name - Spread/inherit from another definition

UI Elements

Note

UI elements are defined client-side in Hytale's UI framework. This documentation is based on actual client .ui files.

Group

Container element for organizing child elements.

Group #MyContainer {
  Anchor: (Width: 600, Height: 400);
  LayoutMode: Top;
  Padding: (Left: 10, Right: 10);
  Background: #000000(0.5);
  Visible: true;

  // Child elements...
}

Properties:

Property	Type	Description
Anchor	Anchor	Positioning and sizing
LayoutMode	String	Layout mode (see below)
Padding	Padding	Inner spacing
FlexWeight	Number	Flex layout weight
Background	String/PatchStyle	Background color or texture
ScrollbarStyle	ScrollbarStyle	Scrollbar styling
Visible	Boolean	Show/hide the element
TextTooltipStyle	TextTooltipStyle	Tooltip on hover

LayoutMode values: Left, Right, Top, Bottom, Center, Middle, Full, TopScrolling, BottomScrolling, MiddleCenter, CenterMiddle

Label

Text display element.

Label #MyLabel {
  Text: "Hello World";
  Style: @MyLabelStyle;
}

Properties:

Property	Type	Description
Text	String	Text content (use %key for localization)
Style	LabelStyle	Text styling
TextTooltipStyle	TextTooltipStyle	Tooltip on hover

Button

Interactive button element (no text, use with child Label or use TextButton).

Button #MyButton {
  Anchor: (Width: 44, Height: 44);
  Style: @MyButtonStyle;
}

Properties:

Property	Type	Description
Anchor	Anchor	Positioning and sizing
Style	ButtonStyle	Button styling
Padding	Padding	Inner padding

TextButton

Button with built-in text label.

TextButton #MyButton {
  Anchor: (Height: 44);
  Style: @PrimaryTextButtonStyle;
  Padding: (Horizontal: 24);
  Text: "Click Me";
}

Properties:

Property	Type	Description
Anchor	Anchor	Positioning and sizing
Style	TextButtonStyle	Button and label styling
Padding	Padding	Inner padding
Text	String	Button text

TextField

Text input field.

TextField #SearchInput {
  Anchor: (Width: 170, Height: 28);
  Style: (FontSize: 15, TextColor: #a5b4c4);
  Padding: (Left: 8);
  Background: @InputBoxBackground;
}

Properties:

Property	Type	Description
Anchor	Anchor	Positioning and sizing
Style	InputFieldStyle	Text styling
Padding	Padding	Inner padding
Background	PatchStyle	Background

CheckBox

Boolean toggle element.

CheckBox #MyCheckbox {
  Anchor: (Width: 18, Height: 18);
  Background: "CheckBoxFrame.png";
  Padding: (Full: 4);
  Style: @DefaultCheckBoxStyle;
}

Properties:

Property	Type	Description
Anchor	Anchor	Positioning and sizing
Background	String	Background texture
Padding	Padding	Inner padding
Style	CheckBoxStyle	Checkbox styling

DropdownBox

Dropdown selection element.

DropdownBox #MyDropdown {
  Anchor: (Width: 194, Height: 42);
  Style: @DefaultDropdownBoxStyle;
}

Properties:

Property	Type	Description
Anchor	Anchor	Positioning and sizing
Style	DropdownBoxStyle	Dropdown styling

SliderNumberField

Slider with numeric input field.

SliderNumberField #MySlider {
  Anchor: (Width: 180, Height: 5);
  SliderStyle: @DefaultSliderStyle;
  NumberFieldContainerAnchor: (Left: 15, Width: 30, Height: 15);
  NumberFieldStyle: (FontSize: 14, TextColor: #a5b4c4);
  Min: 1;
  Max: 100;
}

Properties:

Property	Type	Description
Anchor	Anchor	Positioning and sizing
Padding	Padding	Inner padding
SliderStyle	SliderStyle	Slider styling
NumberFieldContainerAnchor	Anchor	Number field position
NumberFieldStyle	InputFieldStyle	Number field styling
Min	Number	Minimum value
Max	Number	Maximum value

ProgressBar

Progress indicator.

ProgressBar #HealthBar {
  Anchor: (Width: 158, Height: 8);
  BarTexturePath: "HealthBarFill.png";
}

Properties:

Property	Type	Description
Anchor	Anchor	Positioning and sizing
BarTexturePath	String	Fill texture path

ItemGrid

Grid of item slots.

ItemGrid #Inventory {
  Anchor: (Width: 300, Height: 200);
  SlotsPerRow: 9;
  Style: @DefaultItemGridStyle;
  Background: #202c3b(0);
  Padding: 2;
}

Properties:

Property	Type	Description
Anchor	Anchor	Positioning and sizing
SlotsPerRow	Number	Items per row
Style	ItemGridStyle	Grid styling
Background	String	Background color
Padding	Number	Grid padding

ActionButton

Button that shows a keybind hint.

ActionButton #PickItem {
  Alignment: Right;
  ActionName: %client.inventory.action.pickHalf;
  Disabled: true;
  LayoutMode: Right;
}

Properties:

Property	Type	Description
Alignment	String	Alignment
ActionName	String	Localized action name
Disabled	Boolean	Disabled state
LayoutMode	String	Layout mode

Sprite

Animated image element.

Sprite #Spinner {
  Anchor: (Width: 32, Height: 32);
  TexturePath: "Common/Spinner.png";
  Frame: (Width: 32, Height: 32, PerRow: 8, Count: 72);
  FramesPerSecond: 30;
}

Properties:

Property	Type	Description
Anchor	Anchor	Positioning and sizing
TexturePath	String	Sprite sheet path
Frame	Frame	Frame configuration
FramesPerSecond	Number	Animation speed

AssetImage

Image loaded from assets.

AssetImage #Icon {
  Anchor: (Width: 128, Height: 128);
}

Properties:

Property	Type	Description
Anchor	Anchor	Positioning and sizing

SceneBlur

Blurs the game scene behind the UI.

SceneBlur {}

No properties - just add it to enable background blur.

TabNavigation / TabButton

Tab-based navigation.

TabNavigation #Tabs {
  // Tab buttons defined here
  TabButton #Tab1 { ... }
  TabButton #Tab2 { ... }
}

Style Types

LabelStyle

Text styling for labels.

LabelStyle(
  FontSize: 17,
  TextColor: #bfcdd5,
  RenderBold: true,
  RenderUppercase: true,
  HorizontalAlignment: Center,
  VerticalAlignment: Center,
  LetterSpacing: 2,
  Wrap: true
)

Property	Type	Values
FontSize	Number	Font size in pixels
TextColor	Color	Text color
RenderBold	Boolean	Bold text
RenderUppercase	Boolean	Uppercase text
HorizontalAlignment	String	Start, Center, End
VerticalAlignment	String	Start, Center, End
LetterSpacing	Number	Letter spacing
Wrap	Boolean	Text wrapping

PatchStyle

9-patch textured background.

PatchStyle(
  TexturePath: "Common/Button.png",
  Border: 12
)

PatchStyle(
  TexturePath: "Common/Button.png",
  VerticalBorder: 12,
  HorizontalBorder: 80
)

PatchStyle(Color: #000000(0.82))

Property	Type	Description
TexturePath	String	Path to texture
Border	Number	Border size (all sides)
VerticalBorder	Number	Top/bottom border
HorizontalBorder	Number	Left/right border
Color	Color	Solid color instead of texture

ButtonStyle

Button state styling.

ButtonStyle(
  Default: (Background: @DefaultBackground),
  Hovered: (Background: @HoveredBackground),
  Pressed: (Background: @PressedBackground),
  Disabled: (Background: @DisabledBackground),
  Sounds: @ButtonSounds
)

TextButtonStyle

Button with label styling per state.

TextButtonStyle(
  Default: (Background: @DefaultBackground, LabelStyle: @LabelStyle),
  Hovered: (Background: @HoveredBackground, LabelStyle: @LabelStyle),
  Pressed: (Background: @PressedBackground, LabelStyle: @LabelStyle),
  Disabled: (Background: @DisabledBackground, LabelStyle: @DisabledLabelStyle),
  Sounds: @ButtonSounds
)

ScrollbarStyle

Scrollbar styling.

ScrollbarStyle(
  Spacing: 6,
  Size: 6,
  Background: (TexturePath: "Scrollbar.png", Border: 3),
  Handle: (TexturePath: "ScrollbarHandle.png", Border: 3),
  HoveredHandle: (TexturePath: "ScrollbarHandleHovered.png", Border: 3),
  DraggedHandle: (TexturePath: "ScrollbarHandleDragged.png", Border: 3),
  OnlyVisibleWhenHovered: true
)

SliderStyle

Slider styling.

SliderStyle(
  Background: (TexturePath: "SliderBackground.png", Border: 2),
  Handle: "SliderHandle.png",
  HandleWidth: 16,
  HandleHeight: 16,
  Sounds: (Activate: @SliderRelease, MouseHover: @HoverSound)
)

CheckBoxStyle

Checkbox styling.

CheckBoxStyle(
  Unchecked: (
    DefaultBackground: (Color: #00000000),
    HoveredBackground: (Color: #00000000),
    PressedBackground: (Color: #00000000),
    DisabledBackground: (Color: #424242),
    ChangedSound: @UntickSound
  ),
  Checked: (
    DefaultBackground: (TexturePath: "Checkmark.png"),
    HoveredBackground: (TexturePath: "Checkmark.png"),
    PressedBackground: (TexturePath: "Checkmark.png"),
    ChangedSound: @TickSound
  )
)

ItemGridStyle

Item grid styling.

ItemGridStyle(
  SlotSpacing: 2,
  SlotSize: 74,
  SlotIconSize: 64,
  SlotBackground: "Slot.png",
  DefaultItemIcon: "UnknownItemIcon.png",
  DurabilityBar: "DurabilityBar.png",
  DurabilityBarBackground: "DurabilityBarBackground.png",
  DurabilityBarAnchor: (Bottom: 10, Left: 13, Width: 48, Height: 2),
  DurabilityBarColorStart: #a63232,
  DurabilityBarColorEnd: #63b649
)

Properties Reference

Anchor

Controls element positioning and sizing.

Anchor: (Width: 600, Height: 400);
Anchor: (Left: 10, Right: 10, Top: 0, Bottom: 0);
Anchor: (Full: 1);  // Fill parent
Anchor: (Horizontal: 1);  // Fill horizontally
Anchor: (Vertical: 1);  // Fill vertically

Property	Type	Description
Left	Number	Left offset
Right	Number	Right offset
Top	Number	Top offset
Bottom	Number	Bottom offset
Width	Number	Fixed width
Height	Number	Fixed height
MinWidth	Number	Minimum width
MaxWidth	Number	Maximum width
Full	Number	Fill both axes
Horizontal	Number	Fill horizontal
Vertical	Number	Fill vertical

Padding

Inner spacing.

Padding: (Left: 10, Right: 10, Top: 5, Bottom: 5);
Padding: (Horizontal: 10, Vertical: 5);
Padding: (Full: 10);

Property	Type	Description
Left	Number	Left padding
Right	Number	Right padding
Top	Number	Top padding
Bottom	Number	Bottom padding
Horizontal	Number	Left + Right
Vertical	Number	Top + Bottom
Full	Number	All sides

Color Format

Colors can be specified as:

• Hex: #ffffff or #fff
• Hex with alpha: #ffffff(0.5) or #000000(0.82)
• Named constant: @DisabledColor

Selectors

Selectors are used to target elements for manipulation.

// Direct element by ID
"#ElementId"

// Array index access
"#List[0]"
"#List[2]"

// Child element access
"#Parent #Child"
"#Container[0] #Button"

// Property access
"#Element.Property"
"#Element.Style.TextColor"
"#Element[0].Visible"

UICommandBuilder Usage[^1]

Manipulate UI from Java code:

@Override
public void build(@Nonnull Ref<EntityStore> ref,
                  @Nonnull UICommandBuilder commandBuilder,
                  @Nonnull UIEventBuilder eventBuilder,
                  @Nonnull Store<EntityStore> store) {

    // Load a .ui file
    commandBuilder.append("Pages/MyPage.ui");

    // Set text
    commandBuilder.set("#Title.Text", "Welcome!");
    commandBuilder.set("#Description.Text", Message.translation("my.description"));

    // Set visibility
    commandBuilder.set("#ErrorMessage.Visible", false);

    // Set style from another file
    commandBuilder.set("#Button.Style", Value.ref("Pages/Common.ui", "ButtonStyle"));

    // Clear and rebuild lists
    commandBuilder.clear("#ItemList");
    for (int i = 0; i < items.size(); i++) {
        commandBuilder.append("#ItemList", "Pages/ListItem.ui");
        commandBuilder.set("#ItemList[" + i + "].Text", items.get(i).getName());
    }

    // Inline element creation
    commandBuilder.appendInline("#Container",
        "Group { LayoutMode: Left; Anchor: (Bottom: 0); }");

    // Set dropdown entries
    List<DropdownEntryInfo> options = new ArrayList<>();
    options.add(new DropdownEntryInfo(
        LocalizableString.fromString("Option 1"), "opt1"));
    options.add(new DropdownEntryInfo(
        LocalizableString.fromString("Option 2"), "opt2"));
    commandBuilder.set("#Dropdown.Entries", options);
    commandBuilder.set("#Dropdown.Value", "opt1");

    // Set Anchor dynamically
    Anchor anchor = new Anchor();
    anchor.setHeight(Value.of(120 + (count * 18)));
    commandBuilder.setObject("#DynamicGroup.Anchor", anchor);
}

UIEventBuilder Usage[^2]

Bind events to elements:

// Button click
eventBuilder.addEventBinding(
    CustomUIEventBindingType.Activating,
    "#MyButton",
    EventData.of("Action", "submit")
);

// Input value change (with @ prefix to read value)
eventBuilder.addEventBinding(
    CustomUIEventBindingType.ValueChanged,
    "#SearchInput",
    EventData.of("@SearchQuery", "#SearchInput.Value"),
    false  // Don't trigger rebuild
);

// Dropdown selection
eventBuilder.addEventBinding(
    CustomUIEventBindingType.ValueChanged,
    "#CategoryDropdown",
    EventData.of("@Category", "#CategoryDropdown.Value")
);

Event Types[^3]

Event	Description
Activating	Element clicked/activated
RightClicking	Right-click on element
DoubleClicking	Double-click
MouseEntered	Mouse enters element
MouseExited	Mouse exits element
ValueChanged	Input value changed
ElementReordered	Element order changed
Validating	Input validation
Dismissing	Page being dismissed
FocusGained	Element gained focus
FocusLost	Element lost focus
KeyDown	Key pressed
MouseButtonReleased	Mouse button released
SlotClicking	Item slot clicked
SlotDoubleClicking	Item slot double-clicked
SlotMouseEntered	Mouse entered slot
SlotMouseExited	Mouse exited slot
DragCancelled	Drag operation cancelled
Dropped	Item dropped
SlotMouseDragCompleted	Slot drag completed
SlotMouseDragExited	Mouse exited during slot drag
SlotClickReleaseWhileDragging	Click released while dragging slot
SlotClickPressWhileDragging	Click pressed while dragging slot
SelectedTabChanged	Tab selection changed

See Also

• CustomUIPage API - Base class for custom pages
• UICommandBuilder API - UI manipulation methods
• UIEventBuilder API - Event binding methods
• Creating a Plugin - Plugin setup guide

[^1]: See UICommandBuilder API for all methods including append(), appendInline(), set(), clear(), remove(), insertBefore()

[^2]: See UIEventBuilder API for addEventBinding() overloads with optional EventData and locksInterface parameters

[^3]: Event types are from CustomUIEventBindingType enum in com.hypixel.hytale.protocol.packets.interface_