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.

Particles Editor Fields¶

The Preview allows you to play the particle system directly in the editor for a real-time preview of the effect.

The Show Emitter Preview displays a visual representation of the particle emitter, making it easier to adjust its position and shape.

The Pause temporarily halts the simulation, freezing all particles in place until resumed.

The Kill All Particles immediately removes all currently active particles from the system.

The Restart performs a hard restart of the particle system by killing all particles, clearing all internal data, and resetting the simulation time. This is useful for testing during development.

General Settings¶

The Maximum Number of Particles defines the maximum number of particles that can exist in the system at any given time. This limits the total number of active particles to prevent performance issues.

The Duration defines how long the particle system runs, in seconds. A value of -1 indicates that the system will run indefinitely during the playtime.

The Coordinate System determines whether particles move relative to the emitter’s local space or the global world space.

• Local: Particles are emitted relative to the emitter node’s local coordinate system. They move and rotate along with the emitter, maintaining their relative positions.

• World: Particles are emitted in global space and are unaffected by the emitter’s movements or rotations, allowing them to move independently.

Emission settings¶

The Emit All At Once defines whether all particles should be emitted immediately when the simulation starts.

The Auto Respawn option, when enabled, automatically respawns particles immediately after they die. This is only used when Emit All At Once is enabled.

The Spawn amount specifies the number of particles emitted at each emission event. This is only used when Emit All At Once is disabled.

The Spawn Interval defines the time interval, in seconds, between consecutive particle emissions. This is only used when Emit All At Once is disabled.

The Number of Emissions sets the total number of emission events the particle system can perform. Once this limit is reached, no additional particles will be emitted. A value of -1 indicates that emissions continue indefinitely. This is only used when Emit All At Once is disabled.

The Continuous emission option, when enabled, causes particles in each emission to spawn gradually over time instead of instantly, creating a continuous stream.

Size Settings¶

Scaling Mode determines how particle size evolves during their lifetime:

• Constant: particles keep the same constant size throughout their lifetime.

• Variable: particles scale from a base size to a final size using an interpolation function.

• Velocity: particle size is driven by their velocity.

Base Size defines the size of the particles at the moment they are emitted, in pixels.

Final Size sets the size particles should reach at the end of their lifetime, in pixels. If a particle dies before reaching its lifetime, it may not achieve its final size. (Only applies when Scaling Mode is Variable.)

Interpolation Function controls how particle size changes from base to final size when using Variable scaling. Options include Linear, Exponential, Inverse Exponential, and Ease-in, Ease-out.

Interpolation Rate fine-tunes the speed of size transition for interpolation functions. Higher values accelerate or decelerate the scaling effect depending on the chosen function.

Scale Randomness introduces per-particle variation by multiplying the computed size with a random factor. Each particle receives a multiplier between \(1 - \text{ScaleRandomness}\) and \(1 + \text{ScaleRandomness}\), applied after the scaling mode is resolved.

A value of 0.0 means all particles strictly follow the selected scaling mode. A value of 1.0 allows each particle’s size to vary up to ±100% of the computed size.

Velocity Settings¶

Velocity Mode determines how a particle’s velocity evolves over its lifetime:

• Constant: particles retain their initial velocity throughout their lifetime.

• Variable: particles interpolate from an initial velocity to a final velocity.

Initial Velocity specifies the starting velocity vector applied when particles are emitted.

Final Velocity defines the velocity that particles should reach at the end of their lifetime. This only applies when Velocity Mode is Variable.

Interpolation Function controls how particles transition between the initial and final velocity when Variable mode is enabled. Options include Linear, Exponential, Inverse Exponential, and Ease-in, Ease-out.

Interpolation Rate fine-tunes the speed of the transition for interpolation functions. Higher values adjust how quickly or gradually the velocity shifts depending on the chosen function.

Spread

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.

Angular Velocity

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.

The rotation randomness introduces variation to each particle’s angular velocity. A value of 0.0 means all particles spin at the same base speed, while 1.0 allows each particle’s rotation to vary up to ±100% of that base speed. This property ensures more natural and less uniform particle motion.

Force Settings¶

Drift

Drift adds a random velocity to particles, creating more dynamic motion like swirling smoke. Its magnitude is in world units per second and controls how strongly particles deviate from their base velocity.

Gravity

Gravity defines the acceleration applied to particles, simulating a gravitational force that influences their velocity over time. It is measured in world units per second squared (units/s²) and typically ranges from 0.0 (no gravity) to higher values depending on the desired effect, with 9.81 approximating Earth-like gravity. Higher values cause particles to fall faster, while lower values produce a gentler pull, and negative values can simulate upward forces or anti-gravity effects.

Orbital Velocity

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. Units are in scene units per second.

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. Units are in scene units per second.

Target Force

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.

Mass

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 in seconds of each particle. This determines how long a particle will stay alive.

The Particle Life Randomness adds random variation in seconds to the lifetime of particles. The lifetime of a particle is calculated 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.

Blending Settings¶

The Blending Mode determines how particles are visually combined with the background and other particles. Available modes include:

• Normal: Standard alpha blending.

• Add: Colors are added to the background, creating brighter effects.

• Multiply: Colors are multiplied with the background, producing darker results.

• Subtract: Colors are subtracted from the background.

• Negation: Inverts and blends colors for special effects.

The Blend Amount controls the intensity of the blending effect. A value of 0 means no blending is applied, while 1 applies the full blending effect.

Fade Settings¶

The Fading Mode determines how particle opacity changes over their lifetime:

• Constant: Particles maintain a fixed opacity.

• Variable: Particles gradually change opacity from Initial Opacity to Final Opacity over their lifetime.

The Initial Opacity sets the transparency of particles when they are first emitted (0 = fully transparent, 1 = fully opaque).

The Final Opacity defines the opacity particles reach at the end of their lifetime, creating a fade-out effect if lower than the initial opacity. This setting is only used when Fading Mode is Variable.

The Fade Interpolation specifies how the opacity transition occurs over time. Options include Linear, Exponential, Inverse Exponential, and Ease-in, Ease-out.

The Fade Rate controls the speed of the opacity transition according to the chosen interpolation function.

Mathematically, the final particle opacity is calculated as:

Constant mode:

Variable mode:

where \(f(\text{Life})\) is the interpolation function defined by Fade Interpolation and Fade Rate in function of the particle’s life.

Velocity mode:

where \(|\text{v}|\) is the magnitude of the particle’s velocity.

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.