# particles

> Talos 0.7 · Since 0.6; changed in 0.7

Use it in a scene entity's `components` list as `{ "type": "particles", … }`. The contract writes the fields flat and refuses unknown keys.

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `preset` | `ParticlePreset` | no |  | `smoke`, `fire`, `sparks`, `dust`, `steam`, `drips`, `debris`, `glow` | One of the eight built-in looks. Exactly one of `preset` and `effect` is required (particles-source). With a preset, `rate` is the particles per second. |
| `rate` | `number` | no |  |  | Particles per second of a `preset`. Ignored with an `effect` (the effect's own spawn rules apply). |
| `color` | `string` | no |  |  |  |
| `material` | `string` | no |  |  | A key of scene.assets whose kind is "material": a material file with a `shader` (`blend: add` or `blend: blend`) the sprites draw with instead of the built-in sprite. The shader reads `particleAge`, `particleRandom` and `particleColor` from its SurfaceInput. On HD such an emitter is simulated on the CPU so its shader can draw it; emitters without one stay GPU-simulated. Not supported together with `effect` yet (particles-source). |
| `effect` | `string` | no |  |  | A particle effect (docs/VFX.md): a key of scene.assets whose kind is "effect" (a `*.vfx.json` file), a project-relative `*.vfx.json` path, "builtin:<preset>" (smoke, fire, sparks, dust, steam, drips, debris, glow) or "builtin:fx/<preset>" (sparks, flame, dust, puff-burst, hit, confetti, speed-lines; docs/VFX.md, Presets). Exactly one of `preset` and `effect` is required (particles-source). An unknown asset or built-in is vfx-effect-missing. |
| `params` | `object` | no |  |  | Values for the effect's declared `params`, by name: a number, [x, y, z], [r, g, b, a] or "#rrggbb[aa]", by the param's type. A name the effect does not declare, or a value of the wrong type, is ignored with a runtime warning. Only with an `effect`. |

## Rules that can refuse it

- `feel/impact-silent`
- `particles-effect-unknown`
- `particles-override-ignored`
- `particles-param-unknown`
- `particles-source`
- `render.hd.cloud_shadow_unavailable`
- `render.hd.screen-fx-views`
- `vfx-effect-missing`

## Example

From the contract's tested fixture `fixtures/contract/full20/scene.json#smoke-vent`.

```json
{
  "type": "particles",
  "preset": "smoke",
  "rate": 24,
  "color": "#9AA0A6"
}
```