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

GPUParticles3D

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

3D 粒子发射器。

描述

3D 粒子节点，用于创建各种粒子系统和效果。GPUParticles3D 的特点是，发射器以给定的速度产生一定数量的粒子。

使用 process_material 属性来添加一个配置粒子外观和行为的 ParticleProcessMaterial。或者，你可以添加一个应用于所有粒子的 ShaderMaterial。

教程

属性

int

amount

8

float

amount_ratio

1.0

float

collision_base_size

0.01

DrawOrder

draw_order

0

Mesh

draw_pass_1

Mesh

draw_pass_2

Mesh

draw_pass_3

Mesh

draw_pass_4

int

draw_passes

1

Skin

draw_skin

bool

emitting

true

float

explosiveness

0.0

int

fixed_fps

30

bool

fract_delta

true

float

interp_to_end

0.0

bool

interpolate

true

float

lifetime

1.0

bool

local_coords

false

bool

one_shot

false

float

preprocess

0.0

Material

process_material

float

randomness

0.0

float

speed_scale

1.0

NodePath

sub_emitter

NodePath("")

bool

trail_enabled

false

float

trail_lifetime

0.3

TransformAlign

transform_align

0

AABB

visibility_aabb

AABB(-4, -4, -4, 8, 8, 8)

方法

AABB

capture_aabb ( ) const

void

convert_from_particles ( Node particles )

void

emit_particle ( Transform3D xform, Vector3 velocity, Color color, Color custom, int flags )

Mesh

get_draw_pass_mesh ( int pass ) const

void

restart ( )

void

set_draw_pass_mesh ( int pass, Mesh mesh )

信号

finished ( )

当所有活动粒子完成处理时发出。当 one_shot 被禁用时，粒子将连续处理，因此它永远不会发出。

注意：由于粒子是在 GPU 上计算的，因此在该信号发出之前可能会有延迟。

枚举

enum DrawOrder:

DrawOrder DRAW_ORDER_INDEX = 0

粒子按发射顺序绘制。

DrawOrder DRAW_ORDER_LIFETIME = 1

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

DrawOrder DRAW_ORDER_REVERSE_LIFETIME = 2

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

DrawOrder DRAW_ORDER_VIEW_DEPTH = 3

粒子按深度顺序绘制。

enum EmitFlags:

EmitFlags EMIT_FLAG_POSITION = 1

粒子在指定位置开始。

EmitFlags EMIT_FLAG_ROTATION_SCALE = 2

粒子以指定的旋转和缩放开始。

EmitFlags EMIT_FLAG_VELOCITY = 4

粒子从指定的速度向量开始，该向量定义了发射方向和速度。

EmitFlags EMIT_FLAG_COLOR = 8

粒子以指定的颜色开始。

EmitFlags EMIT_FLAG_CUSTOM = 16

粒子以指定的 CUSTOM 数据开始。

enum TransformAlign:

TransformAlign TRANSFORM_ALIGN_DISABLED = 0

TransformAlign TRANSFORM_ALIGN_Z_BILLBOARD = 1

TransformAlign TRANSFORM_ALIGN_Y_TO_VELOCITY = 2

TransformAlign TRANSFORM_ALIGN_Z_BILLBOARD_Y_TO_VELOCITY = 3

常量

MAX_DRAW_PASSES = 4

支持的最大绘制阶段数。

属性说明

int amount = 8

  • void set_amount ( int value )

  • int get_amount ( )

一个发射周期内发射的粒子数。有效发射速率为每秒 (amount * amount_ratio) / lifetime 个粒子。较高的值会增加 GPU 要求，即使在给定时间并非所有粒子都可见或 amount_ratio 减少。

注意：更改该值将导致粒子系统重新启动。为了避免这种情况，请更改 amount_ratio。

float amount_ratio = 1.0

  • void set_amount_ratio ( float value )

  • float get_amount_ratio ( )

实际应该发射的粒子的比率。如果被设置为低于 1.0 的值，则会将整个生命周期内发射的粒子数量设置为 amount * amount_ratio。与更改 amount 不同，发射时更改 amount_ratio 不会影响已发射的粒子，也不会导致粒子系统重新启动。amount_ratio 可用于创建使发射粒子的数量随时间变化的效果。

