FreeMinecraftModels 粒子
FreeMinecraftModels 会播放模型 Blockbench 动画中的粒子关键帧，适用于自定义实体、道具和手持物品。Java 版玩家看到的粒子是由 FMM 在服务器上模拟、仅存在于数据包中的贴图。基岩版玩家则会获得原始的 Snowstorm 效果，由他们自己的客户端绘制。
动画名称和播放规则请参阅动画。定位器以及导入约定的其余部分请参阅模型制作说明。
在 Blockbench 中制作
- 在 Blockbench 的粒子编辑器（Snowstorm）中制作效果，并将其保存为
.json粒子文件。 - 在模型上效果应当发出的位置添加一个定位器。位于骨骼内的定位器会随该骨骼的动画移动，因此放在旋转手臂上的定位器会沿着手臂的轨迹留下拖尾。
- 在动画中打开 Effects（效果）动画器，添加一个粒子关键帧。设置效果名称、定位器和粒子文件。可选的脚本字段会在效果开始前作为 Molang 运行，例如
v.size = 2;。 - 把粒子文件及其纹理 PNG 放在
.bbmodel旁边（或其旁边的particles/文件夹中），并与模型一起分发。
没有定位器的关键帧会在模型原点播放。指定了模型中不存在的定位器的关键帧同样会在原点播放，并记录一条警告。
FMM 如何查找粒子文件
Blockbench 只会保存作者本地的粒子文件路径，因此 FMM 按文件名查找。对于每个效果，FMM 会按以下顺序尝试，先在模型所在文件夹中查找，再在其旁边的 particles/ 文件夹中查找：
- 关键帧中保存的文件名
<effect>.particle.json<effect>.json
不是粒子文件的 .json（例如与效果同名的显示模型）会被跳过。如果什么都没找到，控制台会显示 Particle effect '<effect>' used by animation '<animation>' in <model> was not found，这些关键帧会被丢弃，模型的其余部分照常加载。
纹理
粒子文件的 basic_render_parameters.texture 按路径的最后一段进行匹配：textures/particle/spark 表示 FMM 会查找 spark.png，依次在粒子文件旁边、模型旁边以及模型的 particles/ 文件夹中查找。
如果缺少 PNG，Java 版玩家会看到按效果颜色着色的纯白贴图，控制台也会发出警告。基岩版保留原始纹理路径，因此像 textures/blocks/wool_colored_white 这样的原版基岩版纹理在那里依然有效。若要在 Java 版上获得相同的外观，请以匹配的名称附带一张 PNG。
效果何时播放
- 当动画播放到关键帧时，效果开始。在循环动画中，关键帧会在每次循环时再次触发，其发射器也会重新开始。
- 动画停止或切换时，循环发射器会停止生成粒子。已经在空中的粒子会走完各自的生命周期。
- 当没有任何 Java 版玩家能看到模型时，发射器会暂停。
filmicMode会让每个已加载的模型保持可见，因此它们的粒子也会持续运行。 - 移除模型时，会立即移除其发射器和所有粒子贴图。这包括死亡、消失、区块卸载以及
/fmm deleteall。
道具
道具自身只会播放 idle。请把粒子关键帧放进 idle，或者从道具 Lua 脚本中播放包含粒子关键帧的动画：
context.prop:play_animation("sparkle", true, true)
手持物品
粒子也会在 FMM 自定义物品上播放，即通过 /fmm giveitem 或管理员菜单给予的物品。物品的模型必须带有粒子关键帧。FMM 会读取其显示模型（同名的 .json）中的 thirdperson_righthand 和 thirdperson_lefthand 变换，以确定物品在手中的位置。没有显示模型时，Java 版会按物品没有显示变换的情况放置粒子，而基岩版则不会有手持物品粒子。
- 物品位于任意一只手中时，FMM 会循环播放模型的
held动画。如果没有带粒子关键帧的held动画，则按名称顺序使用第一个带有粒子关键帧的动画。 - 手持物品上的骨骼不会播放动画。定位器在物品上保持其静止位置。
- **Java 版：**服务器无法知道玩家处于第一人称、第三人称还是前置视角。FMM 会根据持有者的身体朝向、是否潜行、持握物品的手、其
scale属性以及显示模型的变换，把粒子放在第三人称姿势下物品的尖端。包括持有者在内的每位 Java 版玩家都会在这同一个位置看到粒子。在第一人称下，持有者会在其第三人称手部所在的位置看到粒子，而不是在第一人称的物品上。挥臂和物品使用姿势不会被追踪，因此在手臂移动时粒子可能会略微落后于物品。距离持有者 48 格以内的 Java 版玩家能看到这些粒子。 - **基岩版：**粒子会被添加到物品的基岩版 attachable 中，基岩版客户端会在所有视角下把它们绘制在真实的手上。这需要 ResourcePackManager 的基岩版转换。
Java 版渲染
- 每个粒子都是一个
item_display数据包实体。它从不真正存在于世界中，因此其他插件无法击中、保存或移除它。 - FMM 每 2 tick 移动一次粒子，客户端会平滑其间的运动。
- UV 表达式在加载时被采样为每个效果最多 16 种纹理变体，每种变体的每一帧翻页动画都会成为一张独立的贴图。这些贴图会放入资源包的
assets/freeminecraftmodels/items/particle/<model>/<effect>/下，其纹理位于textures/entity/fmm_particles/<model>/<effect>.png。FMM 还会写入assets/freeminecraftmodels/rspm_item_java_only/particle/<model>/<effect>.json，告知 ResourcePackManager 不要把这些贴图物品转换为基岩版自定义物品。 - 除非效果带有
minecraft:particle_appearance_lighting，否则粒子以全亮度渲染。 - 单个模型上的单个效果最多显示
maxParticlesPerEmitter个粒子；若文件自身的max_particles更低，则以其为准。单个 Java 版玩家在所有模型上最多看到maxParticlesPerViewer个粒子。超过上限后，该玩家的新粒子会被跳过，直到旧粒子消失。 particleEffectsEnabled: false可以在不编辑模型的情况下关闭所有效果。
Java 版支持的组件
| 组件 | Java 版支持情况 |
|---|---|
emitter_rate_instant、emitter_rate_steady | 完全支持 |
emitter_lifetime_once、emitter_lifetime_looping、emitter_lifetime_expression | 完全支持 |
emitter_initialization | 创建表达式和每次更新表达式 |
emitter_local_space | 位置和旋转 |
emitter_shape_point、_sphere、_box、_disc、_custom | 偏移、半径、半尺寸、平面法线、surface_only，以及 outwards、inwards 或自定义方向 |
particle_initialization | 每次更新表达式和每次渲染表达式 |
particle_initial_speed、particle_initial_spin | 完全支持 |
particle_motion_dynamic | 线性加速度与阻力、旋转加速度与阻力 |
particle_lifetime_expression | max_lifetime 和 expiration_expression |
particle_appearance_billboard | 尺寸、朝向模式、方向和 UV，包括翻页动画 |
particle_appearance_tinting | 固定颜色、按通道的表达式和渐变 |
particle_appearance_lighting | 关闭默认的全亮度 |
其他组件在 Java 版上会被忽略，例如 particle_motion_parametric、particle_motion_collision、emitter_rate_manual 和 emitter_shape_entity_aabb。模型加载时，控制台会按名称列出它们。基岩版玩家仍能看到完整的效果。
朝向模式映射为展示实体的 billboard。rotate_xyz、lookat_xyz 和 lookat_direction 会面向镜头。rotate_y 和 lookat_y 只绕竖直轴旋转。direction_x、direction_y、direction_z 以及 emitter_transform_* 模式会根据粒子的方向或发射器的旋转保持固定朝向。
Molang
表达式支持算术运算、比较、?:、??、赋值和 return。数学函数：
abs、acos、asin、atan、atan2、ceil、clamp、cos、die_roll、die_roll_integer、exp、floor、hermite_blend、lerp、lerprotate、ln、max、min、mod、pow、random、random_integer、round、sin、sqrt、trunc，以及常量 math.pi。
与基岩版一样，三角函数使用角度制。内置变量：
variable.particle_age、variable.particle_lifetime、variable.particle_random_1到_4variable.emitter_age、variable.emitter_lifetime、variable.emitter_random_1到_4
你在初始化表达式和关键帧脚本中定义的 v. 变量都可以使用，曲线（linear、catmull_rom、bezier、bezier_chain）也同样可用。未知的变量和查询读取为 0。
基岩版
启用 sendCustomModelsToBedrockClientsV2 后，基岩版资源包会以 particles/<model>_<effect>.json 的形式携带每个效果，标识符为 fmm:<model>_<effect>。它还会携带粒子纹理、几何体骨骼上的定位器以及基岩版动画中的粒子关键帧。随后，基岩版客户端会原生播放这些效果，包括 Java 版跳过的组件。
对于手持物品，FMM 会在其 Java 版输出中写入 assets/freeminecraftmodels/rspm_item_particles/display/<item>.json。ResourcePackManager 在转换该物品时会读取它，并把定位器和一个循环播放的粒子动画添加到物品的 attachable 中。
故障排除
Particle effect '<effect>' ... was not found。
FMM 找不到粒子文件。请把它以 <effect>.json 或 <effect>.particle.json 的名称放在模型旁边，或使用关键帧中保存的文件名。参见 FMM 如何查找粒子文件。
... uses <components>, which Java players do not see yet。
这只是提示信息。Java 版会播放该效果中的其余所有内容，基岩版则会播放全部内容。
... uses texture '<path>', which is not next to <file>。
请把纹理 PNG 放在粒子文件旁边，并以该路径的最后一段命名。
... follows locator '<name>', which the model does not have。
该定位器已被重命名或删除。在关键帧指定一个存在的定位器之前，该效果会在模型原点播放。
我的道具的粒子始终不出现。
道具自身只会播放 idle。请把关键帧移到 idle 中，或者从脚本中播放该动画。
在第一人称下，我的手持物品的粒子飘离了物品。 这在 Java 版上是预期行为。服务器会把粒子放在第三人称手部的位置。其他玩家以及第三人称视角会看到粒子位于物品上。
我的手持物品不显示任何粒子。
该物品必须是 FMM 自定义物品（带有 fmm_item_id），并且其模型的某个动画中必须有粒子关键帧，且 FMM 能找到这些关键帧对应的文件。