企业官网建设流程全解析

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

本文围绕 MCreator 中"进度"（Advancement / Achievement）编辑器的Hide if not completed yet（未完成时隐藏）参数展开，讲解该参数在进度界面（Advancement Tab）中的实际效果、对应的数据模型字段，以及它如何被写入生成代码中的hiddenJSON 字段。读完本文，你将掌握该参数的完整使用方式、它在 NeoForge 与数据包两种生成管线中的落点，以及如何从源码层面验证和排查其生成结果。

一、参数作用：完成前从进度界面中隐藏

该参数是 MCreator 进度编辑器"逻辑（Logic）"分区中的一个复选框。官方帮助文档（英文默认版）对其描述为：

This parameter hides the advancement in the advancement tab until it's completed.

即：勾选该参数后，进度在其达成条件完成之前，不会显示在玩家的进度界面（Advancement Tab）中；只有当玩家真正完成该进度后，它才会出现在界面里。这对于设计"隐藏成就""秘密进度"或"惊喜奖励"类内容非常有用——玩家无法预先看到未解锁的进度条目，避免了剧透。

该帮助文档在所有语言下均保持同一语义，例如简体中文版写作"此参数将在进度完成前隐藏该进度于界面中"，捷克语版（即本文对应文档）写作"Tento parametr schová pokrok v kategorii než bude dokončen"。原始帮助文档见 hide_if_not_completed.md（default） 与 hide_if_not_completed.md（cs_CZ）。

提示：该参数与同分区中的另一个参数"隐藏显示（Hide display）"不同。前者只影响未完成时的可见性，完成后会正常显示；后者（对应disableDisplay）会直接禁止生成display字段，使进度在界面中始终不显示任何图标与标题。

二、界面中的位置与操作方式

在 MCreator 工作区中新建或打开一个进度类型的元素后，编辑器界面底部为"逻辑（Logic）"面板。其中包含了若干复选框，按源码顺序依次是：

• Hide if not completed yet（未完成时隐藏）——即本文主角；
• Hide display（隐藏显示）；
• Show popup（显示弹窗）、Announce to chat（聊天公告）等显示行为选项。

从 AchievementGUI.java 可以看到，这些复选框均通过L10N.checkbox("elementgui.common.enable")创建，其中隐藏参数还使用HelpUtils.wrapWithHelpButton挂接了帮助按钮，并将this.withEntry("advancement/hide_if_not_completed")作为帮助入口，指向的就是本文开头的帮助文档：

private final JCheckBox hideIfNotCompleted = L10N.checkbox("elementgui.common.enable"); // ... logicPanel.add(HelpUtils.wrapWithHelpButton(this.withEntry("advancement/hide_if_not_completed"), L10N.label("elementgui.advancement.hide_if_not_completed")));

界面标签文案由本地化键elementgui.advancement.hide_if_not_completed提供，定义于 texts.properties：

elementgui.advancement.hide_if_not_completed=Hide if not completed yet:

操作流程如下：

1. 打开进度编辑器，在"逻辑"面板中找到"Hide if not completed yet"复选框；
2. 若希望该进度在完成前对玩家隐藏，则勾选该项；
3. 其余显示行为（弹窗、聊天公告、背景、父进度等）按需配置后保存；
4. 生成代码/数据包，即可在游戏内验证效果。

三、数据模型：Achievement.hideIfNotCompleted 字段

该复选框的状态最终被持久化为进度元素数据模型上的一个布尔字段。在 Achievement.java 中定义如下：

public boolean disableDisplay; public boolean showPopup; public boolean announceToChat; public boolean hideIfNotCompleted;

Achievement继承自GeneratableElement，是进度元素的核心类型，同时承载名称、描述、图标、背景、类型（task/goal/challenge）、父进度、触发条件（triggerxml，由 Blockly 的 JSON 触发器生成）以及各类奖励（经验、战利品表、配方、函数）。

在编辑器与模型之间的双向同步由 AchievementGUI.java 完成：

• 打开元素编辑时（openInEditingMode）：hideIfNotCompleted.setSelected(achievement.hideIfNotCompleted);将已保存的值回填到复选框；
• 从界面收集数据时（getElementFromGUI）：achievement.hideIfNotCompleted = hideIfNotCompleted.isSelected();将复选框状态写回模型。

