MCreator GUI 实体模型显示条件(Entity Model Display Condition):条件筛选机制与代码生成原理

原创2026-10-15 18:43:051,403 阅读
文章标签:桌面应用游戏开发代码生成低代码开发工具模板引擎

MCreator GUI 实体模型显示条件(Entity Model Display Condition):条件筛选机制与代码生成原理

本文围绕 MCreator 内置帮助文档「实体模型显示条件」(即 cs_CZ/gui/entity_model_display_condition.md,英文原版见 default/gui/entity_model_display_condition.md)展开。该功能作用于 MCreator 的 WYSIWYG 图形界面(GUI)编辑器:当你在界面中添加一个「实体模型」组件时,可以通过一个返回逻辑值(true/false)的过程(Procedure)决定该模型是否被渲染显示。读完本文,你将掌握该选项的配置入口、条件语义、可用依赖参数,以及它最终如何被翻译为 Minecraft 模组渲染代码的底层原理。

功能定位:什么条件下才显示这个实体模型

原文档的说明非常简洁,其含义是:如果指定了条件,则该实体模型只有在条件通过(返回 true)时才显示;若条件不通过(返回 false),模型在界面上完全不可见。

这一机制与 MCreator 中其他 GUI 组件的 displayCondition(显示条件)设计一脉相承。从源码结构看,MCreator 的 GUI 组件体系中,按钮(Button)、图片(Image)、图片按钮(ImageButton)、标签(Label)、精灵图(Sprite)、提示框(Tooltip)以及实体模型(EntityModel)都声明了 displayCondition 字段,见 EntityModel.java 与 Button.java、Image.java 等同目录实现。实体模型的特殊之处在于,它渲染的对象是一个动态实体(例如一只猪、一只苦力怕或你自己的自定义生物),因此「显示条件」常被用来实现诸如「仅在玩家拥有某物品时显示」「仅在某游戏状态/世界时间下显示」「仅在玩家持特定道具时显示该宠物模型」这类动态界面效果。

配置入口与操作步骤

在哪里找到该选项

该选项位于 GUI 编辑器(WYSIWYG)的「添加实体模型」对话框中。在 MCreator 的 GUI 编辑器中,将「实体模型」组件拖入画布,或双击已有的实体模型组件,即可打开 EntityModelDialog.java 对应的对话框。

对话框中的字段布局(参考 EntityModelDialog.java)如下:

字段 说明 源码依据
实体模型(Entity Model) 决定显示哪个实体,过程返回值必须是一个实体(entity)类型 ProcedureSelector ... BuiltInTypes.ENTITY,参考 entity_model.md
模型显示条件(Model Display Condition) 决定该实体模型是否显示,过程返回值必须为逻辑(LOGIC)类型 ProcedureSelector ... BuiltInTypes.LOGIC
缩放(Scale) 模型显示大小,默认 30,范围 1~100 SpinnerNumberModel(30, 1, 100, 1)
旋转 X(Rotation X) 模型绕 X 轴旋转角度,范围 -360~360 度 SpinnerNumberModel(0, -360, 360, 1)
跟随鼠标(Follow Mouse Movement) 模型随鼠标位置旋转(仅非 Overlay 类型界面可用) 参考 entity_model_follow_mouse.md

具体操作

  1. 在 GUI 编辑器中添加或双击「实体模型」组件,打开实体模型对话框。
  2. 在「实体模型」选择器中选中一个返回实体类型的过程(这是必选项,未选择时会触发 NonEmptyValidator 校验,见 EntityModelDialog.java)。
  3. 在「模型显示条件」选择器中选中一个返回逻辑类型的过程;也可以留空——留空时该选项不生效,模型无条件显示(详见下文「未指定条件时的默认行为」)。
  4. 配置缩放、旋转角度等外观参数,点击确定保存。