注意：减少 amount_ratio 不会带来性能优势，因为无论 amount_ratio 是多少，都需要为粒子总数 amount 分配和处理资源。如果你不打算在粒子发射时更改发射的粒子数量，请确保将 amount_ratio 设置为 1 并根据你的喜好更改 amount。

float collision_base_size = 0.01

  • void set_collision_base_size ( float value )

  • float get_collision_base_size ( )

粒子碰撞的基本直径（以米为单位）。如果碰撞时粒子似乎沉入地下，请增加该值。如果粒子在碰撞时出现漂浮，请减小该值。仅当 ParticleProcessMaterial.collision_mode 为 ParticleProcessMaterial.COLLISION_RIGID 或 ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT 时有效。

注意：粒子始终具有球形碰撞形状。

DrawOrder draw_order = 0

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

注意：DRAW_ORDER_INDEX 是支持 TAA 等效果的运动向量的唯一选项。如果粒子不透明，建议使用该绘制顺序来修复重影伪影。

Mesh draw_pass_1

  • void set_draw_pass_mesh ( int pass, Mesh mesh )

  • Mesh get_draw_pass_mesh ( int pass ) const

第一绘制阶段所绘制的 Mesh。

Mesh draw_pass_2

  • void set_draw_pass_mesh ( int pass, Mesh mesh )

  • Mesh get_draw_pass_mesh ( int pass ) const

第二绘制阶段所绘制的 Mesh。

Mesh draw_pass_3

  • void set_draw_pass_mesh ( int pass, Mesh mesh )

  • Mesh get_draw_pass_mesh ( int pass ) const

第三绘制阶段所绘制的 Mesh。

Mesh draw_pass_4

  • void set_draw_pass_mesh ( int pass, Mesh mesh )

  • Mesh get_draw_pass_mesh ( int pass ) const

第四绘制阶段所绘制的 Mesh。

int draw_passes = 1

  • void set_draw_passes ( int value )

  • int get_draw_passes ( )

渲染粒子时的绘制阶段数。

Skin draw_skin

  • void set_skin ( Skin value )

  • Skin get_skin ( )

目前没有这个属性的描述。请帮我们贡献一个！

bool emitting = true

  • void set_emitting ( bool value )

  • bool is_emitting ( )

如果为 true，则正在发射粒子。emitting 可用于启动和停止粒子发射。但是，如果 one_shot 为 true，则将 emitting 设置为 true 将不会重新启动该发射循环，直到所有活动粒子完成处理为止。一旦所有活动粒子完成处理，你可以使用 finished 信号来收取通知。

float explosiveness = 0.0

  • void set_explosiveness_ratio ( float value )

  • float get_explosiveness_ratio ( )

每次发射之间的时间比。如果为 0，则粒子是连续发射的。如果为 1，则所有的粒子都同时发射。

int fixed_fps = 30

  • void set_fixed_fps ( int value )

  • int get_fixed_fps ( )

粒子系统的帧速率被固定为一个值。例如，将值更改为 2 会使粒子以每秒 2 帧的速度渲染。请注意，这并不会降低粒子系统本身的模拟速度。

bool fract_delta = true

  • void set_fractional_delta ( bool value )

  • bool get_fractional_delta ( )

如果为 为true，则使用分数增量 delta 计算，将具有更平滑的粒子显示效果。

float interp_to_end = 0.0

  • void set_interp_to_end ( float value )

  • float get_interp_to_end ( )

导致该节点中的所有粒子插值到其生命周期结束时。

注意：这仅在与 ParticleProcessMaterial 一起使用时才有效。对于自定义进程着色器，需要手动实现。

bool interpolate = true

  • void set_interpolate ( bool value )

  • bool get_interpolate ( )

启用粒子插值，当fixed_fps 低于屏幕刷新率时，使粒子运动更平滑。

float lifetime = 1.0

  • void set_lifetime ( float value )

  • float get_lifetime ( )

