MCreator 进度(Advancement)"完成前隐藏"(Hide if not completed)参数详解:从界面勾选到 JSON 生成

原创2026-10-16 13:34:141,839 阅读
文章标签:桌面应用游戏开发代码生成低代码开发工具模板引擎

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 关联起来——这正是你在界面中点击"?"帮助按钮时看到的那句说明的来源。

操作路径归纳:

  1. 在 MCreator 工作区新建或打开一个 Advancement / Achievement 元素;
  2. 在元素编辑界面的右侧 Logic 分区中找到 "Hide if not completed yet:" 复选框;
  3. 勾选后保存元素并生成/构建 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 能否正确生成。这从工程层面保证了该参数"勾选 → 字段 → 模板输出"整条链路在各生成器版本下的稳定性。

典型使用场景建议

结合上述机制,该参数在以下场景中尤为实用:

  1. 隐藏剧透型进度:进度名称或描述本身揭示了后续玩法内容(如 BOSS 名称、隐藏区域),在玩家达成前先隐藏,避免提前泄露;
  2. 树状进度中的阶段性隐藏:将"完成前隐藏"用于进度树的分支节点,让玩家在主线推进到该节点前不会看到杂项分支;
  3. 配合纯逻辑进度:若某个进度仅作为自定义函数(Function)的前置触发条件,可将显示层面的参数与 reward_function 组合使用,并按需决定隐藏粒度。

小结

"Hide if not completed yet" 参数虽在帮助文档中仅有一句说明,但其完整链路贯穿 MCreator 的界面层(AchievementGUI.java)、数据层(Achievement.java)与生成层(advancement.json.ftl)。勾选后生成的 "hidden": true 会让进度在玩家完成前从进度界面消失,而这一行为完全符合 Minecraft 原版进度机制,不需要任何额外模组代码。在需要设计"完成前保密"或"阶段性揭示"进度树时,优先考虑这个开关,同时注意与 "Hide advancement display"(彻底无显示)在语义上的区别。

登录后查看全文
MCreator