MCreator 精灵组件显示条件(Sprite Display Condition)完全指南:配置、原理与代码生成机制
MCreator 精灵组件显示条件(Sprite Display Condition)完全指南:配置、原理与代码生成机制
本指南以 plugins/mcreator-localization/help/de_DE/gui/sprite_display_condition.md(及其同源的多语言版本)为核心,系统讲解 MCreator 中精灵(Sprite)组件的"显示条件"(Display Condition)功能:它是什么、在哪些编辑器中出现、如何配置、底层数据模型如何存储,以及最终如何被代码生成模板翻译为可运行的 Minecraft 模组代码。读完本文,你将掌握在 GUI 与 Overlay 中按任意逻辑条件动态控制精灵显示/隐藏的完整实战方案,并理解其从界面操作到生成代码的完整链路。
一、功能概述:什么是"精灵显示条件"
1.1 文档原文的语义
MCreator 各语言版本帮助文档中对"精灵显示条件"的描述高度一致:
- 德文(关联文档原文):"Wenn die Bedingung angegeben ist, kann dieser Sprite nur dann angezeigt werden, wenn er übergeht."(如果指定了条件,该精灵只有在条件通过时才能被显示。)
- 英文(default 版):"If the condition is specified, this sprite can only be displayed in case it passes."
- 中文(zh_CN 版):"如果指定了条件,精灵图只能在它通过的情况下显示。"
综合原文语义,该功能的核心含义是:显示条件是一段可选的过程(Procedure),它返回一个布尔值(真/假)。当条件为真("通过")时,精灵才被渲染到画面上;条件为假时,精灵不显示;条件留空(未指定)时,精灵始终显示。
"Passes / 通过"这一措辞点明了该字段的布尔性质——它不是数值、字符串或位置,而是一个逻辑判断,直接决定精灵的"可见性(visibility)"。
1.2 显示条件在整个 GUI 组件体系中的位置
"显示条件"并不是精灵组件的专属特性,而是 MCreator 图形界面组件体系的通用能力。从 WYSIWYGEditor.java 中的组件注册表可见,GUI/Overlay 编辑器支持多达 12 类组件,其中多数组件的对话框都带有显示条件字段:
| 组件 | 对话框类 | 显示条件字段 |
|---|---|---|
| 精灵(Sprite) | SpriteDialog.java | displayCondition |
| 图片(Image) | ImageDialog | displayCondition |
| 标签(Label) | LabelDialog | displayCondition |
| 按钮(Button) | ButtonDialog | displayCondition |
| 图片按钮(ImageButton) | ImageButtonDialog | displayCondition |
| 滑块(Slider) | SliderDialog | displayCondition |
| 实体模型(EntityModel) | EntityModelDialog | displayCondition |
| 提示框(Tooltip) | TooltipDialog | displayCondition |
语言文件中同样为各组件分别注册了各自的显示条件文案,例如 texts.properties 中的 dialog.gui.button_display_condition、dialog.gui.image_display_condition、dialog.gui.sprite_display_condition、dialog.gui.slider_display_condition、dialog.gui.model_display_condition、dialog.gui.tooltip_display_condition 等。这说明显示条件是一个被广泛复用的设计模式,而本文聚焦的精灵组件是其中行为最具代表性的一类——因为精灵常用于多状态动画、生命值条、技能图标等需要频繁切换显示内容的场景。
二、配置实操:在 Sprite 对话框中设置显示条件
2.1 对话框中的字段布局
在 SpriteDialog.java 中,精灵编辑对话框包含以下核心字段:
- 纹理选择(Texture):通过
TextureComboBox从工作区选择一张TextureType.SCREEN类型的纹理图片(即屏幕/GUI 纹理)。 - 精灵数量(Sprite count):
JSpinner,范围从 1 到Integer.MAX_VALUE,但实际会被所选纹理的像素尺寸所约束(见下)。 - 精灵索引(Sprite index):一个
NumberProcedureSelector,可以填固定数字,也可以挂一个返回数字的过程。 - 显示条件(Sprite display condition):一个
ProcedureSelector,即本文主角。
对话框的显示条件字段通过 IHelpContext.NONE.withEntry("gui/sprite_display_condition") 关联到帮助文档条目——这正是本文关联文档在界面中的"入口":当用户在精灵对话框的显示条件字段旁点击帮助按钮时,MCreator 会打开该帮助页。
2.2 关键配置要点与约束
(1)显示条件的类型必须是"逻辑"过程
在 SpriteDialog.java 中,显示条件选择器的定义如下:
ProcedureSelector displayCondition = new ProcedureSelector(
IHelpContext.NONE.withEntry("gui/sprite_display_condition"), editor.mcreator,
L10N.t("dialog.gui.sprite_display_condition"), ProcedureSelector.Side.CLIENT, false,
VariableTypeLoader.BuiltInTypes.LOGIC,
Dependency.fromString("x:number/y:number/z:number/world:world/entity:entity"));
其中两个参数至关重要:
VariableTypeLoader.BuiltInTypes.LOGIC:限定只能选择**返回布尔值(逻辑类型)**的过程。这从编辑器层面保证了"条件通过/不通过"的语义一致性。ProcedureSelector.Side.CLIENT:限定为客户端过程。因为精灵渲染发生在客户端屏幕绘制阶段,服务端过程无法参与 GUI 绘制判断。Dependency.fromString(...):声明了该条件过程可用的依赖变量——x、y、z(坐标)、world(世界)、entity(实体)。这意味着你在编写显示条件时,可以直接引用"玩家位置""实体状态""世界时间"等上下文信息,从而实现如"玩家靠近时显示""只在夜晚显示"等动态效果。
(2)精灵数量与纹理尺寸的联动约束
SpriteDialog 中有一处容易被忽略的联动逻辑:当所选纹理被确定后,spritesCountModel 的最大值会被限制为纹理长宽中的较大值(Math.max(iconWidth, iconHeight))。这是因为精灵图集(sprite sheet)通常把多个子精灵按水平或垂直方向排列在同一张纹理中,子精灵的数量不可能超过纹理在该方向上的像素数。精灵索引(sprite index)则被限制在 0 ~ spritesCount-1 之间,超出范围会被裁剪,见 Sprite.java。
2.3 帮助文档的界面入口与多语言机制
MCreator 的帮助文档位于 plugins/mcreator-localization/help 目录,按 default(英文默认)+ 各语言代码(de_DE、zh_CN、fr_FR、ru_RU、pl_PL、hu_HU、pt_BR、en_GB 等)分目录组织。gui/sprite_display_condition.md 在全部 9 个语言版本中都有对应文件,说明该帮助条目是本地化基础设施的常规组成部分。关联文档所在的 de_DE 版 与 default 版 语义完全一致。
三、底层数据模型:displayCondition 如何存储
3.1 精灵组件的数据结构
精灵组件的数据模型定义在 Sprite.java:
public class Sprite extends GUIComponent {
@Nonnull @TextureReference(TextureType.SCREEN) public String sprite; // 精灵纹理文件名
public int spritesCount; // 图集中的精灵数量
public Procedure displayCondition; // 显示条件(可为 null)
public NumberProcedure spriteIndex; // 精灵索引(固定值或过程)
public Sprite(int x, int y, @Nonnull String sprite, int spritesCount, Procedure displayCondition,
NumberProcedure spriteIndex) { ... }
}
关键点:
displayCondition的类型是Procedure,它本质上是一个按名称引用工作区中过程 Mod 元素的引用对象,而非内联的布尔常量。当该字段为null或引用的过程在工作区中不存在时,表示"无显示条件",精灵无条件显示。@TextureReference(TextureType.SCREEN)注解会将精灵纹理注册为工作区资源引用,保证纹理被改名/删除时系统能正确追踪。
3.2 Procedure 引用的序列化与解析
Procedure.java 中的 GSON 适配器揭示了存储格式:过程引用在保存时被序列化为一个字符串(过程名),加载时还原为 Procedure 对象。判断"是否有有效过程"的关键方法是 Procedure.hasProcedure:
public static boolean hasProcedure(@Nullable Procedure procedure, Workspace workspace) {
return procedure != null && procedure.name != null && !procedure.name.isEmpty()
&& !"null".equals(procedure.name) && workspace.containsModElement(procedure.name);
}
该方法的语义恰好与文档"如果指定了条件"(If the condition is specified)相呼应:只有当引用非空、名称合法且指向的工作区 Mod 元素真实存在时,代码生成阶段才会认为"指定了条件"。
3.3 其他支持显示条件的组件类型(佐证通用性)
除精灵外,以下组件的数据类同样拥有 displayCondition 字段,印证了该设计是 GUI 组件体系的通用约定:
此外,Overlay(覆盖层)本身在 Overlay.java 中也有一个 displayCondition 字段——用于控制整个覆盖层是否绘制,相当于"覆盖层的全局显示条件"。与之相对,每个组件自己的 displayCondition 是组件级(局部)条件,二者可以叠加:覆盖层先整体判断一次,通过后再逐个判断组件条件。
四、代码生成原理:条件如何变成 Minecraft 模组代码
4.1 精灵在 GUI 中的渲染与条件包裹
GUI 窗口的生成模板是 plugins/generator-1.21.1/neoforge-1.21.1/templates/gui/gui_window.java.ftl(26.3.x 的对应模板在 plugins/generator-26.3.x/neoforge-26.3/templates/gui/gui_window.java.ftl)。精灵的绘制代码生成逻辑位于 renderBg 方法中(1.21.1 模板第 201-213 行):
<#list data.getComponentsOfType("Sprite") as component>
<#if hasProcedure(component.displayCondition)>if (<@procedureOBJToConditionCode component.displayCondition/>) {</#if>
guiGraphics.blit(SPRITE_${component?index},
this.leftPos + ${component.gx(data.width)}, this.topPos + ${component.gy(data.height)},
<#if (component.getTextureWidth(w.getWorkspace()) > component.getTextureHeight(w.getWorkspace()))>
<@getSpriteByIndex component "width"/>, 0
<#else>
0, <@getSpriteByIndex component "height"/>
</#if>,
${component.getWidth(w.getWorkspace())}, ${component.getHeight(w.getWorkspace())},
${component.getTextureWidth(w.getWorkspace())}, ${component.getTextureHeight(w.getWorkspace())});
<#if hasProcedure(component.displayCondition)>}</#if>
</#list>
这里可以清晰地看到两条生成规则:
- 条件包裹渲染调用:
<#if hasProcedure(component.displayCondition)>判断是否配置了条件;若配置了,则用if (<@procedureOBJToConditionCode component.displayCondition/>) { ... }把blit(纹理绘制)调用包起来。procedureOBJToConditionCode宏会把显示条件过程翻译成一段返回布尔值的 Java 条件表达式。 - 精灵图集裁剪:根据纹理宽高关系判断是横向图集还是纵向图集,用
getSpriteByIndex宏计算要裁剪的子精灵在源纹理中的偏移坐标,见模板第 397-419 行的getSpriteByIndex宏。精灵索引可以是固定值,也可以是过程(<@procedureOBJToNumberCode component.spriteIndex/>),且结果会被Mth.clamp钳制在合法范围内。
同理,Image 组件(第 192-199 行)和 EntityModel(第 145-153 行)的绘制也采用完全相同的"条件包裹"模式;而 Button / ImageButton 组件除了在渲染时判断,还会在 containerTick()(第 362-379 行)中每帧用 this.${component.getName()}.visible = <@procedureOBJToConditionCode component.displayCondition/>; 同步按钮的可见性,并在点击回调 buttonOnClick 宏(第 384-395 行)里再次校验条件后才向服务器发送点击消息——这保证了"不可见按钮不可点击"。
4.2 精灵在 Overlay 中的渲染与条件包裹
Overlay(游戏内覆盖层,如 HUD)的生成模板是 plugins/generator-1.21.1/neoforge-1.21.1/templates/overlay.java.ftl。其渲染入口是一个客户端事件处理器(@EventBusSubscriber(Dist.CLIENT) + @SubscribeEvent),按 overlayTarget 决定挂载到 RenderGuiEvent.Pre(游戏内 HUD)还是 ScreenEvent.Render.Post(指定界面之上),见第 51-61 行。
该模板中"显示条件"的运用分为两层:
(1)覆盖层级条件(第 86 行)——整个覆盖层渲染体被包裹:
if (<@procedureOBJToConditionCode data.displayCondition/>) {
<#if data.baseTexture?has_content>
event.getGuiGraphics().blit(BACKGROUND, 0, 0, 0, 0, w, h, w, h);
</#if>
<#list data.getComponentsOfType("Image") as component>
<#if hasProcedure(component.displayCondition)>
if (<@procedureOBJToConditionCode component.displayCondition/>) {
</#if>
...
</#list>
...
}
(2)组件级条件(第 102-111 行)——每个精灵组件在覆盖层内部被二次包裹:
<#list data.getComponentsOfType("Sprite") as component>
<#if hasProcedure(component.displayCondition)>if (<@procedureOBJToConditionCode component.displayCondition/>) {</#if>
event.getGuiGraphics().blit(SPRITE_${component?index}, <@calculatePosition component/>,
<#if (component.getTextureWidth(w.getWorkspace()) > component.getTextureHeight(w.getWorkspace()))>
<@getSpriteByIndex component "width"/>, 0
<#else>
0, <@getSpriteByIndex component "height"/>
</#if>,
${component.getWidth(w.getWorkspace())}, ${component.getHeight(w.getWorkspace())},
${component.getTextureWidth(w.getWorkspace())}, ${component.getTextureHeight(w.getWorkspace())});
<#if hasProcedure(component.displayCondition)>}</#if>
</#list>
注意覆盖层模板中计算精灵子图偏移的宏 <@getSpriteByIndex .../> 与 GUI 模板一致,精灵纹理被注册为 SPRITE_${component?index} 这样的 ResourceLocation(第 47-49 行),引用自 modid:textures/screens/<文件名>。
从源码结构可以推断:由于 Overlay 的显示条件必须依赖玩家实体(模板第 68-74 行取 Minecraft.getInstance().player 及其坐标、所在世界),因此在 Overlay 中编写显示条件时通常利用 entity、world、x/y/z 依赖来实现"按玩家状态动态显示 HUD 元素"的效果。
4.3 两个生成器版本的一致性
本文引用的模板同时存在于两个生成器插件中:
- generator-1.21.1/neoforge-1.21.1(对应 Minecraft 1.21.1 的 NeoForge 生成器)
- generator-26.3.x/neoforge-26.3(对应新版 26.3.x 的 NeoForge 生成器)
两者对精灵显示条件的处理逻辑完全一致(条件包裹 + 图集裁剪),区别仅在于少量 API 差异(如 1.21.1 使用 ResourceLocation.parse、26.3 模板的对应写法)。这说明"显示条件"是跨 Minecraft 版本长期稳定的生成语义,升级生成器版本不会破坏既有精灵显示条件的配置。
五、实战示例:常见显示条件场景
结合上文依赖变量(x/y/z/world/entity)与客户端逻辑限制,以下是几类可直接落地的显示条件思路:
- 按玩家状态显示:条件引用
entity依赖,例如"仅当玩家拥有某 Buff 时显示对应技能精灵图标",或"玩家饱食度低于阈值时显示饥饿警告精灵"。 - 按位置显示:条件引用
x/y/z与world,例如"玩家处于特定维度(如地狱)时显示该维度的环境精灵"。 - 按时间显示:利用
world依赖读取世界时间,实现"只在夜晚显示"的月亮/星星精灵,或"只在白天显示"的太阳精灵。 - 按交互状态显示:结合游戏内状态变量(scoreboard、NBT 数据)作为条件输入,实现任务进度、解锁状态驱动的显示切换。
在实际使用中,如果你在精灵对话框的显示条件字段中不选择任何过程(保持为空),则该精灵会无条件始终显示,等价于传统静态贴图;只有当你需要"按条件动态切换可见性"时,才需要在该字段挂接一个返回逻辑值(布尔)的客户端过程。
六、总结与延伸阅读
- 一句话概括:精灵显示条件是挂接在精灵组件上的一个可选客户端逻辑过程,条件为真(通过)时渲染精灵,条件为假或未指定时按默认行为处理(未指定 = 始终显示)。
- 界面入口:GUI/Overlay 编辑器 → 精灵组件对话框 → "Sprite display condition" 字段(右侧帮助按钮即打开本文关联文档页面)。
- 数据层:字段类型为
Procedure(逻辑返回类型),序列化为过程名引用,见 Sprite.java 与 Procedure.java。 - 生成层:GUI 模板 gui_window.java.ftl 与 Overlay 模板 overlay.java.ftl 用
if (条件) { blit(...) }包裹精灵绘制调用。
若想继续深入,可对照阅读同一帮助体系下的姊妹条目:sprite_index.md(精灵索引,注意索引从 0 开始、最大为精灵数量减 1)与 sprite_count.md(精灵数量),并结合 SpriteDialog.java 理解精灵图集的完整配置链路。