MCreator 成就系统 "Hide advancement display" 参数深度解析:隐藏显示与纯逻辑成就的实现机制
MCreator 成就系统 "Hide advancement display" 参数深度解析:隐藏显示与纯逻辑成就的实现机制
导读
在 MCreator 中创建 Minecraft 成就(Advancement,仓库内亦称 Achievement)时,"Hide advancement display"(隐藏成就显示)是一个经常被忽略却至关重要的开关:它决定了成就是否在进度界面(Advancement Tab)中持续可见。本文以该帮助文档为核心,结合 AchievementGUI.java、Achievement.java 与代码生成模板 advancement.json.ftl,完整讲解该参数的作用、它与 "Hide if not completed yet" 的区别、底层数据模型以及最终生成的 JSON 结构,并给出"纯逻辑成就"的典型落地场景。
一、参数是什么:文档原文与界面定位
原文档(捷克语帮助文件 hide_display.md)对该参数的说明为:
勾选此复选框,可以在该成就完成之前,将其在(进度)分类中隐藏起来。
对应的英文原版(default 帮助文档)表述为:
Check this parameter to hide the advancement in the advancement tab until it's completed.
在 MCreator 的成就编辑器中,该选项位于 Logic(逻辑) 分组,而非展示参数(Display parameters)分组。相关界面定义可以在 AchievementGUI.java 中看到:logicPanel 中依次加入了 advancement/hide_if_not_completed 与 advancement/hide_display 两个帮助按钮对应的行,其中 advancement/hide_display 帮助按钮绑定的是 disableDisplay 复选框:
logicPanel.add(HelpUtils.wrapWithHelpButton(this.withEntry("advancement/hide_if_not_completed"),
L10N.label("elementgui.advancement.hide_if_not_completed")));
logicPanel.add(hideIfNotCompleted);
logicPanel.add(HelpUtils.wrapWithHelpButton(this.withEntry("advancement/hide_display"),
L10N.label("elementgui.advancement.hide_display")));
logicPanel.add(disableDisplay);
界面文案本身也对用途做了补充说明,见 texts.properties:
elementgui.advancement.hide_if_not_completed=Hide if not completed yet:
elementgui.advancement.hide_display=<html>Hide advancement display:<br><small>Used for "logic only" advancements such as function triggers
即:该开关主要服务于"仅逻辑"(logic only)的成就——例如由 function 触发器驱动、不需要向玩家展示任何界面的隐藏成就。
二、容易混淆的兄弟参数:hide_display 与 hide_if_not_completed
MCreator 成就编辑器中有两个名字相近的开关,本文主角 hide_display 与之容易混淆,必须先厘清:
| 界面参数 | 帮助文档条目 | 对应数据字段 | 生成 JSON 中的作用 |
|---|---|---|---|
| Hide if not completed yet | advancement/hide_if_not_completed |
hideIfNotCompleted |
输出 "hidden": true/false,完成前不在进度标签页显示 |
| Hide advancement display | advancement/hide_display |
disableDisplay |
为 true 时整个 display 块都不输出 |
两者的关系可以这样理解:
hide_if_not_completed(hidden 字段):成就仍然拥有完整的展示数据(图标、标题、描述、帧类型等),只是在该成就被解锁前,玩家在进度界面中看不到它的节点;完成后它就会出现在树状图中。hide_display(disableDisplay):直接丢弃整个display块,成就完全没有图标、标题、描述等展示信息,只能通过触发器(trigger)逻辑存在,成为纯功能性成就。
在生成模板 advancement.json.ftl 中,两者分别体现在不同位置:
<#if !data.disableDisplay>
"display": {
...
"hidden": ${data.hideIfNotCompleted}
},
</#if>
即:外层 disableDisplay 决定整个 display 对象是否生成;内层 hidden 决定显示是否延迟到完成时。
三、数据模型层面:字段如何存储
成就元素的数据模型定义在 Achievement.java:
public boolean disableDisplay;
public boolean showPopup;
public boolean announceToChat;
public boolean hideIfNotCompleted;
disableDisplay、hideIfNotCompleted 等都是简单的布尔字段,它们随成就的 .mod 元素定义持久化保存,并在生成代码时通过 FreeMarker 数据模型(data.*)注入模板。GUI 加载与保存逻辑同样在 AchievementGUI.java 中,保存时读取复选框状态写入 achievement.disableDisplay / achievement.hideIfNotCompleted 字段。
四、代码生成层面:最终 JSON 长什么样
以数据包生成器为例,advancement.json.ftl 是成就 JSON 的核心模板。当勾选 "Hide advancement display"(即 disableDisplay == true)时,生成的成就 JSON 形如:
{
"criteria": {
"advancement_trigger": {
"trigger": "minecraft:impossible"
}
}
}
整个 display 块被跳过,不再包含 icon、title、description、frame、show_toast、announce_to_chat、hidden、background 等任何展示字段。这是 Minecraft 原版数据格式允许的状态,适合需要成就奖励但不想暴露进度的场景。
对比未勾选时的完整 JSON(示意):
{
"display": {
"background": "minecraft:textures/block/stone.png",
"icon": { "id": "minecraft:diamond" },
"title": { "translate": "advancements.example.title" },
"description": { "translate": "advancements.example.descr" },
"frame": "task",
"show_toast": true,
"announce_to_chat": true,
"hidden": false
},
"criteria": {
...
}
}
关于 disableDisplay 生效条件,模板源码还揭示了一个细节:parent 为 "none" 且未指定背景时,模板会写入默认背景 minecraft:textures/block/stone.png;而一旦 disableDisplay 为真,这一切都被整体跳过。成就的奖励部分(experience、function、loot、recipes)位于 display 块之外,因此即使隐藏显示,奖励依然可以正常发放——这正是"纯逻辑成就"可落地的基础。
此外,criteria 部分由 Blockly 触发器生成:当成就没有任何触发器代码时,Achievement.java 会回退为 "minecraft:impossible" 触发器,使成就永远不会通过正常游戏行为完成,只能由命令 /advancement grant 等外部手段授予。
五、典型应用场景与实战建议
结合界面文案与模板行为,"Hide advancement display" 的典型用法包括:
- 纯逻辑成就(Logic-only advancement):仅作为触发器/函数链路的中间节点存在,用于标记流程状态,玩家无需看到它。例如 texts.properties 中提到的 "function triggers"——由
function触发的成就。 - 成就奖励分发:在不暴露进度 UI 的前提下,通过完成成就发放经验、战利品表或合成配方(
rewards部分不受display影响)。 - 配合
hide_if_not_completed做渐进式展示:如果希望成就最终出现在进度树中但完成前保密,应使用 "Hide if not completed yet"(生成"hidden": true),而非完全隐藏显示。
需要特别说明的是,本文所述行为以当前仓库为基准:相关代码生成模板位于 plugins/generator-1.21.1/datapack-1.21.1/templates/advancement.json.ftl,而模组(NeoForge)生成器 plugins/generator-1.21.1/neoforge-1.21.1 与数据包生成器共用同一套成就数据模型与生成逻辑。实际使用时,建议先在 MCreator 中新建成就并勾选/取消该复选框,导出后对比生成的 advancements/*.json,即可直观验证上述机制。
六、总结
- "Hide advancement display" 对应数据字段
disableDisplay,勾选后成就 JSON 中不再生成display块,成就成为纯逻辑节点; - 它区别于 "Hide if not completed yet"(
hideIfNotCompleted→"hidden": true),后者仍保留完整展示数据,仅延迟可见性; - 无论是否隐藏显示,成就的
criteria与rewards均正常生成,因此可以用于奖励分发与流程标记; - 底层实现链路清晰:GUI 复选框(AchievementGUI.java)→ 数据模型字段(Achievement.java)→ FreeMarker 模板输出(advancement.json.ftl)。
掌握这一参数,你就能在 MCreator 中自如设计"看得见"的成就树与"看不见"的逻辑节点,让进度系统既美观又可控。