Particles explosions and visual effects

The recipe

Author component values with project_add_component, and drive them at runtime with ctx.entity.patchComponent in a script.

1. Continuous emitter (fire, smoke, a trail): project_add_component a ParticleEmitterComponent with emissionMode continuous (the default). Tune emissionRate, lifetimeSeconds, particleSize (with optional startSize/endSize), startColor and endColor for the ramp, gravity, and shape.type (point, sphere, box, cone, disc, edge). Pick blendMode additive for fire and sparks, alpha for smoke.
2. One-shot burst (explosion, impact): set emissionMode burst and burstCount (particles per puff, up to 512). The emitter emits the whole burst once at birth, the particles live one lifetimeSeconds, then it idles (no loop, no re-emit). To re-fire the same emitter for a repeated hit, patch enabled false then true. This is native now, so a burst no longer needs a spawn-then-despawn dance; the Poof (burst) variant is a ready-made preset.
3. Attach to motion: because particles simulate in the entity's LOCAL space, parent the emitter under the moving object (a rocket trail follows the rocket) with ctx.entity.setParent.
4. Surface marks: add a DecalComponent (blendMode blend/multiply/add, set color and opacity) at the impact point for a scorch or paint splat.
5. Outline for attention: toggle a HighlightComponent (enabled, color, depthMode occluded or xray) on an interactable or a target.

Pitfalls

• Choose the emission mode deliberately: continuous streams and loops (fire, smoke, trails); burst fires burstCount particles once and stops (explosions, impacts). A continuous emitter with emissionRate 0 shows nothing; use burst for a one-shot, not a zero rate.
• Particles are LOCAL space and move with the entity; a world-anchored effect needs its own unparented entity at the world position.
• maxParticles and emissionRate are budgeted; the default maxParticles is 64. Large sustained emitters are costly, so size them to the effect.
• Only enabled highlights count against the per-tier highlight budget; turn outlines off when not needed.
• Particles are a look, not a hitbox; damage or collision still needs a collider and script (see hazards-water-and-damage-zones).

Verify

• qa_capture_renderer_viewport (qa.renderer.viewport.capture) to see the effect render, and simulation_run to confirm a scripted burst enables and clears.
• project_get_graph_snapshot to confirm the ParticleEmitterComponent and any DecalComponent or HighlightComponent landed.