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

CPUParticles3D

繼承： GeometryInstance3D < VisualInstance3D < Node3D < Node < Object

基於 CPU 的 3D 粒子發射器。

說明

基於 CPU 的 3D 粒子節點，可用於建立各種粒子系統、粒子效果。

另見 GPUParticles3D，利用硬體加速提供了相同的功能，但可能無法在較舊的裝置上運作。

教學

屬性

int

amount

8

Curve

angle_curve

float

angle_max

0.0

float

angle_min

0.0

Curve

angular_velocity_curve

float

angular_velocity_max

0.0

float

angular_velocity_min

0.0

Curve

anim_offset_curve

float

anim_offset_max

0.0

float

anim_offset_min

0.0

Curve

anim_speed_curve

float

anim_speed_max

0.0

float

anim_speed_min

0.0

Color

color

Color(1, 1, 1, 1)

Gradient

color_initial_ramp

Gradient

color_ramp

Curve

damping_curve

float

damping_max

0.0

float

damping_min

0.0

Vector3

direction

Vector3(1, 0, 0)

DrawOrder

draw_order

0

Vector3

emission_box_extents

PackedColorArray

emission_colors

PackedColorArray()

PackedVector3Array

emission_normals

PackedVector3Array

emission_points

Vector3

emission_ring_axis

float

emission_ring_cone_angle

float

emission_ring_height

float

emission_ring_inner_radius

float

emission_ring_radius

EmissionShape

emission_shape

0

float

emission_sphere_radius

bool

emitting

true

float

explosiveness

0.0

int

fixed_fps

0

float

flatness

0.0

bool

fract_delta

true

Vector3

gravity

Vector3(0, -9.8, 0)

Curve

hue_variation_curve

float

hue_variation_max

0.0

float

hue_variation_min

0.0

float

initial_velocity_max

0.0

float

initial_velocity_min

0.0

float

lifetime

1.0

float

lifetime_randomness

0.0

Curve

linear_accel_curve

float

linear_accel_max

0.0

float

linear_accel_min

0.0

bool

local_coords

false

Mesh

mesh

bool

one_shot

false

Curve

orbit_velocity_curve

float

orbit_velocity_max

float

orbit_velocity_min

bool

particle_flag_align_y

false

bool

particle_flag_disable_z

false

bool

particle_flag_rotate_y

false

float

preprocess

0.0

Curve

radial_accel_curve

float

radial_accel_max

0.0

float

radial_accel_min

0.0

float

randomness

0.0

Curve

scale_amount_curve

float

scale_amount_max

1.0

float

scale_amount_min

1.0

Curve

scale_curve_x

Curve

scale_curve_y

Curve

scale_curve_z

int

seed

0

float

speed_scale

1.0

bool

split_scale

false

float

spread

45.0

Curve

tangential_accel_curve

float

tangential_accel_max

0.0

float

tangential_accel_min

0.0

bool

use_fixed_seed

false

AABB

visibility_aabb

AABB(0, 0, 0, 0, 0, 0)

方法

AABB

capture_aabb() const

void

convert_from_particles(particles: Node)

Curve

get_param_curve(param: Parameter) const

float

get_param_max(param: Parameter) const

float

get_param_min(param: Parameter) const

bool

get_particle_flag(particle_flag: ParticleFlags) const

void

request_particles_process(process_time: float, process_time_residual: float = 0.0)

void

restart(keep_seed: bool = false)

void

set_param_curve(param: Parameter, curve: Curve)

void

set_param_max(param: Parameter, value: float)

void

set_param_min(param: Parameter, value: float)

void

set_particle_flag(particle_flag: ParticleFlags, enable: bool)

訊號

finished() 🔗

所有活動粒子完成處理時發出。當 one_shot 停用時，粒子將連續處理，因此永遠不會發出。

列舉

enum DrawOrder: 🔗

DrawOrder DRAW_ORDER_INDEX = 0

粒子按發射順序繪製。

DrawOrder DRAW_ORDER_LIFETIME = 1

Particles are drawn in order of remaining lifetime. In other words, the particle with the highest lifetime is drawn at the front.

DrawOrder DRAW_ORDER_VIEW_DEPTH = 2

粒子按深度順序繪製。

enum Parameter: 🔗

Parameter PARAM_INITIAL_LINEAR_VELOCITY = 0

與 set_param_min()、set_param_max()、set_param_curve() 一起使用，設定初始速度屬性。

Parameter PARAM_ANGULAR_VELOCITY = 1

與 set_param_min()、set_param_max()、set_param_curve() 一起使用，設定角速度屬性。

