---
title: "Particles explosions and visual effects"
description: "A torch needs fire, a hit needs sparks, an explosion needs a burst. Particles are a real component (`ParticleEmitterComponent`, pack `rendering.v1`), richly AI-authorable. Surface marks use `DecalComponent`; attention outlines use `HighlightComponent`. Note the `FxHost` particle-burst call is a bare SDK surface, not a capability-pack host; drive particles through the component."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/knowledge/playbooks/particles-and-visual-effects/
---

# Particles explosions and visual effects

## When to use

A torch needs fire, a hit needs sparks, an explosion needs a burst. Particles are
a real component (`ParticleEmitterComponent`, pack `rendering.v1`), richly
AI-authorable. Surface marks use `DecalComponent`; attention outlines use
`HighlightComponent`. Note the `FxHost` particle-burst call is a bare SDK
surface, not a capability-pack host; drive particles through the component.

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