MCreator 基岩版物品「挖掘条目（Digger entries）」配置详解：方块/标签挖掘速度机制与源码实现

• 低代码
• 代码生成
• 桌面应用
• 游戏开发

导读

在 MCreator 的基岩版物品（Bedrock Item）编辑器中，「挖掘条目（Digger entries）」是一组用于定义工具挖掘能力的核心配置：它声明了该工具会受到影响的方块或方块标签，并为每一项指定对应的挖掘速度。本文围绕 digger_entries.md 的官方说明展开，结合仓库中的 GUI 实现、数据模型与代码生成模板，完整讲解挖掘条目的含义、配置方式、源码级工作原理，以及它与效率附魔（Efficiency）的联动机制，帮助你在创作基岩版 Add-On 时精确控制工具的开采行为。

一、挖掘条目的官方定义：逐句解读

原文档 digger_entries.md 的全文如下（英文原文），它是理解该功能的第一手依据：

The following list declares all possible blocks and tags that will be affected by this tool. Each entry can define the speed at which this tool will break the selected block/blocks from the tag.

If a block (as a standalone block or part of a tag) is not present inside this list, the block will keep the normal behavior.

将这段话拆解为三条核心规则：

1. 作用域声明：挖掘条目列表声明了该工具会受到影响的"所有方块与标签"。列表中的每一项既可以是一个独立方块（如minecraft:stone），也可以是一整类方块构成的标签（如minecraft:logs）。
2. 逐项速度控制：每个条目都可以为该条目选中的方块（或标签下的所有方块）单独定义挖掘速度，从而实现"对不同方块有不同破坏速率"的差异化工具效果。
3. 默认回退行为：如果一个方块（无论它是独立方块还是某个标签的一部分）没有出现在此列表中，它将保持 Minecraft 的正常行为——即该工具对它没有特殊挖掘加成，破坏速度遵循游戏原有的计算逻辑。

简而言之：挖掘条目就是一张"工具能力白名单"，只有被明确列出的方块/标签才会享受到你指定的挖掘速度；列表之外的一切都维持原状。

二、挖掘条目的数据模型：一个条目由什么组成

在仓库的源码中，每个挖掘条目的数据结构定义在 src/main/java/net/mcreator/element/types/bedrock/BEItem.java 的DiggerEntry内部类中：

public static class DiggerEntry { @ModElementReference public MItemBlock block; @Numeric(init = 1, min = 0, max = Integer.MAX_VALUE, step = 1) public int speed; public DiggerEntry(MItemBlock block, int speed) { this.block = block; this.speed = speed; } }

这里可以明确两个字段的语义与约束：

注意speed是整数，这是 MCreator 对原版 Bedrock 组件模型的具体化；它没有上限（最大值是 Java 的Integer.MAX_VALUE），意味着理论上可以做出"瞬间破坏"的极端工具。而block字段同时接受独立方块与标签，这与文档中"blocks and tags"的表述完全一致。

同时，BEItem的数据类在 同一文件的 76-77 行 声明了物品层面的两个相关属性：

public boolean diggerUseEfficiency; @ModElementReference public List<DiggerEntry> diggerEntries;

• diggerUseEfficiency（布尔值）：是否让效率附魔影响挖掘速度，对应下文第五节。
• diggerEntries：挖掘条目列表，新建物品时在 构造函数中初始化为空列表，即默认一个条目都没有——按文档规则，此时该工具对所有方块都保持"正常行为"。

三、UI 操作：在哪里配置挖掘条目

挖掘条目的编辑界面位于基岩版物品编辑器（BEItem）的 GUI 中，实现类是 src/main/java/net/mcreator/ui/modgui/bedrock/BEItemGUI.java。

3.1 列表的挂载位置

从源码看，该列表被组织在"工具属性（tool properties）"面板之下。在 BEItemGUI.java 的 293-318 行 中，toolProperties是一个 3 行 2 列的网格面板，依次包含：

• 附魔槽位（enchantment slot）与可附魔开关；
• 附魔等级值（enchantability value）；
• 效率附魔开关diggerUseEfficiency（对应帮助文档 tool_use_efficiency.md）；
• 以及下方挂载的挖掘条目列表diggerEntries。

列表标签通过HelpUtils.wrapWithHelpButton(this.withEntry("beitem/digger_entries"), ...)关联到本文所述的帮助文档，也就是说：你在界面上点击这个列表标题旁的帮助按钮，看到的正是 digger_entries.md 的内容。

3.2 条目编辑器 JDiggerEntry

每个条目由 src/main/java/net/mcreator/ui/minecraft/bedrock/digger/JDiggerEntry.java 渲染，布局为一行三个部分：

