MCreator 进度(Advancement)"完成前隐藏"(Hide if not completed)参数详解:从界面勾选到 JSON 生成
MCreator 进度(Advancement)"完成前隐藏"(Hide if not completed)参数详解:从界面勾选到 JSON 生成
本文聚焦 MCreator 中"进度(Advancement,旧称成就 Achievement)"元素的 Hide if not completed yet 复选框,讲解它在游戏中的实际效果、界面配置位置、底层数据模型与代码生成原理,并厘清它与"隐藏显示"(Hide advancement display)等相近参数的区别。读完本文,你将能够准确控制自制 Mod 中进度的可见性策略,并理解所生成 JSON 文件中
hidden字段的来龙去脉。
参数是什么:一行说明背后的行为
MCreator 官方帮助文档对该参数的定义非常简洁:
This parameter hides the advancement in the advancement tab until it's completed. (该参数会在进度完成之前,将进度从进度选项卡中隐藏。)
也就是说,当该选项被勾选时,玩家在打开游戏内"进度"界面(Advancement 选项卡)时,看不到这个未完成的进度条目;只有在该进度的触发条件(criteria)全部满足、进度被判定为"已完成"之后,它才会出现在进度界面中。
这个行为对应 Minecraft 原生进度 JSON 中 display 对象里的 hidden 布尔字段:值为 true 时隐藏未完成的进度,值为 false(默认)时进度始终可见(只是未完成时以"待解锁"的暗色样式呈现)。
在 MCreator 界面中的配置位置
该参数位于"进度"元素的 GUI 编辑界面中。在 AchievementGUI.java 中,它被实现为一个复选框控件:
private final JCheckBox hideIfNotCompleted = L10N.checkbox("elementgui.common.enable");
其中 L10N.checkbox("elementgui.common.enable") 表示该复选框的文案取自本地化键 elementgui.common.enable,对应值为 "Check to enable"(texts.properties)。而复选框前面的标签文本来自键 elementgui.advancement.hide_if_not_completed,即 "Hide if not completed yet: "(texts.properties)。
在布局上,该复选框被放置在主界面右侧的 Logic(逻辑) 分区面板中(见 AchievementGUI.java):
logicPanel.add(HelpUtils.wrapWithHelpButton(this.withEntry("advancement/hide_if_not_completed"),
L10N.label("elementgui.advancement.hide_if_not_completed")));
logicPanel.add(hideIfNotCompleted);
wrapWithHelpButton 将该参数的说明按钮与帮助文档 hide_if_not_completed.md 关联起来——这正是你在界面中点击"?"帮助按钮时看到的那句说明的来源。
操作路径归纳:
- 在 MCreator 工作区新建或打开一个 Advancement / Achievement 元素;
- 在元素编辑界面的右侧 Logic 分区中找到 "Hide if not completed yet:" 复选框;
- 勾选后保存元素并生成/构建 Mod。
数据模型层:字段如何被保存
勾选状态会被保存到元素类型 Achievement 的布尔字段 hideIfNotCompleted 中。该字段定义在 Achievement.java:
public boolean hideIfNotCompleted;
结合同文件中相邻的字段(Achievement.java)可以看到,进度显示相关的几个开关是并列存在的:
public boolean disableDisplay; // 完全禁用进度显示("纯逻辑"进度)
public boolean showPopup; // 完成时右上角弹窗提示
public boolean announceToChat; // 完成时聊天栏公告
public boolean hideIfNotCompleted; // 完成前在进度界面中隐藏
界面的读写闭环在 AchievementGUI.java 与 AchievementGUI.java 中完成:
// 编辑模式:把已保存的字段值回填到界面
hideIfNotCompleted.setSelected(achievement.hideIfNotCompleted);
// 保存模式:把界面勾选状态写入字段
achievement.hideIfNotCompleted = hideIfNotCompleted.isSelected();
代码生成层:字段如何映射为 JSON 的 hidden 字段
MCreator 使用 FreeMarker 模板把元素数据渲染为 Minecraft 原生的进度 JSON 文件。负责生成进度的模板为 advancement.json.ftl(对应 1.21.1 数据包)与 advancement.json.ftl(对应 26.3.x 数据包),两个模板中均有同一行映射:
"hidden": ${data.hideIfNotCompleted}
即:勾选该参数 → hideIfNotCompleted = true → 生成的进度 JSON 中 "hidden": true。
以 1.21.1 数据包模板为参照(advancement.json.ftl),display 对象由以下参数组合而成:
"frame": "${data.achievementType}",
"show_toast": ${data.showPopup},
"announce_to_chat": ${data.announceToChat},
"hidden": ${data.hideIfNotCompleted}
可以推断,当用户勾选该参数后,生成的数据包中对应进度文件(位于 data/<modid>/advancement/<registryname>.json 路径下)的 display 部分大致呈现如下效果(示意,字段顺序以实际生成文件为准):
{
"display": {
"icon": { "id": "minecraft:diamond" },
"title": "示例进度",
"description": "完成某个目标",
"frame": "task",
"show_toast": true,
"announce_to_chat": true,
"hidden": true
},
"criteria": {
"trigger0": { "trigger": "minecraft:impossible" }
}
}
值得注意的细节是,模板中整段 display 对象包裹在 <#if !data.disableDisplay> 条件中(见 advancement.json.ftl):一旦"隐藏显示"(Hide advancement display)被勾选,整个 display 块都不会输出,hidden 字段自然也不会出现。这说明"完成前隐藏"与"完全隐藏显示"是两种不同粒度的隐藏策略。
与相近参数的区分:三种"隐藏/提示"开关的取舍
MCreator 帮助体系在 advancement 目录下为每个参数提供了独立说明。为避免混淆,这里把三个易混开关并列说明:
| 参数(GUI 标签) | 帮助文档 | 底层字段 | 生成 JSON 位置 | 效果 |
|---|---|---|---|---|
| Hide if not completed yet | hide_if_not_completed.md | hideIfNotCompleted |
display.hidden |
未完成时进度在进度界面中隐藏,完成后才显示 |
| Hide advancement display | hide_display.md | disableDisplay |
整个 display 块不输出 |
完全无显示,仅作纯逻辑触发(如作为函数执行的进度前置) |
| Show toast | show_toast.md | showPopup |
display.show_toast |
完成时屏幕右上方弹出进度提示 |
其中"完全隐藏显示"的定位正如 texts.properties 中的说明所示:
Used for "logic only" advancements such as function triggers (用于"纯逻辑"进度,例如函数触发器)
也就是说:
- 若只是想让玩家完成后才能看到这个进度,勾选 Hide if not completed yet;
- 若想让进度完全不显示(只在后台作为触发条件/奖励逻辑存在),勾选 Hide advancement display;
- 若想让玩家完成时有反馈,配合勾选 Show toast(弹窗)与 Announce to chat(聊天公告)。
测试覆盖:字段参与自动生成的回归验证
该字段同样参与了 MCreator 的自动化集成测试。在 TestWorkspaceDataProvider.java 中,测试数据提供器会构造一个带有随机取值进度的样例工作区,其中明确包含对 hideIfNotCompleted 的赋值:
achievement.announceToChat = _true;
achievement.showPopup = _true;
achievement.disableDisplay = !_true;
achievement.rewardXP = getRandomInt(random, Achievement.class, "rewardXP");
achievement.hideIfNotCompleted = !_true;
同时 GTJSONTriggersBlocks.java 等生成器测试会通过 getAdvancementExample(...) 取得该样例进度,驱动代码生成流程,从而验证包含 hidden 字段在内的进度 JSON 能否正确生成。这从工程层面保证了该参数"勾选 → 字段 → 模板输出"整条链路在各生成器版本下的稳定性。
典型使用场景建议
结合上述机制,该参数在以下场景中尤为实用:
- 隐藏剧透型进度:进度名称或描述本身揭示了后续玩法内容(如 BOSS 名称、隐藏区域),在玩家达成前先隐藏,避免提前泄露;
- 树状进度中的阶段性隐藏:将"完成前隐藏"用于进度树的分支节点,让玩家在主线推进到该节点前不会看到杂项分支;
- 配合纯逻辑进度:若某个进度仅作为自定义函数(Function)的前置触发条件,可将显示层面的参数与 reward_function 组合使用,并按需决定隐藏粒度。
小结
"Hide if not completed yet" 参数虽在帮助文档中仅有一句说明,但其完整链路贯穿 MCreator 的界面层(AchievementGUI.java)、数据层(Achievement.java)与生成层(advancement.json.ftl)。勾选后生成的 "hidden": true 会让进度在玩家完成前从进度界面消失,而这一行为完全符合 Minecraft 原版进度机制,不需要任何额外模组代码。在需要设计"完成前保密"或"阶段性揭示"进度树时,优先考虑这个开关,同时注意与 "Hide advancement display"(彻底无显示)在语义上的区别。