奎恩的灵活HUD

奎恩的灵活HUD

一个用于辅助排版的 HUD 库

基础库

FlexHUD

show

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

目标

  • 通过 RelativeRect 和 Anchor 描述 HUD 元素的位置和尺寸,使布局在不同分辨率/宽高比下保持稳定。
  • 提供简单的注册 API:实现 Layer#render 即可接入自定义 HUD 元素。
  • 提供可视化配置界面(FlexHudConfigScreen):拖拽移动,使用手柄缩放;ResizeMode 控制约束(Free、Aspect、Horizontal、Vertical、Fixed)。
  • 持久化与热更新:使用 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 到目标 rect 的仿射变换,以实现自由移动/缩放
            pose.mulPose(defaultRect.transform(rect));

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

        // 使用默认相对矩形和渲染层,以 Free 缩放模式注册
        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(见构建脚本 / 项目配置)。