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。
教程
属性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法
capture_aabb() const |
|
void |
convert_from_particles(particles: Node) |
void |
emit_particle(xform: Transform3D, velocity: Vector3, color: Color, custom: Color, flags: int) |
get_draw_pass_mesh(pass: int) const |
|
void |
request_particles_process(process_time: float) |
void |
|
void |
set_draw_pass_mesh(pass: int, mesh: Mesh) |
信号
finished() 🔗
所有活动粒子完成处理时发出。立即重启发射周期请调用 restart()。
禁用 one_shot 时不会发出该信号，因为会持续发出并处理粒子。
注意：由于粒子是在 GPU 上计算的，所以 one_shot 的发射器在收到该信号后可能存在一小段特殊时期，在此期间将 emitting 设为 true 无法重启发射周期。改成调用 restart() 就可以避免这段延迟。
枚举
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 🔗
支持的最大绘制阶段数。
属性说明
一个发射周期内发射的粒子数。有效发射速率为每秒 (amount * amount_ratio) / lifetime 个粒子。较高的值会增加 GPU 要求，即使在给定时间并非所有粒子都可见或 amount_ratio 减少。
注意：更改该值将导致粒子系统重新启动。为了避免这种情况，请更改 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 🔗
粒子碰撞的基本直径（以米为单位）。如果碰撞时粒子似乎沉入地下，请增加该值。如果粒子在碰撞时出现漂浮，请减小该值。仅当 ParticleProcessMaterial.collision_mode 为 ParticleProcessMaterial.COLLISION_RIGID 或 ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT 时有效。
注意：粒子始终具有球形碰撞形状。
粒子绘制顺序。使用 DrawOrder 值。
注意：DRAW_ORDER_INDEX 是支持 TAA 等效果的运动向量的唯一选项。如果粒子不透明，建议使用该绘制顺序来修复重影伪影。
第一绘制阶段所绘制的 Mesh。
第二绘制阶段所绘制的 Mesh。
第三绘制阶段所绘制的 Mesh。
第四绘制阶段所绘制的 Mesh。
渲染粒子时的绘制阶段数。
该属性目前没有描述，请帮我们贡献一个吧！
如果为 true，则正在发射粒子。emitting 可用于启动和停止粒子发射。但是，如果 one_shot 为 true，则将 emitting 设置为 true 将不会重新启动该发射循环，除非所有活动粒子都已完成处理。一旦所有活动粒子完成处理，可以使用 finished 信号来收取通知。
注意：对于 one_shot 发射器，由于粒子是在 GPU 上计算的，因此在收到 finished 信号后可能会有一段短暂的时间，在此期间将其设置为 true 将不会重新启动发射循环。
提示：如果你的 one_shot 发射器需要在收到 finished 信号后立即重新启动发射粒子，请考虑调用 restart() 而不是设置 emitting。
每次发射之间的时间比。如果为 0，则粒子是连续发射的。如果为 1，则所有的粒子都同时发射。
粒子系统的帧速率被固定为一个值。例如，将值更改为 2 会使粒子以每秒 2 帧的速度渲染。请注意，这并不会降低粒子系统本身的模拟速度。
如果为 为true，则使用分数增量 delta 计算，将具有更平滑的粒子显示效果。
导致该节点中的所有粒子插值到其生命周期结束时。
注意：这仅在与 ParticleProcessMaterial 一起使用时才有效。对于自定义进程着色器，需要手动实现。
启用粒子插值，当fixed_fps 低于屏幕刷新率时，使粒子运动更平滑。
每个粒子存在的时间（以秒为单位）。有效发射速率为每秒 (amount * amount_ratio) / lifetime 个粒子。
如果为 true，则粒子使用父节点的坐标空间（称为局部坐标）。这将导致粒子在移动或旋转时沿着 GPUParticles3D 节点（及其父节点）移动和旋转。如果为 false，则粒子使用全局坐标；当移动或旋转时，它们不会沿着 GPUParticles3D 节点（及其父节点）移动或旋转。
如果为 true，将只发出 amount 数量的粒子。
动画开始之前预处理粒子的时间量。允许你在粒子开始发射后的一段时间内启动动画。
注意：如果设置为较高的数字可能会非常耗费资源，因为它需要每秒运行与 fixed_fps 相等的次数的粒子着色器（如果 fixed_fps 为 0 则为 30 次）。在极端情况下，这甚至可能导致 GPU 崩溃，因为在单个帧中完成的工作量过大。
用于处理粒子的 Material 。可以是 ParticleProcessMaterial 或 ShaderMaterial 。
发出随机率。
设置粒子系统所使用的随机数种子。仅在 use_fixed_seed 为 true 时有效。
速度缩放比例。0 的值可被用于暂停粒子。
NodePath sub_emitter = NodePath("") 🔗
到将被用作子发射器（请参阅 ParticleProcessMaterial.sub_emitter_mode）的另一个 GPUParticles3D 节点的路径。子发射器可被用于实现烟花、碰撞火花、气泡弹出水滴等效果。
注意：当 sub_emitter 被设置时，该目标 GPUParticles3D 节点将不再自行发射粒子。
如果为 true，则使用网格蒙皮系统来启用粒子尾迹。旨在与 RibbonTrailMesh 和 TubeTrailMesh 一起使用。
注意：还必须在粒子网格的材质上启用 BaseMaterial3D.use_particle_trails。否则，将 trail_enabled 设置为 true 将无效。
注意：与 GPUParticles2D 不同，尾迹部分及其细分的数量是在 RibbonTrailMesh 或 TubeTrailMesh 的属性中设置的。
代表粒子轨迹的时间量（以秒为单位）。仅当 trail_enabled 为 true 时有效。
TransformAlign transform_align = 0 🔗
void set_transform_align(value: TransformAlign)
TransformAlign get_transform_align()
该属性目前没有描述，请帮我们贡献一个吧！
如果为 true，则每次模拟中粒子会使用 seed 中定义的种子。适用于需要在重放时保持视觉效果一致的情况，例如使用 Movie Maker 模式时。
AABB visibility_aabb = AABB(-4, -4, -4, 8, 8, 8) 🔗
AABB 确定节点的区域，该区域需要在屏幕上可见，才能使粒子系统处于活动状态。GeometryInstance3D.extra_cull_margin 被添加到 AABB 的每个轴上。粒子碰撞和吸引只会发生在该区域内。
如果在节点进入/退出屏幕时，粒子突然出现/消失，则应该增大矩形。AABB 可以通过代码，或使用 粒子 → 生成 AABB 编辑器工具生成。
注意：如果该属性被设置为非默认值，visibility_aabb 会被 GeometryInstance3D.custom_aabb 覆盖。
方法说明
返回包含当前帧中所有活动粒子的轴对齐边界框。
void convert_from_particles(particles: Node) 🔗
设置该节点的属性以匹配给定的 CPUParticles3D 节点。
void emit_particle(xform: Transform3D, velocity: Vector3, color: Color, custom: Color, flags: int) 🔗
发射单个粒子。是否应用 xform、velocity、color 和 custom 取决于 flags 的值。见 EmitFlags。
默认的 ParticleProcessMaterial 会覆盖 color，使用 custom 的内容作为 (rotation, age, animation, lifetime)。
注意：emit_particle() 只有 Forward+ 和 Mobile 渲染方法支持，Compatibility 不支持。
Mesh get_draw_pass_mesh(pass: int) const 🔗
返回在索引 pass 处绘制的 Mesh 。
void request_particles_process(process_time: float) 🔗
请求让粒子在一帧中使用额外的处理时间进行处理。
适用于粒子回放，需要与 use_fixed_seed 配合使用，或者调用 restart() 时将 keep_seed 参数设为 true。
void restart(keep_seed: bool = false) 🔗
重新开始粒子发射周期，清除现存粒子。要避免粒子从视口中凭空消失，请在调用前等待 finished 信号。
注意：只有 one_shot 的发射器会发出 finished 信号。
如果 keep_seed 为 true，则会保留当前的随机数种子。适用于跳转播放。
void set_draw_pass_mesh(pass: int, mesh: Mesh) 🔗
设置在索引 pass 处绘制的 Mesh 。