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...

粒子著色器

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.

粒子著色器很特別，因為它們不是用來繪製物件本身，而是用來計算粒子的屬性，這些屬性會被 CanvasItem 或 Spatial 著色器使用。粒子著色器包含兩個處理函式：start() 和 process()。

與其他著色器類型不同，粒子著色器會保留上一幀輸出的資料。因此，粒子著色器能用來實現需跨多幀運算的複雜特效。

備註

粒子著色器僅能搭配 GPU 型粒子節點（GPUParticles2D 與 GPUParticles3D）使用。

CPU 型粒子節點（CPUParticles2D 與 CPUParticles3D）會在 GPU 上進行算繪（可使用自訂 CanvasItem 或 Spatial 著色器），但其運動是在 CPU 上模擬的。

算繪模式

算繪模式	說明
keep_data	重新啟動時不清除先前的資料。
disable_force	停用吸引力。
disable_velocity	忽略 `VELOCITY` 值。
collision_use_scale	於碰撞時套用粒子的縮放大小。

內建變數

標記為 in 的值為唯讀。標記為 out 的值可以選擇寫入，且不一定包含合理的預設值。標記為 inout 的值則有預設值，可以選擇寫入。取樣器（sampler）無法寫入，因此未標註。

全域內建變數

全域內建變數可於任何地方使用，包括自訂函式。

內建變數	說明
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 與 Process 內建變數

這些屬性可於 start() 與 process() 兩個函式中存取。

函式	說明
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 to `false`.
inout vec4 COLOR	Particle color, can be written to and accessed in the mesh's vertex function.
inout vec3 VELOCITY	粒子的速度，可修改。
inout mat4 TRANSFORM	粒子的變換。
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	可將額外的自訂資料整合進入粒子處理著色器的向量。`USERDATAX` 有六個內建變數，以數字區分，`X` 可為 1 到 6，例如 `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	Particles2D 或 Particles3D 節點的發射器速度。
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.

備註

若要在 StandardMaterial3D 中使用 COLOR 變數，請將 vertex_color_use_as_albedo 設為 true。在 ShaderMaterial 中，直接以 COLOR 變數存取。

Start 內建變數

內建變數	說明
in bool RESTART_POSITION	若粒子被重新啟動，或未指定自訂位置時（即這個粒子是由 `emit_subparticle()` 且未帶 `FLAG_EMIT_POSITION` 旗標產生），則為 `true`。
in bool RESTART_ROT_SCALE	若粒子被重新啟動，或未指定自訂旋轉／縮放時（即這個粒子是由 `emit_subparticle()` 且未帶 `FLAG_EMIT_ROT_SCALE` 旗標產生），則為 `true`。
in bool RESTART_VELOCITY	若粒子被重新啟動，或未指定自訂速度時（即這個粒子是由 `emit_subparticle()` 且未帶 `FLAG_EMIT_VELOCITY` 旗標產生），則為 `true`。
in bool RESTART_COLOR	若粒子被重新啟動，或未指定自訂顏色時（即這個粒子是由 `emit_subparticle()` 且未帶 `FLAG_EMIT_COLOR` 旗標產生），則為 `true`。
in bool RESTART_CUSTOM	若粒子被重新啟動，或未指定自訂屬性時（即這個粒子是由 `emit_subparticle()` 且未帶 `FLAG_EMIT_CUSTOM` 旗標產生），則為 `true`。

Process 內建變數

內建變數	說明
in bool RESTART	`true` if the current process frame is the first for the particle.
in bool COLLIDED	當粒子與碰撞器發生碰撞時為 `true`。
in vec3 COLLISION_NORMAL	上一次碰撞的法線。如果沒有偵測到碰撞，則為 `(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	該粒子當前受到的所有吸引器合力。

Process 函式

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);

函式	說明
bool emit_subparticle (mat4 xform, vec3 velocity, vec4 color, vec4 custom, uint flags)	從子發射器發射一個粒子。