MCreator 实体视觉缩放与碰撞箱缩放完全指南:Visual scale 与 Bounding box scale 参数详解
MCreator 实体视觉缩放与碰撞箱缩放完全指南:Visual scale 与 Bounding box scale 参数详解
在 MCreator 中创建自定义实体时,一个经常被忽视却极具表现力的配置项是实体尺寸控制。官方帮助文档(如 de_DE 版 与 zh_CN 版)明确指出:该功能用于控制实体在游戏中的模型外观尺寸,而若要调整实体的碰撞箱比例,则需要使用 "Bounding box scale" 参数。本文将围绕这两个参数,结合 MCreator 源码与 NeoForge 代码生成模板,说明它们的区别、取值范围、底层实现原理与实战注意事项,帮助你在不破坏实体碰撞行为的前提下自由放大或缩小实体外观。
一、两个缩放参数的本质区别
MCreator 的实体编辑界面(Living Entity 类型)在"模型/渲染"相关设置中提供了两个名称相近、作用域完全不同的缩放参数:
| 参数 | GUI 标签 | 作用对象 | 生效端 |
|---|---|---|---|
| Model visual scale | 模型外观缩放 | 实体的视觉模型(渲染层) | 仅客户端(CLIENT) |
| Bounding box scale | 边框/碰撞箱比例 | 实体的碰撞箱(物理尺寸) | 客户端与服务端(BOTH) |
这一区分在源码中有着清晰的体现。实体数据结构 LivingEntity.java 中同时声明了 public NumberProcedure visualScale; 与 public NumberProcedure boundingBoxScale; 两个字段,分别对应上述两个参数。
从设计意图看:外观缩放只改变"看起来的样子",不影响实体被方块、玩家或其他实体碰撞阻挡的判定区域;而碰撞箱缩放则改变实体实际的物理占位尺寸。两者可以独立设置,也可以组合使用来制作"模型很大但碰撞箱很小"或相反的特殊生物。
二、参数在实体编辑器中的位置与操作方式
在 MCreator 中打开或新建一个实体(Entity → Living Entity)类型的元素,向下滚动到"模型/渲染"相关区域,即可看到这两个参数。其 GUI 构建逻辑位于 LivingEntityGUI.java:两个参数选择器 visualScale 与 boundingBoxScale 被依次添加到界面面板中,并各自通过帮助按钮挂接了帮助文档条目(entity/visual_scale、entity/bounding_box_scale),这也是本文所依据的帮助文档 visual_scale.md 在软件内的触发入口。
两个参数在 GUI 中的定义细节可从 LivingEntityGUI.java 中看到:
visualScale = new NumberProcedureSelector(this.withEntry("entity/visual_scale"), mcreator,
L10N.t("elementgui.living_entity.visual_scale"), AbstractProcedureSelector.Side.CLIENT,
new JSpinner(new SpinnerNumberModel(1, 0.01, 1024, 0.01)), 0,
Dependency.fromString("x:number/y:number/z:number/world:world/entity:entity"));
boundingBoxScale = new NumberProcedureSelector(this.withEntry("entity/bounding_box_scale"), mcreator,
L10N.t("elementgui.living_entity.bounding_box_scale"), AbstractProcedureSelector.Side.BOTH,
new JSpinner(new SpinnerNumberModel(1, 0.01, 1024, 0.01)), 210,
Dependency.fromString("x:number/y:number/z:number/world:world/entity:entity"));
由此可以总结出以下实操要点:
- 取值范围:两个参数的固定值均为
0.01 ~ 1024,步进为0.01,默认值为1(即原始尺寸,不缩放)。 - 两种输入模式:它们都是
NumberProcedureSelector,即既可以填写固定数值,也可以通过数字型过程(Procedure)动态计算缩放值,实现"变大变小随时间/状态变化"的效果。 - 过程依赖:当使用过程动态计算时,可用的依赖为
x / y / z / world / entity,即实体自身坐标、所在世界与实体引用。 - 客户端/服务端差异:
visualScale标记为Side.CLIENT(仅客户端,因为模型渲染只发生在客户端);boundingBoxScale标记为Side.BOTH(碰撞箱影响物理逻辑,需要服务端同步)。
界面上的参数标签文本由本地化文件 texts.properties 提供,分别为 Model visual scale: 与 Bounding box scale:。
三、Visual scale:模型外观缩放的底层实现
在 NeoForge 1.21.1 与 26.3.x 的生成器模板中,外观缩放通过覆写渲染器的 scale(...) 方法实现。以 livingentity_renderer.java.ftl(1.21.1) 为例:
@Override protected void scale(NameEntity entity, PoseStack poseStack, float f) {
// 使用过程动态计算缩放值时
Level world = entity.level();
double x = entity.getX();
double y = entity.getY();
double z = entity.getZ();
float scale = (float) <@procedureOBJToNumberCode data.visualScale/>;
poseStack.scale(scale, scale, scale);
// 使用固定数值且不为 1 时
poseStack.scale(<value>f, <value>f, <value>f);
}
关键实现事实:
- 缩放通过对渲染的
PoseStack进行三轴等比scale调用完成,因此外观是等比缩放,不会出现 X/Y/Z 方向拉伸。 - 该覆写方法仅在满足条件时才生成:当
visualScale的固定值不等于 1、或配置了缩放过程、或模型为 Villager、或实体可繁殖(breedable)时(26.3.x 模板见 livingentity_renderer.java.ftl(26.3))。 - 对于可繁殖实体,渲染层还会额外叠加
entity.getAgeScale()(幼年/成年阶段缩放);对于 Villager 模型,还会叠加0.9375f的固定缩放。
实战含义:如果你只调大 Visual scale 而不同步调整 Bounding box scale,就会出现"模型看起来很大、但身体可以穿墙/穿入方块,玩家也能轻易站在模型内部"的视觉效果;反之,只调大碰撞箱会出现"看不见的隐形墙"。
四、Bounding box scale:碰撞箱缩放的底层实现
碰撞箱缩放通过覆写实体的 getDefaultDimensions(Pose) 方法实现,这在两个生成器模板中一致。以 livingentity.java.ftl(1.21.1) 为例:
@Override public EntityDimensions getDefaultDimensions(Pose pose) {
// 使用过程动态计算时
Entity entity = this;
Level world = this.level();
double x = this.getX();
double y = this.getY();
double z = this.getZ();
return super.getDefaultDimensions(pose).scale((float) <@procedureOBJToNumberCode data.boundingBoxScale/>);
// 使用固定数值时
return super.getDefaultDimensions(pose).scale(<value>f);
}
在 26.3.x 模板中还补充了尺寸刷新的细节(livingentity.java.ftl(26.3) 与 L676-L691):
- 当固定值不等于 1 时,实体构造函数中会调用
refreshDimensions(),使碰撞箱在实体生成时立即生效; - 当使用过程动态计算时,实体
baseTick()中每个 tick 都会调用refreshDimensions(),确保过程返回的数值变化能实时反映到碰撞箱上。
EntityDimensions.scale(float) 是 Minecraft/NeoForge 原生的等比缩放 API,会同时缩放实体的宽、高与整体包围盒体积。
五、实战建议与注意事项
- 等比对齐:默认两者均为 1。若想让实体"整体变大",建议同时设置 Visual scale 与 Bounding box scale 为相同数值,避免出现"穿模"或"隐形障碍"。
- 注意取值范围上限:GUI 限制固定值最大为
1024,最小0.01。过大的缩放可能导致实体穿出世界边界或渲染异常;过小的碰撞箱(如 0.01)可能使实体陷入地面判定异常。 - 动态缩放场景:两个参数都支持过程驱动。典型用法包括:用过程按实体血量百分比返回缩放值,制作"受伤变小/变强变大"的 Boss;或利用
baseTick刷新机制实现持续的体型动画。注意visualScale仅客户端执行,若过程依赖服务端状态(如计分板),需保证数据已同步。 - 与 AI/寻路的关系:碰撞箱影响实体的物理占位与寻路碰撞判定,改变 Bounding box scale 会影响实体穿过通道的能力;Visual scale 则纯粹是视觉表现。
- 与其他模型参数的配合:实体编辑界面中还有模型宽度/高度、阴影大小(model shadow size)、坐骑 Y 偏移(mounted Y offset)等参数(见 LivingEntityGUI.java)。调整缩放后,若阴影大小未同步调整,可能出现"阴影与模型不匹配"的视觉瑕疵。
六、帮助文档与多语言支持
MCreator 为这两个参数提供了完善的随界面帮助文档。本文依据的 de_DE 版帮助文档 内容为:
Diese Funktion erlaubt es dir, die Größe des visuellen Modells im Spiel zu bestimmen. Um die Kollisionsbox der Entität zu skalieren, verwendest du den Parameter "Bounding box scale".
其 中文版 为:
此功能允许您控制实体游戏中的模型外观尺寸。要调整实体的碰撞箱比例,请使用"边框比例"参数。
该帮助文件位于 mcreator-localization 插件的 help 目录下,并随 默认语言(英文) 一同提供了 de_DE、zh_CN、zh_TW、fr_FR、ja_JP、ko_KR、ru_RU 等多语言版本,在编辑实体时点击参数旁的帮助按钮即可查阅。同时,参数默认值与取值范围的完整约束定义集中在 LivingEntityGUI.java 中,是排查"缩放不生效"问题时的首要检查点。
小结:Visual scale 与 Bounding box scale 是 MCreator 实体创作中一对"形"与"实"分离的缩放控制——前者通过渲染层 PoseStack.scale 改变外观,后者通过 EntityDimensions.scale 改变物理碰撞尺寸。理解二者在 GUI、数据结构与生成模板中的对应关系,即可精准掌控自定义实体的体型表现与碰撞行为。