` elements with `LayoutMode` or item grids. ### 3. No Absolute/Fixed Positioning There's no `position: absolute` or `position: fixed`. Elements are positioned by: * Their parent's `LayoutMode` * `anchor-*` properties (which work more like constraints than positioning) * `flex-weight` for space distribution ## Element Limitations ### 1. Nesting Restrictions While most elements can nest, some Hytale UI macros have unexpected behavior when deeply nested: ```html

``` Specialized buttons (`action-button`, `toggle-button`, etc.) work best with minimal nesting. ### 2. Container Child Structure Containers (`.container`, `.decorated-container`) expect specific child structure: ```html

This goes to content

``` ### 3. Raw Buttons Need Specific Content `raw-button` class is for buttons with custom child content: ```html ``` ### 4. Event Listeners Require IDs Only elements with `id` attributes can have event listeners attached: ```html ``` ### 5. UI File Parsing Is Experimental (0.9.0+) Use `fromUIFile(...)` to parse `.ui` files into HyUI elements so you can call `getById(...)` and attach events. This feature is **experimental**, and may change as it matures. If you use `fromFile(...)`, the UI is loaded as raw assets (no parsing), so element access is limited to low-level commands like `.editElement(...)`. ## Image Limitations ### 1. Dynamic Image Limits Dynamic images (including Hyvatar) are limited: * **25 dynamic images** per page, per player * Downloaded PNGs cached for **15 seconds** * No support for animated images (GIF, APNG, etc.) ```html

``` File path support (0.9.0+), relative to `mods`: ```html

``` This resolves to `mods/ModGroup_ModName/avatars/head/Elyra.png`. ### 2. Image Paths Are Relative All `src` paths are relative to `Common/UI/Custom`: ```html

``` ## Style Reference Limitations ### 1. Style References Override Other Properties When using `hyui-style-reference`, other CSS properties in the same block may be ignored: ```css .my-element { color: #ff0000; /* May be ignored */ font-size: 20; /* May be ignored */ hyui-style-reference: "Common.ui" "DefaultLabel"; /* This takes precedence */ } ``` Apply overrides after the reference or use `data-hyui-style` for specific properties. ### 2. Default Styles Override Partially Elements with `default-style` class apply Hytale's default styling, but CSS can override: ```html Red Label ``` However, not all properties may override correctly depending on the element type. ## Form Input Limitations ### 1. Input Values Need Tracking Form inputs don't automatically track their values. You must handle value changes: ```html ``` ```java builder.addEventListener("username", CustomUIEventBindingType.TextValueChanged, (event, ctx) -> { String newValue = event.getValue(); // Track value changes // Store or process value }); ``` ### 2. No Native Form Submission There's no `

` element or native form submission. Implement your own submission logic: ```html ``` ```java builder.addEventListener("submit", CustomUIEventBindingType.Activating, (ignored, ctx) -> { // Manually collect and process form values }); ``` ## Tab Limitations ### 1. Tab Content Must Use Specific IDs Tab content blocks must use `data-hyui-tab-id` that matches the tab ID: ```html

Home content

About content

Won't show

``` ### 2. Multiple Tab Navs Need Explicit Links When using multiple tab navigations on one page, use `data-hyui-tab-nav`: ```html

...

``` ## Performance Considerations ### 1. Page Updates Can Be Expensive Calling `updatePage()` or rebuilding UIs frequently can impact performance. Cache built UIs when possible and only update when necessary. ### 2. Deep Nesting Affects Performance Deeply nested element structures increase build time and memory usage. Keep hierarchies as flat as practical. ### 3. Many Dynamic Images Hurt Performance Each dynamic image is a network request and texture upload. Minimize usage and cache where possible. ## Common Mistakes ### 1. Using HTML/CSS You Know ```css /* ❌ Common mistakes from web development */ .box { display: flex; /* Use layout-mode instead */ border: 1px solid black; /* Use background-image with borders */ margin: 10px; /* Use anchor-* properties */ opacity: 0.5; /* Use rgba() in colors instead */ } /* ✅ HYUIML equivalents */ .box { layout-mode: Left; background-color: rgba(0, 0, 0, 0.8) 1; anchor-left: 10; anchor-right: 10; } ``` ### 2. Expecting Browser Behavior ```java // ❌ No DOM APIs Element button = builder.querySelector("#my-button"); // ✅ Use HyUI APIs builder.addEventListener("my-button", ...); builder.getById("my-button"); ``` ### 3. Forgetting ID Sanitization ```java // ❌ Using sanitized ID builder.addEventListener("HYUUIDmybutton0", ...); // ✅ Using original ID builder.addEventListener("my-button", ...); ``` ### 4. Overusing Custom Buttons Custom buttons (`custom-textbutton`, `custom-button`) require state style definitions. For simple styled buttons, use regular buttons with CSS: ```html ``` ## Tips for Success 1. **Start simple** - Use standard elements before reaching for custom components 2. **Test frequently** - HYUIML doesn't have browser DevTools, so test changes often 3. **Read the element reference** - Many elements have specific attribute requirements 4. **Use default styles** - Add `class="default-style"` to get consistent Hytale styling 5. **Keep hierarchies flat** - Avoid deep nesting when possible 6. **Cache values** - Track form input values in your own data structures 7. **Use IDs strategically** - Only add IDs where you need event listeners or queries 8. **Check the CSS docs** - Don't assume CSS properties work—verify they're supported ## When to Use Raw Builders Instead Consider using HyUI's Java builders directly when: * You need complex dynamic behavior * You're building reusable components * Performance is critical * You need fine-grained control HYUIML is best for: * Static or semi-static layouts * Rapid prototyping * Declarative UIs with simple logic * When HTML/CSS familiarity speeds development