HUD 图标库

.detail-panel[hidden] { display: block !important; } .detail-tabs { display: none; } /* These three panels are rendered by the browser. */ [data-versions], [data-changelog-panel], [data-comments] { display: none; }

什么是 HUD 图标库？

HUD 图标库是一个实用模组，它为其他 Fabric 模组提供了一个简单的 API，用于在屏幕上显示图标。它通常用于：

状态指示器（生命值、法力值、耐力）
增益/减益效果通知（速度提升、力量等）
任务标记和任务目标
自定义 HUD 元素
带计时器的临时通知

特性

✨ 多图标：可同时显示多个图标 ⏱️ 计时器支持：图标可以永久显示，或在设定时间后自动移除 🎯 灵活定位：图标可放置在屏幕任意位置（默认：左上角） 📐 可自定义尺寸：默认 16x16 像素（物品栏物品尺寸），完全可调 🖼️ 图像支持：PNG 和 JPG 格式 📝 文字显示：图标旁可添加可选文字标签 ⚙️ 基于代码的配置：简单 API，无需配置文件 🪶 轻量级：除 Fabric API 外无额外依赖

集成指南

本指南将说明如何将 HUD 图标库集成到您现有的 Fabric 模组中。

添加依赖

选项 1：使用编译后的 JAR 文件

将 JAR 文件下载到您模组的 libs/ 文件夹
将其添加到您模组的 build.gradle：

   repositories {
       flatDir {
           dirs 'libs'
       }
   }

   dependencies {
       // ... 其他依赖

       // 添加 HUD 图标库
    modImplementation project(':hudiconlib')
    include project(':hudiconlib')
   }

声明依赖

将库添加到您的 fabric.mod.json 依赖中：

{
  "depends": {
    "fabricloader": ">=0.15.0",
    "minecraft": "~1.20.1",
    "hudiconlib": "*"
  }
}

基本用法

导入 API

import net.cookiebrain.hudiconlib.HudIconLib;
import net.cookiebrain.hudiconlib.Icon;

创建并注册图标

简单图标（始终可见）

// 为您的纹理创建一个标识符
Identifier iconTexture = new Identifier("mymod", "textures/gui/icon.png");

// 在默认位置（左上角）创建一个图标
Icon myIcon = HudIconLib.createIcon(
    "mymod:my_icon",              // 唯一 ID
    iconTexture,                  // 纹理标识符
    10, 10, 16, 16               // X, Y, 宽度, 高度
);

// 可选：添加文字
myIcon.setText("我的图标");

// 注册图标
HudIconLib.registerIcon(myIcon);

自定义位置和尺寸

Identifier customTexture = new Identifier("mymod", "textures/gui/custom.png");

Icon customIcon = HudIconLib.createIcon(
    "mymod:custom_icon",
    customTexture,
    100,  // X 位置
    50,   // Y 位置
    24,   // 宽度
    24    // 高度
);
HudIconLib.registerIcon(customIcon);

定时图标（在指定时间后自动移除）

Identifier buffTexture = new Identifier("mymod", "textures/gui/buff.png");

Icon timedIcon = HudIconLib.createIcon(
    "mymod:timed_icon",
    buffTexture,
    10, 10, 16, 16
);
timedIcon.setText("增益效果已激活！");
timedIcon.setTextColor(0x00FF00);  // 绿色文字
timedIcon.setDuration(30);         // 30 秒

HudIconLib.registerIcon(timedIcon);

快速入门示例

以下是您模组初始化的完整示例：

package com.example.mymod;

import net.fabricmc.api.ClientModInitializer;
import net.minecraft.util.Identifier;
import net.cookiebrain.hudiconlib.HudIconLib;
import net.cookiebrain.hudiconlib.Icon;

public class MyModClient implements ClientModInitializer {
    private static final String MOD_ID = "mymod";

    @Override
    public void onInitializeClient() {
        // 初始化您的模组...

        // 在初始化期间添加图标
        setupIcons();
    }

    private void setupIcons() {
        // 示例 1：永久生命值图标
        Identifier heartTexture = new Identifier(MOD_ID, "textures/gui/heart.png");
        Icon healthIcon = HudIconLib.createIcon(
            "mymod:health",
            heartTexture,
            10, 10, 16, 16
        );
        healthIcon.setText("❤ 20");
        healthIcon.setTextColor(0xFF0000); // 红色
        HudIconLib.registerIcon(healthIcon);

        // 示例 2：基于计时器的增益效果图标
        Identifier speedTexture = new Identifier(MOD_ID, "textures/gui/speed.png");
        Icon buffIcon = HudIconLib.createIcon(
            "mymod:speed_buff",
            speedTexture,
            10, 30, 16, 16
        );
        buffIcon.setText("速度提升");
        buffIcon.setDuration(60); // 60 秒
        HudIconLib.registerIcon(buffIcon);
    }