Parameter PARAM_ORBIT_VELOCITY = 2

與 set_param_min()、set_param_max()、set_param_curve() 一起使用，設定軌道速度屬性。

Parameter PARAM_LINEAR_ACCEL = 3

與 set_param_min()、set_param_max()、set_param_curve() 一起使用，設定線性加速度屬性。

Parameter PARAM_RADIAL_ACCEL = 4

與 set_param_min()、set_param_max()、set_param_curve() 一起使用，設定徑向加速度屬性。

Parameter PARAM_TANGENTIAL_ACCEL = 5

與 set_param_min()、set_param_max()、set_param_curve() 一起使用，設定切向加速度屬性。

Parameter PARAM_DAMPING = 6

與 set_param_min()、set_param_max()、set_param_curve() 一起使用，設定阻尼屬性。

Parameter PARAM_ANGLE = 7

與 set_param_min()、set_param_max()、set_param_curve() 一起使用，設定角度屬性。

Parameter PARAM_SCALE = 8

與 set_param_min()、set_param_max()、set_param_curve() 一起使用，設定縮放屬性。

Parameter PARAM_HUE_VARIATION = 9

與 set_param_min()、set_param_max()、set_param_curve() 一起使用，設定色相變化屬性。

Parameter PARAM_ANIM_SPEED = 10

與 set_param_min()、set_param_max()、set_param_curve() 一起使用，設定動畫速度屬性。

Parameter PARAM_ANIM_OFFSET = 11

與 set_param_min()、set_param_max()、set_param_curve() 一起使用，設定動畫偏移屬性。

Parameter PARAM_MAX = 12

代表 Parameter 列舉的大小。

enum ParticleFlags: 🔗

ParticleFlags PARTICLE_FLAG_ALIGN_Y_TO_VELOCITY = 0

與 set_particle_flag() 一起使用，設定 particle_flag_align_y。

ParticleFlags PARTICLE_FLAG_ROTATE_Y = 1

與 set_particle_flag() 一起使用，設定 particle_flag_rotate_y。

ParticleFlags PARTICLE_FLAG_DISABLE_Z = 2

與 set_particle_flag() 一起使用，設定particle_flag_disable_z。

ParticleFlags PARTICLE_FLAG_MAX = 3

代表 ParticleFlags 列舉的大小。

enum EmissionShape: 🔗

EmissionShape EMISSION_SHAPE_POINT = 0

所有粒子將從單個點發射。

EmissionShape EMISSION_SHAPE_SPHERE = 1

粒子將在球體的體積中發射。

EmissionShape EMISSION_SHAPE_SPHERE_SURFACE = 2

粒子將在球體表面發射。

EmissionShape EMISSION_SHAPE_BOX = 3

粒子將在盒子的體積中發射。

EmissionShape EMISSION_SHAPE_POINTS = 4

粒子將在 emission_points 中隨機選擇的位置發射。粒子顏色將通過 emission_colors 進行調變。

EmissionShape EMISSION_SHAPE_DIRECTED_POINTS = 5

粒子將在 emission_points 中隨機選擇的位置發射。粒子的速度和旋轉將基於 emission_normals 進行設定。粒子顏色將通過 emission_colors 進行調變。

EmissionShape EMISSION_SHAPE_RING = 6

粒子將以環形或圓柱的形式發射出來。

EmissionShape EMISSION_SHAPE_MAX = 7

代表 EmissionShape 列舉的大小。

屬性說明

int amount = 8 🔗

  • void set_amount(value: int)

  • int get_amount()

單個發射週期內發射的粒子數。

Curve angle_curve 🔗

Each particle's rotation will be animated along this Curve. Should be a unit Curve.

float angle_max = 0.0 🔗

最大角度。

float angle_min = 0.0 🔗

最小角度。

Curve angular_velocity_curve 🔗

Each particle's angular velocity (rotation speed) will vary along this Curve over its lifetime. Should be a unit Curve.

float angular_velocity_max = 0.0 🔗

套用於每個粒子的最大初始角速度（旋轉速度），單位：度每秒。

float angular_velocity_min = 0.0 🔗

套用於每個粒子的最小初始角速度（旋轉速度），單位：度每秒 。

Curve anim_offset_curve 🔗

Each particle's animation offset will vary along this Curve. Should be a unit Curve.

float anim_offset_max = 0.0 🔗

最大動畫偏移。

float anim_offset_min = 0.0 🔗

最小動畫偏移。

Curve anim_speed_curve 🔗

Each particle's animation speed will vary along this Curve. Should be a unit Curve.

