blockbench-particles

Blockbench 粒子

Blockbench 只有一种粒子系统：Bedrock 粒子效果，也就是 Snowstorm 编辑的 JSON 格式。当动画的 Effects 轨道上的粒子关键帧触发时，Blockbench 会使用 Wintersky 预览这些效果，也可以选择将效果放在骨骼上的定位器处。同一文件也可在 Minecraft Bedrock 中运行，而 GeckoLib 动画会将相同的关键帧传递给模组的粒子处理器。Blockbench 中的其他格式（glTF、OBJ、Java 方块模型、Hytale）均不会导出粒子。

请先加载 blockbench-use。粒子依附于动画，因此如果模型还没有动画片段，请加载 blockbench-animation。

1. 确定效果的承载方式

如果尚不清楚目标位置，请先询问，因为这会决定以下所有内容。

目标位置	粒子	效果所在位置
Bedrock 实体或可穿戴物（bedrock）	原生	粒子 JSON + 几何体中的定位器 + 动画 JSON 或控制器状态中的关键帧 + 客户端实体中的 particle_effects 映射。请参阅交付方式。
GeckoLib（geckolib_model）	仅关键帧	（效果、定位器、脚本）关键帧会导出到动画 JSON；模组的粒子关键帧处理器负责生成实际粒子。此处的 Bedrock JSON 仅用于 Blockbench 预览。
通用模型 / glTF、Java 方块/物品、Hytale、OBJ	无	使用几何体、自发光序列帧纹理和骨骼关键帧模拟效果，或交由运行时处理。请参阅不支持粒子的目标。

开始制作前还要确定触发方式，因为 Bedrock 对两者的处理方式不同：

• 动画关键帧（manage_particle_keyframes）：触发后不再管理。适合一次性效果（撞击火花、落地时的烟雾、爱心）。通过这种方式触发的循环发射器在游戏中永远不会停止；循环动画片段每循环一次，就会再次启动一个发射器。对于循环动画片段上的持续效果，请使用 looping: false，并将 duration 设为与动画片段等长，关键帧设在 0。
• 动画控制器状态：游戏会在进入状态时启动发射器，并在退出状态时将其结束。持续循环效果（燃烧状态、施法状态）应使用此方式。MCP 工具不会编辑控制器；请在 Blockbench 的 Animation Controllers 面板或控制器 JSON 中添加条目（交付方式）。

如果循环效果设在关键帧上，工具会发出警告。

2. 工具

桌面插件（打开 Blockbench）：

工具	用途
list_particle_presets	预设、内置精灵图和纹理、材质、朝向模式。设计前先阅读。
create_particle_effect	预设 + 设计参数（或原始 JSON）→ <pack_root>/particles/<name>.json，并进行验证、加载到预览中。可选使用 Blockbench 纹理或 PNG 作为自定义纹理。
update_particle_effect	更改现有文件的参数（只重写每个参数所属的组件）、替换为原始 JSON，或从磁盘加载文件。
add_locator	骨骼上的命名点，效果会在此生成并跟随骨骼。支持定位器的格式：Bedrock Entity、GeckoLib、Generic Model。
manage_particle_keyframes	在动画上添加、移除或列出粒子关键帧。验证定位器和时间。
list_particle_effects	已加载的效果、使用情况、预览问题、关键帧上的循环警告以及客户端实体映射。
export_particle_pack	将使用到的效果和自定义纹理复制到资源包；返回 particle_effects 映射。
animation_timeline set_time、capture_screenshot	预览。

无头服务端（仅处理文件，可供并行 Agent 使用）：bbmodel_particle_effect（在模型旁创建或更新文件）、bbmodel_edit 操作 add_locator、set_particle_keyframe、remove_particle_keyframe，以及 bbmodel_particle_pack。关键帧 file 路径相对于 .bbmodel（particles/smoke.json）；提供 model 时，bbmodel_particle_effect 会在 keyframe_file 中返回正确的值。无头模式无法渲染粒子；请在 Blockbench 中打开模型进行预览。

3. 工作流

1. 规划效果。 写下效果所表达的内容、生成位置、持续时间、峰值时的存活粒子数量，以及效果是持续型还是一次性。阅读效果设计，了解尺寸、时间、颜色和预算规则。
2. 在生成点放置定位器：烟囱顶部、嘴部、剑尖、车轮接触点等。将它们设为应携带效果的骨骼的子级。位置使用模型绝对单位（每个方块为 16 单位）。

   add_locator: name="mouth", parent="head", position=[0, 26, -7]
   

