blockbench-particles

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Blockbench Particles

Blockbench 粒子效果

Blockbench has one particle system: Bedrock particle effects, the JSON format Snowstorm edits. Blockbench previews them with Wintersky when a particle keyframe on an animation's Effects track fires, optionally at a locator on a bone. The same files run in Minecraft Bedrock, and GeckoLib animations carry the same keyframes to a mod's particle handler. Nothing else in Blockbench (glTF, OBJ, Java block models, Hytale) exports particles.

Load blockbench-use first. Particles ride on animations, so load blockbench-animation when the model has no clip yet.

Blockbench 只有一种 particle system：Bedrock particle effects，即由 Snowstorm 编辑的 JSON 格式。当动画 Effects 轨道上的 particle keyframe 触发时，Blockbench 会使用 Wintersky 预览它们，也可以选择将生成位置设在骨骼的 locator 上。相同的文件可在 Minecraft Bedrock 中运行，GeckoLib animation 也会将相同的 keyframe 传递给 mod 的 particle handler。Blockbench 中的其他格式（glTF、OBJ、Java block model、Hytale）都无法导出 particle。

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

1. Decide What Carries the Effect

1. 确定由什么承载效果

Ask for the destination if it is unknown; it decides everything below.

Destination	Particles	Where the effect lives
Bedrock entity or attachable ( `bedrock` )	Native	Particle JSON + locators in geometry + keyframes in animation JSON or controller states + `particle_effects` map in the client entity. See delivery.
GeckoLib ( `geckolib_model` )	Keyframes only	Keyframes (effect, locator, script) export in the animation JSON; the mod's particle keyframe handler spawns real particles. Bedrock JSON here is only the Blockbench preview.
Generic Model / glTF, Java block/item, Hytale, OBJ	None	Fake the effect with geometry, emissive flipbook textures and bone keyframes, or leave it to the runtime. See non-particle targets.

Also settle the trigger before building, because Bedrock treats the two differently:

Animation keyframe (
```
manage_particle_keyframes
```
): fire-and-forget. Good for one-shots (impact sparks, a poof on landing, hearts). A looping emitter fired this way never stops in game, and a looping clip starts another one every cycle. For a continuous effect keyed on a looping clip, use
```
looping: false
```
with
```
duration
```
equal to the clip length, keyed at 0.
Animation controller state: the game starts the emitters on state entry and ends them on exit. This is the right home for sustained loops (a burning state, a casting state). The MCP tools do not edit controllers; add the entry in Blockbench's Animation Controllers panel or in the controller JSON (delivery).

The tools warn when a looping effect lands on a keyframe.

如果尚不清楚目标平台，请先询问；目标平台决定以下所有选择。

目标平台	Particle 支持	效果所在位置
Bedrock entity 或 attachable（ `bedrock` ）	原生支持	Particle JSON + geometry 中的 locator + animation JSON 或 controller state 中的 keyframe + client entity 中的 `particle_effects` 映射。参见 delivery。
GeckoLib（ `geckolib_model` ）	仅 keyframe	Keyframe（effect、locator、script）会导出到 animation JSON；mod 的 particle keyframe handler 负责生成真实 particle。此处的 Bedrock JSON 只用于 Blockbench preview。
Generic Model / glTF、Java block/item、Hytale、OBJ	不支持	使用 geometry、emissive flipbook texture 和 bone keyframe 模拟效果，或将其留给 runtime 处理。参见 non-particle targets。

构建前还要确定 trigger，因为 Bedrock 对以下两种方式的处理不同：

Animation keyframe（
```
manage_particle_keyframes
```
）：触发即执行（fire-and-forget）。适合一次性效果（撞击火花、落地时的一团烟、爱心）。以此方式触发的 looping emitter 在游戏中永远不会停止，而 looping clip 每完成一个 cycle 都会再启动一个。若要在 looping clip 上设置持续效果，请使用
```
looping: false
```
，将
```
duration
```
设为 clip 长度，并在 0 处设置 keyframe。
Animation controller state：游戏在进入 state 时启动 emitter，在退出 state 时结束它们。持续循环效果应使用此方式。MCP 工具无法编辑 controller；请在 Blockbench 的 Animation Controllers 面板或 controller JSON 中添加 entry（delivery）。