在对话框中,条件选择器与实体模型选择器被并排放置在「North」区域(options.add("North", PanelUtils.join(entityModel, displayCondition)),见 EntityModelDialog.java),并且编辑已有组件时会自动回填已保存的选择(displayCondition.setSelectedProcedure(model.displayCondition),见同文件 #L113)。

条件语义与可用依赖参数

从 EntityModelDialog.java 的源码可以看到,显示条件选择器的定义如下:

  • 过程执行端:ProcedureSelector.Side.CLIENT——条件在客户端侧求值,因此可以放心使用客户端可用的事件与过程(例如按键状态、鼠标位置、渲染相关参数),也意味着它是纯界面表现层的筛选,不会影响服务端逻辑。
  • 返回类型:VariableTypeLoader.BuiltInTypes.LOGIC——即布尔值,true 显示、false 隐藏。
  • 可用依赖:x:number / y:number / z:number / world:world / entity:entity——编写条件过程时,你可以直接引用当前界面所在世界的坐标(x/y/z)、世界对象(world)以及被渲染的实体(entity)作为输入。例如判断 entity 是否处于某个状态、world 是否处于夜晚等。

生成代码时,这些依赖会由模板系统的 procedureDependenciesCode 机制注入到渲染函数中,保证条件过程在正确的上下文中执行。

代码生成原理:条件如何进入最终模组

当条件过程被选中后,MCreator 的 FreeMarker 模板会把它翻译为实体渲染代码中的运行时判断。以 NeoForge 1.21.1 生成器为例,模板 gui_window.java.ftl 中生成的核心逻辑为:

<#list data.getComponentsOfType("EntityModel") as component>
    if (<@procedureOBJToConditionCode component.entityModel/> instanceof LivingEntity livingEntity) {
        <#if hasProcedure(component.displayCondition)>
            if (<@procedureOBJToConditionCode component.displayCondition/>)
        </#if>
        ...渲染实体模型...
    }
</#list>

也就是说,生成的 Java 渲染代码会先取得实体模型过程返回的实体对象,并在类型校验通过后,用 if (条件过程返回 true) 包裹整个模型渲染调用;条件不通过时,模型的渲染代码被直接跳过,界面上不绘制该模型。

新版生成器(26.3.x,面向更新版本 Minecraft 的 NeoForge)采用了相同的模式,见 gui_window.java.ftl:同样先校验 entityModel 返回值是否为 LivingEntity,再以 if (<@procedureOBJToConditionCode component.displayCondition/>) 作为渲染前置条件。

条件宏的底层实现

procedureOBJToConditionCode 是在 procedures.java.ftl 中定义的模板宏:

  • 当对象指向一个真实存在的过程时,宏会输出该过程的调用代码(procedureToRetvalCode),把过程编译后的返回值直接作为条件表达式的值;
  • 当过程不存在(<#else>)时,输出默认值 true(${defaultValue?c}),这正是「未指定条件 = 无条件显示」的生成侧依据。

该宏还支持 invertCondition 参数(输出前加 !),不过实体模型显示条件默认不取反。

未指定条件时的默认行为

结合模板与宏可以看出,「模型显示条件」是可选配置:

  • 未选择任何过程时,模板中的 <#if hasProcedure(component.displayCondition)> 不成立,不会生成条件包裹代码,实体模型始终显示;
  • 选择了过程但过程返回 false 时,模型不显示;
  • 选择了过程且返回 true 时,模型正常显示。

这与原文档「如果指定了条件,则仅当条件通过时显示」的描述完全一致:条件是对默认「总是显示」行为的收窄。

典型应用场景建议

基于上述语义,可以推断出几个常见用法(具体效果取决于你编写的过程逻辑):

  • 状态式展示:当玩家拥有特定物品、处于特定维度、或实体拥有某 Buff 时才在界面中展示对应的模型;
  • 分页/多形态展示:在同一个 GUI 中放置多个实体模型组件,每个组件绑定不同的条件与不同实体,实现「根据条件切换展示哪个生物」的效果;
  • 条件装饰:只在世界为夜晚、下雨等环境条件下显示某个装饰性实体模型;
  • 与跟随鼠标选项组合:显示条件与 entity_model_follow_mouse.md 描述的方向旋转叠加机制(鼠标旋转角叠加在固定旋转值上)相互独立,可以组合使用,实现「条件触发 + 面向鼠标」的动态展示。

由于条件过程运行在客户端侧,且依赖参数包含 x/y/z/world/entity,编写时建议只使用客户端可靠的状态来源,避免依赖仅在服务端更新的数据。

与其他组件的「显示条件」横向对照

「实体模型显示条件」并非孤立功能,MCreator 的 GUI 组件普遍具备同名机制。仓库中相关帮助文档与组件如下:

组件 帮助文档(英文原版) 字段位置
实体模型 entity_model_display_condition.md EntityModel.java
按钮 button_display_condition.md Button.java
图片 image_display_condition.md Image.java
标签 label_display_condition.md Label.java
精灵图 sprite_display_condition.md Sprite.java
提示框 tooltip_display_condition.md Tooltip.java

这些组件的显示条件在生成时都会被转换为渲染循环内的 if (<@procedureOBJToConditionCode component.displayCondition/>) 判断(参见 gui_window.java.ftl 中 Tooltip 的同类写法),因此掌握实体模型显示条件后,其余组件的条件逻辑可以触类旁通。此外,实体模型组件本身还有配套的 entity_model.md(实体模型过程的返回值必须为实体)、entity_model_scale.md、entity_model_rotation.md、entity_model_follow_mouse.md 等帮助条目,可作为完整配置该组件的参考。

小结

MCreator 的「实体模型显示条件」是一个客户端侧的布尔筛选开关:指定则「条件通过才显示」,未指定则「总是显示」。它由 WYSIWYG 对话框中的 ProcedureSelector(逻辑类型、CLIENT 端、可引用 x/y/z/world/entity)配置,在生成阶段被 FreeMarker 模板翻译为实体渲染器中的 if 判断,其行为与按钮、图片等组件的 displayCondition 一致。善用该选项,可以让你的自定义 GUI 根据运行时状态动态、精准地展示实体模型,显著提升界面交互的丰富度。

登录后查看全文
MCreator