# Particles

SimVX provides a `ParticleEmitter` node for CPU or GPU-accelerated particle effects. Particles move, scale, and recolor over their lifetime based on configurable settings.

## Emitter Properties

`ParticleEmitter` extends `Node3D` and exposes all configuration as `Property` descriptors, making them editable in the inspector.

| Property | Default | Description |
|---------|---------|-------------|
| `amount` | `100` | Maximum particle pool size |
| `lifetime` | `2.0` | Seconds each particle lives |
| `emission_rate` | `50.0` | Particles emitted per second |
| `one_shot` | `False` | Emit once then stop |
| `emitting` | `True` | Whether the emitter is active |
| `emission_shape` | `"point"` | `"point"`, `"sphere"`, or `"box"` |
| `emission_radius` | `1.0` | Radius for sphere emission shape |
| `emission_box` | `(1, 1, 1)` | Half-extents for box emission shape |
| `initial_velocity` | `(0, 5, 0)` | Starting velocity vector |
| `velocity_spread` | `0.3` | Randomization factor for velocity direction |
| `gravity` | `(0, -9.8, 0)` | Gravity applied each frame |
| `damping` | `0.0` | Velocity damping per second |
| `start_color` | `(1, 1, 1, 1)` | RGBA at birth |
| `end_color` | `(1, 1, 1, 0)` | RGBA at death (fades out by default) |
| `start_scale` | `1.0` | Scale at birth |
| `end_scale` | `0.0` | Scale at death |
| `gpu_simulation` | `False` | Offload simulation to a compute shader |

## Properties

- **`alive_count`** -- Number of currently alive particles.
- **`particle_data`** -- NumPy structured array of alive particles (position, velocity, color, scale, lifetime, age). Returns `None` when no particles are alive.
- **`emitter_config`** -- Dict of emitter parameters for GPU compute dispatch.

## Fire Effect Example

```python
from simvx.core import ParticleEmitter, Vec3

class FireEmitter(ParticleEmitter):
    amount = 200
    lifetime = 1.5
    emission_rate = 80
    emission_shape = "sphere"
    emission_radius = 0.3
    initial_velocity = (0, 4, 0)
    velocity_spread = 0.2
    gravity = (0, 1.0, 0)          # Hot air rises
    start_color = (1.0, 0.6, 0.1, 1.0)
    end_color = (0.8, 0.1, 0.0, 0.0)
    start_scale = 0.8
    end_scale = 0.0
```

## One-Shot Explosion

Set `one_shot = True` and a high `emission_rate` to burst all particles at once:

```python
class Explosion(ParticleEmitter):
    amount = 300
    lifetime = 0.8
    emission_rate = 10000   # Emit all 300 in the first frame
    one_shot = True
    emission_shape = "sphere"
    emission_radius = 0.1
    initial_velocity = (0, 8, 0)
    velocity_spread = 1.0   # Scatter in all directions
    gravity = (0, -12, 0)
    start_color = (1.0, 1.0, 0.5, 1.0)
    end_color = (0.5, 0.1, 0.0, 0.0)
    start_scale = 1.2
    end_scale = 0.0
```

## GPU Simulation

When `gpu_simulation = True`, the CPU skips per-particle work and only uploads the `emitter_config` dict each frame. The graphics backend dispatches a compute shader that reads the config and writes particle positions, colors, and scales directly in GPU memory -- zero-copy rendering with no per-particle CPU cost.

## API Reference

See {py:mod}`simvx.core.particles` for the complete particle API.