ParticleEmitter

Emits a stream or burst of particles, each ageing through its own size, colour, speed and spin: steam, embers, dripping water, a burst of sparks off an impact. One emitter covers all of these; only the numbers differ.

On this page

Add it
From a script
Fields

Add it

+ Add node → Particles creates a node with it already on. Already have a node for it? Add component → ParticleEmitterComponent.

From a script

A script on the same node writes these fields by name. ParticleEmitterComponent is the name to pass.

rgs

set_flag("ParticleEmitterComponent", "emitting", true);
set_number("ParticleEmitterComponent", "rate", 20.0);
set_number("ParticleEmitterComponent", "lifetime", 1.2);
set_number("ParticleEmitterComponent", "speed", 60.0);
set_point("ParticleEmitterComponent", "direction", vec2(0.0, -1.0));
set_number("ParticleEmitterComponent", "spread", 0.6);
set_number("ParticleEmitterComponent", "gravity", -40.0);
set_colour("ParticleEmitterComponent", "start_color", vec4(0.9, 0.9, 0.95, 0.8));
set_colour("ParticleEmitterComponent", "end_color", vec4(0.7, 0.75, 0.85, 0.0));
set_number("ParticleEmitterComponent", "start_size", 8.0);
set_number("ParticleEmitterComponent", "end_size", 2.0);
set_flag("ParticleEmitterComponent", "one_shot", false);
set_number("ParticleEmitterComponent", "prewarm", 0.0);
set_flag("ParticleEmitterComponent", "unshaded", false);
set_flag("ParticleEmitterComponent", "light_only", false);
set_number("ParticleEmitterComponent", "drag", 0.0);
set_point("ParticleEmitterComponent", "speed_range", vec2(0.0, 60.0));
set_number("ParticleEmitterComponent", "start_rotation", 0.0);
set_number("ParticleEmitterComponent", "rotation_spread", 0.0);
set_number("ParticleEmitterComponent", "angular_velocity", 0.0);
set_number("ParticleEmitterComponent", "angular_velocity_spread", 0.0);
set_flag("ParticleEmitterComponent", "align_to_velocity", false);
set_number("ParticleEmitterComponent", "inherit_velocity", 0.0);

Fields

Field Script name Kind Default What it does

Emitting emitting checkbox on Whether new particles are produced.

Rate rate number, at least 0 20 Particles per second.

Lifetime lifetime number, at least 0.01 1.2 How long each lives, in seconds.

Speed speed number, at least 0 60 Initial speed, in world units per second.

Direction direction two numbers (x, y) (0, -1) Direction particles are fired along.

Spread spread number, 0 to 7, step 0.05 0.6 Angular scatter around direction, in radians.

Gravity gravity number -40 Downward acceleration. Positive values pull down; negative push up.

Start Color start_color colour #e6e6f2, 80% opaque Colour at birth.

End Color end_color colour #b3bfd9, 0% opaque Colour at death. Fading the alpha to zero is what makes an ember die rather than blink out.

Start Size start_size number, at least 0 8 Size at birth, in world units.

End Size end_size number, at least 0 2 Size at death.

One Shot one_shot checkbox off Fire once and stop, rather than emitting continuously.

Burst burst number, at least 1 24 How many particles a one-shot emits at once.

Capacity capacity number, at least 1 128 The most particles that can exist at once.

Prewarm prewarm number, 0 to 10, step 0.1 0 s Seconds the emitter has already run when the room opens, so smoke is already rising.

Trail trail number, 0 to 4 0 Past positions drawn behind each particle.

Sort Layer layer number 10 Lower draws first.

Blend blend one of Alpha, Add, Multiply, Screen, Subtract Alpha Additive for embers and sparks, multiply for smoke.

Unshaded unshaded checkbox off Draw at full brightness, ignoring the room's lighting.

Light Only light_only checkbox off Draw only where light falls.

Sprite

Texture texture asset none Texture each particle draws; empty draws the fallback disc.

Texture Sheet sheet section none Frames laid out on texture, or nothing for one whole image.