float anim_speed_max = 0.0 🔗

最大粒子動畫速度。

float anim_speed_min = 0.0 🔗

最小粒子動畫速度。

Color color = Color(1, 1, 1, 1) 🔗

每個粒子的初始顏色。

注意：color 乘以粒子網格的頂點顏色。要在 BaseMaterial3D 上產生可見效果，BaseMaterial3D.vertex_color_use_as_albedo 必須為 true。對於 ShaderMaterial，必須在著色器的 fragment() 函式中插入 ALBEDO *= COLOR.rgb;。否則，color 將沒有可見效果。

Gradient color_initial_ramp 🔗

  • void set_color_initial_ramp(value: Gradient)

  • Gradient get_color_initial_ramp()

Each particle's initial color will vary along this Gradient (multiplied with color).

Note: color_initial_ramp multiplies the particle mesh's vertex colors. To have a visible effect on a BaseMaterial3D, BaseMaterial3D.vertex_color_use_as_albedo must be true. For a ShaderMaterial, ALBEDO *= COLOR.rgb; must be inserted in the shader's fragment() function. Otherwise, color_initial_ramp will have no visible effect.

Gradient color_ramp 🔗

Each particle's color will vary along this Gradient over its lifetime (multiplied with color).

Note: color_ramp multiplies the particle mesh's vertex colors. To have a visible effect on a BaseMaterial3D, BaseMaterial3D.vertex_color_use_as_albedo must be true. For a ShaderMaterial, ALBEDO *= COLOR.rgb; must be inserted in the shader's fragment() function. Otherwise, color_ramp will have no visible effect.

Curve damping_curve 🔗

Damping will vary along this Curve. Should be a unit Curve.

float damping_max = 0.0 🔗

最大阻尼。

float damping_min = 0.0 🔗

最小阻尼。

Vector3 direction = Vector3(1, 0, 0) 🔗

指定粒子發射方向的單位向量。

DrawOrder draw_order = 0 🔗

Particle draw order.

Vector3 emission_box_extents 🔗

  • void set_emission_box_extents(value: Vector3)

  • Vector3 get_emission_box_extents()

emission_shape 被設定為 EMISSION_SHAPE_BOX 時，該矩形的範圍。

PackedColorArray emission_colors = PackedColorArray() 🔗

設定使用 EMISSION_SHAPE_POINTS 或 EMISSION_SHAPE_DIRECTED_POINTS 時對粒子進行調變的 Color。

注意：emission_colors 會與粒子網格的頂點顏色相乘。要在 BaseMaterial3D 上產生可見效果，BaseMaterial3D.vertex_color_use_as_albedo 必須為 true。對於 ShaderMaterial，必須在著色器的 fragment() 函式中插入 ALBEDO *= COLOR.rgb;。否則 emission_colors 不會產生可見效果。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedColorArray for more details.

PackedVector3Array emission_normals 🔗

設定使用 EMISSION_SHAPE_DIRECTED_POINTS 時粒子發射的方向。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedVector3Array for more details.

PackedVector3Array emission_points 🔗

設定使用 EMISSION_SHAPE_POINTS 或 EMISSION_SHAPE_DIRECTED_POINTS 時出生粒子的初始位置。

Note: The returned array is copied and any changes to it will not update the original property value. See PackedVector3Array for more details.

Vector3 emission_ring_axis 🔗

  • void set_emission_ring_axis(value: Vector3)

  • Vector3 get_emission_ring_axis()

使用形為 EMISSION_SHAPE_RING 的發射器時環的軸。

float emission_ring_cone_angle 🔗

  • void set_emission_ring_cone_angle(value: float)

  • float get_emission_ring_cone_angle()

The angle of the cone when using the emitter EMISSION_SHAPE_RING. The default angle of 90 degrees results in a ring, while an angle of 0 degrees results in a cone. Intermediate values will result in a ring where one end is larger than the other.

Note: Depending on emission_ring_height, the angle may be clamped if the ring's end is reached to form a perfect cone.

float emission_ring_height 🔗

  • void set_emission_ring_height(value: float)

  • float get_emission_ring_height()

使用形為 EMISSION_SHAPE_RING 的發射器時環的高度。

float emission_ring_inner_radius 🔗

  • void set_emission_ring_inner_radius(value: float)

  • float get_emission_ring_inner_radius()

使用形為 EMISSION_SHAPE_RING 的發射器時環的內半徑。

float emission_ring_radius 🔗

  • void set_emission_ring_radius(value: float)

  • float get_emission_ring_radius()