每个粒子存在的时间（以秒为单位）。有效发射速率为每秒 (amount * amount_ratio) / lifetime 个粒子。

bool local_coords = false

  • void set_use_local_coordinates ( bool value )

  • bool get_use_local_coordinates ( )

如果为 true，则粒子使用父节点的坐标空间（称为局部坐标）。这将导致粒子在移动或旋转时沿着 GPUParticles3D 节点（及其父节点）移动和旋转。如果为 false，则粒子使用全局坐标；当移动或旋转时，它们不会沿着 GPUParticles3D 节点（及其父节点）移动或旋转。

bool one_shot = false

  • void set_one_shot ( bool value )

  • bool get_one_shot ( )

如果为 true，将只发出 amount 数量的粒子。

float preprocess = 0.0

  • void set_pre_process_time ( float value )

  • float get_pre_process_time ( )

动画开始前对粒子进行预处理的时间。让你在粒子开始发射后的一段时间内开始动画。

Material process_material

  • void set_process_material ( Material value )

  • Material get_process_material ( )

用于处理粒子的 Material 。可以是 ParticleProcessMaterial 或 ShaderMaterial 。

float randomness = 0.0

  • void set_randomness_ratio ( float value )

  • float get_randomness_ratio ( )

发出随机率。

float speed_scale = 1.0

  • void set_speed_scale ( float value )

  • float get_speed_scale ( )

速度缩放比例。0 的值可被用于暂停粒子。

NodePath sub_emitter = NodePath("")

到将被用作子发射器（请参阅 ParticleProcessMaterial.sub_emitter_mode）的另一个 GPUParticles3D 节点的路径。子发射器可被用于实现烟花、碰撞火花、气泡弹出水滴等效果。

注意：当 sub_emitter 被设置时，该目标 GPUParticles3D 节点将不再自行发射粒子。

bool trail_enabled = false

  • void set_trail_enabled ( bool value )

  • bool is_trail_enabled ( )

如果为 true，则使用网格蒙皮系统来启用粒子尾迹。旨在与 RibbonTrailMesh 和 TubeTrailMesh 一起使用。

注意：还必须在粒子网格的材质上启用 BaseMaterial3D.use_particle_trails。否则，将 trail_enabled 设置为 true 将无效。

注意：与 GPUParticles2D 不同，尾迹部分及其细分的数量是在 RibbonTrailMesh 或 TubeTrailMesh 的属性中设置的。

float trail_lifetime = 0.3

  • void set_trail_lifetime ( float value )

  • float get_trail_lifetime ( )

代表粒子轨迹的时间量（以秒为单位）。仅当 trail_enabled 为 true 时有效。

TransformAlign transform_align = 0

目前没有这个属性的描述。请帮我们贡献一个！

AABB visibility_aabb = AABB(-4, -4, -4, 8, 8, 8)

  • void set_visibility_aabb ( AABB value )

  • AABB get_visibility_aabb ( )

AABB 确定节点的区域，该区域需要在屏幕上可见，才能使粒子系统处于活动状态。GeometryInstance3D.extra_cull_margin 被添加到 AABB 的每个轴上。粒子碰撞和吸引只会发生在该区域内。

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

注意：如果该属性被设置为非默认值，visibility_aabb 会被 GeometryInstance3D.custom_aabb 覆盖。

方法说明

AABB capture_aabb ( ) const

返回包含当前帧中所有活动粒子的轴对齐边界框。

void convert_from_particles ( Node particles )

设置该节点的属性以匹配给定的 CPUParticles3D 节点。

void emit_particle ( Transform3D xform, Vector3 velocity, Color color, Color custom, int flags )

发射单个粒子。是否应用 xform、velocity、color 和 custom 取决于 flags 的值。请参阅 EmitFlags。

Mesh get_draw_pass_mesh ( int pass ) const

返回在索引 pass 处绘制的 Mesh 。

void restart ( )

重新发射粒子，清除现有的粒子。

void set_draw_pass_mesh ( int pass, Mesh mesh )

设置在索引 pass 处绘制的 Mesh 。