Field	Script name	Kind	Default	What it does
Columns	`columns`	number, at least 1	none	Cells across.
Rows	`rows`	number, at least 1	none	Cells down.
First	`first`	number	none	First cell played, counting from zero.
Last	`last`	number	none	Last cell played, inclusive.
Driver	`driver`	one of Lifetime, Speed	none	What picks the frame within the range.

Stretch stretch section none Stretch each particle along its flight instead of drawing it square.

Field	Script name	Kind	Default	What it does
Length Scale	`length_scale`	number, at least 0, step 0.05	none	Length at a standstill, as a multiple of the particle's size.
Speed Scale	`speed_scale`	number, at least 0, step 0.001	none	Extra length per world unit per second, as a multiple of the size.

Over Lifetime

Size Over Life size_over_life section none Extra multiplier on size across a particle's life.

Color Over Life color_over_life section none Extra tint across a particle's life.

Rotation Over Life rotation_over_life section none Multiplier on how fast a particle spins, across its life.

Velocity Over Life velocity_over_life section none Multiplier on how far a particle travels this step.

Drag drag number, at least 0, step 0.1 0 /s How much air resistance slows the particle down over time.

By Speed

Size By Speed size_by_speed section none Multiplier on size, driven by how fast the particle is going.

Color By Speed color_by_speed section none Tint driven by speed, multiplied in like Color Over Life.

Speed Range speed_range two numbers (x, y), at least 0 (0, 60) The speeds that map to 0 and 1 for the two by-speed curves.

Emission Shape

Shape shape one of Point, Circle, Box, Cone, Line Point Where in the emitter's neighbourhood particles are born.

Rotation

Start Rotation start_rotation number, step 1 0 ° Angle a particle starts at, in degrees; a script sets it in radians.

Rotation Spread rotation_spread number, 0 to 7, step 0.05 0 Random spread around Start Rotation, in radians.

Angular Velocity angular_velocity number, step 0.1 0 rad/s How fast a particle spins, in radians per second.

Angular Velocity Spread angular_velocity_spread number, at least 0, step 0.1 0 rad/s Random spread around Angular Velocity, in radians per second.

Align To Velocity align_to_velocity checkbox off Point each particle along its own velocity.

Sub-emitter

On Death on_death asset none An emitter to spawn where each particle dies.

Collision

Collision collision section none What particles do when they meet the world, or nothing to pass through.

Field	Script name	Kind	Default	What it does
Bounce	`bounce`	number, 0 to 1, step 0.05	none	0 sticks, 1 is elastic.
Friction	`friction`	number, 0 to 1, step 0.05	none	0 is ice, 1 stops it dead.

Inherit

Inherit Velocity inherit_velocity number, 0 to 1, step 0.05 0 Fraction of the emitter's own velocity a new particle carries.

Noise

Noise noise section none A noise field that bends particles off their paths, or nothing for still air.

Field	Script name	Kind	Default	What it does
Strength	`strength`	number, at least 0	none	How hard the field pushes, in world units per second.
Frequency	`frequency`	number, at least 0, step 0.001	none	How fine the swirl pattern is. Low is a slow, wide swirl; high is jitter.
Scroll	`scroll`	two numbers (x, y)	none	How fast the field itself drifts, in world units per second.
Seed	`seed`	number	none	Which field, of all the fields this frequency can produce.

Trigger

Trigger trigger section none A region that reports the particles crossing it, or nothing.

Field	Script name	Kind	Default	What it does
Offset	`offset`	two numbers (x, y)	none	Where the shape sits, relative to the emitter, in world units.
Shape	`shape`	one of Box, Circle	none	What the region is.
Report	`report`	one of Enter, Exit, Both	none	Which crossings are reported.

Custom Data

Custom Data custom_data section none Four per-particle numbers for a material to read, or nothing.

Field	Script name	Kind	Default	What it does
X	`x`	one of Fixed, Random, OverLife	none	First channel.
Y	`y`	one of Fixed, Random, OverLife	none	Second channel.
Z	`z`	one of Fixed, Random, OverLife	none	Third channel.
W	`w`	one of Fixed, Random, OverLife	none	Fourth channel.