配置与 GUI 界面集成 (MC 26.2)
本文档详细介绍 Minecraft 26.2 下 Item Clumps 的配置文件结构、YACL v3 界面集成、ModMenu 入口点及世界优先级规则。
📊 配置信息框
| 属性 | 数值 |
|---|---|
| 配置文件路径 | config/item-clumps.json |
| 文件格式 | JSON（由 DasikLibrary ConfigHelper 管理） |
| 当前结构版本 | configVersion: 1 |
| 图形配置界面支持 | YetAnotherConfigLib v3 (YACL) 通过 ModMenu |
| 类加载隔离 | 延迟反射隔离 (GuiHelper.getOptionalYaclFactory) |
| 优先级准则 | 配置文件定义新建世界默认值；现有世界以 GameRules 为准 |
⚠️ 全局配置与活跃世界优先级规则
⚠️ 重要提示：修改
config/item-clumps.json或在 ModMenu 界面中调整设置，仅会定义新建世界的基线默认值。若要调整现有活跃世界的设置，请在游戏内使用/gamerule指令或原版游戏规则编辑界面。
📄 JSON 文件格式规范 (config/item-clumps.json)
json
{
"configVersion": 1,
"enableClumping": true,
"maxClumpSize": 9999,
"renderLabels": true,
"mergeRadius": 1,
"labelMinCount": -1
}字段定义说明
| JSON 键 | 类型 | 默认值 | 描述说明 |
|---|---|---|---|
configVersion | 整数 | 1 | 内部结构版本迁移追踪标识。 |
enableClumping | 布尔值 | true | 开启或关闭掉落物巨型堆叠聚合功能。 |
maxClumpSize | 整数 | 9999 | 单个聚合实体的物品数量硬上限 ($64\text{ 至 }2,147,483,647$)。 |
renderLabels | 布尔值 | true | 在聚合体上方渲染原版浮空自定义铭牌数量。 |
mergeRadius | 整数 | 1 | 水平方块搜索聚合半径 ($1\text{ 至 }10\text{ 格}$)。 |
labelMinCount | 整数 | -1 | 数量标签显示门槛阈值 (-1 = 原版最大堆叠数)。 |
🖥️ 图形配置界面 (YACL v3 & ModMenu)
Item Clumps 通过 YetAnotherConfigLib (YACL v3) 和 ModMenu 提供了可选的客户端配置屏幕：
+-------------------------------------------------------------------------+
| ITEM CLUMPS CONFIGURATION |
| |
| [ General Settings ] |
| |
| Enable Clumping ............................................ [ ON ] |
| When true, ground items aggressively merge into mega-stacks. |
| |
| Max Clump Size ............................................. [ 9999 ] |
| The hard cap on items per entity. (Hidden if Stack Size Adjuster on) |
| |
| Render Labels .............................................. [ ON ] |
| Renders holographic count above item clumps. |
| |
| Merge Radius ................................... [───●──────────] (1) |
| Horizontal block search radius (1-10 blocks). |
| |
| Label Min Count ............................................ [ -1 ] |
| Minimum item count before label displays (-1 for vanilla max stack). |
| |
| [ Cancel ] [ Save & Quit ] |
+-------------------------------------------------------------------------+安全的延迟类加载保障
为确保模组绝不会在专用服务端或未安装 YACL/ModMenu 的客户端上发生类加载崩溃，界面实例化被完全隔离在 GuiHelper.getOptionalYaclFactory 之后：
java
// ModMenuIntegration.java (MC 26.2)
public class ModMenuIntegration implements ModMenuApi {
@Override
public ConfigScreenFactory<?> getModConfigScreenFactory() {
return GuiHelper.getOptionalYaclFactory(
"item_clumps",
"net.instantgratification.item_clumps.config.YaclScreenHelper",
"createScreen"
);
}
}