HyUI

HyUI 是一款面向开发者、功能强大的 Java 库，旨在简化 Hytale 服务器中自定义用户界面的创建与管理。通过桥接 Hytale 底层的 UI 协议与高级抽象，HyUI 让您能够使用流畅的 Java 构建器 API 或 HYUIML（一种声明式、类似 HTML/CSS 的语法），构建复杂、交互性强且高性能的 UI。

无论您是构建一个简单的管理面板、一个持久化的 HUD，还是一个完整的 RPG 菜单系统，HyUI 都能提供所需的工具和“应急出口”，让您高效地完成任务。

文档：https://hyui.gitbook.io/docs

---

功能特性

• HYUIML (HTML/CSS)： 使用类似 HTML 的声明式语法配合 CSS 样式来构建界面，并支持模板化和可重用组件。
• 流畅的构建器 API： 通过清晰、可读的方法链来构建嵌套的 UI 层级结构（组、按钮、标签等）。
• 多 HUD 系统： 能够轻松与其他模组共存。HyUI 自动管理 Hytale 的单个 HUD 插槽，允许多个独立的 HUD 元素同时显示。
• 动态元素注入： 加载基础的 .ui 文件，并在运行时将动态元素注入到特定的选择器中。
• 简化的事件处理： 使用简单的 Lambda 表达式将服务器端逻辑直接绑定到 UI 事件，并通过 UIContext 访问 UI 状态。
• 周期性 UI 刷新： 内置对批量、周期性 HUD 更新的支持，性能开销低。
• 专用构建器： 包含可直接使用的构建器，用于：
  • 按钮： 标准化的游戏主题文字按钮和返回按钮。
  • 输入字段： 文本、数字、滑块、复选框和颜色选择器。
  • 进度条： 带有可定制纹理和效果的动态进程指示器。
  • 物品图标： 使用资源包支持的纹理显示物品图标。
  • 容器： 灵活的组构建器，支持多种布局模式和窗口框架。
• 图像： 易于使用的资源包支持图像，以及运行时下载的动态图像。
• 高级逻辑 (应急出口)： 在任何时候都能访问原始的 UICommandBuilder 实例，以实现 API 本身未原生支持的属性。

---

快速开始

1. 安装 (Gradle)

要在您的 Hytale 项目中使用 HyUI，可以通过使用示例项目快速开始：https://github.com/Elliesaur/Hytale-Example-UI-Project

否则，通过 Cursemaven 将 HyUI 添加到您的项目：

repositories {
    maven { url "https://www.cursemaven.com" }
}

dependencies {
    // 项目 ID: 1431415
    implementation "curse.maven:hyui-1431415:<file-id>"
}

2. 使用 HYUIML (HTML) 创建页面

对于大多数用例，HYUIML 是构建布局最快的方式：

String html = """
    <div class="page-overlay">
        <div class="container" data-hyui-title="我的菜单">
            <div class="container-contents">
                <p>欢迎来到菜单！</p>
                <button id="myBtn">点击我</button>
                <img class="dynamic-image" src="https://example.invalid/render/PlayerName" />
            </div>
        </div>
    </div>
    """;

PageBuilder.pageForPlayer(playerRef)
    .fromHtml(html)
    .addEventListener("myBtn", CustomUIEventBindingType.Activating, (ctx) -> {
        playerRef.sendMessage(Message.raw("已点击！"));
    })
    .open(store);

3. 创建 HUD

HUD 是持久化的屏幕元素：

HudBuilder.hudForPlayer(playerRef)
    .fromHtml("<div style='anchor-top: 10; anchor-left: 10;'><p>生命值: 100</p></div>")
    .show(store);

---

组件

构建器	用途
PageBuilder	全屏 UI 的入口点；管理文件加载和生命周期。
HudBuilder	HUD 创建的入口点；管理多 HUD 共存和刷新。
GroupBuilder	用于组织和对齐子元素的容器。
ContainerBuilder	提供标准的 Hytale 窗口框架。
PageOverlayBuilder	全屏覆盖层容器。
TabNavigationBuilder	标签页导航栏。
TabContentBuilder	标签页内容容器。
ButtonBuilder	用于交互式按钮；支持标准的 Hytale 美学风格。
LabelBuilder	用于显示带有样式和对齐支持的动态文本。
ImageBuilder	用于显示资源包支持的图像 (.png)。
DynamicImageBuilder	运行时下载的 PNG 图像。
TextFieldBuilder	捕获玩家的字符串输入。
NumberFieldBuilder	捕获玩家的数字输入。
DropdownBoxBuilder	下拉选择控件。
CheckBoxBuilder	复选框输入控件。
ColorPickerBuilder	提供十六进制颜色选择界面。
SliderBuilder	提供数字滑块支持。
ProgressBarBuilder	提供进度条支持。
TimerLabelBuilder	带格式的计时器标签。
SpriteBuilder	动画精灵渲染。
ItemIconBuilder	提供物品图标支持。
ItemSlotBuilder	物品插槽 UI 元素。
ItemGridBuilder	可滚动的物品网格。

---

文档与示例

详细的安装、页面构建、HUD 构建和 HYUIML 文档可以在 docs 文件夹中找到。

点击本页面上的 Source 按钮（桌面端在右侧边栏，移动端在详情 -> Source）查看完整的文档和实现示例！

要求：

• 将 Hytale 服务器作为依赖项添加
• Java 25（或当前与 Hytale 兼容的版本）
• jsoup（在 MIT 许可下嵌入于 JAR 中）
• MultipleHUD - 可选依赖项 - 已在 JAR 中包含源码（未嵌入），遵循 MIT 许可。

许可证

所有开源许可证均可在 JAR 文件和 GitHub 仓库中找到。

帮助和支持

欢迎加入 Discord：https://discord.gg/NYeK9JqmNB - 乐于提供帮助！