1. "影响方块/标签"选择器（MCItemHolder block）：该组件通过ElementUtil::loadBlocks加载方块列表，并传入true参数以允许选择标签（tag）。选择器还挂载了MCItemHolderValidator校验器，空值会触发校验失败提示。
2. "挖掘速度"数值框（JSpinner speed）：通过ComponentFromAnnotation.spinner(...)根据@Numeric注解自动生成，即上文提到的整数区间[0, Integer.MAX_VALUE]，默认 1。
3. 两个控件各带一个帮助按钮，分别关联帮助文档 digger_block.md 与 digger_speed.md。

条目的读写通过getEntry()/setEntry()完成，保存时调用new BEItem.DiggerEntry(block.getBlock(), (Integer) speed.getValue())组装数据。列表中"添加条目"按钮的文案来自国际化键elementgui.beitem.add_digger_entry（"添加挖掘条目"）。

3.3 列表容器 JDiggerList

列表本体由 src/main/java/net/mcreator/ui/minecraft/bedrock/digger/JDiggerList.java 实现，它继承JSimpleEntriesList<JDiggerEntry, BEItem.DiggerEntry>，支持动态增删多个条目。其校验逻辑会聚合所有子条目的校验结果（AggregatedValidationResult），确保保存前每个条目都选择了有效的方块/标签。

3.4 数据流转

GUI 与数据模型的绑定发生在 BEItemGUI.java 的 428-475 行：

• 打开元素时：diggerEntries.setEntries(item.diggerEntries)将已保存的条目回填到界面；
• 保存元素时：item.diggerEntries = diggerEntries.getEntries()与item.diggerUseEfficiency = diggerUseEfficiency.isSelected()将界面状态写回数据模型。

从源码结构看，挖掘条目使用@ModElementReference引用方块，意味着引用其他 MCreator 元素时需重新映射（remap）依赖，这与一般的方块引用机制一致。

四、代码生成：挖掘条目如何写入 Add-On JSON

挖掘条目的最终产物是基岩版物品定义 JSON 中的minecraft:digger组件。生成模板位于 plugins/generator-addon-26.5x/addon-26.5x/templates/item.json.ftl：

<#if data.diggerEntries?? && !data.diggerEntries.isEmpty()> "minecraft:digger": { "use_efficiency": ${data.diggerUseEfficiency}, "destroy_speeds": [ <#list data.diggerEntries as entry> { "block": ${mappedMCItemToRegistryNameOrTag(entry.block)}, "speed": ${entry.speed} }<#sep>, </#list> ] }, </#if>

该模板揭示了几点实现细节：

1. 条件输出：只有当diggerEntries非空时，minecraft:digger组件才会被写入 JSON。列表为空则整个组件不生成——这正是文档"未列入则保持正常行为"的底层保证。
2. use_efficiency：直接输出布尔值data.diggerUseEfficiency，控制效率附魔是否作用于destroy_speeds。
3. 条目序列化：每个条目输出一个{ "block": ..., "speed": ... }对象，多个条目用逗号分隔（FreeMarker 的<#sep>指令）。

其中block字段的序列化由宏 mappedMCItemToRegistryNameOrTag 完成：

<#function mappedMCItemToRegistryNameOrTag mappedBlock> <#if mappedBlock.getUnmappedValue().startsWith("TAG:")> <#return "{\"tags\": \"q.any_tag(\'" + mappedBlock.asTagEntry() + "\')\" }"> <#else> <#return "\"" + mappedMCItemToRegistryNameNoTags(mappedBlock) + "\""> </#if> </#function>

可见标签与独立方块在 JSON 中的表达方式不同：

• 标签（以TAG:开头的映射值）：输出为{ "tags": "q.any_tag('<标签名>')" }，即 Bedrock 的q.any_tag查询语法，表示该条目匹配标签下的所有方块；
• 独立方块：输出为带引号的注册名，如"minecraft:stone"。

同时可以对照宏 mappedMCItemToRegistryNameNoTags：若传入的是CUSTOM:（MCreator 自定义元素），会解析为${modid}:<registryname>形式；若传入的是无命名空间的标签或TAG:标签，则回退为minecraft:air（该宏本身不直接用于 digger 输出，但说明了方块引用归一化的完整规则）。

最终生成的minecraft:digger组件是 Bedrock 原生物品组件，由基岩版运行时解释执行，因此挖掘条目的实际游戏效果由 Minecraft Bedrock 的组件机制保证。

五、两个强关联的配套设置

挖掘条目不是孤立功能，它与另外两个帮助文档描述的设置紧密配合，建议一起配置：

