Up to date

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

パーティクルシェーダー¶

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.

注釈

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.

レンダリングモード¶

レンダリングモード	説明
keep_data	再起動時に以前のデータをクリアしない。
disable_force	Disable attractor force.
disable_velocity	VELOCITY 値を無視します。
collision_use_scale	Scale the particle's size for collisions.

Built-ins¶

"in"としてマークされた値は読み取り専用です。"out"とマークされた値はオプションの書き込み用であり、必ずしも適切な値を含むとは限りません。"inout"とマークされた値は、適切なデフォルト値を提供し、オプションで書き込むことができます。サンプラーは書込みの対象ではなく、マークされていません。

Global built-ins¶

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

ビルトイン	説明
in float TIME	秒単位のグローバル時間。
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.

関数	説明
in float LIFETIME	パーティクルの寿命。
in float DELTA	デルタプロセス時間。
in uint NUMBER	放出開始以降のユニークな番号。
in uint INDEX	パーティクルインデックス(パーティクル全体から)。
in mat4 EMISSION_TRANSFORM	エミッタの変換(非ローカルシステムに使用)。
in uint RANDOM_SEED	乱数のベースとして使用される乱数シード。
inout bool ACTIVE	`true` when the particle is active, can be set `false`.
inout vec4 COLOR	パーティクルの色。メッシュの頂点関数に書き込み、アクセスできます。
inout vec3 VELOCITY	パーティクルの速度は変更できます。
inout mat4 TRANSFORM	パーティクルの変換。
inout vec4 CUSTOM	カスタムパーティクルデータ。メッシュのシェーダーから 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.

注釈

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¶

ビルトイン	説明
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¶

ビルトイン	説明
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);

関数	説明
bool emit_subparticle (mat4 xform, vec3 velocity, vec4 color, vec4 custom, uint flags)	Emits a particle from a sub-emitter.