使用形為 EMISSION_SHAPE_RING 的發射器時環的半徑。

EmissionShape emission_shape = 0 🔗

Particles will be emitted inside this region.

float emission_sphere_radius 🔗

  • void set_emission_sphere_radius(value: float)

  • float get_emission_sphere_radius()

EmissionShape 被設定為 EMISSION_SHAPE_SPHERE時，該球體的半徑。

bool emitting = true 🔗

  • void set_emitting(value: bool)

  • bool is_emitting()

如果 true，則正在發射粒子。emitting 可用於啟動和停止粒子發射。但是，如果 one_shot 為 true `` 將\ :ref:`emitting<class_CPUParticles3D_property_emitting>` 設為\ ``true 直到所有活動粒子完成處理後才會重新啟動發射週期。一旦所有活動粒子都完成，您可以使用finished 訊號來通知粒子完成處理。

float explosiveness = 0.0 🔗

  • void set_explosiveness_ratio(value: float)

  • float get_explosiveness_ratio()

粒子在單個發射週期中的發射有多急。如果大於 0，則在下一個發射週期開始之前，發射會出現一個間隔。

int fixed_fps = 0 🔗

  • void set_fixed_fps(value: int)

  • int get_fixed_fps()

粒子系統的畫面播放速率被固定為一個值。例如，將值更改為 2 會使粒子以每秒 2 影格的速度算繪。請注意，這並不會降低粒子系統本身的速度。

float flatness = 0.0 🔗

  • void set_flatness(value: float)

  • float get_flatness()

Y/Z 平面中的 spread 數量。值 1 將粒子限制在 X/Z 平面上。

bool fract_delta = true 🔗

  • void set_fractional_delta(value: bool)

  • bool get_fractional_delta()

如果為 為true，則使用分數差異量 delta 計算，將具有更平滑的粒子顯示效果。

Vector3 gravity = Vector3(0, -9.8, 0) 🔗

套用於每個粒子的重力。

Curve hue_variation_curve 🔗

Each particle's hue will vary along this Curve. Should be a unit Curve.

float hue_variation_max = 0.0 🔗

最大色相變化。

float hue_variation_min = 0.0 🔗

最小色相變化。

float initial_velocity_max = 0.0 🔗

初始速度的最大值。

float initial_velocity_min = 0.0 🔗

初始速度的最小值。

float lifetime = 1.0 🔗

  • void set_lifetime(value: float)

  • float get_lifetime()

每個粒子存在的時間。

float lifetime_randomness = 0.0 🔗

  • void set_lifetime_randomness(value: float)

  • float get_lifetime_randomness()

粒子壽命隨機率。

Curve linear_accel_curve 🔗

Each particle's linear acceleration will vary along this Curve. Should be a unit Curve.

float linear_accel_max = 0.0 🔗

最大線性加速度。

float linear_accel_min = 0.0 🔗

最小線性加速度。

bool local_coords = false 🔗

  • void set_use_local_coordinates(value: bool)

  • bool get_use_local_coordinates()

如果為 true，粒子使用父節點的座標空間（稱為局部座標）。這將導致粒子在移動或旋轉時，沿著 CPUParticles3D 節點（及其父節點）移動和旋轉。如果為 false，則粒子使用全域座標；當移動或旋轉時，它們不會沿著 CPUParticles3D 節點（及其父節點）移動或旋轉。

Mesh mesh 🔗

  • void set_mesh(value: Mesh)

  • Mesh get_mesh()

每個粒子使用的 Mesh。如果為 null，則粒子將為球形。

bool one_shot = false 🔗

  • void set_one_shot(value: bool)

  • bool get_one_shot()

如果為 true，則只發生一個發射週期。如果在某個週期內設定為 true，則發射將在該週期結束時停止。

Curve orbit_velocity_curve 🔗

Each particle's orbital velocity will vary along this Curve. Should be a unit Curve.

float orbit_velocity_max 🔗

最大軌道速度。

float orbit_velocity_min 🔗

最小軌道速度。

bool particle_flag_align_y = false 🔗

將粒子的 Y 軸與其速度方向對齊。

bool particle_flag_disable_z = false 🔗

如果為 true，則粒子將不會在 Z 軸上移動。

bool particle_flag_rotate_y = false 🔗

如果為 true，則粒子繞 Y 軸旋轉 angle_min。

float preprocess = 0.0 🔗

  • void set_pre_process_time(value: float)

  • float get_pre_process_time()

粒子系統啟動時就好像已經運作了這麼多秒一樣。

Curve radial_accel_curve 🔗

