Particle shaders

Particle shaders are a special type of shader that runs before the object is drawn. They are used for calculating material properties such as color, position, and rotation. They are drawn with any regular material for CanvasItem or Spatial, depending on whether they are 2D or 3D.

Particle shaders are unique because they are not used to draw the object itself; they are used to calculate particle properties, which are then used by the CanvasItem of Spatial shader. They contain two processor functions: start() and process().

Unlike other shader types, particle shaders keep the data that was output the previous frame. Therefore, particle shaders can be used for complex effects that take place over multiple frames.

Note

Particle shaders are only available with GPU-based particle nodes (GPUParticles2D and GPUParticles3D).

CPU-based particle nodes (CPUParticles2D and CPUParticles3D) are rendered on the GPU (which means they can use custom CanvasItem or Spatial shaders), but their motion is simulated on the CPU.

Render modes

Render mode	Description
keep_data	Do not clear previous data on restart.
disable_force	Disable attractor force.
disable_velocity	Ignore VELOCITY value.

Built-ins

Values marked as "in" are read-only. Values marked as "out" are for optional writing and will not necessarily contain sensible values. Values marked as "inout" provide a sensible default value, and can optionally be written to. Samplers are not subjects of writing and they are not marked.

Global built-ins

Global built-ins are available everywhere, including custom functions.

Built-in	Description
in float TIME	Global time, in seconds.
in float PI	A PI constant (3.141592). A ration of circle's circumference to its diameter and amount of radians in half turn.
in float TAU	A TAU constant (6.283185). An equivalent of PI * 2 and amount of radians in full turn.
in float E	A E constant (2.718281). Euler's number and a base of the natural logarithm.

Start and Process built-ins

Function	Description
in float LIFETIME	Particle lifetime.
in float DELTA	Delta process time.
in uint NUMBER	Unique number since emission start.
in uint INDEX	Particle index (from total particles).
in mat4 EMISSION_TRANSFORM	Emitter transform (used for non-local systems).
in uint RANDOM_SEED	Random seed used as base for random.
inout bool ACTIVE	true when the particle is active, can be set false.
inout vec4 COLOR	Particle color, can be written to and accessed in mesh's vertex function.
inout vec3 VELOCITY	Particle velocity, can be modified.
inout mat4 TRANSFORM	Particle transform.
inout vec4 CUSTOM	Custom particle data. Accessible from shader of mesh as INSTANCE_CUSTOM.
inout float MASS	Particle mass, intended to be used with attractors. Equals 1.0 by default.

Note

In order to use the COLOR variable in a StandardMaterial3D, set vertex_color_use_as_albedo to true. In a ShaderMaterial, access it with the COLOR variable.

Start built-ins

Built-in	Description
in bool RESTART_POSITION
in bool RESTART_ROT_SCALE
in bool RESTART_VELOCITY
in bool RESTART_COLOR
in bool RESTART_CUSTOM
in bool RESTART_VELOCITY

Process built-ins

Built-in	Description
in bool RESTART	true if the current process frame is first for the particle.
in uint FLAG_EMIT_POSITION	A flag for using on the last argument of emit_subparticle function to assign a position to a new particle's transform.
in uint FLAG_EMIT_ROT_SCALE	A flag for using on the last argument of emit_subparticle function to assign the rotation and scale to a new particle's transform.
in uint FLAG_EMIT_VELOCITY	A flag for using on the last argument of emit_subparticle function to assign a velocity to a new particle.
in uint FLAG_EMIT_COLOR	A flag for using on the last argument of emit_subparticle function to assign a color to a new particle.
in uint FLAG_EMIT_CUSTOM	A flag for using on the last argument of emit_subparticle function to assign a custom data vector to a new particle.
in bool COLLIDED	true when the particle has collided with a particle collider.
in vec3 COLLISION_NORMAL	A normal of the last collision. If there is no collision detected it is equal to vec3(0.0).
in float COLLISION_DEPTH	A length of normal of the last collision. If there is no collision detected it is equal to 0.0.
in vec3 ATTRACTOR_FORCE	A combined force of the attractors at the moment on that particle.
in vec4 USERDATAX	Vector that enables the integration of supplementary user-defined data into the particle process shader. USERDATAX are six built-ins identified by number, X can be numbers between 1 and 6.

Process functions

Function	Description
bool emit_subparticle (mat4 xform, vec3 velocity, vec4 color, vec4 custom, uint flags)	Forces to emit a particle from a sub-emitter.