> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nmentities.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Particle Equations

> Plot animated particle shapes from math formulas.

`particleequation` plots a **parametric curve** from math formulas. It evaluates `x`, `y` and `z` as the parameter `t` sweeps from `tmin` to `tmax` over `points` steps, spawning a particle at each point relative to the target.

```yaml theme={null}
- particleequation{particle=flame;x=cos(t)*3;y=0;z=sin(t)*3;points=48} @self   # a circle
```

**Aliases:** `particleeq`, `pe`

| Attribute     | Default | Description                       |
| ------------- | ------- | --------------------------------- |
| `particle`    |         | Particle id.                      |
| `x`, `y`, `z` |         | Formulas evaluated per point.     |
| `tmin`        | `0`     | Start of the sweep.               |
| `tmax`        | `2π`    | End of the sweep.                 |
| `points`      |         | Number of points along the curve. |

## Formula syntax

* **Operators:** `+ - * / % ^`, unary `-`, parentheses.
* **Variables:** `t` (the sweep) and `time` (the world clock in ticks, for animation).
* **Constants:** `pi`, `tau` (2π), `e`.
* **Functions:** `sin cos tan asin acos atan sinh cosh tanh sqrt cbrt abs exp ln log log2 floor ceil round sign`.
* No scientific notation: write `1000`, not `1e3`. A bad formula is logged and the line is skipped.

## Animation

The `time` variable makes shapes move when the equation is redrawn. Run it inside a [`repeat`](timers-auras) with a short interval:

```yaml theme={null}
- repeat{effect=galaxy;every=2t;for=30s} #onSpawn @self
```

```yaml theme={null}
# Effects/shapes.yml
galaxy:                     # rotating spiral arms
- particleequation{particle=end_rod;x=cos(t+time*0.05)*t*0.15;y=0;z=sin(t+time*0.05)*t*0.15;tmax=25;points=80} @self
rose:                       # 4-petal rose that spins
- particleequation{particle=flame;x=cos(4*t)*cos(t+time*0.04)*3;y=1;z=cos(4*t)*sin(t+time*0.04)*3;points=120} @self
lissajous:                  # weaving 3D ribbon
- particleequation{particle=soul_fire_flame;x=sin(t*3+time*0.05)*2;y=sin(t*2)*2;z=cos(t*4)*2;tmax=6.283;points=100} @self
breathing_ring:             # ring that expands and contracts
- particleequation{particle=flame;x=cos(t)*(2+sin(time*0.1));y=1;z=sin(t)*(2+sin(time*0.1));points=48} @self
```

## A rotating 3D cube

Three equations, one per set of parallel edges. `t` sweeps `0→4`; `floor(t)` picks which of the four parallel edges (its two bits give the fixed `±1` corners), `t-floor(t)` slides along the edge, and the `cos/sin(time*0.05)` pair rotates everything around Y:

```yaml theme={null}
cube:
- particleequation{particle=end_rod;tmax=4;points=64;x=(-1+2*(t-floor(t)))*cos(time*0.05)-(2*floor(floor(t)/2)-1)*sin(time*0.05);y=2*(floor(t)%2)-1;z=(-1+2*(t-floor(t)))*sin(time*0.05)+(2*floor(floor(t)/2)-1)*cos(time*0.05)} @self
- particleequation{particle=end_rod;tmax=4;points=64;x=(2*(floor(t)%2)-1)*cos(time*0.05)-(2*floor(floor(t)/2)-1)*sin(time*0.05);y=-1+2*(t-floor(t));z=(2*(floor(t)%2)-1)*sin(time*0.05)+(2*floor(floor(t)/2)-1)*cos(time*0.05)} @self
- particleequation{particle=end_rod;tmax=4;points=64;x=(2*(floor(t)%2)-1)*cos(time*0.05)-(-1+2*(t-floor(t)))*sin(time*0.05);y=2*floor(floor(t)/2)-1;z=(2*(floor(t)%2)-1)*sin(time*0.05)+(-1+2*(t-floor(t)))*cos(time*0.05)} @self
```

Size: multiply each formula by a factor. Spin speed: change `time*0.05`. Density: raise `points`.

## Crisp shapes

Vanilla particles live around 0.5–2 seconds, so a fast-spinning shape smears: old particles from previous angles stay visible. For clean shapes, slow the rotation (`time*0.02`) and prefer stationary particles (`dust`, `electric_spark`, `crit`) over drifting ones (`end_rod` floats upward).