当 looping effect 绑定到 keyframe 时，工具会发出警告。

2. Tools

2. 工具

Desktop plugin (Blockbench open):

Tool	Use
`list_particle_presets`	Presets, built-in sprites and textures, materials, facing modes. Read before designing.
`create_particle_effect`	Preset + design knobs (or raw JSON) → `<pack_root>/particles/<name>.json` , validated and loaded into the preview. Optional custom texture from a Blockbench texture or PNG.
`update_particle_effect`	Change knobs on an existing file (only the components each knob owns are rewritten), replace it with raw JSON, or load a file from disk.
`add_locator`	Named point on a bone that effects spawn at and follow. Formats with locators: Bedrock Entity, GeckoLib, Generic Model.
`manage_particle_keyframes`	Add, remove or list particle keyframes on an animation. Validates locators and times.
`list_particle_effects`	Loaded effects, usages, preview problems, looping-on-keyframe warnings and the client-entity map.
`export_particle_pack`	Copy used effects and custom textures into a resource pack; returns the `particle_effects` map.
`animation_timeline` `set_time` , `capture_screenshot`	Preview.

Headless server (files only, parallel agents):

bbmodel_particle_effect

(create/update a file next to the model),

bbmodel_edit

operations

add_locator

set_particle_keyframe

remove_particle_keyframe

, and

bbmodel_particle_pack

. Keyframe

file

paths are relative to the

.bbmodel

(

particles/smoke.json

);

bbmodel_particle_effect

returns the right value as

keyframe_file

when given

model

. Headless cannot render particles; open the model in Blockbench to preview.

桌面 plugin（Blockbench 已打开）：

工具	用途
`list_particle_presets`	Preset、内置 sprite 和 texture、material、facing mode。设计前先阅读。
`create_particle_effect`	使用 preset + design knob（或 raw JSON）创建 `<pack_root>/particles/<name>.json` ，完成验证并加载到 preview。可选 custom texture 可来自 Blockbench texture 或 PNG。
`update_particle_effect`	修改现有文件上的 knob（仅重写各 knob 所拥有的 component），使用 raw JSON 替换文件，或从磁盘加载文件。
`add_locator`	骨骼上的命名点，供 effect 在此生成并跟随。支持 locator 的格式：Bedrock Entity、GeckoLib、Generic Model。
`manage_particle_keyframes`	在 animation 上添加、删除或列出 particle keyframe。验证 locator 和时间。
`list_particle_effects`	已加载的 effect、使用情况、preview problem、looping-on-keyframe 警告和 client-entity 映射。
`export_particle_pack`	将已使用的 effect 和 custom texture 复制到 resource pack；返回 `particle_effects` 映射。
`animation_timeline` `set_time` 、 `capture_screenshot`	Preview。

无头 server（仅文件操作，面向并行 Agent）：

bbmodel_particle_effect

（在 model 旁创建或更新文件）、

bbmodel_edit

操作

add_locator

、

set_particle_keyframe

、

remove_particle_keyframe

，以及

bbmodel_particle_pack

。Keyframe 的

file

路径相对于

.bbmodel

（

particles/smoke.json

）；传入

model

时，

bbmodel_particle_effect

会返回适合用作

keyframe_file

的值。Headless 模式无法渲染 particle；请在 Blockbench 中打开 model 进行 preview。

3. Workflow

3. 工作流

