Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

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 can be drawn with any regular material for CanvasItem or Spatial, depending on whether they are 2D or 3D.

Les shaders de particules sont uniques car ils ne sont pas utilisés pour dessiner l'objet lui-même. Ils sont utilisés pour calculer les propriétés des particules, qui sont ensuite utilisées par le shader CanvasItem ou du Spatial. Ils contiennent deux fonctions de processeur : start() et 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

Les shaders de particules sont uniquement disponibles dans des nœuds de particules basées sur le GPU (GPUParticles2D et 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	Désactiver la force d'attracteur.
disable_velocity	Ignorer la valeur de `VELOCITY`.
collision_use_scale	Scale the particle's size for collisions.

Variables intégrées

Values marked as in are read-only. Values marked as out can optionally be written to and will not necessarily contain sensible values. Values marked as inout provide a sensible default value, and can optionally be written to. Samplers cannot be written to so they are not marked.

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	Global time since the engine has started, in seconds. It repeats after every `3,600` seconds (which can be changed with the rollover setting). It's affected by time_scale but not by pausing. If you need a `TIME` variable that is not affected by time scale, add your own global shader uniform and update it each frame.
in float PI	A `PI` constant (`3.141592`). The ratio of a circle's circumference to its diameter and the number of radians in a half turn.
in float TAU	A `TAU` constant (`6.283185`). Equivalent to `PI * 2` and the number of radians in a full turn.
in float E	An `E` constant (`2.718281`). Euler's number, the 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 to `false`.
inout vec4 COLOR	Particle color, can be written to and accessed in the mesh's vertex function.
inout vec3 VELOCITY	La vélocité des particules, peut être modifiée.
inout mat4 TRANSFORM	Transformation de particules.
inout vec4 CUSTOM	Custom particle data. Accessible from the mesh's shader as `INSTANCE_CUSTOM`.
inout float MASS	Particle mass, intended to be used with attractors. `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, for example `USERDATA3`.
in uint FLAG_EMIT_POSITION	A flag for the last argument of the `emit_subparticle()` function to assign a position to a new particle's transform.
in uint FLAG_EMIT_ROT_SCALE	A flag for the last argument of the `emit_subparticle()` function to assign a rotation and scale to a new particle's transform.
in uint FLAG_EMIT_VELOCITY	A flag for the last argument of the `emit_subparticle()` function to assign a velocity to a new particle.
in uint FLAG_EMIT_COLOR	A flag for the last argument of the `emit_subparticle()` function to assign a color to a new particle.
in uint FLAG_EMIT_CUSTOM	A flag for the last argument of the `emit_subparticle()` function to assign a custom data vector to a new particle.
in vec3 EMITTER_VELOCITY	Velocity of the Particles2D (3D) node.
in float INTERPOLATE_TO_END	Value of the interp_to_end (3D) property of the Particles node.
in uint AMOUNT_RATIO	Value of the amount_ratio (3D) property of the 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 the 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 `(0.0, 0.0, 0.0)`.
in float COLLISION_DEPTH	A length of the 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.

Fonctions de traitement

emit_subparticle() is currently the only custom function supported by particle 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 velocite, vec4 couleur, vec4 personnalise, uint options)	Emits a particle from a sub-emitter.