    // 您可以随时添加/移除图标
    public void showCustomIcon(String message, int duration) {
        Identifier infoTexture = new Identifier(MOD_ID, "textures/gui/info.png");
        Icon notification = HudIconLib.createIcon(
            "mymod:notification_" + System.currentTimeMillis(),
            infoTexture,
            10, 50, 16, 16
        );
        notification.setText(message);
        notification.setDuration(duration);
        HudIconLib.registerIcon(notification);
    }
}

高级用法

使用建造者模式

Identifier advancedTexture = new Identifier("mymod", "textures/gui/advanced.png");

HudIconLib.builder("mymod:advanced_icon", advancedTexture)
    .position(150, 100)
    .size(32, 32)
    .text("高级图标")
    .textColor(0xFFAA00)
    .duration(45)
    .alpha(0.8f)
    .buildAndRegister();

动态图标管理

// 显示/隐藏图标
HudIconLib.hideIcon("mymod:my_icon");
HudIconLib.showIcon("mymod:my_icon");

// 移除图标
HudIconLib.removeIcon("mymod:my_icon");

// 检查图标是否存在
if (HudIconLib.hasIcon("mymod:my_icon")) {
    // 执行某些操作
}

// 更新现有图标
Icon icon = HudIconLib.getIcon("mymod:my_icon");
if (icon != null) {
    icon.setText("已更新文字");
    icon.setAlpha(0.5f);
}

// 清除所有图标
HudIconLib.clearAllIcons();

响应游戏事件

import net.fabricmc.fabric.api.client.event.lifecycle.v1.ClientTickEvents;

public class MyModClient implements ClientModInitializer {

    @Override
    public void onInitializeClient() {
        // 在玩家刻更新图标
        ClientTickEvents.END_CLIENT_TICK.register(client -> {
            if (client.player != null) {
                updatePlayerIcons(client.player);
            }
        });
    }

    private void updatePlayerIcons(PlayerEntity player) {
        // 更新生命值显示
        Icon healthIcon = HudIconLib.getIcon("mymod:health");
        if (healthIcon != null) {
            int health = (int) player.getHealth();
            healthIcon.setText("❤ " + health);
        }

        // 显示低生命值警告
        if (player.getHealth() < 6.0f) {
            if (!HudIconLib.hasIcon("mymod:low_health_warning")) {
                Identifier warningTexture = new Identifier("mymod", "textures/gui/warning.png");
                Icon warning = HudIconLib.createIcon(
                    "mymod:low_health_warning",
                    warningTexture,
                    10, 50, 16, 16
                );
                warning.setText("生命值低！");
                warning.setTextColor(0xFF0000);
                HudIconLib.registerIcon(warning);
            }
        } else {
            HudIconLib.removeIcon("mymod:low_health_warning");
        }
    }
}

最佳实践

1. 图标文件组织

将图标文件存储在可预测的位置：

src/main/resources/
  assets/
    yourmod/
      textures/
        gui/
          icon1.png
          icon2.png

2. 使用命名空间 ID

始终使用您的模组 ID 作为图标 ID 的前缀：

    // 好
    HudIconLib.createIcon("mymod:health_icon", ...)

    // 不好 - 可能与其他模组冲突
    HudIconLib.createIcon("health_icon", ...)

3. 清理定时图标

对于短时图标，始终使用 .setDuration() 以便它们自动移除：

icon.setDuration(30); // 30 秒后自动移除

4. 检查现有图标

在创建重复图标之前：

if (!HudIconLib.hasIcon("mymod:my_icon")) {
    Icon icon = HudIconLib.createIcon(...);
    HudIconLib.registerIcon(icon);
}

5. 安全地处理空值

获取图标时：

Icon icon = HudIconLib.getIcon("mymod:my_icon");
if (icon != null) {
    // 更新图标
}

6. 性能考虑

限制同时显示的图标数量（推荐：少于 20 个）
使用合适的图标尺寸（推荐 16x16，避免大图）
在不再需要时移除图标

7. 文字格式化

使用 Minecraft 颜色代码为文字着色：

icon.setTextColor(0xFFFFFF); // 白色
icon.setTextColor(0xFF0000); // 红色
icon.setTextColor(0x00FF00); // 绿色
icon.setTextColor(0x0000FF); // 蓝色
icon.setTextColor(0xFFAA00); // 橙色

故障排除

图标未显示

检查文件路径：确保纹理路径正确且文件存在
检查可见性：确保 icon.isVisible() 返回 true
检查注册：验证图标已成功注册

图标闪烁

不要在每一帧创建/移除图标
使用 hideIcon()/showIcon() 代替移除和重新创建

性能问题

减少同时显示的图标数量
使用更小的纹理文件
使用 removeIcon() 或 clearAllIcons() 移除未使用的图标

示例项目结构

your-mod/
├── build.gradle
├── src/main/
│   ├── java/com/yourmod/
│   │   ├── YourMod.java
│   │   └── YourModClient.java
│   └── resources/
│       ├── fabric.mod.json
│       └── assets/
│           └── yourmod/
│               └── textures/
│                   └── gui/
│                       ├── icon1.png
│                       └── icon2.png
└── libs/
    └── hudiconlib-0.2.0.jar