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)

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

粒子按照剩余寿命的顺序绘制。换句话说，寿命最长的粒子被绘制在前面。

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 🔗

每个粒子的旋转将沿着这个 Curve 进行动画。应当为单位 Curve。

float angle_max = 0.0 🔗

最大角度。

float angle_min = 0.0 🔗

最小角度。

Curve angular_velocity_curve 🔗

每个粒子的角速度（旋转速度）将在其生命周期内沿着这个 Curve 变化。应当为单位 Curve。

float angular_velocity_max = 0.0 🔗

应用于每个粒子的最大初始角速度（旋转速度），单位：度每秒。

float angular_velocity_min = 0.0 🔗

应用于每个粒子的最小初始角速度（旋转速度），单位：度每秒 。

Curve anim_offset_curve 🔗

每个粒子的动画偏移将沿着这个 Curve 变化。应当为单位 Curve。

float anim_offset_max = 0.0 🔗

最大动画偏移。

float anim_offset_min = 0.0 🔗

最小动画偏移。

Curve anim_speed_curve 🔗

每个粒子的动画速度将沿着这个 Curve 变化。应当为单位 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()

每个粒子的初始颜色将沿着该 Gradient 变化（乘以 color）。

注意：color_initial_ramp 会与粒子网格的顶点颜色相乘。要在 BaseMaterial3D 上产生可见效果，BaseMaterial3D.vertex_color_use_as_albedo 必须为 true。对于 ShaderMaterial，必须在着色器的 fragment() 函数中插入 ALBEDO *= COLOR.rgb;。否则 color_initial_ramp 将没有可见效果。

Gradient color_ramp 🔗

每个粒子的颜色将在其生命周期内沿该 Gradient 变化（乘以 color）。

注意：color_ramp 会与粒子网格的顶点颜色相乘。要在 BaseMaterial3D 上产生可见效果，BaseMaterial3D.vertex_color_use_as_albedo 必须为 true。对于 ShaderMaterial，必须在着色器的 fragment() 函数中插入 ALBEDO *= COLOR.rgb;。否则 color_ramp 将没有可见效果。

Curve damping_curve 🔗

阻尼将沿着这个 Curve 变化。应当为单位 Curve。

float damping_max = 0.0 🔗

最大阻尼。

float damping_min = 0.0 🔗

最小阻尼。

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

指定粒子发射方向的单位向量。

DrawOrder draw_order = 0 🔗

粒子绘制顺序。使用 DrawOrder 的值。

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

使用形为 EMISSION_SHAPE_RING 的发射器时圆锥体的张角。默认的 90 度角会得到一个环，而 0 度角则会得到椎体。两者之间的值会得到一端大于另一端的环。

注意：根据 emission_ring_height 的不同，圆环的末端形成尖顶时可能会对角度进行限制。

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 🔗

粒子将在此区域内发射。可能的取值见 EmissionShape。

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，则将 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 🔗

每个粒子的色相将沿着这个 Curve 变化。应当为单位 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 🔗

每个粒子的线性加速度将沿着这个 Curve 变化。应当为单位 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 🔗

每个粒子的轨道速度将沿着这个 Curve 变化。应当为单位 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 🔗

每个粒子的径向加速度将沿着这个 Curve 变化。应当为单位 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 🔗

每个粒子的缩放将沿着这个 Curve 变化。应当为单位 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()

设置粒子系统所使用的随机数种子。仅在 use_fixed_seed 为 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 🔗

每个粒子的切向加速度将沿着这个 Curve 变化。应当为单位 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()

如果为 true，则每次模拟中粒子会使用 seed 中定义的种子。适用于需要在重放时保持视觉效果一致的情况，例如使用 Movie Maker 模式时。

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

  • void set_visibility_aabb(value: AABB)

  • AABB get_visibility_aabb()

AABB 确定节点的区域，该区域需要在屏幕上可见才能使粒子系统处于活动状态。

如果当节点进入/退出屏幕时粒子突然出现/消失，则增大盒子。AABB 可以通过代码或使用 粒子 → 生成 AABB 编辑器工具来生成。

方法说明

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 🔗

返回给定粒子标志的启用状态（选项见 ParticleFlags）。

void request_particles_process(process_time: float) 🔗

请求让粒子在一帧中使用额外的处理时间进行处理。

适用于粒子回放，需要与 use_fixed_seed 配合使用，或者调用 restart() 时将 keep_seed 参数设为 true。

void restart(keep_seed: bool = false) 🔗

重启粒子发射器。

如果 keep_seed 为 true，则会保留当前的随机数种子。适用于跳转和播放。

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

设置 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) 🔗

启用或禁用给定的粒子标志（选项见 ParticleFlags）。