FlexHUD

FlexHUD

hud lib

FlexHUD

展示

一个基于 NeoForge 构建的可扩展 HUD 布局和渲染库。它使用 "RelativeRect + Anchor" 以独立于分辨率的方式描述 HUD 元素位置和大小，提供带有约束的拖拽/调整大小的交互式配置界面，并将布局持久化到客户端配置中，同时在屏幕尺寸变化时自动重新计算。

目标

  • 通过 RelativeRect 和 Anchor 描述 HUD 元素位置和大小，使布局在不同分辨率/宽高比下保持稳定。
  • 提供简单的注册 API：实现 Layer#render 即可插入自定义 HUD 元素。
  • 提供可视化配置界面 (FlexHudConfigScreen)：拖拽移动，使用手柄调整大小；ResizeMode 控制约束（自由、纵横比、水平、垂直、固定）。
  • 持久化和热更新：使用 NeoForge ModConfig 存储和同步位置；更改在运行时立即生效。

快速开始

注册一个可自由调整大小的快捷栏 HUD 元素：

public class BuiltInFlexHud {
    public static void registerHotbarHud() {
        ResourceLocation id = FlexHudApi.HOTBAR_ID; // 唯一元素 ID

        // 默认相对矩形：底部中心锚点，宽度 182，高度 22
        FlexHudApi.RelativeRect defaultRelativeRect = new FlexHudApi.RelativeRect(
                FlexHudApi.Anchor.BOTTOM_CENTER,
                0, 0,
                182, 22
        );

        // 渲染层：使用计算出的绝对矩形进行绘制
        FlexHudApi.Layer hotbarLayer = (rect, guiGraphics, deltaTracker) -> {
            PoseStack pose = guiGraphics.pose();
            pose.pushPose();

            int screenWidth = guiGraphics.guiWidth();
            int screenHeight = guiGraphics.guiHeight();
            // 从默认相对矩形计算默认快捷栏绝对矩形
            FlexHudApi.Rect defaultRect = defaultRelativeRect.toAbsolute(screenWidth, screenHeight);
            // 应用从 defaultRect 到目标矩形的仿射变换，实现自由移动/缩放
            pose.mulPose(defaultRect.transform(rect));

            ((GuiAccessor) Minecraft.getInstance().gui).callRenderHotbar(guiGraphics, deltaTracker);
            pose.popPose();
        };

        // 使用自由调整大小模式注册，附带默认相对矩形和渲染层
        FlexHudApi.INSTANCE.register(id, FlexHudApi.ResizeMode.Free, defaultRelativeRect, hotbarLayer);
    }
}

运行时，库在渲染前调用 updateScreenDimensions()，将每个元素的 RelativeRect 转换为当前分辨率下的绝对 Rect，并传递给您的 Layer#render。

API 概览

  • FlexHudApi#register(ResourceLocation id, ResizeMode mode, RelativeRect defaultRect, Layer layer)
    • 注册一个 HUD 元素；如果配置中存在已保存的布局，则覆盖默认布局。
  • FlexHudApi.Impl#updateElementRelativeRect(ResourceLocation id, RelativeRect newRect)
    • 运行时更新布局并持久化；配置界面使用此方法。
  • FlexHudApi.Impl#updateScreenDimensions()
    • 当屏幕尺寸/宽高比变化时重新计算所有绝对矩形。
  • FlexHudApi.Layer#render(Rect rect, GuiGraphics g, DeltaTracker dt)
    • 渲染回调：使用提供的绝对矩形进行绘制。
  • FlexHudApi.ResizeMode
    • Free（自由）、Aspect（保持比例）、Horizontal（水平）、Vertical（垂直）、Fixed（固定）。
  • FlexHudApi.Anchor
    • 九宫格锚点：TOP_LEFT / TOP_CENTER / TOP_RIGHT / CENTER_LEFT / CENTER / CENTER_RIGHT / BOTTOM_LEFT / BOTTOM_CENTER / BOTTOM_RIGHT（左上 / 中上 / 右上 / 左中 / 居中 / 右中 / 左下 / 中下 / 右下）。
  • FlexHudApi.RelativeRect
    • 字段：anchor, offsetX, offsetY, width, height, useRelativeSize
    • 方法：toAbsolute(int w, int h) 转换为绝对矩形；fromAbsolute(Rect rect, Anchor a, int w, int h) 推断相对矩形。
  • FlexHudApi.Rect#transform(Rect to)
    • 从源矩形到目标矩形的仿射变换（平移 + 缩放），用于将现有绘制逻辑映射到新位置/大小。

可视化配置

  • 游戏中按 Alt + H 打开 FlexHudConfigScreen。
  • 拖拽移动，使用手柄调整大小；ResizeMode 决定约束。
  • 更改会持久化到客户端配置（NeoForge ModConfig），例如：
  [hud]
  relative_rects = [
    "flexhud:hotbar|BOTTOM_CENTER|-2.9042664|-37.03853|188.19147|22.961472|false"
  ]

要求

  • Minecraft 1.21.1
  • NeoForge 21.x（例如 21.1.213）
  • Java 21

许可证

  • MIT（参见构建脚本/项目配置）。