MCreator 标签显示条件(Label Display Condition)完全指南:让 GUI 与 Overlay 中的标签按需显示
MCreator 标签显示条件(Label Display Condition)完全指南:让 GUI 与 Overlay 中的标签按需显示
导读
本文围绕 MCreator 内置帮助文档 label_display_condition.md(其他语言版本见 default、zh_CN)展开,系统讲解 MCreator GUI(图形界面)与 Overlay(游戏内覆盖层)编辑器中"标签显示条件"这一核心特性。读完本文,你将掌握:如何在标签编辑器中为标签绑定显示条件、条件可用的输入依赖有哪些、条件在代码生成阶段的底层实现原理,以及典型的实战应用场景。
一、功能定位:一句话概括标签显示条件
原文档(德文版)的核心表述为:
Wenn die Bedingung angegeben ist, kann diese Bezeichnung nur angezeigt werden, wenn die Bedingung übergeht.
中文版 label_display_condition.md 的对应表述是:
如果指定了条件,此标签只有在条件通过时显示。
这句话概括了该功能的全部语义:标签(Label)组件可以绑定一个逻辑条件(Condition),仅当该条件在运行时评估为真("通过")时,标签才会被渲染显示;条件不通过时,标签被完全跳过,不占用渲染、不产生可见输出。
在 MCreator 的组件体系中,标签是最常用的 GUI 元素之一,用于显示文本信息(如状态提示、数值、说明文字)。显示条件让标签从"静态文本"升级为"动态元素"——它可以在特定游戏状态下出现或消失,是实现 HUD 提示、状态指示等玩法的关键能力。
二、如何配置:在标签编辑器中绑定显示条件
2.1 入口:标签编辑器对话框
在 MCreator 工作区的 GUI 或 Overlay 编辑器中,新建或双击一个标签组件,会打开"标签编辑器"对话框。从源码 LabelDialog.java 可以看到,该对话框包含以下配置项:
| 配置项 | 本地化键 | 说明 |
|---|---|---|
| 文本 | dialog.gui.label_text |
标签显示的内容,可以是固定文本,也可以绑定字符串程序(String Procedure) |
| 标签显示条件 | dialog.gui.label_event_display_condition |
本文主题,绑定逻辑程序作为显示开关 |
| 文本颜色 | dialog.gui.label_text_color |
标签文字颜色(JColor 选择器) |
| 阴影 | dialog.gui.label_text_shadow |
是否为文字绘制阴影 |
| 锚点 | dialog.gui.anchor |
仅 Overlay 类型可用,设置组件锚点(AnchorPoint) |
其中"标签显示条件"字段的本地化文案在 texts.properties 中定义为 Label display condition,中文版本 texts_zh_CN.properties 为 标签显示条件。
2.2 条件选择器的关键参数
从源码实现看,"标签显示条件"并不是简单的复选框,而是一个完整的逻辑程序选择器(ProcedureSelector)。其构造关键参数如下(见 LabelDialog.java):
ProcedureSelector displayCondition = new ProcedureSelector(
IHelpContext.NONE.withEntry("gui/label_display_condition"), editor.mcreator,
L10N.t("dialog.gui.label_event_display_condition"), ProcedureSelector.Side.CLIENT, false,
VariableTypeLoader.BuiltInTypes.LOGIC,
Dependency.fromString("x:number/y:number/z:number/world:world/entity:entity"));
这些参数决定了该条件选择器的行为边界:
Side.CLIENT(客户端侧):条件程序只在游戏客户端执行。这与渲染机制一致——标签的绘制发生在客户端,因此可选的程序只能是从 ProcedureSelector.java 中标记为客户端侧的事件/程序,选择器上会显示客户端图标并提示"只在客户端触发"。- 返回类型
VariableTypeLoader.BuiltInTypes.LOGIC(逻辑型):条件必须返回布尔值(true/false)。选择器默认值为condition.common.true(即"真"),意味着不修改时条件恒为真、标签始终显示。 - 提供依赖
x:number / y:number / z:number / world:world / entity:entity:条件程序在被调用时可访问这五个上下文输入——标签所在坐标(x、y、z)、所在世界(world)以及关联实体(entity)。这意味着你可以在条件里直接判断"实体是否处于某个状态""玩家是否在某个坐标区域"等,而无需额外声明变量。
2.3 编辑与复用
条件选择器支持从已有逻辑程序中挑选,也支持直接新建。当你选择或新建一个逻辑程序后,该程序名会被保存进标签组件的数据结构中;在生成代码时,这个程序会被编译为一段内联的条件判断表达式。由于条件本质是一个独立的逻辑程序元素,它同样可以被按钮、图片、工具提示等其他组件复用(见下文"通用性"一节)。
三、底层原理:从数据结构到代码生成
3.1 数据模型:displayCondition 字段
标签组件的数据模型定义在 Label.java 中:
public class Label extends GUIComponent {
@Nonnull public String name;
public StringProcedure text; // 文本(固定值或字符串程序)
public Color color; // 文字颜色
public boolean hasShadow; // 是否带阴影
public Procedure displayCondition; // 显示条件(逻辑程序)
...
}
displayCondition 的类型是 Procedure(程序引用)。当该字段为 null 或未绑定程序时,说明用户没有指定条件;绑定后则保存了程序引用,供代码生成器读取。此外,Overlay 元素本身在 Overlay.java 中也有一个独立的 displayCondition 字段,用于控制整个覆盖层的显隐——这一点与"标签组件级"的条件是两级不同的开关。
3.2 生成阶段:FTL 模板如何"包裹"渲染调用
MCreator 采用 FreeMarker(FTL)模板把工作区数据编译为 Java 源码。不同 Minecraft 版本/加载器(Forge、NeoForge 等)的生成插件都有对应的模板,逻辑完全一致。以 NeoForge 1.21.1 生成器为例:
(1)普通 GUI 中的标签渲染 —— gui_window.java.ftl 的 renderLabels 方法:
<#list data.getComponentsOfType("Label") as component>
<#if hasProcedure(component.displayCondition)>
if (<@procedureOBJToConditionCode component.displayCondition/>)
</#if>
guiGraphics.drawString(this.font,
<#if hasProcedure(component.text)><@procedureOBJToStringCode component.text/><#else>Component.translatable("gui.${modid}.${registryname}.${component.getName()}")</#if>,
${component.gx(data.width)}, ${component.gy(data.height)}, ${component.color.getRGB()}, ${component.hasShadow});
</#list>
可见生成逻辑非常简单直观:模板首先用 hasProcedure 判断组件是否绑定了显示条件,若绑定了,则在 drawString 前插入一行 if (条件代码) { 前缀;若没有绑定条件,则直接无条件绘制。这正是文档所述"只有条件通过时才显示"的代码形态。
(2)Overlay 中的渲染 —— overlay.java.ftl 结构类似,且存在两层条件:
if (<@procedureOBJToConditionCode data.displayCondition/>) { <#-- 覆盖层整体开关 -->
<#-- 绘制背景图、图片、精灵等 -->
<#list data.getComponentsOfType("Label") as component>
<#if hasProcedure(component.displayCondition)>
if (<@procedureOBJToConditionCode component.displayCondition/>)
</#if>
event.getGuiGraphics().drawString(...);
</#list>
<#-- 实体模型等 -->
}
外层 if 控制整个 Overlay 是否渲染(对应 Overlay 元素自身的 displayCondition),内层 if 再逐个控制每个标签组件。两级条件串联,可实现"覆盖层关闭时其下所有组件都不渲染、覆盖层开启时再按组件条件逐一过滤"的精细控制。
(3)其他组件的通用模式 —— 显示条件并非标签独有。在 gui_window.java.ftl 中,Image、Sprite 组件同样使用 if (hasProcedure(component.displayCondition)) 包裹 blit 调用;按钮类组件则在 gui_window.java.ftl 中通过 this.${component.getName()}.visible = 条件代码; 动态控制可见性。这也解释了为什么 MCreator 的显示条件机制在整个 GUI 组件体系内是一套统一的设计。新版本生成器(如 gui_window.java.ftl(26.3.x))保持了完全相同的模式。
四、实战场景与使用建议
4.1 典型应用
- 状态提示:只有玩家持有某物品、处于某个维度、或某个计分板值达到阈值时,才在 HUD 上显示提示标签(结合依赖中的
entity、world)。 - 区域指示:利用
x / y / z依赖,判断玩家(或标签关联实体)是否处于某个坐标范围内,从而显示/隐藏地标标签。 - 阶段化教程:将标签与某个进度变量关联,只有变量为真时显示下一阶段的操作说明。
- Overlay 整体开关:在 Overlay 元素层面设置显示条件,配合优先级(
priority,见 Overlay.java),控制整套 HUD 在特定状态下的出现与消失。
4.2 注意事项
- 条件在客户端执行:由于标签渲染发生在客户端渲染循环中,选择器仅允许选择客户端侧可用的程序;不要在其中依赖服务器侧才会更新的数据,除非该数据通过同步机制在客户端可见。
- 条件不通过 ≠ 隐藏占位:从生成代码可见,条件不通过时
drawString调用被整体跳过,不会绘制任何内容,也不会影响其他组件的布局与交互。 - 依赖并非默认填充:虽然选择器"提供"了 x/y/z/world/entity 五个依赖,但具体某个程序是否使用、如何使用这些依赖,取决于你编写的逻辑程序本身;未使用依赖不会影响运行。
- 不指定条件时:
hasProcedure判断为假,渲染调用不加任何if包裹,标签恒常显示——这也符合文档"如果指定了条件"("Wenn die Bedingung angegeben ist")这一前提表述。
五、帮助文档体系:该文档在 MCreator 中的角色
label_display_condition.md 属于 MCreator 的本地化帮助文档插件 mcreator-localization。整套帮助文档按 gui、procedure、mod_element 等主题目录组织,并翻译为 30 种语言(plugins/mcreator-localization/lang/ 下每种语言一个 texts_*.properties 文件),帮助内容本身也按语言分目录存放于 plugins/mcreator-localization/help/。
这份文档的加载入口在 LabelDialog.java:通过 IHelpContext.NONE.withEntry("gui/label_display_condition") 将帮助按钮与文档条目关联。用户在"标签显示条件"选择器旁点击帮助图标时,MCreator 会按当前界面语言加载对应的帮助文档并弹出展示。因此,该文档不仅是面向用户的帮助文案,更是被代码显式引用的 UI 帮助上下文,其权威性与技术准确性直接服务于 GUI 编辑器的一线使用体验。
小结
标签显示条件让 MCreator 中的 GUI 标签从"静态装饰"变成"有感知的界面元素":数据层面由 Label.displayCondition 承载程序引用,编辑层面由客户端侧的逻辑程序选择器提供,生成层面则由 FTL 模板以 if 包裹渲染调用落地为真实代码。掌握这一机制,你就能在 Mod 的界面与 HUD 中实现精确的按需显示逻辑。