5.1 挖掘速度（Digging speed）

对应文档 digger_speed.md，控制方块被开采的速度：

The speed at which the block will be mined. If you set this value to0, the item will not be able to destroy the block.

要点：

• 速度值越大，破坏方块越快；
• 设置为0时，该工具将完全无法破坏对应的方块——这在数据模型中由@Numeric(min = 0)注解保证（BEItem.java），"不可破坏"是一个合法的显式声明，而非错误状态；
• 该值以整数形式写入destroy_speeds的speed字段，属于 Bedrock 组件语义中的破坏速度系数。

5.2 效率附魔开关（Tool use efficiency）

对应文档 tool_use_efficiency.md：

If true, the "Efficiency" enchantment will affect the destroy speeds of the diggeable blocks.

• 勾选后，"效率"附魔会作用于挖掘条目中声明的方块，即附魔等级越高，destroy_speeds中列出的方块破坏越快；
• 未勾选时，效率附魔对这些方块无效；
• 其布尔值在生成时被直接写入minecraft:digger组件的use_efficiency字段（item.json.ftl），与挖掘条目一同生效。

六、选块与选标签的辅助说明

挖掘条目中的"影响方块/标签"选择器对应帮助文档 digger_block.md：

This is the block or the tag that will be affected by the chosen speed. For all vanilla block tags, check this page

• 选择器中可填入独立方块或方块标签；
• 官方文档建议查阅 Minecraft Wiki 的"Bedrock 版方块标签（Block tag）"页面，以确认原版标签的准确名称（例如原版的minecraft:logs、minecraft:planks等木材类标签，便于让工具批量影响某一类方块）；
• 标签选择方式在代码中体现为MCItemHolder的 tag 支持（new MCItemHolder(mcreator, ElementUtil::loadBlocks, true)，第三个参数即允许标签），并在生成时通过q.any_tag语法输出（见第四节）。

七、实战配置示例

综合以上内容，一个典型配置流程如下：

1. 在 MCreator 中创建或打开一个基岩版物品元素，切到物品编辑器的工具属性区；
2. 点击"挖掘条目"列表的添加挖掘条目按钮（对应源码elementgui.beitem.add_digger_entry的"添加挖掘条目"文案）；
3. 在条目中选择一个方块或标签（如minecraft:stone或TAG:minecraft:logs）；
4. 设置对应的挖掘速度（如2、3或更快的值；设为0表示无法破坏）；
5. 重复上述步骤，为不同方块/标签添加多个条目，实现差异化挖掘；
6. 若希望效率附魔加成，勾选"效率附魔影响挖掘速度"开关（diggerUseEfficiency）；
7. 生成 Add-On，编译产物中会得到带minecraft:digger组件的物品 JSON。

例如，添加两个条目后生成的 JSON 片段形如：

"minecraft:digger": { "use_efficiency": true, "destroy_speeds": [ { "block": "minecraft:stone", "speed": 3 }, { "block": { "tags": "q.any_tag('minecraft:logs')" }, "speed": 4 } ] }

（上述输出形式依据 item.json.ftl 与 mcitems.ftl 的序列化逻辑推演。）

八、完整链路小结

把本文涉及的源码串联起来，挖掘条目的完整生命周期是：

九、常见问题与注意事项

1. 列表为空时会发生什么？按文档规则与模板逻辑（<#if data.diggerEntries?? && !data.diggerEntries.isEmpty()>），minecraft:digger组件不会被生成，工具对所有方块保持正常行为。
2. 速度可以设为 0 吗？可以，且语义明确：该工具无法破坏对应方块（见 digger_speed.md 与@Numeric(min = 0)约束）。
3. 同一个方块既在标签中又被单独列出怎么办？文档说明标签下的方块同样受白名单规则约束——只要方块（无论以何种形式）出现在列表中，就应用对应条目的速度；MCreator 允许为独立方块与标签分别建立条目，实际以生成的destroy_speeds数组为准。
4. 标签与独立方块的 JSON 写法不同：标签使用q.any_tag查询表达式，独立方块使用注册名字符串，二者不可混用写法（由 mcitems.ftl 自动区分处理）。
5. 效率附魔联动：只有勾选"Tool use efficiency"后，效率附魔才会提升白名单内方块的破坏速度。

通过本文的配置说明与源码级解析，你可以准确地在 MCreator 中为基岩版工具类物品设计"按方块/标签差异化"的挖掘能力，并理解其最终落到minecraft:digger组件上的完整实现原理。

• 低代码
• 代码生成
• 桌面应用
• 游戏开发