Plan the effect. Write down what it communicates, where it spawns, how long it lasts, how many particles are alive at peak, and whether it is continuous or one-shot. Read effect design for scale, timing, color and budget rules.
Place locators at the spawn points: a chimney top, a mouth, a sword tip, a wheel's contact point. Parent them to the bone that should carry the effect. Positions are absolute model units (16 per block).
```
add_locator: name="mouth", parent="head", position=[0, 26, -7]
```
Create the effect from the closest preset and adjust knobs. Units are blocks and seconds.
```
create_particle_effect: identifier="mymod:dragon_smoke", preset="smoke",
  design={rate: 10, size: [0.3, 0.9], color: ["#6b5b53cc", "#3a3a3a"], looping: false, duration: 2}
```
Use your own namespace, never
```
minecraft:
```
. For a custom sprite, paint or generate a small PNG first (8-32 px, transparent background) and pass
```
texture_image
```
; sprite sheets use
```
design.flipbook
```
(vertical strips by default, like flipbook textures).
Key it. Continuous effect on a looping clip: one keyframe at 0 with the
```
looping: false
```
,
```
duration
```
= clip length variant. One-shot: a keyframe on the contact frame.
```
manage_particle_keyframes: animation_id=<clip uuid>, action="add",
  keyframes=[{time: 0, effect: "mymod:dragon_smoke", locator: "mouth"}]
```
Read every returned warning; fix them rather than reporting them.
Preview in Animate mode:
```
animation_timeline set_time
```
to 0, then to two or three moments (early, peak, late), capturing each. After editing an effect, go back to 0 first so emitters restart with the new settings. Check readability at the intended camera distance, not only close up.
Validate with
```
list_particle_effects
```
: no problems, no checkerboard textures, sensible counts.
Deliver per delivery:
```
export_particle_pack
```
to the resource pack, paste the returned
```
client_entity.particle_effects
```
into the client entity, export the animation JSON, and save the
```
.bbmodel
```
. Report the files written and any step left to the user (client entity edits, controller states, in-game check).

规划效果。 写明效果要传达的信息、生成位置、持续时间、峰值存活 particle 数量，以及它是持续效果还是一次性效果。阅读 effect design，了解缩放、时序、颜色和预算规则。
放置 locator。 将 locator 放在生成点：烟囱顶部、嘴部、剑尖、车轮接触点。将它们 parent 到应承载效果的骨骼。位置采用绝对 model 单位（每个 block 为 16 个单位）。
```
add_locator: name="mouth", parent="head", position=[0, 26, -7]
```
创建效果。 从最接近的 preset 创建效果并调整 knob。单位为 block 和秒。
```
create_particle_effect: identifier="mymod:dragon_smoke", preset="smoke",
  design={rate: 10, size: [0.3, 0.9], color: ["#6b5b53cc", "#3a3a3a"], looping: false, duration: 2}
```
使用自己的 namespace，绝不要使用
```
minecraft:
```
。如需 custom sprite，请先绘制或生成一张小型 PNG（8–32 px，透明背景），然后传入
```
texture_image
```
；sprite sheet 使用
```
design.flipbook
```
（默认是垂直条带，与 flipbook textures 类似）。
为其设置 keyframe。 在 looping clip 上设置持续效果时：在 0 处添加一个 keyframe，并使用
```
looping: false
```
、
```
duration
```
等于 clip 长度的变体。一次性效果：在接触帧上设置 keyframe。
```
manage_particle_keyframes: animation_id=<clip uuid>, action="add",
  keyframes=[{time: 0, effect: "mymod:dragon_smoke", locator: "mouth"}]
```
读取返回的每条警告；应修复警告，而不是仅作报告。
在 Animate 模式中 preview： 使用
```
animation_timeline set_time
```
移到 0，再移到两三个时间点（早期、高峰、后期），并在每个时间点截取画面。编辑效果后，先回到 0，让 emitter 使用新设置重新启动。检查预期 camera distance 下的可读性，而不要只看近距离效果。
使用
list_particle_effects
验证：不应存在问题、棋盘格 texture 或不合理的数量。
按照 delivery 交付： 使用
```
export_particle_pack
```
导出到 resource pack，将返回的
```
client_entity.particle_effects
```
粘贴到 client entity 中，导出 animation JSON，并保存
```
.bbmodel
```
。报告已写入的文件以及仍需用户完成的任何步骤（client entity 编辑、controller state、游戏内检查）。

4. Rules That Prevent Broken Effects

4. 防止效果损坏的规则

