Particle systems

The Particle System component emits a continuous stream of GPU points — fire, smoke, sparks, magic, dust, rain, explosions. Add it from Add Component → Particle System, tune it in the Inspector, or set it from a script or the AI with setComponent('particleSystem', { … }).

One-shot vs. continuous

This page is the component — a persistent emitter attached to an entity. For a fire-and-forget burst from a script (a hit spark, a pickup pop) with no component to author, use particles.burst() instead. It cleans itself up when the particles fade.

Every property below is optional except where noted — leave one out and it takes its default.

Emission

How many particles, how often, and for how long.

Property	Type	Default	What it does
maxParticles	number	100	Pool size (50–1000). The hard cap on particles alive at once.
emissionRate	number	10	Particles spawned per second (continuous emission).
duration	number	0	Seconds the system emits, then stops. 0 = emit forever.
startDelay	number	0	Seconds to wait before the first particle.
looping	boolean	false	Restart emission when duration elapses (loop the effect).
playOnAwake	boolean	true*	Start emitting as soon as the entity spawns. Turn off to start paused and trigger it from a script.
bursts	{ time, count }[]	—	Emit count particles all at once at elapsed time seconds — shockwaves, puffs. Combine with a low emissionRate or none.

* The default depends on how the component is created; set it explicitly when the timing matters.

Shape — where particles are born

Property	Type	Default	What it does
shape	'point' | 'sphere' | 'cone' | 'box'	'point'	The emission volume. cone throws particles in a direction; sphere/box fill a volume.
shapeRadius	number	1	Radius of the sphere/box/cone base.
shapeAngle	number	30	Cone half-angle in degrees (only for shape: 'cone').

Movement

Initial velocity plus the forces acting over each particle's life.

Property	Type	Default	What it does
speed	number	5	Initial outward speed.
speedVariation	number	0	Randomness added to the initial speed, 0–1 (0 = every particle identical, 1 = wide spread).
gravity	number	-9.8	Constant Y acceleration. Positive floats particles up (embers, bubbles).
velocityOverLifetime	[x, y, z]	—	A constant force/wind added every frame — drift smoke sideways, curve sparks.
damping	number	0	Velocity drag, 0–1. Higher = particles slow to a stop (settling dust).
simulationSpace	'local' | 'world'	'local'	Unity's Simulation Space — what happens when the emitter entity moves. local: every particle (in flight too) rides along — a torch flame that follows the torch. world: emitted particles keep their world trajectory and only new spawns follow, leaving a trail behind a mover — rocket smoke, rain. No difference for emitters that never move.

Turbulence

Organic, swirling motion (smoke, fire, magic).

Property	Type	Default	What it does
noiseStrength	number	0	Turbulence intensity. 0 = off.
noiseFrequency	number	1	Turbulence scale — higher = tighter, more chaotic swirls.

Size

Property	Type	Default	What it does
size	number	0.2	Base particle size.
startSizeMin	number	size	Low end of a random per-particle size range.
startSizeMax	number	size	High end of the random size range. Set both to vary particle sizes.
sizeOverLifetime	boolean	false	Shrink each particle to nothing as it dies.

Rotation

Property	Type	Default	What it does
startRotation	number	0	Initial rotation in degrees.
rotationOverLifetime	number	0	Spin speed in degrees/second.

Lifetime

Property	Type	Default	What it does
lifetime	number	2	Seconds each particle lives.
lifetimeMin	number	lifetime	Low end of a random per-particle lifetime range.
lifetimeMax	number	lifetime	High end of the random lifetime range.

Colour & appearance

Property	Type	Default	What it does
color	hex string	—	Starting colour of each particle.
endColor	hex string	—	Colour to fade toward over the particle's life (used when colorGradient is absent).
colorGradient	{ t, color }[]	—	Multi-stop colour-over-lifetime (Unity's Color over Lifetime). Each stop is { t: 0–1, color: hex }. With 2+ stops it overrides the color → endColor fade.
opacityOverLifetime	'none' | 'fadeOut' | 'fadeInOut'	'none'	Alpha curve. fadeOut = dissolve as it dies; fadeInOut = ease in and out (soft smoke).
blending	'normal' | 'additive'	'normal'	additive makes overlapping particles glow — fire, magic, energy. normal for smoke/dust.

Rendering

Property	Type	Default	What it does
renderMode	'billboard' | 'stretched'	'billboard'	billboard always faces the camera; stretched streaks each particle along its velocity — sparks, rain, tracers.
stretchFactor	number	1	How far stretched particles elongate per unit of speed.
textureAssetId	string	—	An imported texture asset drawn as every particle's sprite (leaves, snowflakes, smoke puffs — a PNG with transparency works best). Unset = the default soft points. Pick it in the Inspector's Renderer → Texture field or drag a texture in from the Project panel; color/gradient tints multiply on top.

Ground collision

Property	Type	Default	What it does
worldCollision	boolean	false	Bounce particles off the ground plane (Y = 0) instead of passing through.
bounceRestitution	number	0.5	Bounciness on collision, 0–1 (0 = stick, 1 = no energy lost). Only applies when worldCollision is on.

Sub-emitters

Spawn a burst of child particles when a particle dies — a rocket trail bursting into sparks, a firework shell exploding. World-space, one level deep (children don't sub-emit).

subEmitters: [
  {
    count: 12,        // child particles per burst
    color: '#ffcc00', // child colour (default: parent's)
    sizeScale: 0.6,   // child size relative to parent
    speed: 4,         // child burst speed (default: parent's)
    lifetime: 0.5,    // child lifetime (default: half the parent's)
  },
]

Recipes

Campfire — additive, upward, flickering:

setComponent('particleSystem', {
  shape: 'cone', shapeAngle: 12, emissionRate: 40,
  speed: 2, gravity: 1.5, lifetime: 1.2,
  size: 0.4, sizeOverLifetime: true,
  color: '#ffcc33', endColor: '#ff3300',
  blending: 'additive', opacityOverLifetime: 'fadeOut',
  noiseStrength: 0.8, noiseFrequency: 1.5,
})

Bouncing sparks — stretched, additive, collide with the ground:

setComponent('particleSystem', {
  shape: 'point', emissionRate: 0, bursts: [{ time: 0, count: 30 }],
  speed: 8, speedVariation: 0.6, gravity: -18, lifetime: 1.5,
  size: 0.1, color: '#fff2a0', endColor: '#ff7700',
  renderMode: 'stretched', stretchFactor: 2, blending: 'additive',
  worldCollision: true, bounceRestitution: 0.5,
})

Firework — a shell that explodes into a coloured burst via a sub-emitter:

setComponent('particleSystem', {
  shape: 'point', emissionRate: 0, bursts: [{ time: 0, count: 1 }],
  speed: 14, gravity: -6, lifetime: 1.4, size: 0.3, color: '#ffffff',
  subEmitters: [{ count: 60, color: '#66ccff', speed: 7, lifetime: 1.2, sizeScale: 0.5 }],
})

See also

• particles.burst() — one-shot bursts from a script, no component.
• Scripting basics → Reading & writing components — how setComponent / addComponent edit a component from a script.