3. 创建效果，从最接近的预设开始并调整参数。单位为方块和秒。

   create_particle_effect: identifier="mymod:dragon_smoke", preset="smoke",
     design={rate: 10, size: [0.3, 0.9], color: ["#6b5b53cc", "#3a3a3a"], looping: false, duration: 2}
   

   使用自己的命名空间，切勿使用 minecraft:。如需自定义精灵图，请先绘制或生成一张小型 PNG（8-32 px，透明背景），并传入 texture_image；精灵图集使用 design.flipbook（默认竖向条带，类似 翻页纹理）。
4. 设置关键帧。 循环片段上的持续效果：在 0 处设置一个关键帧，使用 looping: false，并将 duration 设为片段长度变体。一次性效果：在接触帧设置关键帧。

   manage_particle_keyframes: animation_id=<clip uuid>, action="add",
     keyframes=[{time: 0, effect: "mymod:dragon_smoke", locator: "mouth"}]
   

   阅读所有返回的警告；修复它们，而不是只报告问题。
5. 预览：在 Animate 模式中，先运行 animation_timeline set_time 将时间设为 0，再设为两个或三个时刻（早期、峰值、后期），并分别截图。编辑效果后，先回到 0，让发射器以新设置重新启动。在预期的摄像机距离下检查效果是否清晰易辨，而不只是近距离查看。
6. 验证：使用 list_particle_effects，确保没有问题、没有棋盘格纹理，且数量合理。
7. 交付：按照交付说明，使用 export_particle_pack 导出到资源包，将返回的 client_entity.particle_effects 粘贴到客户端实体中，导出动画 JSON，并保存 .bbmodel。报告写入的文件，以及留给用户完成的步骤（客户端实体编辑、控制器状态、游戏内检查）。

4. 避免效果出错的规则

• 以方块为单位，而非像素。 粒子大小、速度、偏移量和形状半径均以方块为单位；定位器和模型坐标以像素为单位（每个方块 16 像素）。Billboard 的 size 表示半宽：0.1 是原版烟雾粒子（宽 0.2 个方块），0.5 则横跨整个方块。
• 材质决定淡出方式。 particles_alpha 会截断部分透明度，因此 Alpha 渐变会显得突兀。烟雾和柔和形状使用 particles_blend，光效（火焰、魔法、火花、辉光）使用 particles_add。
• 白色能保留精灵颜色。 色调会与精灵颜色相乘。彩色精灵（火焰、爱心、气泡、灵魂、火）应使用白色色调或不设置色调。
• 控制存活粒子数量： 生成速率 × 生命周期。环境循环效果保持在约 50 个以下，繁忙效果保持在 100 个以下；切勿让 max_particles 在稳定发射器运行时限制粒子数量（验证器会报告此问题）。
• 局部空间与世界空间： local_space: true 会让粒子随骨骼移动（光环、圆环、环绕的微粒）。烟雾、轨迹和尾气应关闭此选项，使它们在模型移动时留在原处。关键帧中的 bind_to_actor: false 会让整个发射器留在生成位置。
• 预览效果不等于游戏内效果。 Blockbench 没有方块可用于碰撞，并且只会近似模拟光照；它还会每隔 duration 秒重新启动循环发射器（因此预设使用 10 s）。尽可能在游戏中验证碰撞、光照和 entity_aabb 形状；无法验证时请说明。
• 名称必须能解析。 关键帧使用效果名称；客户端实体会将名称映射为标识符。export_particle_pack 会报告名称冲突、缺失纹理以及没有文件的关键帧。

参考资料

• 效果设计：规划、预设、配方、颜色、时序、数量预算、Molang 模式、自定义精灵。
• Bedrock 粒子格式：组件速查表、原始 JSON 骨架、事件和曲线，适用于无法通过参数表达的效果。
• 交付：Bedrock 资源包接入、控制器状态、可附加对象、GeckoLib 处理程序，以及不支持粒子的目标对象的替代方案。
• 主要来源：粒子实体集成（Microsoft）、Bedrock 粒子文档、用于手动编辑的 Snowstorm，以及 Mojang 的原版粒子文件，可作为示例。