MCreator 标签显示条件(Label Display Condition)完全指南:让 GUI 与 Overlay 中的标签按需显示

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

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 注意事项

  1. 条件在客户端执行:由于标签渲染发生在客户端渲染循环中,选择器仅允许选择客户端侧可用的程序;不要在其中依赖服务器侧才会更新的数据,除非该数据通过同步机制在客户端可见。
  2. 条件不通过 ≠ 隐藏占位:从生成代码可见,条件不通过时 drawString 调用被整体跳过,不会绘制任何内容,也不会影响其他组件的布局与交互。
  3. 依赖并非默认填充:虽然选择器"提供"了 x/y/z/world/entity 五个依赖,但具体某个程序是否使用、如何使用这些依赖,取决于你编写的逻辑程序本身;未使用依赖不会影响运行。
  4. 不指定条件时: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 中实现精确的按需显示逻辑。

登录后查看全文
MCreator