粒子著色器

粒子著色器是一種特殊類型的著色器，在物件被繪製前執行。它們用來計算材質屬性，例如顏色、位置與旋轉。根據粒子是 2D 還是 3D，會與 CanvasItem 或 Spatial 的一般材質一同繪製。

粒子著色器很特別，因為它們不是用來繪製物件本身，而是用來計算粒子的屬性，這些屬性會被 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	自引擎啟動以來的全域時間（秒）。每 3,600 秒會重設（可透過 rollover 設定變更）。該值會受到 time_scale 影響，但不受暫停影響。如果你需要不受 time_scale 影響的 `TIME`，請自訂全域著色器 uniform 並於每幀更新。
in float PI	常數 PI（3.141592），為圓周長與直徑的比值，也是一半圈的弧度數。
in float TAU	常數 TAU（6.283185），等於 PI * 2，也是一整圈的弧度數。
in float E	常數 E（2.718281），歐拉數，也是自然對數的底數。

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`，可設為 `false` 以禁用。
inout vec4 COLOR	粒子的顏色，可寫入與於網格的頂點函式中存取。
inout vec3 VELOCITY	粒子的速度，可修改。
inout mat4 TRANSFORM	粒子的變換。
inout vec4 CUSTOM	自訂粒子資料。可在網格的著色器中以 `INSTANCE_CUSTOM` 讀取。
inout float MASS	粒子的質量，通常搭配吸引器使用。預設值為 `1.0`。
in vec4 USERDATAX	可將額外的自訂資料整合進入粒子處理著色器的向量。`USERDATAX` 有六個內建變數，以數字區分，`X` 可為 1 到 6，例如 `USERDATA3`。
in uint FLAG_EMIT_POSITION	用於 `emit_subparticle()` 函式最後一個參數的旗標，用來為新粒子的變換指定位置。
in uint FLAG_EMIT_ROT_SCALE	用於 `emit_subparticle()` 函式最後一個參數的旗標，用來為新粒子的變換指定旋轉與縮放。
in uint FLAG_EMIT_VELOCITY	用於 `emit_subparticle()` 函式最後一個參數的旗標，用來為新粒子指定速度。
in uint FLAG_EMIT_COLOR	用於 `emit_subparticle()` 函式最後一個參數的旗標，用來為新粒子指定顏色。
in uint FLAG_EMIT_CUSTOM	用於 `emit_subparticle()` 函式最後一個參數的旗標，用來為新粒子指定自訂資料向量。
in vec3 EMITTER_VELOCITY	Particles2D 或 Particles3D 節點的發射器速度。
in float INTERPOLATE_TO_END	Particles 節點屬性 interp_to_end （或 3D）的數值。
in uint AMOUNT_RATIO	Particles 節點屬性 amount_ratio （或 3D）的數值。

備註

若要在 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`。
in bool COLLIDED	當粒子與碰撞器發生碰撞時為 `true`。
in vec3 COLLISION_NORMAL	上一次碰撞的法線。如果沒有偵測到碰撞，則為 `(0.0, 0.0, 0.0)`。
in float COLLISION_DEPTH	上一次碰撞的法線長度。如果沒有偵測到碰撞，則為 `0.0`。
in vec3 ATTRACTOR_FORCE	該粒子當前受到的所有吸引器合力。

Process 函式

目前粒子著色器僅支援 emit_subparticle() 這個自訂函式。它可讓你從子發射器新增一個帶指定參數的新粒子。新建的粒子只會使用符合 flags 旗標的屬性。例如，下列程式碼會發射一個有指定位置、速度及顏色的粒子，但不指定旋轉、縮放與自訂值：

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)	從子發射器發射一個粒子。