ParticlesGPU

继承： GeometryRender < VisualRender < Item3D < Item < Object

3D粒子发射器。

描述

用于创建各种粒子系统和效果的3D粒子节点。ParticlesGPU具有以给定速率生成一定数量粒子的发射器。

使用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
int	seed	0
float	speed_scale	1.0
ItemPath	sub_emitter	ItemPath("")
bool	trail_enabled	false
float	trail_lifetime	0.3
TransformAlign	transform_align	0
bool	use_fixed_seed	false
AABB	visibility_aabb	AABB(-4, -4, -4, 8, 8, 8)

方法

AABB	capture_aabb() const
void	convert_from_particles(particles: Item)
void	emit_particle(xform: Transform3D, velocity: Vector3, color: Color, custom: Color, flags: int)
Mesh	get_draw_pass_mesh(pass: int) const
void	request_particles_process(process_time: float)
void	restart(keep_seed: bool = false)
void	set_draw_pass_mesh(pass: int, mesh: Mesh)

---

信号

finished() 🔗

当所有活性粒子都完成处理时发射。要立即重新启动发射循环，请调用restart()。

当禁用one_shot时，此信号永远不会发出，因为粒子将被连续发出和处理。

注意：对于one_shot发射器，由于粒子正在GPU上计算，在接收到信号后可能会有一段短时间，在此期间将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 🔗

支持的最大绘制通道数。

---

属性说明

int amount = 8 🔗

• void set_amount(value: int)

• int get_amount()

在一个发射周期内发射的粒子数量。有效发射速率为每秒（量*amount_ratio）/寿命粒子。更高的值将增加GPU要求，即使在给定时间并非所有粒子都可见或amount_ratio减少。

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

---

float amount_ratio = 1.0 🔗

• void set_amount_ratio(value: float)

• float get_amount_ratio()

实际应该发射的粒子的比例。如果设置为低于1.0的值，这将在整个生命周期内将发射粒子的数量设置为量*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(value: float)

• float get_collision_base_size()

粒子碰撞的基本直径，以米为单位。如果粒子在碰撞时看起来沉入地下，则增加该值。如果粒子在碰撞时看起来漂浮，则减少该值。仅当ParticleProcessMaterial.collision_mode为ParticleProcessMaterial.COLLISION_RIGID或ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT时有效。

注意：粒子总是具有球形碰撞形状。

---

DrawOrder draw_order = 0 🔗

• void set_draw_order(value: DrawOrder)

• DrawOrder get_draw_order()

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

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

---

Mesh draw_pass_1 🔗

• void set_draw_pass_mesh(pass: int, mesh: Mesh)

• Mesh get_draw_pass_mesh(pass: int) const

为第一次绘制通道绘制的Mesh。

---

Mesh draw_pass_2 🔗

• void set_draw_pass_mesh(pass: int, mesh: Mesh)

• Mesh get_draw_pass_mesh(pass: int) const

为第二次绘制通道绘制的Mesh。

---

Mesh draw_pass_3 🔗

• void set_draw_pass_mesh(pass: int, mesh: Mesh)

• Mesh get_draw_pass_mesh(pass: int) const

Mesh为第三次抽签而绘制。

---

Mesh draw_pass_4 🔗

• void set_draw_pass_mesh(pass: int, mesh: Mesh)

• Mesh get_draw_pass_mesh(pass: int) const

Mesh为第四次抽签而绘制。

---

int draw_passes = 1 🔗

• void set_draw_passes(value: int)

• int get_draw_passes()

渲染粒子时的绘制次数。

---

Skin draw_skin 🔗

• void set_skin(value: Skin)

• Skin get_skin()

---

bool emitting = true 🔗

• void set_emitting(value: bool)

• bool is_emitting()

如果true，则粒子正在发射。emitting可用于启动和停止粒子发射。但是，如果one_shot是true，则将emitting设置为true不会重新启动发射循环，除非所有活动粒子都完成处理。一旦所有活动粒子完成处理，请使用finished信号进行通知。

