Particle system¶

Particle systems enable the creation of dynamic and visually stunning effects, such as fire, smoke, rain, explosions, and more. They are an essential tool for simulating natural phenomena or magical visuals in your project.

The core concept of a particle system is that individual “particles” are emitted over time, each with a limited lifespan. While all particles share a base configuration, their unique appearance and behaviour is driven by random variations applied to their properties.

The Particle System panel provides a powerful tool for creating and customizing particle-based effects in your project. It allows for the configuration of emitters, particle behavior, and various rendering properties to achieve complex visual effects such as fire, smoke, rain, explosions, and more. Some of the key features include:

• Easily control particle emission, including starting, stopping, and adjusting the emission rate. Configure whether particles are emitted continuously or all at once.

• Modify various particle properties such as color, size, velocity, rotation, and lifetime.

• Apply textures to particles, with built-in support for texture blending modes. Dynamically shift particle texture hues for animated, colorful effects.

• Manage particle colors with the ability to set initial colors, final colors, and color transitions over the particle’s lifetime, enabling smooth visual effects.

• Control particle fading behavior, allowing particles to gradually fade as they approach the end of their lifetime.

• Adjust both angular and directional velocity, creatng swirling effects for particles.

• Apply forces to your particle system, allowing you to simulate gravity, wind, or other environmental influences on the particles’ behavior.

• Set and adjust bounding boxes to restrict the movement of particles within specific areas. Dynamically define the minimum and maximum bounds for precise control over particle positioning.

• Store particle system settings persistently, making configurations easy to save and reload.

This documentation page will drive users through an high level overview of the particle system capabilities. For further information on the lua API interface and advanced scripting examples visit the Developer Documentation.

General Settings¶

The Maximum Number of Particles defines the maximum number of particles the system will consecutively run.

The Particle System Duration defines how long the particle system will run. A value of -1 means that the particle system will keep running during the whole play time.

The Coordinate System defines whether wolrd or local coordinates are used for the particles system.

Local Coordinates: Particles are emitted relative to the emitter node’s local coordinate system. When the emitter moves or rotates, the particles remain attached to it, maintaining their relative positions.

Global Coordinates: Particles are emitted in world space, unaffected by the emitter node’s movements or rotations. This allows particles to move independently and freely, even if the emitter is moved or transformed.

Emission settings¶

Emit All Particles defines whether all particles should be emitted at the start of the simulation..

Particles Spawn Amount specifies the number of particles emitted at each emission event.

Particles Spawn Rate defines the time interval, in seconds, between emission events.

Maximum Number of Emissions sets the total number of emissions the particle system can perform. Once this limit is reached, no additional particles will be emitted. A value of -1 indicates that the system will continue emitting particles indefinitely.

Continuous emssion if enabled , particles are emitted continuously between each emission cycle creating a stream of particles rather than discrete bursts.

Respawn Particles when enabled particles are respawned immediately after they die.

Size Settings¶

Particle Initial Size specifies the size of particles at the moment they are emitted.

Particle Final Size defines the size particles will have at the end of their lifetime.

Particle Size Approach Value controls how quickly particles transition from their initial size to the final size. A value of 0 means particles will retain their initial size throughout their lifetime and will never reach the final size. A value of 1 means that the particles immediately reach the final size upon emission. Intermediate values create a gradual size change over the particle’s lifetime.

Velocity Settings¶

The initial velocity determines the speed at which particles are emitted. This speed may change during the particle’s lifetime due to external forces such as gravity

The final velocity specifies the speed that particles will attain at the end of their lifetime. Regardless of other forces acting on the particles, they will adjust their speed to match this value by the time they expire.

The velocity approach value controls how quickly particles transition from their initial velocity

to the final velocity. A value of 0 means the final velocity has no effect, and the particles will retain their initial velocity throughout their lifetime. A value of 1 ensures that the particles immediately match the final velocity at the moment of emission.

The spread parameter is the angle (in degrees) which will be added randomly to the initial velocity. A spread of 180 will emit particles in all directions. Spread will not have any effect if the “Initial Velocity” parameter is zero.

The angular velocity determines the rate of rotation for each particle, expressed in degrees or radians per second. This property controls how fast particles spin when they are emitted.

The rotation direction specifies whether particles rotate clockwise, counterclockwise, or in both directions randomly. A value of 1.0 sets the particles to rotate counterclockwise. A value of -1.0 sets the particles to rotate clockwise and a value of 0.0 results in no rotation.

Force Settings¶

Drift defines a random velocity applied to the particles. This property allows to simulate more dynamic and organic effects like a swirling smoke.

Gravity defines the strength of the gravity applied to the particles.

Tthe Orbital Center Point defines a point in world coordinates that particles will rotate around. Tis setting can be configured to create rotational patterns.

Orbital Velocity defines the speed particles rotate around the Orbital Center Point.

The Orbital plane defines the 2D surface in which the particles orbit. By specifying the plane’s orientation 3D coordinates, you can control the direction and angle of the orbit.

Orbital decay determines how quickly a particle’s orbital motion slows down over its lifetime. A higher decay value causes particles to gradually lose their orbital velocity, resulting in tighter spirals around the center. Analogously, a lower decay value maintains the orbital motion for longer.

The particle target defines a force that exerts an attractive force on particles, pulling them toward it over their lifetime.

Target force controls the strength of the attraction toward the particle target. A higher force value causes particles to accelerate more rapidly toward the target, while a lower value results in a gentler pull.

If kill particle on target is enabled, particles will die instantenously when they reach the target.

The Mass fields define the mass of particles. A higher mass will make particles less affected by external forces, while a lower mass will result in more pronounced reactions to those forces.

Currently, all particles have a fixed mass of 1.0. In future updates, users will be able to adjust the mass property to fine-tune how particles respond to forces.

Life Settings¶

The Particle Life defines the total lifetime of each particle. This determines how long a particle will stay alive.

The Particle Life Randomness adds random variation to the lifetime of particles. The lifetime of a particle is calculated according to the formula:

The Particle Life Decay controls the rate at which particle’s age. A higher value causes particles to age more quickly reducing the lenght of their lifetime.

The Particle Life Decay Randomness introduces variability to the decay rate of particles according to the formula:

Texture and Color Settings¶

Different settings are avaiable to control the appearance of particles, allowing for customization of colors, textures, and sprites.

Emitter Settings¶

The Emitter Shape defines the shape of the emitter.

Different emitter shapes might support different emission types. Below a table describing which emission types are supported by each emission shape.

Bounding Box Settings¶

The bounding box defines a constrained area within which particles are allowed to move. By default, the bounding box is disabled, and particles can move freely throughout the scene. To enable it, toggle the Enable Bounding Box option.

When the bounding box is enabled, two additional fields become available:

1. Bounding Box Maximum Corner : describes Specifies the world-space coordinates of the lower-left corner of the bounding box.

2. Bounding Box Minimum Corner: describes the world-space coordinates of the upper-right corner of the bounding box.

Curl Noise Settings¶

The curl noise allows for advanced, organic particle system simulations by introducing turbulence and irregular motion patterns. To enable curl noise, toggle the Enable Curl Noise option. Once enabled, a Noise Preview becomes visible providing a visual representation of the noise pattern.

The following settings are avaiable to adjust the curl noise effect:

1. Noise Strenght: Controls the intensity of the noise.

2. Noise Frequency: Determines the scale of the noise. Higher frequencies give a more frequent noise changing pattern.

3. Noise Octaves: Controls the complexity of the noise by layering multiple noise patterns with different frequencies. Increasing the number of octaves adds details to the noise but are also more resource-intensive to calculate.