Your First Hytale UI: A Friendly Guide to CustomUI

So you want to create custom menus, dialogs, or interfaces for your Hytale mod? You’re in the right place. I wrote this guide because when I started making UIs in Hytale, I found the official docs a bit… sparse. This is the comprehensive walkthrough I wished I’d had.

By the end of this guide, you’ll be able to:

• Create your own UI screens from scratch
• Arrange elements using Hytale’s layout system
• Style your interfaces with colors, fonts, and textures
• Build reusable templates to keep your code clean
• Connect your UI to Java code for interactivity

Ready? Let’s build something!

---

Table of Contents

1. What is CustomUI?
2. Your First UI File
3. Understanding Elements
4. Arranging Elements with Layout
5. Positioning and Sizing with Anchor
6. Colors and Backgrounds
7. Styling Your Elements
8. Creating Reusable Templates
9. Practical UI Patterns
10. Connecting UI to Java
11. Quick Reference

---

What is CustomUI?

Before we dive into code, let’s understand what we’re working with.

Hytale uses its own language for describing user interfaces. Think of it like writing a recipe that tells the game exactly how to draw your UI - where things go, what colours they are, how they respond to clicks. This language is called a Domain-Specific Language (or DSL), and it lives in files with the .ui extension.

If you’ve used CSS or JSON before, the syntax might look vaguely familiar. But don’t worry if you haven’t - we’re starting from the beginning and I’ll explain everything as we go.

Here are the core concepts you’ll learn:

• Elements are the building blocks of your UI. Things like text labels, buttons, input fields, and containers are all elements.
• Properties control how elements look and behave. Want a button to be blue? That’s a property. Want text to be centered? Also a property.
• Templates let you save and reuse UI patterns. Once you’ve designed a nice button style, you can use it everywhere without copying and pasting.

The game also provides a file called Common.ui that’s packed with pre-built templates and styles. Think of it as a starter kit - professionally-designed components that you can use right out of the box. It’s honestly a lifesaver when you’re starting out.

---

Your First UI File

Enough theory - let’s create something! Here’s a complete, working UI file that displays a simple message:

// my-first-ui.ui
// A simple welcome dialog

Group {
  LayoutMode: CenterMiddle;
  Anchor: (Full: 0);
  Background: #000000(0.5);

  Group {
    Background: #1a1a2e;
    Padding: (Full: 20);
    Anchor: (Width: 300, Height: 150);

    LayoutMode: Top;

    Label {
      Text: "Welcome to Hytale!";
      Anchor: (Height: 40);
      Style: (
        FontSize: 20,
        TextColor: #ffffff,
        HorizontalAlignment: Center,
        RenderBold: true
      );
    }

    Label {
      Text: "Your mod is working.";
      Anchor: (Height: 30);
      Style: (
        FontSize: 14,
        TextColor: #cccccc,
        HorizontalAlignment: Center
      );
    }
  }
}

Save this in your mod’s UI folder, and you’ve got a centered dialog box with a dark semi-transparent background, a title, and a subtitle. Not bad for 30 lines of code!

Let’s break down what’s happening:

1. The outer Group fills the entire screen (Anchor: (Full: 0)) with a semi-transparent black background. This creates that nice “overlay” effect.
2. The inner Group is our actual dialog box, sized at 300x150 pixels with padding inside.
3. Two Labels display our text, stacked vertically because of LayoutMode: Top.

Now let’s explore each of these concepts in detail.

---

Understanding Elements

Elements are the building blocks of your UI. Each type serves a specific purpose, and you’ll combine them like LEGO bricks to create complete interfaces. Once you understand the basic elements, you can build pretty much anything.

How to Write an Element

Every element follows the same pattern:

ElementType {
  Property: value;
  Property: value;
}

You can also give elements an ID so you can reference them later:

Label #WelcomeMessage {
  Text: "Hello!";
}

The #WelcomeMessage part is the ID. You’ll use this when you want to update the element from Java code or target it with selectors.

Container Elements

Group is your workhorse - you’ll use these constantly. It’s a container that holds other elements and controls how they’re arranged.

Group {
  LayoutMode: Top;
  Padding: (Full: 10);
  Background: #1a1a2e;

  Label { Text: "Child 1"; }
  Label { Text: "Child 2"; }
}

