Blockbench Particles

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.

1. Decide What Carries the Effect

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

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.

2. Tools

Desktop plugin (Blockbench open):

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.

3. Workflow

1. 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.
2. 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]
   

   Copy
3. 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}
   

   Copy
   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).
4. 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"}]
   

   Copy
   Read every returned warning; fix them rather than reporting them.
5. 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.
6. Validate with list_particle_effects: no problems, no checkerboard textures, sensible counts.
7. 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).

4. Rules That Prevent Broken Effects

• 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.

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.