HUD 合奏

HUD 组合器

HUD 组合器是一个服务端 Hytale 插件，可实现每位玩家的多层 HUD 组合。

在原始行为中，同一时间只能激活一个 CustomUIHud — 这意味着插件通常会互相覆盖。HUD 组合器通过将多个 HUD 层组合成一个单一的复合 HUD 来解决此问题，使不同系统（或不同插件）能够同时显示 UI。

---

主要功能

• 多层 HUD
  为同一玩家堆叠多个 CustomUIHud 层。

• 命名空间层（无冲突）
  每个插件可通过客户端句柄使用自己的命名空间，防止意外的 ID 冲突。

• 快速更新（无需重建）
  使用 updateLayer(...) 在现有层内更新 UI 元素，无需重建整个 HUD。

• 广播辅助
  为所有在线玩家显示/移除层（尽力而为；按世界线程调度）。

• 清理安全性
  正确的 close() 会移除你的所有层。当客户端变得不可达时，存在一个尽力而为的垃圾回收安全网，但它不能替代调用 close()。

---

安装

1. 构建插件 .jar 文件。
2. 将其放入服务器的 plugins 文件夹中。
3. 启动（或重启）服务器。

建议：

• 在依赖 HUD 组合器的插件之前加载它。
• 始终使用至少两个设置 HUD 的插件进行测试，以确认组合按预期工作。

---

演示命令

这些命令仅用于服务器测试。对于实际集成，请使用 API（见下文）。

• /hudens demo — 启用演示 HUD 层
• /hudens clean — 移除演示 HUD 层

---

开发者指南（API）

HUD 组合器提供了一个专为其他服务器插件设计的公共 API。

1) 获取服务 / 打开客户端

使用客户端句柄可自动为你的层 ID 添加命名空间并简化清理工作。

import com.example.hudensemble.api.HudEnsemble;
import com.example.hudensemble.api.HudEnsembleClient;
public class MyPlugin extends JavaPlugin {
  private HudEnsembleClient hud;
  @Override
  protected void setup() {
    hud = HudEnsemble.openClientOrThrow(this);
  }
  @Override
  protected void shutdown() {
    if (hud != null) {
      hud.close(); // 重要：清理
      hud = null;
    }
  }
}

如果未安装 HUD 组合器或不兼容，openClientOrThrow(...) 会抛出一个明确的错误。

2) 向特定玩家显示 HUD 层

hud.setLayer(player, playerRef, "greeting", new MyHud());

稍后使用相同的层 ID 进行替换以更新该层（对该层进行完全重建）。

3) 移除层（或清除此客户端拥有的所有层）

hud.removeLayer(player, "greeting");
hud.clear(player);

4) 在现有层内更新 UI（快速路径）

如果层已存在，就地更新 UI 命令：

hud.updateLayer(player, "greeting", cmd -> {
  cmd.set("#Title.Text", "你好，HUD 组合器！");
  cmd.set("#Counter.Text", "42");
});

选择器按常规编写。HUD 组合器会自动将它们前缀到正确的层根下。

5) 广播（所有在线玩家）

为所有已连接的玩家显示一个层：

int scheduled = hud.setLayerForAllOnline("watermark", pr -> new MyHud());

为所有在线玩家移除一个层：

int scheduled = hud.removeLayerForAllOnline("watermark");

为所有在线玩家清除此客户端拥有的所有层：

int scheduled = hud.clearForAllOnline();

返回的数字是已安排进行操作的玩家数量。

---

兼容性说明（重要）

未使用此 API 的其他插件

• 如果另一个插件在 HUD 组合器为某玩家激活之前设置了 CustomUIHud，该 HUD 可作为“基础层”保留。
• 如果另一个插件在组合器激活之后设置了 CustomUIHud，它将覆盖复合 HUD（这是 setCustomHud 的工作方式），并且 HUD 组合器的层将消失。

回退行为

HUD 组合器依赖一个桥接来构建分层命令。如果当前服务器版本不支持，插件可能会回退到单一 HUD 模式。在该模式下：

• 分层可能不可用，
• 按层移除/更新可能无法按预期工作。

---

API 版本控制

HUD 组合器公开一个 API 版本号，以便依赖插件能验证兼容性。

int v = HudEnsemble.getServiceOrThrow().getApiVersion();

---

联系方式

• Discord / Telegram / 社交平台: artur_hatoka