MCreator 粒子"视觉缩放(Scale)"参数深度解析:从 GUI 配置到代码生成原理

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

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 源码中"固定数值 + 可选程序"的双轨设计。

六、实践建议

  1. 制作统一尺寸的粒子(如雪花、灰尘):将 Scale 设为固定值,并勾选"禁用粒子大小变化(fixedScale)",保证视觉效果整齐一致。
  2. 实现缩放动画:为 Scale 绑定依赖 age 的程序(例如 age * 0.05),即可获得粒子随时间长大的效果,无需额外制作多张纹理。
  3. 留意范围限制:固定数值模式受 Spinnder 约束为 0.1 ~ 4096;如需超出此范围的极端缩放,可考虑通过程序返回值绕过(程序返回值不受该 Spinner 范围限制)。
  4. 区分"渲染大小"与"碰撞大小":若粒子需要与方块/实体交互,应同时关注 width / height 包围盒参数;Scale 只决定视觉大小。

七、小结

"粒子外观比例(Scale)"是 MCreator 粒子元素中最直观也最灵活的视觉控制参数之一。通过本文可以看到,它从帮助文档中的一句话定义,延伸到 GUI 中的 NumberProcedureSelector(固定值 0.1~4096、默认 1、可绑定程序),再经模板 particle.java.ftl 分别生成"固定缩放"与"动态缩放"两条代码路径,最终与 fixedScale、width/height 等参数共同决定粒子的屏幕呈现。理解这一条完整的"配置 → 数据模型 → 模板生成"链路,能帮助你在制作自定义粒子时精准控制尺寸,并安全地使用程序实现动态特效。

登录后查看全文
MCreator