MCreator 生物群系粒子生成概率（particlesProbability）参数完全解析：从编辑器配置到数据包生成的底层原理

在 MCreator 中创建自定义生物群系时，"粒子生成概率"（Particle spawn probability）决定了该群系环境粒子的出现频率。本文以 particle_probability.md 帮助文档为核心，结合群系数据模型、编辑器实现与数据包生成模板的源码，完整讲解该参数的语义、取值范围、"除以 100"的底层换算机制，以及它在不同 Minecraft 版本生成管线中的实际落地方式，帮助你在制作群系时准确控制环境粒子密度。

参数含义：每 tick 生成粒子的百分比概率

MCreator 的群系编辑器（Biome GUI）中，"Ambient particles"（群系环境粒子）区域提供了三个联动配置项，分别由 BiomeGUI.java 中的三个控件承载：

控件	帮助条目	作用
spawnParticle（开关）	spawn_particle.md	勾选后启用该群系的环境粒子生成
particleToSpawn（粒子选择）	particle_type.md	选择要在群系中生成的粒子类型
particlesProbability（概率）	particle_probability.md	设定粒子生成的百分比概率

对应地，英文语言文件 texts_en_GB.properties 将该参数标签定义为 Particle spawn probability (% chance per tick):，即"每游戏刻（tick）生成粒子的百分比概率"。也就是说，这个数值描述的是每个 tick 内粒子出现的期望概率，值越大，群系环境中飘浮的粒子越密集。

需要说明的是，该参数仅在 spawnParticle 被勾选后生效；粒子类型 particleToSpawn 与概率值在此开关关闭时会在界面中被禁用（见 BiomeGUI.java）。

数据类型与取值范围：0～100 的浮点数

在群系数据模型 Biome.java 中，该参数通过 @Numeric 注解声明：

public boolean spawnParticles;
@NonNullIf("spawnParticles") public ParticleEntry particleToSpawn;
@Numeric(init = 0.5, min = 0, max = 100, step = 0.1) public double particlesProbability;

由注解可以明确该参数的完整约束：

• 类型：double（浮点数，支持小数概率）；
• 默认值（init）：0.5，即编辑器新建群系时默认每 tick 有 0.5% 的粒子生成概率；
• 最小值（min）：0，表示不生成粒子；
• 最大值（max）：100，表示理论上的最大概率输入；
• 步长（step）：0.1，界面中的微调步进为 0.1。

同时 @NonNullIf("spawnParticles") 约束保证：只要开启粒子生成开关，就必须指定一个有效的粒子类型，否则数据不完整；概率字段则始终存在默认值。

关键机制：为什么代码中要"除以 100"

原帮助文档明确指出该值会在代码中除以 100（原文为德语："HINWEIS: Dieser Wert wird durch 100 im Code geteilt."）。这并非界面显示与内部存储的差异，而是 MCreator 在数据包生成阶段完成的一次百分比到归一化概率的换算。

以 1.21.1 数据包生成模板 biome.json.ftl 为例：

<#if data.spawnParticles>
"particle": {
    "options": {
        "type": "${data.particleToSpawn.getMappedValue(1)}"
    },
    "probability": ${data.particlesProbability / 100}
},
</#if>

FreeMarker 模板中的 ${data.particlesProbability / 100} 就是"除以 100"的实体实现。例如：

• 界面输入 0.5（默认值）→ 生成的 JSON 中 probability: 0.005；
• 界面输入 5 → 生成的 JSON 中 probability: 0.05；
• 界面输入 100 → 生成的 JSON 中 probability: 1.0（每个 tick 必然触发一次判定）。

之所以这样设计，是因为 Minecraft 原生的生物群系粒子配置（minecraft:biome JSON 中的 particle.probability 字段）要求的是 0.0～1.0 的归一化概率，而 MCreator 为了在编辑器中提供更直观的"百分比"体验，让用户直接填写 0～100 的百分比数值，再在模板输出时统一除以 100 完成换算。这也是帮助文档特意强调该提示的原因——你在编辑器里看到的数字是"百分比"，而不是原生产物中的归一化小数。

不同版本的生成差异：从 JSON 字段到数据组件

MCreator 仓库同时维护了多个版本的生成器插件，粒子概率在其中的落地方式随 Minecraft 版本的数据格式演进有所不同：

• Forge/NeoForge 1.21.1（数据包生成器）：如上文所示，输出到 biome.json 的顶层 particle 对象，字段为 options.type 与 probability；
• 26.3.x（数据包生成器）：在 biome.json.ftl 中，改为输出到数据组件 minecraft:visual/ambient_particles：

<#if data.spawnParticles>
"minecraft:visual/ambient_particles": {
    "modifier": "append",
    "argument": [
        {
            "particle": {
                "type": "${data.particleToSpawn.getMappedValue(1)}"
            },
            "probability": ${data.particlesProbability / 100}
        }
    ]
},
</#if>

可以看出，particlesProbability / 100 的换算逻辑在两个版本中完全一致，变化的只是外层 JSON 结构（由顶层 particle 字段迁移为数据组件形式）。这意味着无论你使用哪个生成器版本，编辑器中的百分比输入语义都保持不变，底层换算由模板统一处理。

实战建议与排查要点

结合参数约束与生成模板，在实际制作群系时应注意以下几点：

1. 概率感知上的量级差异：0.5 的默认值换算后仅为 0.005，属于"偶尔飘几个粒子"的稀疏效果；想要明显的粒子氛围（例如魔法群系中的大量萤火虫效果），建议从 1～10 之间的数值开始调试，而非在 0～1 的小数区间摸索。
2. 不要手动在 JSON 中重复换算：由于模板已经执行 / 100，你只需在界面中填写 0～100 的百分比；若在生成结果基础上二次手工改动，需注意换算关系，避免概率被重复缩放。
3. 调试入口：生成后的数据包文件可直接检查 probability 字段的实际值来验证换算结果；群系数据模型定义位于 Biome.java，生成模板位于对应版本的 biome.json.ftl，两者是排查"为什么粒子不出现/太密集"问题的第一现场。
4. 参数联动：若粒子完全没有生成，请先确认 spawnParticle 开关已勾选且 particleToSpawn 指定了有效粒子，再排查概率值是否被误设为 0。

小结

MCreator 的"粒子生成概率"参数是一个典型的"编辑器友好型百分比、引擎归一化概率"的换算案例：界面提供 0～100、默认 0.5、步长 0.1 的浮点输入，数据包模板在输出时统一执行除以 100 的换算，将百分比转换为原生的 0.0～1.0 概率。理解这一层换算关系，是精确控制自定义群系环境粒子密度的关键，也是阅读 MCreator 生成模板源码时最容易建立联动的知识点。