Groups can have these properties:

Property	What it does
LayoutMode	How children are arranged (vertical, horizontal, etc.)
Background	Background color or texture
Padding	Space between the edge and children
Anchor	Position and size
Visible	Show or hide the group
HitTestVisible	Whether clicks pass through (set to false for overlays)
FlexWeight	How much space to take in flex layouts
ScrollbarStyle	Scrollbar appearance for scrolling layouts

Text Elements

Label displays text. That’s it. Simple, but you’ll use it everywhere.

Label {
  Text: "Hello World";
  Style: (
    FontSize: 16,
    TextColor: #ffffff,
    RenderBold: true
  );
  Anchor: (Height: 24);
}

You can also use translation keys for localized text:

Label {
  Text: %my.translation.key;
}

Label properties include:

Property	What it does
Text	The text to display (string or translation key)
Style	Font size, color, alignment, and other text styling
Anchor	Position and size
Visible	Show or hide
FlexWeight	Flex layout weight

Button Elements

Hytale gives you two button types, and knowing when to use which will save you some confusion.

Button is for icon-only buttons where you provide your own graphics:

Button #CloseButton {
  Anchor: (Width: 32, Height: 32);
  Style: (
    Default: (Background: "Icons/close.png"),
    Hovered: (Background: "Icons/close_hover.png"),
    Pressed: (Background: "Icons/close_press.png")
  );
}

TextButton combines a button with a text label:

TextButton #SaveButton {
  Text: "Save Game";
  Anchor: (Width: 120, Height: 40);
  Disabled: false;
  Style: $C.@DefaultTextButtonStyle;
}

Both button types share these properties:

Property	What it does
Style	Visual states (Default, Hovered, Pressed, Disabled)
Anchor	Position and size
Visible	Show or hide
Disabled	Grey out and prevent interaction
Background	Background color or texture
Padding	Inner spacing

TextButton also has a Text property for its label.

Input Elements

TextField is for single-line text input:

TextField #NameInput {
  Anchor: (Height: 38);
  Padding: (Horizontal: 10);
  PlaceholderText: %enter.name;
  MaxLength: 64;
  Style: $C.@DefaultInputFieldStyle;
  Background: $C.@InputBoxBackground;
}

NumberField adds validation for numeric input:

NumberField #AgeInput {
  Value: 25;
  Format: (
    MinValue: 0,
    MaxValue: 120,
    Step: 1
  );
}

CheckBox is for boolean toggles:

CheckBox #EnableFeature {
  Anchor: (Width: 22, Height: 22);
  Value: true;
  Style: $C.@DefaultCheckBoxStyle;
  Background: (TexturePath: "Common/CheckBoxFrame.png", Border: 7);
}

Item Display

ItemSlot displays game items with their quality/rarity backgrounds:

ItemSlot #WeaponSlot {
  Anchor: (Width: 64, Height: 64);
  ShowQualityBackground: true;
  ShowQuantity: false;
}

Property	What it does
ShowQualityBackground	Display item rarity colors
ShowQuantity	Show stack count
Anchor	Size and position
Visible	Show or hide

---

Arranging Elements with Layout

When you put multiple elements inside a Group, the LayoutMode property determines how they’re arranged. This is honestly one of the most important concepts to understand - get this right and your UIs will practically build themselves.

Layout Modes

Mode	What it does
Top	Stack children vertically, starting from the top
Bottom	Stack vertically, starting from the bottom
Left	Stack horizontally, starting from the left
Right	Stack horizontally, starting from the right
Center	Center horizontally
Middle	Center vertically
CenterMiddle	Center both horizontally and vertically
Full	Children fill the container completely
TopScrolling	Vertical stack with a scrollbar when content overflows
LeftScrolling	Horizontal stack with scrollbar

Vertical Stacking

This is probably what you’ll use most often - I’d estimate 70% of my layouts use LayoutMode: Top. Elements stack from top to bottom:

Group {
  LayoutMode: Top;

  Label { Text: "First"; Anchor: (Height: 30); }
  Label { Text: "Second"; Anchor: (Height: 30); }
  Label { Text: "Third"; Anchor: (Height: 30); }
}

Horizontal Rows

Perfect for button bars, icon rows, or any side-by-side layout:

Group {
  LayoutMode: Left;

  Button { Anchor: (Width: 40, Height: 40); }
  Button { Anchor: (Width: 40, Height: 40); }
  Button { Anchor: (Width: 40, Height: 40); }
}

Scrolling Content

For lists that might grow longer than the available space:

Group {
  LayoutMode: TopScrolling;
  ScrollbarStyle: $C.@DefaultScrollbarStyle;

  // Add as many children as you need
  Label { Text: "Item 1"; Anchor: (Height: 30); }
  Label { Text: "Item 2"; Anchor: (Height: 30); }
  Label { Text: "Item 3"; Anchor: (Height: 30); }
  // ... many more items
}

Flexible Sizing with FlexWeight

Sometimes you want elements to share available space proportionally rather than having fixed sizes. The FlexWeight property is your friend here - it’s how you build responsive layouts that adapt to different sizes.

Group {
  LayoutMode: Left;
  Anchor: (Width: 300, Height: 40);

  Label { Text: "Fixed"; Anchor: (Width: 80); }
  Group { FlexWeight: 1; }
  Button { Anchor: (Width: 60); }
}

In this example, the Label takes 80 pixels, the Button takes 60 pixels, and the middle Group with FlexWeight: 1 expands to fill whatever space remains.

You can use multiple FlexWeight elements to distribute space:

Group {
  LayoutMode: Left;

  Group { FlexWeight: 1; }  // Takes 1 part
  Group { FlexWeight: 2; }  // Takes 2 parts (twice as wide)
  Group { FlexWeight: 1; }  // Takes 1 part
}

Adding Space Between Elements

There are two ways to create gaps between elements.

Empty spacer Groups:

Group {
  LayoutMode: Left;

  Button { Anchor: (Width: 40); }
  Group { Anchor: (Width: 10); }
  Button { Anchor: (Width: 40); }
}

Padding on elements:

Group {
  LayoutMode: Left;

  Button { Anchor: (Width: 40); }
  Button {
    Anchor: (Width: 40);
    Padding: (Left: 10);
  }
}

---

Positioning and Sizing with Anchor

The Anchor property is how you control where elements appear and how big they are. It’s a tuple (a group of related values) that can include different combinations of properties. This one takes a bit of practice to master, but once it clicks, you’ll have precise control over every element.

Setting Size

Anchor: (Width: 200, Height: 100);

This gives you an element that’s exactly 200 pixels wide and 100 pixels tall.

Filling the Parent

Anchor: (Full: 0);

This makes the element fill its parent completely. The number is the margin on all sides, so Full: 0 means no margin, while Full: 10 leaves 10 pixels of space around the edges.

Positioning from Edges

You can position elements relative to their parent’s edges:

Property	What it does
Top	Distance from the top edge
Bottom	Distance from the bottom edge
Left	Distance from the left edge
Right	Distance from the right edge
Horizontal	Distance from both left and right
Vertical	Distance from both top and bottom

Example: Top-right corner positioning:

Anchor: (Width: 32, Height: 32, Top: 8, Right: 8);

Example: Horizontally centered with margins:

Anchor: (Height: 40, Horizontal: 20);

This creates an element that’s 40 pixels tall and stretches across the container with 20 pixels of margin on each side.

Negative Values for Overlapping

Here’s a neat trick: negative anchor values position elements outside their parent’s bounds:

Anchor: (Width: 32, Height: 32, Top: -16, Right: -16);

This creates a close button that overlaps the container’s corner, a common design pattern for dismissable dialogs.

---

Colors and Backgrounds

Now we’re getting to the fun part! Making your UI visually appealing starts with understanding how colours and backgrounds work.

Color Format

Colors use hexadecimal format, just like in CSS or HTML:

#RRGGBB

Where RR, GG, and BB are two-digit hex values (00-FF) for red, green, and blue.

#ffffff    // White
#000000    // Black
#ff0000    // Red
#00ff00    // Green
#0000ff    // Blue
#1a1a2e    // Dark blue-gray (great for UI backgrounds)

Transparency

Add an alpha value in parentheses to make colors transparent:

#ffffff(0.5)    // 50% transparent white
#000000(0.7)    // 70% opaque black (nice for overlays)
#000000(0)      // Fully transparent

The alpha value ranges from 0 (invisible) to 1 (fully opaque).

