Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Shaders de particules

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 a CanvasItem or 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.

Mode de rendu

Mode de rendu

Description

keep_data

Ne pas effacer les données précédentes au redémarrage.

disable_force

Disable attractor force.

disable_velocity

Ignorer la valeur de VELOCITY.

collision_use_scale

Scale the particle's size for collisions.

Variables intégrées

Les valeurs marquées comme "in" sont en lecture seule. Les valeurs marquées comme "out" sont pour l'écriture facultative et ne contiendront pas nécessairement de valeurs sensibles. Les valeurs marquées comme "inout" fournissent une valeur par défaut sensible et peuvent éventuellement être réécrites. Les échantillonneurs ne sont pas soumis à l'écriture et ne sont pas marqués.

Variables intégrées Globales

Les modules intégrés globaux sont disponibles partout, y compris dans les fonctions personnalisées.

Intégré

Description

in float TIME

Temps global, en secondes.

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

These properties can be accessed from both the start() and process() functions.

Fonction

Description

in float LIFETIME

Durée de vie des particules.

in float DELTA

Durée du processus Delta.

in uint NUMBER

Numéro unique depuis le début de l'émission.

in uint INDEX

Indice de particule (sur le nombre total de particules).

in mat4 EMISSION_TRANSFORM

Transformation de l'émetteur (utilisée pour les systèmes non locaux).

in uint RANDOM_SEED

Graine aléatoire utilisée comme base pour le hasard.

inout bool ACTIVE

true when the particle is active, can be set false.

inout vec4 COLOR

Couleur de particule, peut être écrit et accessible dans la fonction vertex du mesh.

inout vec3 VELOCITY

La vélocité des particules, peut être modifiée.

inout mat4 TRANSFORM

Transformation de particules.

inout vec4 CUSTOM

Données personnalisées des particules. Accessible depuis le shader de la maille comme INSTANCE_CUSTOM.

inout float MASS

Particle mass, intended to be used with attractors. Equals 1.0 by default.

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.

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 vec3 EMITTER_VELOCITY

Velocity of the Particles node.

in float INTERPOLATE_TO_END

Value of interp_to_end property of Particles node.

in uint AMOUNT_RATIO

Value of amount_ratio property of Particles node.

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

Intégré

Description

in bool RESTART_POSITION

true if particle is restarted, or emitted without a custom position (i.e. this particle was created by emit_subparticle() without the FLAG_EMIT_POSITION flag).

in bool RESTART_ROT_SCALE

true if particle is restarted, or emitted without a custom rotation or scale (i.e. this particle was created by emit_subparticle() without the FLAG_EMIT_ROT_SCALE flag).

in bool RESTART_VELOCITY

true if particle is restarted, or emitted without a custom velocity (i.e. this particle was created by emit_subparticle() without the FLAG_EMIT_VELOCITY flag).

in bool RESTART_COLOR

true if particle is restarted, or emitted without a custom color (i.e. this particle was created by emit_subparticle() without the FLAG_EMIT_COLOR flag).

in bool RESTART_CUSTOM

true if particle is restarted, or emitted without a custom property (i.e. this particle was created by emit_subparticle() without the FLAG_EMIT_CUSTOM flag).

Process built-ins

Intégré

Description

in bool RESTART

true if the current process frame is first for the 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.

Process functions

emit_subparticle is currently the only custom function supported by particles shaders. It allows users to add a new particle with specified parameters from a sub-emitter. The newly created particle will only use the properties that match the flags parameter. For example, the following code will emit a particle with a specified position, velocity, and color, but unspecified rotation, scale, and custom value:

mat4 custom_transform = mat4(1.0);
custom_transform[3].xyz = vec3(10.5, 0.0, 4.0);
emit_subparticle(custom_transform, vec3(1.0, 0.5, 1.0), vec4(1.0, 0.0, 0.0, 1.0), vec4(1.0), FLAG_EMIT_POSITION | FLAG_EMIT_VELOCITY | FLAG_EMIT_COLOR);

Fonction

Description

bool emit_subparticle (mat4 xform, vec3 velocity, vec4 color, vec4 custom, uint flags)

Emits a particle from a sub-emitter.