MCreator 粒子"视觉缩放(Scale)"参数深度解析:从 GUI 配置到代码生成原理
MCreator 粒子"视觉缩放(Scale)"参数深度解析:从 GUI 配置到代码生成原理
粒子视觉缩放(Scale)是 MCreator 粒子元素中用于控制粒子纹理显示尺寸的核心参数。本文围绕官方帮助文档 plugins/mcreator-localization/help/de_DE/particle/scale.md 中"此参数定义了粒子纹理应缩放多少"这一主题,结合 MCreator 开源源码(GUI 面板、数据模型、代码生成模板与集成测试),完整讲解该参数的取值含义、配置方式、与其"固定缩放"等关联参数的配合,以及它最终如何在生成的 NeoForge 模组代码中落地生效。读完本文,你将能准确设置粒子大小,并通过绑定数值型程序实现运行时动态缩放。
一、参数定位:粒子编辑器中的"粒子外观比例"
在 MCreator 的粒子元素编辑界面中,Scale 参数对应本地化键 elementgui.particle.visual_scale,中文界面显示为"粒子外观比例"(见 texts_zh_CN.properties)。帮助文档对其定义非常简洁:
Dieser Parameter legt fest, wie stark die Partikeltextur skaliert werden soll.(此参数定义了粒子纹理应缩放多少。)
英文默认版(default/particle/scale.md)与中文版(zh_CN/particle/scale.md)语义一致:该值是一个缩放倍数,直接作用于粒子渲染时的四边形尺寸(quadSize)。
从 GUI 源码 ParticleGUI.java 可以看到该控件的完整构造:
scale = new NumberProcedureSelector(this.withEntry("particle/scale"), mcreator,
L10N.t("elementgui.particle.visual_scale"), AbstractProcedureSelector.Side.CLIENT,
new JSpinner(new SpinnerNumberModel(1, 0.1, 4096, 0.1)), 0,
Dependency.fromString("x:number/y:number/z:number/world:world/age:number/scale:number"));
这说明它并非一个普通数值输入框,而是一个 NumberProcedureSelector——既能填写固定数值,也能绑定一个返回数值的程序(Procedure),用于动态计算缩放。
二、取值规则与默认行为
2.1 固定数值模式
NumberProcedureSelector 内嵌的 JSpinner 使用 SpinnerNumberModel(1, 0.1, 4096, 0.1),即:
| 属性 | 值 |
|---|---|
| 默认值 | 1.0(保持原始大小) |
| 最小值 | 0.1(缩小到 1/10) |
| 最大值 | 4096 |
| 步进 | 0.1 |
当取值为 1 且未启用"固定缩放"时,粒子使用原版的默认尺寸行为;取值大于 1 放大,小于 1 缩小。该固定值最终由 NumberProcedure.getFixedValue() 提供给代码生成模板(该类继承自 RetvalProcedure.java,负责存储并返回固定数值)。
2.2 程序(Procedure)模式
由于绑定的是 NumberProcedureSelector,你可以为 Scale 挂接一个返回数值的程序。从源码可见,该程序可用的上下文依赖(Dependencies)为:
x:number / y:number / z:number / world:world / age:number / scale:number
即程序运行时可以读取粒子当前的位置坐标(x、y、z)、所在世界、存活时间(age)以及当前缩放值(scale),并据此返回新的缩放倍数。这为实现"粒子出生时小、随时间长大""靠近某位置时变大"等动态效果提供了官方支持的基础能力。
三、与相关参数的配合
3.1 固定缩放(fixedScale)
帮助文档 fixed_scale.md 说明:
Wenn aktiviert, stellt dieser Parameter sicher, dass das Partikel keine Größenvariation anzeigt, wenn es erzeugt wird.(启用时,确保粒子在生成时不会显示任何大小变化。)
中文界面中该项显示为"禁用粒子大小变化?"(texts_zh_CN.properties)。Minecraft 原版的粒子在渲染时会依据随机种子产生一定的尺寸抖动;勾选该项后,粒子将使用固定的基准尺寸,使所有同类型粒子外观完全一致。它在数据模型中与 Scale 并列存储于 Particle.java:
public NumberProcedure scale;
public boolean fixedScale;
3.2 与宽高(width / height)的区别
注意不要与粒子的宽高参数混淆。width / height 定义的是粒子包围盒(Bounding Box)在方块单位下的尺寸(对应文档 width.md、height.md),用于碰撞与物理交互;而 Scale 只影响渲染出来的纹理四边形大小。在数据模型中二者同样并排出现(Particle.java):
@Numeric(init = 0.2, min = 0, max = 4096, step = 0.1) public double width;
@Numeric(init = 0.2, min = 0, max = 4096, step = 0.1) public double height;
四、代码生成原理:Scale 如何落地为模组代码
粒子元素的生成定义见 neoforge-1.21.1/particle.definition.yaml,它引用 particle.java.ftl 生成客户端粒子类,并输出 @MODASSETSROOT/particles/@registryname.json 纹理清单。缩放逻辑在模板 particle.java.ftl 中分为两条路径:
4.1 固定数值路径
<#if (data.scale.getFixedValue() != 1 || data.fixedScale) && !hasProcedure(data.scale)>
this.quadSize <#if data.fixedScale>= 0.15f *<#else>*=</#if> ${data.scale.getFixedValue()}f;
</#if>
该条件揭示了几条关键规则:
- 仅当固定值不等于
1,或启用了固定缩放时,才会生成这条缩放赋值语句; - 若未启用固定缩放(
fixedScale为 false),采用quadSize *= <scale>,即在原版默认(含随机抖动)的尺寸基础上相乘; - 若启用固定缩放,则采用
quadSize = 0.15f * <scale>,以0.15f为固定基准尺寸,彻底移除随机抖动,保证所有粒子大小一致; - 若固定值恰好为
1且未启用固定缩放,则不生成任何缩放代码,完全保留原版行为。
4.2 程序(动态)路径
当 Scale 绑定了程序时,模板重写 getQuadSize 方法(particle.java.ftl):
<#if hasProcedure(data.scale)>
@Override public float getQuadSize(float scale) {
Level world = this.level;
return <#if data.fixedScale>0.15f<#else>super.getQuadSize(scale)</#if> * (float) <@procedureOBJToConditionCode data.scale/>;
}
</#if>
这里程序返回值作为每一帧的缩放乘数参与计算:固定缩放开启时基准为 0.15f,否则沿用 super.getQuadSize(scale)(原版基于年龄与随机的基准尺寸)。由于 getQuadSize 在渲染时每帧调用,程序返回值的动态变化会直接反映为粒子大小的连续动画。
说明:NeoForge 26.3.x 的对应模板 neoforge-26.3/templates/particle.java.ftl 使用新版
SingleQuadParticle基类,但缩放逻辑(含0.15f基准与getQuadSize重写)与 1.21.1 版本保持一致。
五、测试中的参数形态
在集成测试数据提供器 TestWorkspaceDataProvider.java 中,粒子元素的 Scale 相关字段被这样构造:
Particle particle = new Particle(modElement);
particle.texture = new TextureHolder(modElement.getWorkspace(), "particle1");
particle.width = getRandomDouble(random, Particle.class, "width");
particle.height = getRandomDouble(random, Particle.class, "height");
particle.scale = new NumberProcedure(emptyLists ? null : "number1", 1.38);
particle.fixedScale = _true;
可以看到 scale 字段同时携带"程序名(number1,可为空)"与"固定回退值(1.38)"两部分——这正是 NumberProcedure 的典型形态:绑定了程序时用程序结果,未绑定时用固定值。这也验证了上文 GUI 源码中"固定数值 + 可选程序"的双轨设计。
六、实践建议
- 制作统一尺寸的粒子(如雪花、灰尘):将 Scale 设为固定值,并勾选"禁用粒子大小变化(fixedScale)",保证视觉效果整齐一致。
- 实现缩放动画:为 Scale 绑定依赖
age的程序(例如age * 0.05),即可获得粒子随时间长大的效果,无需额外制作多张纹理。 - 留意范围限制:固定数值模式受 Spinnder 约束为
0.1 ~ 4096;如需超出此范围的极端缩放,可考虑通过程序返回值绕过(程序返回值不受该 Spinner 范围限制)。 - 区分"渲染大小"与"碰撞大小":若粒子需要与方块/实体交互,应同时关注
width/height包围盒参数;Scale 只决定视觉大小。
七、小结
"粒子外观比例(Scale)"是 MCreator 粒子元素中最直观也最灵活的视觉控制参数之一。通过本文可以看到,它从帮助文档中的一句话定义,延伸到 GUI 中的 NumberProcedureSelector(固定值 0.1~4096、默认 1、可绑定程序),再经模板 particle.java.ftl 分别生成"固定缩放"与"动态缩放"两条代码路径,最终与 fixedScale、width/height 等参数共同决定粒子的屏幕呈现。理解这一条完整的"配置 → 数据模型 → 模板生成"链路,能帮助你在制作自定义粒子时精准控制尺寸,并安全地使用程序实现动态特效。