注意：对于one_shot发射器，由于粒子在GPU上被计算，在接收到finished信号后可能会有一段短时间，在此期间将其设置为true不会重新启动发射循环。

提示：如果您的one_shot发射器需要在收到finished信号后立即重新启动发射粒子，请考虑调用restart()而不是设置emitting。

---

float explosiveness = 0.0 🔗

• void set_explosiveness_ratio(value: float)

• float get_explosiveness_ratio()

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

---

int fixed_fps = 30 🔗

• void set_fixed_fps(value: int)

• int get_fixed_fps()

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

---

bool fract_delta = true 🔗

• void set_fractional_delta(value: bool)

• bool get_fractional_delta()

如果true，则导致分数增量计算，具有更平滑的粒子显示效果。

---

float interp_to_end = 0.0 🔗

• void set_interp_to_end(value: float)

• float get_interp_to_end()

使此节点中的所有粒子在其生命周期结束时进行插值。

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

---

bool interpolate = true 🔗

• void set_interpolate(value: bool)

• bool get_interpolate()

启用粒子插值，当它们的fixed_fps低于屏幕刷新率时，粒子移动更加平滑。

---

float lifetime = 1.0 🔗

• void set_lifetime(value: float)

• float get_lifetime()

每个粒子将存在的时间量（以秒为单位）有效发射率为（量*amount_ratio）/寿命粒子每秒。

---

bool local_coords = false 🔗

• void set_use_local_coordinates(value: bool)

• bool get_use_local_coordinates()

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

---

bool one_shot = false 🔗

• void set_one_shot(value: bool)

• bool get_one_shot()

如果true，则只会发射等于amount的粒子数。

---

float preprocess = 0.0 🔗

• void set_pre_process_time(value: float)

• float get_pre_process_time()

动画开始前预处理粒子的时间量。让您在粒子开始发射后的一段时间开始动画。

注意：如果设置为高数字，这可能非常昂贵，因为它需要每秒运行粒子着色器的次数等于fixed_fps（或30，如果fixed_fps为0）。在极端情况下，由于单个帧中完成的工作量，它甚至可能导致GPU崩溃。

---

Material process_material 🔗

• void set_process_material(value: Material)

• Material get_process_material()

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

---

float randomness = 0.0 🔗

• void set_randomness_ratio(value: float)

• float get_randomness_ratio()

排放随机性比。

---

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的值可用于暂停粒子。

---

ItemPath sub_emitter = ItemPath("") 🔗

• void set_sub_emitter(value: ItemPath)

• ItemPath get_sub_emitter()

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

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

---

bool trail_enabled = false 🔗

• void set_trail_enabled(value: bool)

• bool is_trail_enabled()

如果true，则使用网格蒙皮系统启用粒子轨迹。设计用于与RibbonTrailMesh和TubeTrailMesh一起使用。

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

注意：尾迹部分和细分的数量在RibbonTrailMesh或TubeTrailMesh的属性中设置的。

---

float trail_lifetime = 0.3 🔗

• void set_trail_lifetime(value: float)

• float get_trail_lifetime()

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

---

TransformAlign transform_align = 0 🔗

• void set_transform_align(value: TransformAlign)

• TransformAlign get_transform_align()

---

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(-4, -4, -4, 8, 8, 8) 🔗

• void set_visibility_aabb(value: AABB)

• AABB get_visibility_aabb()

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

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

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

---

方法说明

AABB capture_aabb() const 🔗

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

---

void convert_from_particles(particles: Item) 🔗

设置此节点的属性以匹配给定的ParticlesCPU节点。

---

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

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

默认ParticleProcessMaterial将覆盖color并使用custom的内容作为（旋转、年龄、动画、生命周期）。

注意：emit_particle()仅在Forward+和Mobile渲染方法上受支持，不支持兼容性。

---

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信号后再调用。

注意：finished信号仅由one_shot发射器发射。

如果keep_seed为true，则保留当前的随机种子。用于查找和回放。

---

void set_draw_pass_mesh(pass: int, mesh: Mesh) 🔗

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