MCreator 成就系统 "Hide advancement display" 参数深度解析:隐藏显示与纯逻辑成就的实现机制

原创2026-10-14 22:44:021,445 阅读
文章标签:桌面应用游戏开发代码生成低代码开发工具模板引擎

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" 的典型用法包括:

  1. 纯逻辑成就(Logic-only advancement):仅作为触发器/函数链路的中间节点存在,用于标记流程状态,玩家无需看到它。例如 texts.properties 中提到的 "function triggers"——由 function 触发的成就。
  2. 成就奖励分发:在不暴露进度 UI 的前提下,通过完成成就发放经验、战利品表或合成配方(rewards 部分不受 display 影响)。
  3. 配合 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 中自如设计"看得见"的成就树与"看不见"的逻辑节点,让进度系统既美观又可控。

登录后查看全文
MCreator