Each particle's radial acceleration will vary along this Curve. Should be a unit Curve.

float radial_accel_max = 0.0 🔗

最大徑向加速度。

float radial_accel_min = 0.0 🔗

最小徑向加速度。

float randomness = 0.0 🔗

  • void set_randomness_ratio(value: float)

  • float get_randomness_ratio()

發射壽命隨機率。

Curve scale_amount_curve 🔗

Each particle's scale will vary along this Curve. Should be a unit Curve.

float scale_amount_max = 1.0 🔗

最大縮放。

float scale_amount_min = 1.0 🔗

最小縮放。

Curve scale_curve_x 🔗

  • void set_scale_curve_x(value: Curve)

  • Curve get_scale_curve_x()

生命週期內，沿 X 軸的縮放曲線。

Curve scale_curve_y 🔗

  • void set_scale_curve_y(value: Curve)

  • Curve get_scale_curve_y()

生命週期內，沿 Y 軸的縮放曲線。

Curve scale_curve_z 🔗

  • void set_scale_curve_z(value: Curve)

  • Curve get_scale_curve_z()

生命週期內，沿 Z 軸的縮放曲線。

int seed = 0 🔗

  • void set_seed(value: int)

  • int get_seed()

Sets the random seed used by the particle system. Only effective if use_fixed_seed is true.

float speed_scale = 1.0 🔗

  • void set_speed_scale(value: float)

  • float get_speed_scale()

粒子系統的運作速度的縮放率。0 值可用於暫停粒子。

bool split_scale = false 🔗

  • void set_split_scale(value: bool)

  • bool get_split_scale()

如果設定為 true，則可以指定三條不同的縮放曲線，每個縮放軸一條。

float spread = 45.0 🔗

  • void set_spread(value: float)

  • float get_spread()

每個粒子的初始方向範圍為 +spread 至 -spread 度。適用於 X/Z 平面和 Y/Z 平面。

Curve tangential_accel_curve 🔗

Each particle's tangential acceleration will vary along this Curve. Should be a unit Curve.

float tangential_accel_max = 0.0 🔗

最大切向加速度。

float tangential_accel_min = 0.0 🔗

最小切向加速度。

bool use_fixed_seed = false 🔗

  • void set_use_fixed_seed(value: bool)

  • bool get_use_fixed_seed()

If true, particles will use the same seed for every simulation using the seed defined in seed. This is useful for situations where the visual outcome should be consistent across replays, for example when using Movie Maker mode.

AABB visibility_aabb = AABB(0, 0, 0, 0, 0, 0) 🔗

  • void set_visibility_aabb(value: AABB)

  • AABB get_visibility_aabb()

The AABB that determines the node's region which needs to be visible on screen for the particle system to be active.

Grow the box if particles suddenly appear/disappear when the node enters/exits the screen. The AABB can be grown via code or with the Particles → Generate AABB editor tool.

方法說明

AABB capture_aabb() const 🔗

返回包含目前影格中所有活動粒子的軸對齊邊界框。

void convert_from_particles(particles: Node) 🔗

設定該節點的屬性以配對給定的 GPUParticles3D 節點，該給定節點已分配了一個 ParticleProcessMaterial。

Curve get_param_curve(param: Parameter) const 🔗

返回由 Parameter 指定的參數的 Curve。

float get_param_max(param: Parameter) const 🔗

返回給定參數的最大值範圍。

float get_param_min(param: Parameter) const 🔗

返回給定參數的最小值範圍。

bool get_particle_flag(particle_flag: ParticleFlags) const 🔗

Returns the enabled state of the given particle flag.

void request_particles_process(process_time: float, process_time_residual: float = 0.0) 🔗

Requests the particles to process for extra process time during a single frame.

process_time defines the time that the particles will process while emitting is on. process_time_residual defines the time that particles will process with emitting turned off for the simulation. When combined with speed_scale set to 0.0, this is useful to be able to seek a particle system timeline.

void restart(keep_seed: bool = false) 🔗

Restarts the particle emitter.

If keep_seed is true, the current random seed will be preserved. Useful for seeking and playback.

void set_param_curve(param: Parameter, curve: Curve) 🔗

Sets the Curve of the parameter specified by Parameter. Should be a unit Curve.

void set_param_max(param: Parameter, value: float) 🔗

設定給定參數的最大值。

void set_param_min(param: Parameter, value: float) 🔗

設定給定參數的最小值。

void set_particle_flag(particle_flag: ParticleFlags, enable: bool) 🔗

Enables or disables the given particle flag.