因此，无论界面如何调整，最终都以hideIfNotCompleted字段的布尔值参与后续模板生成。

四、代码生成：从字段到 advancement JSON 的 hidden 属性

MCreator 的进度既面向 NeoForge 模组（加载数据包生成器模板），也面向纯数据包输出。两者共用同一个 FTL 模板文件，定义文件 achievement.definition.yaml（neoforge-1.21.1） 中注释标明"loaded from datapack generator"，即模板从数据包生成器复用：

templates: - template: advancement.json.ftl # loaded from datapack generator writer: json name: "@MODDATAROOT/advancement/@registryname.json"

模板 advancement.json.ftl（1.21.1） 在display对象中输出hidden字段：

"frame": "${data.achievementType}", "show_toast": ${data.showPopup}, "announce_to_chat": ${data.announceToChat}, "hidden": ${data.hideIfNotCompleted}

同一逻辑在较新的 advancement.json.ftl（26.3.x） 中保持不变。当勾选该参数时，data.hideIfNotCompleted为true，生成的 JSON 中即为"hidden": true。

在 Minecraft 原版进度系统中，hidden字段的作用与本文档描述完全一致：该进度在完成之前不会出现在进度界面中，其所有子进度同样不可见；一旦达成条件完成，该进度及后续条目才会显现。需要注意的是，hidden仅影响进度界面的可见性，不影响进度本身的触发、奖励发放以及announce_to_chat等行为，因此可以放心与弹窗、公告选项组合使用。

生成的 JSON 整体结构示例如下（示意，实际由模板按元素数据填充）：

{ "display": { "icon": { "id": "minecraft:diamond" }, "title": { "translate": "advancements.example.title" }, "description": { "translate": "advancements.example.descr" }, "frame": "task", "show_toast": true, "announce_to_chat": true, "hidden": true }, "criteria": { "example": { "trigger": "minecraft:impossible" } } }

其中criteria部分由 Achievement.java 中的getAdditionalTemplateData()调用BlocklyToJSONTrigger把 Blockly 触发器转换为 JSON 触发器代码注入模板；若触发条件为空，则回退为"minecraft:impossible"。

五、测试与验证：字段在集成测试中的覆盖

仓库的集成测试数据提供器在构造示例进度元素时，也会为hideIfNotCompleted赋值，见 TestWorkspaceDataProvider.java：

public static Achievement getAdvancementExample(...) { ... achievement.hideIfNotCompleted = !_true; ... }

这保证了该字段会被纳入生成器集成测试的覆盖范围，从而验证"隐藏"参数能在模板中正确渲染、生成的 JSON 合法可解析。你可以通过运行对应的生成器集成测试（例如GTJSONTriggersBlocks相关用例，见 GTJSONTriggersBlocks.java）来复核这一行为。

六、排查与常见问题

• 勾选后进度仍然可见：检查display对象是否被disableDisplay（隐藏显示）之外的配置意外跳过；若勾选了"隐藏显示"，则整个display不生成，进度既无图标也不会以常规方式显示，与本文参数的语义不同。
• 生成 JSON 中hidden字段缺失：确认模板 advancement.json.ftl 未被第三方生成器插件覆盖，并检查进度元素是否保存成功（字段是否已写入工作区元素文件）。
• 想隐藏某个子进度但保留父进度：直接对该子进度勾选"未完成时隐藏"即可；父进度的显示不受影响，只是界面中父进度与隐藏子进度之间会出现"断层"式的可见性差异，这属于原版进度的预期行为。
• 想在完成后仍然隐藏：这不是本参数的能力范围，需要改为使用"隐藏显示"（disableDisplay）或将进度设计为不生成display。

七、小结

"Hide if not completed yet（未完成时隐藏）"是 MCreator 进度元素上一个简单但实用的显示控制开关：它在数据层对应Achievement.hideIfNotCompleted布尔字段，在生成层映射为 Minecraft advancement JSON 的hidden属性，最终实现"完成前对玩家隐藏进度条目"的效果。配合弹窗、聊天公告、父进度与奖励体系，可以轻松设计出充满惊喜感的隐藏成就链。整个链路——从界面复选框、帮助文档、数据模型、FTL 模板到集成测试——在仓库中均可直接查阅，便于开发者二次定制或排查生成问题。

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