Documentation/content/ui-systems/ui-syntax.en.md

title, type, weight

title	type	weight
UI Syntax	docs	11

This page covers the complete syntax of Hytale's UI markup language.

Comments

// Single line comment

/* Multi-line
   comment */

Variables

Local Variables

Define variables with @ prefix:

@MyNumber = 50;
@MyString = "Hello";
@MyColor = #ff5500;
@MyObject = (Key: value, Other: 123);

Variable Types

Type	Example
Number	@Size = 50;
String	@Text = "Hello";
Color	@Color = #ff5500;
Object	@Obj = (Width: 100, Height: 50);
Array	@List = [item1, item2, item3];
Boolean	@Visible = true;

Using Variables

Reference variables with @:

Group {
  Anchor: (Height: @MyNumber);
  Background: (Color: @MyColor);
}

Imports

Import Files

Use $ prefix to import external files:

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

Reference Imported Variables

Access imported variables with dot notation:

$Common.@DefaultButtonStyle
$Sounds.@ButtonsLight

Use Imported Templates

Instantiate templates from imports:

$Common.@TextButton {
  @Text = "Click Me";
}

Colors

Hexadecimal

@Color1 = #ff5500;          // RGB
@Color2 = #ff5500ff;        // RGBA

With Opacity

@Color3 = #ff5500(0.5);     // 50% opacity
@Color4 = #000000(0.8);     // 80% opacity

Objects

Basic Object

@Style = (
  FontSize: 16,
  TextColor: #ffffff,
  RenderBold: true
);

Nested Objects

@ButtonStyle = (
  Default: (
    Background: (TexturePath: "Button.png", Border: 12)
  ),
  Hovered: (
    Background: (TexturePath: "ButtonHovered.png", Border: 12)
  )
);

Spread Operator

Use ... to extend/merge objects:

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

@ExtendedStyle = (
  ...@BaseStyle,          // Inherit all properties from @BaseStyle
  RenderBold: true        // Add/override properties
);

Spread works in any object context:

Style: (
  ...$Common.@DefaultButtonStyle,
  Sounds: (
    ...$Sounds.@ButtonsLight,
    Activate: (Volume: 10)
  )
);

Templates (Macros)

Define a Template

Templates are reusable widget definitions with parameters:

@MyButton = TextButton {
  @Text = "";                    // Parameter with default
  @Anchor = Anchor();            // Parameter with default
  @Sounds = ();                  // Empty default

  Style: @DefaultTextButtonStyle;
  Anchor: (...@Anchor, Height: 44);
  Text: @Text;
};

Instantiate a Template

// Use with defaults
@MyButton {}

// Override parameters
@MyButton {
  @Text = "Submit";
  @Anchor = (Width: 200);
}

// From import
$Common.@TextButton {
  @Text = %ui.button.confirm;
}

Widget Declarations

Basic Widget

WidgetType {
  Property: value;
}

Widget with ID

IDs start with # and allow targeting from Java. IDs must be in UpperCamelCase format (no hyphens or underscores):

Label #PlayerName {
  Text: "Unknown";
}

// Valid IDs
#MainPanel
#ConfirmButton
#PlayerHealthBar

// Invalid IDs (will cause errors)
#main-panel      // No hyphens allowed
#confirm_button  // No underscores allowed
#playerhealthbar // Should be UpperCamelCase

Nested Widgets

Group #Container {
  Label #Title {
    Text: "Header";
  }

  Group #Content {
    Label {
      Text: "Body text";
    }
  }
}

Anonymous Widgets

Widgets without ID are anonymous:

Group {
  Label { Text: "No ID"; }
}

Selectors

Selectors are strings starting with # used to target elements:

// In Java code
builder.set("#PlayerName", "Steve");
builder.append("#Container", "ui/child_template");
builder.clear("#Content");

Translation Keys

Use % prefix for localized strings:

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

TextButton {
  Text: %client.button.confirm;
}

Typed Constructors

Some complex types use function-style constructors:

// Style constructors
@Style = LabelStyle(FontSize: 16, TextColor: #fff);
@BtnStyle = ButtonStyle(Default: (...), Hovered: (...));

// Layout constructors
@Pad = Padding(Full: 10);
@Anch = Anchor(Width: 100, Height: 50);

// Visual constructors
@Bg = PatchStyle(TexturePath: "bg.png", Border: 12);
@Scroll = ScrollbarStyle(Size: 6, Spacing: 8);

Complete Example

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

@PanelWidth = 400;
@PanelHeight = 300;
@TitleColor = #b4c8c9;

@PanelTitle = Label {
  @Text = "";

  Style: (
    FontSize: 20,
    TextColor: @TitleColor,
    RenderBold: true,
    HorizontalAlignment: Center
  );
  Text: @Text;
};

Group #MainPanel {
  Anchor: (Width: @PanelWidth, Height: @PanelHeight);
  Background: (TexturePath: "Panel.png", Border: 20);
  LayoutMode: Top;
  Padding: (Full: 16);

  @PanelTitle {
    @Text = %ui.panel.title;
  }

  Group #Content {
    FlexWeight: 1;
    LayoutMode: TopScrolling;
    ScrollbarStyle: $Common.@DefaultScrollbarStyle;
  }

  $Common.@TextButton #ConfirmButton {
    @Text = %ui.button.confirm;
    @Sounds = $Sounds.@ButtonsLight;
  }
}