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

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

```java
// 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;
  }
}
```