Solid Color Backgrounds

The simplest background is just a color:

Background: #1a1a2e;
Background: #ffffff(0.1);

Texture Backgrounds

You can use image files as backgrounds:

Background: "path/to/texture.png";
Background: (TexturePath: "path/to/texture.png");

9-Slice Backgrounds with PatchStyle

This is a powerful technique that’s worth understanding. A 9-slice (or “9-patch”) image has corners that stay fixed while the edges and center stretch to fill the available space. It’s how you make buttons and panels that look crisp at any size.

Background: PatchStyle(
  TexturePath: "Common/Panel.png",
  Border: 12
);

The Border value tells the game how many pixels from each edge belong to the corners.

For more control, you can specify different borders for horizontal and vertical edges:

Background: PatchStyle(
  TexturePath: "Common/Button.png",
  HorizontalBorder: 20,
  VerticalBorder: 10
);

Creating Visual Borders

Want a colored border around something? Use nested Groups:

Group #Border {
  Background: #000000;
  Padding: 2;

  Group #Inner {
    Anchor: (Full: 0);
    Background: #ffffff;
  }
}

The outer Group provides the border color, the padding creates the border width, and the inner Group fills with your desired background color.

---

Styling Your Elements

Styling is what takes your UI from “it works” to “it looks professional.” Different element types have different styling options, and mastering these will set your mod apart.

Styling Labels

Label styles control everything about how text appears:

Style: (
  FontSize: 16,
  TextColor: #ffffff,
  FontName: "Default",
  RenderBold: true,
  RenderUppercase: true,
  RenderItalics: true,
  HorizontalAlignment: Center,
  VerticalAlignment: Center,
  Wrap: true,
  LetterSpacing: 2,
  OutlineColor: #000000(0.3)
);

Property	Values	What it does
FontSize	Number	Text size in pixels
TextColor	Color	The text color
FontName	”Default”, “Secondary”	Which font to use
RenderBold	true/false	Bold text
RenderUppercase	true/false	Force uppercase
RenderItalics	true/false	Italic text
HorizontalAlignment	Start, Center, End	Left/center/right
VerticalAlignment	Start, Center, End	Top/middle/bottom
Wrap	true/false	Allow text to wrap to next line
LetterSpacing	Number	Extra space between letters
OutlineColor	Color	Text outline/shadow

Styling Buttons

Buttons have different visual states. You define how the button looks in each state:

Style: (
  Default: (Background: #3a3a4a),
  Hovered: (Background: #4a4a5a),
  Pressed: (Background: #2a2a3a),
  Disabled: (Background: #1a1a2a),
  Sounds: $C.@ButtonSounds
);

Styling TextButtons

TextButtons combine background styling with label styling:

Style: TextButtonStyle(
  Default: (
    Background: #3a3a4a,
    LabelStyle: (TextColor: #ffffff)
  ),
  Hovered: (
    Background: #4a4a5a,
    LabelStyle: (TextColor: #ffffff)
  ),
  Pressed: (
    Background: #2a2a3a,
    LabelStyle: (TextColor: #cccccc)
  ),
  Disabled: (
    Background: #1a1a2a,
    LabelStyle: (TextColor: #666666)
  )
);

Using Pre-built Styles

The game’s Common.ui file has professionally-designed styles ready to use:

$C = "../../Common.ui";

Label {
  Style: $C.@DefaultLabelStyle;
}

TextButton {
  Style: $C.@DefaultTextButtonStyle;
}

---

Creating Reusable Templates

Once you’ve designed something nice, you really don’t want to copy and paste it everywhere - that’s a maintenance nightmare waiting to happen. Templates let you define a pattern once and reuse it throughout your mod. This is one of those things that feels like extra work at first but saves you hours later.

Basic Templates

Define a template with the @ prefix:

@MyButton = TextButton {
  Anchor: (Height: 40);
  Style: (
    Default: (Background: #3a4a5a),
    Hovered: (Background: #4a5a6a)
  );
};

// Now use it
@MyButton { Text: "Click Me"; }
@MyButton { Text: "Or Click Me"; }

Each use of @MyButton creates a new button with all those properties already set.

Templates with Parameters

Templates can accept parameters to customize each instance. Parameters use @Name = value; syntax (with an equals sign), while properties use Name: value; syntax (with a colon):

@FlexLabel = Label {
  @Text = "Default";
  @Color = #ffffff;

  Text: @Text;
  Style: (TextColor: @Color, FontSize: 14);
  FlexWeight: 1;
};

// Usage
@FlexLabel {
  @Text = "Custom Text";
  @Color = #ff0000;
}

Extending Styles with Spread

Use the spread operator ... to build on existing styles:

@BaseStyle = (FontSize: 14, TextColor: #ffffff);

@HeaderStyle = (...@BaseStyle, FontSize: 24, RenderBold: true);

The @HeaderStyle inherits everything from @BaseStyle and adds or overrides specific properties.

Importing Templates from Other Files

To use templates from another file, import it first:

$C = "../../Common.ui";
$Sounds = "../../Sounds.ui";

The path is relative to your .ui file’s location. Then reference templates with the import prefix:

$C.@TextButton { ... }
$C.@DefaultLabelStyle

Templates from Common.ui

Here are some of the most useful templates available from Common.ui:

Template	What it is
@PageOverlay	Full-screen overlay background
@DecoratedContainer	Bordered container with title area
@TextButton	Standard primary button
@SecondaryTextButton	Secondary action button
@TextField	Text input field
@CheckBox	Checkbox control
@BackButton	Navigation back button
@DefaultScrollbarStyle	Scrollbar appearance

Here’s how to use them together:

$C = "../../Common.ui";

$C.@PageOverlay {
  $C.@DecoratedContainer {
    Anchor: (Width: 400, Height: 300);

    #Title {
      $C.@Title { @Text = "My Dialog"; }
    }

    #Content {
      Label { Text: "Hello!"; }

      $C.@TextButton {
        @Text = "OK";
      }
    }
  }
}

---

Practical UI Patterns

Let’s look at some common UI patterns you’ll use again and again. These are the bread and butter of UI design - master these and you can build almost any interface.

Form Row (Label + Input)

This pattern creates a horizontal row with a label on the left and an input field that fills the remaining space:

Group {
  LayoutMode: Left;
  Anchor: (Height: 40);

  Label {
    Text: "Name:";
    Anchor: (Width: 100);
    Style: (VerticalAlignment: Center);
  }

  TextField {
    FlexWeight: 1;
    Anchor: (Height: 32);
  }
}

Button Row (Right-Aligned)

For dialogs that need Cancel and Save buttons:

Group {
  LayoutMode: Left;
  Anchor: (Height: 44);
  Padding: (Top: 10);

  Group { FlexWeight: 1; }

  $C.@SecondaryTextButton {
    @Text = "Cancel";
    Anchor: (Width: 100);
  }

  Group { Anchor: (Width: 10); }

  $C.@TextButton {
    @Text = "Save";
    Anchor: (Width: 100);
  }
}

The FlexWeight: 1 spacer pushes the buttons to the right side.

Item Slot with Quantity

Display an item with a quantity badge:

Group {
  Anchor: (Width: 48, Height: 48);

  Group #SlotBorder {
    Anchor: (Full: 0);
    Background: #2a3a4a;
    Padding: 2;

    ItemSlot #Slot {
      Anchor: (Full: 0);
      ShowQualityBackground: true;
    }
  }

  Label #Quantity {
    Anchor: (Right: 4, Bottom: 2);
    Style: (
      FontSize: 12,
      TextColor: #ffffff,
      HorizontalAlignment: End
    );
    Text: "1";
  }
}

---

Connecting UI to Java

Your UI comes alive when you connect it to your mod’s Java code. This is where static screens become interactive experiences that actually do things.

Setting Properties at Runtime

Use commandBuilder.set() to update UI elements:

commandBuilder.set("#MyLabel.Text", "New text");
commandBuilder.set("#MyButton.Visible", true);
commandBuilder.set("#MyButton.Disabled", false);
commandBuilder.set("#ItemSlot.ItemId", "Sword_Iron");

The first argument is a selector that targets your element by its ID, followed by the property name.

What You Can Set on Each Element

Element	Settable Properties
Label	.Text, .Visible
TextButton	.Text, .Disabled, .Visible
Button	.Disabled, .Visible
Group	.Visible
ItemSlot	.ItemId, .Visible

Working with Lists

For dynamic lists, you can clear and append items:

commandBuilder.clear("#MyList");
commandBuilder.append("#MyList", "Pages/MyMod/ListItem.ui");
commandBuilder.set("#MyList[0] #ItemText.Text", "First item");
commandBuilder.set("#MyList[1] #ItemText.Text", "Second item");

The [0] and [1] are index selectors that target specific children in the list.

Handling Button Clicks

Bind events to respond to user interactions:

eventBuilder.addEventBinding(
    CustomUIEventBindingType.Activating,
    "#SaveButton",
    EventData.action("SAVE"),
    false
);

Testing Your UIs

Once you’ve created your .ui files, you’ll need to register them with the game and trigger them to see your work in action. Head back to the Building and Testing Your Mod section in the Getting Started guide for the full walkthrough on building your mod JAR, installing it, and verifying everything works as expected.

---

Quick Reference

Here’s a condensed reference for when you just need to look something up quickly. Bookmark this section - you’ll be back.

Element Types

Element	Purpose
Group	Container for layout
Label	Display text
Button	Clickable (no text)
TextButton	Clickable with text
TextField	Text input
NumberField	Numeric input
CheckBox	Boolean toggle
ItemSlot	Display game item
Sprite	Animated image

Layout Modes

Mode	Description
Top	Vertical, top-aligned
Bottom	Vertical, bottom-aligned
Left	Horizontal, left-aligned
Right	Horizontal, right-aligned
Center	Horizontal center
Middle	Vertical center
CenterMiddle	Centered both axes
Full	Fill container
TopScrolling	Vertical with scroll
LeftScrolling	Horizontal with scroll

Property Value Types

Type	Example	Notes
String	"Hello"	Quote-wrapped text
Translation	%key.path;	Localization key
Number	42, 3.14	Integer or float
Boolean	true, false
Color	#ffffff, #ff0000(0.5)	Hex with optional alpha
Tuple	(Key: value, Key2: value2)	Grouped properties
Reference	@TemplateName	Template or style reference

Group Properties

Property	Example
LayoutMode	LayoutMode: Top;
Background	Background: #1a1a2e;
Padding	Padding: (Full: 10);
Anchor	Anchor: (Width: 100);
Visible	Visible: false;
HitTestVisible	HitTestVisible: false;
FlexWeight	FlexWeight: 1;
ScrollbarStyle	ScrollbarStyle: $C.@DefaultScrollbarStyle;

Label Properties

Property	Example
Text	Text: "Hello";
Style	Style: (FontSize: 14);
Anchor	Anchor: (Height: 20);
Visible	Visible: true;
FlexWeight	FlexWeight: 1;

Button/TextButton Properties

Property	Example
Text	Text: "Click"; (TextButton only)
Style	Style: $C.@DefaultTextButtonStyle;
Disabled	Disabled: true;
Anchor	Anchor: (Width: 100);
Visible	Visible: true;
Background	Background: #3a3a4a;
Padding	Padding: (Full: 8);

Color Examples

#ffffff            // White
#000000            // Black
#ff0000            // Red
#00ff00            // Green
#0000ff            // Blue
#ffffff(0.5)       // 50% transparent white
#000000(0)         // Fully transparent
#1a1a2e            // Dark blue-gray (common UI background)

Comments

// This is a single-line comment
// Comments can appear anywhere in your file

---

Where to Go Next

Look at how far you’ve come! You now know how to build custom UIs in Hytale - from simple dialogs to complex interactive interfaces. That’s a genuinely useful skill.

Here’s where to go from here:

• Getting Started with Hytale Modding - If you need a refresher on project structure, the plugin lifecycle, or how to register and display UI pages from Java, the first guide in this series has you covered.
• Common.ui - Located at Common/UI/Custom/Common.ui, this file contains all the standard templates and styles. Reading through it is like getting a masterclass in Hytale UI design.
• Vanilla UI Pages - Check Common/UI/Custom/Pages/ to see how the game’s own interfaces are built. These are excellent real-world examples, and I still reference them regularly.
• Sounds.ui - Audio definitions for UI interactions. Adding subtle sounds to your buttons and interactions makes everything feel so much more polished.

If something in this guide didn’t click or you’re stuck on a specific problem, feel free to reach out. I love hearing about what people are building and helping debug tricky UI issues.

Happy modding!