Blocks, not pixels. Particle sizes, speeds, offsets and shape radii are in blocks; locators and model coordinates are in pixels (16 per block). Billboard
```
size
```
is a half-width: 0.1 is a vanilla smoke puff (0.2 blocks across) and 0.5 spans a whole block.
Material decides fades.
```
particles_alpha
```
cuts off partial transparency, so alpha gradients pop. Use
```
particles_blend
```
for smoke and soft shapes and
```
particles_add
```
for light (fire, magic, sparks, glow).
White keeps sprite colors. Tints multiply. Colored sprites (flame, heart, bubble, soul, fire) want white or no tint.
Budget live particles: rate × lifetime. Keep ambient loops under about 50, busy effects under 100, and never let
```
max_particles
```
cap a steady emitter mid-effect (the validator reports it).
Local space vs world space:
```
local_space: true
```
makes particles move with the bone (auras, rings, orbiting motes). Leave it off for smoke, trails and exhaust so they stay behind as the model moves.
```
bind_to_actor: false
```
on a keyframe leaves the whole emitter where it spawned.
The preview is not the game. Blockbench has no blocks to collide with and approximates lighting, and it restarts looping emitters every
```
duration
```
seconds (presets use 10 s for that reason). Verify collisions, lighting and
```
entity_aabb
```
shapes in game when possible and say so when not.
Names must resolve. Keyframes use effect names; the client entity maps names to identifiers.
```
export_particle_pack
```
reports name conflicts, missing textures and keyframes without files.

使用 block，而不是 pixel。 Particle 大小、速度、偏移和形状半径都以 block 为单位；locator 和 model 坐标以 pixel 为单位（每个 block 为 16 个单位）。Billboard 的
```
size
```
表示半宽：0.1 是原版烟雾团（横跨 0.2 个 block），0.5 则横跨整个 block。
Material 决定淡化方式。
```
particles_alpha
```
会截断部分透明区域，因此 alpha 渐变会显得突兀。烟雾和柔和形状使用
```
particles_blend
```
，火焰、魔法、火花、辉光等发光效果使用
```
particles_add
```
。
白色会保留 sprite 颜色。 Tint 采用乘法混合。flame、heart、bubble、soul、fire 等彩色 sprite 应使用白色或不使用 tint。
为活跃 particle 设置预算： rate × lifetime。环境循环效果应控制在约 50 以下，繁忙效果应控制在 100 以下，并且绝不能让
```
max_particles
```
在效果中途限制稳定 emitter（validator 会报告此问题）。
Local space 与 world space：
```
local_space: true
```
会让 particle 随骨骼移动（光环、圆环、环绕光点）。烟雾、trail 和 exhaust 应关闭此选项，使 particle 在 model 移动后仍留在原处。Keyframe 上的
```
bind_to_actor: false
```
会让整个 emitter 留在生成位置。
Preview 不等于游戏。 Blockbench 没有可供碰撞的 block，且仅近似模拟光照；它每隔
```
duration
```
秒重启 looping emitter（因此 preset 使用 10 秒）。如有可能，请在游戏中验证碰撞、光照和
```
entity_aabb
```
形状；若无法验证，应明确说明。
名称必须能够解析。 Keyframe 使用 effect 名称；client entity 将名称映射到 identifier。
```
export_particle_pack
```
会报告名称冲突、缺失的 texture，以及没有对应文件的关键帧。

References

参考资料

Effect design: planning, presets, recipes, color, timing, budgets, Molang patterns, custom sprites.
Bedrock particle format: component cheat sheet, raw JSON skeleton, events and curves, for effects the knobs cannot express.
Delivery: Bedrock resource pack wiring, controller states, attachables, GeckoLib handlers, and substitutes for targets without particles.
Primary sources: Particle entity integration (Microsoft), Bedrock particle documentation, Snowstorm for hand editing, and Mojang's vanilla particle files as worked examples.

Effect design：规划、preset、配方、颜色、时序、预算、Molang 模式和 custom sprite。
Bedrock particle format：component 速查表、raw JSON 骨架、event 和 curve，用于实现 design knob 无法表达的效果。
Delivery：Bedrock resource pack 接线、controller state、attachable、GeckoLib handler，以及不支持 particle 的 target 的替代方案。
主要来源：Particle entity integration (Microsoft)、Bedrock particle documentation、用于手动编辑的 Snowstorm，以及作为完整示例的 Mojang vanilla particle files。