Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

GPUParticles3D

Inherits: GeometryInstance3D < VisualInstance3D < Node3D < Node < Object

A 3D particle emitter.

Description

3D particle node used to create a variety of particle systems and effects. GPUParticles3D features an emitter that generates some number of particles at a given rate.

Use process_material to add a ParticleProcessMaterial to configure particle appearance and behavior. Alternatively, you can add a ShaderMaterial which will be applied to all particles.

Tutorials

• Particle systems (3D)

• Controlling thousands of fish with Particles

• Third Person Shooter Demo

Properties

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)

Methods

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 )

---

Signals

finished ( )

Emitted when all active particles have finished processing. When one_shot is disabled, particles will process continuously, so this is never emitted.

Note: Due to the particles being computed on the GPU there might be a delay before the signal gets emitted.

---

Enumerations

enum DrawOrder:

DrawOrder DRAW_ORDER_INDEX = 0

Particles are drawn in the order emitted.

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_REVERSE_LIFETIME = 2

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

DrawOrder DRAW_ORDER_VIEW_DEPTH = 3

Particles are drawn in order of depth.

---

enum EmitFlags:

EmitFlags EMIT_FLAG_POSITION = 1

Particle starts at the specified position.

EmitFlags EMIT_FLAG_ROTATION_SCALE = 2

Particle starts with specified rotation and scale.

EmitFlags EMIT_FLAG_VELOCITY = 4

Particle starts with the specified velocity vector, which defines the emission direction and speed.

EmitFlags EMIT_FLAG_COLOR = 8

Particle starts with specified color.

EmitFlags EMIT_FLAG_CUSTOM = 16

Particle starts with specified CUSTOM data.

---

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

---

Constants

MAX_DRAW_PASSES = 4

Maximum number of draw passes supported.

---

Property Descriptions

int amount = 8

• void set_amount ( int value )

• int get_amount ( )

The number of particles to emit in one emission cycle. The effective emission rate is (amount * amount_ratio) / lifetime particles per second. Higher values will increase GPU requirements, even if not all particles are visible at a given time or if amount_ratio is decreased.

Note: Changing this value will cause the particle system to restart. To avoid this, change amount_ratio instead.

---

float amount_ratio = 1.0

• void set_amount_ratio ( float value )

• float get_amount_ratio ( )

The ratio of particles that should actually be emitted. If set to a value lower than 1.0, this will set the amount of emitted particles throughout the lifetime to amount * amount_ratio. Unlike changing amount, changing amount_ratio while emitting does not affect already-emitted particles and doesn't cause the particle system to restart. amount_ratio can be used to create effects that make the number