Init

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

@@ -0,0 +1,331 @@
+---
+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;
+  }
+}
+```