粒子着色器

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	Ignore `VELOCITY` value.
collision_use_scale	为进行碰撞而缩放粒子的大小。

内置

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.

全局内置

全局的内置在所有地方均可用，包括自定义函数中。

内置	描述
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	圆周率常量 `PI`（`3.141592`）。圆的周长与直径的比值，转半圈的弧度值。
in float TAU	`TAU` 常数（`6.283185`）。等价于 `PI * 2`，即转一圈对应的弧度。
in float E	`E` 常数（`2.718281`）。欧拉数，即自然对数的底。

Start 和 Process 内置

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`，可以设置为 `false`。
inout vec4 COLOR	粒子的颜色, 可以写入Mesh的顶点函数中, 也可以访问.
inout vec3 VELOCITY	粒子的速度，可以修改。
inout mat4 TRANSFORM	粒子变换。
inout vec4 CUSTOM	Custom particle data. Accessible from shader of mesh as `INSTANCE_CUSTOM`.
inout float MASS	粒子的质量，旨在配合吸引器使用。默认为 `1.0`。
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 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 Particles2D (3D) node.
in float INTERPOLATE_TO_END	Value of interp_to_end (3D) property of Particles node.
in uint AMOUNT_RATIO	Value of amount_ratio (3D) 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 内置

内置	描述
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 内置

内置	描述
in bool RESTART	当前为该粒子的第一个处理帧时为 `true`。
in bool COLLIDED	粒子与粒子碰撞器碰撞时为 `true`。
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	上一次碰撞的法线长度。未检测到碰撞时等于 `0.0`。
in vec3 ATTRACTOR_FORCE	A combined force of the attractors at the moment on that particle.

Process 函数

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.