This page has been translated automatically.
Setting Up Development Environment
Usage Examples
High-Level Systems
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
Double Precision Coordinates
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes
Warning! This version of documentation is OUTDATED, as it describes an older SDK version! Please switch to the documentation for the latest SDK version.
Warning! This version of documentation describes an old SDK version which is no longer supported! Please upgrade to the latest SDK version.

Particle Systems

A particle system is a really versatile technique that consists in creating complex moving structures that produce dynamic and "fuzzy" effects. They are used for simulation of abstract effects of fire, smoke, explosions, magic, electricity, fountains, rocket trails, flocking, and many many more. All of these are hard to reproduce using traditional rigid objects: particles are not represented by a set of primitive surface elements, but by point masses forming the particles primitives volume. Another distinctive feature is that particles are not static, they alter not only their position, but can also change their form with the time.

A particle system consists of three main entities:

  • Emitter - the source that emits particles
  • Particles themselves which are emitted.
  • Additional forces applied to the particles that have influence on their emission.

See also


By using finely adjusted particles, you can make the scene more attractive. This section contains description of the parameters of the particles that emitted.

Fire and smoke simulated by using particles systems.

Types of Particles

Unigine has the following types of particles:

  • Billboard particles are by far the most usable type. They represent rotating square planes, that are camera-oriented. To give an example, billboard particles can be used to create smoke.
  • Flat particles are perpendicular to the Z axis of their particle system. They are good for simulating some effects on the plane surfaces like water.
  • Point particles are similar to the billboard type. They also always face the camera, but have fixed screen-aligned orientation.
  • Length are billboard particles that could be stretched along the direction of their movement. The stretching is adjustable factor. Sparks and splashes can be effectively simulated using this type of particles.
  • Random are square particles randomly oriented in the space. The leaf fall can be successfully imitated with this type of particles.
  • Route are can be used to create tracks from moving objects (for example, foam line after a ship). They are similar to the previous implementation of flat particles.
  • Chain are billboard particles that form a continuous, visually uninterrupted flow. Their length directly depends on the spawn rate of the emitter. This type of particles is intended to be used with shift emitter creating a chain-like trail after it.

Stretch and Flattening of the Length Particles

You can specify the length of particles with the Length stretch parameter:

  • With the value of 0, the length particles are simply square billboard.
  • Increasing the value stretches the particles in the direction of their movement. The result is calculated by multiplying the stretch value by the particle velocity value. So, the higher the velocity is, the more stretched in the direction of their movement the particles are, while the other side remains of the same width.
Length Stretch = 0
Length Stretch = 1

Also, you can specify the Length Flattening parameter. This parameter makes the length particles not camera-oriented as usual billboard particles, but more perpendicular to the Z axis.

  • With the value of 0, the particles wouldn't be flattered.
  • With the maximum value of 1, the particles will be flat (perpendicular to the Z axis) when they are emitted.
Length Flattering = 0
Length Flattering = 1


The Variation parameters (VariationX and VariationY) provides a diversity of emitted particles to make the scene more natural.

If variation option is enabled, the particles will randomly take one of the possible orientations of the assigned texture along the proper axis.

Use these parameters wisely: sometimes it makes the scene look more naturally, sometimes (especially when the texture has accurately defined top and bottom parts) it can ruin the plausibility of the scene.

An example of variation: four automatic particles orientations

Particles Interaction Detection

Interaction of the particles is confined to the application of forces and collisions with external objects. There are two method to detect the collision with external objects: by using Intersection parameter or Collision parameter.

Particle-particle collisions are not checked as collision detection is an expensive operation.


Intersection stands for calculating collision of the mesh only with the center of the particle, not the whole particle shape. Intersection may look a bit unnatural as physical reaction starts only when half of the particle has already penetrated the mesh, but it is perfectly suitable if there are a lot of small particles. The main advantage of this method is its fastness and cheapness performance-wise.


Collision option, unlike the intersection, detects whether the whole particle shape has collided with the mesh. If the particles are big enough, this is the preferable method, as it provides the higher degree of visual realism: the particles react according to the set settings, when their edge or vertex comes in contact with the objects. Collision calculations are more expensive, so big particles systems should use this option carefully.

Interaction with Physical Nodes

Another way of interaction of the particle systems is the interaction with the environment through physical nodes (also known as effects): wind, force and water.

Particles Physical Mass

To participate in the scene dynamics, the particles should have a certain mass in kilograms. Its value shows, how the physical nodes will influence the particles flow.

The Physical Mass parameter doesn't have influence on other calculations.
  • With the mass of 0, the trajectory of particle system is not influenced by the external forces.
  • The higher the mass, the heavier the particles are, and the less the physical nodes can decline their flow, stretch them or otherwise affect.
Physical Mask

For the more selective interaction of the particles systems with the physical nodes, bit mask is used, that is set for both the particles and the force. These masks should have at least one bit matching, or otherwise no influence will be effected. The other bits of the mask can match with the other forces, thus providing perfect control over the scene integration.

Particles Node Hierarchy

To create the complex effects, it is necessary that all the particles systems are synchronized in time. Setting a particle system as a parent node will result in the following:

  • All the particles systems, that are the child nodes, will be synchronized relative to their parent particle systems. If the children have the children of their own, they will still be synchronized to the main parent system highest in the hierarchy.
  • When creating a new child particle system, it should be synchronized to the parent one by disabling and again enabling the parent emitter (Parameters  tab  ->   Enabled   box). At this moment of time each of the child systems is initialized with itssimulation parameters (such as generation duration, period of generation pause, and delay of initialization).
  • Disabling or enabling the parent emitter (Parameters  tab  ->   Enabled   box) affects all the child particle systems: they will be automatically and synchronously stop or start emitting particles (the existing particles will still live out their time).
  • Disabling or enabling the parent node (Node  tab  ->   Enabled   box) also affects all the children: all the particle systems in the hierarchy are turned off and on — and appear in thesame state as they were at the moment of their disabling.

Delay of Initialization

Delay option defines the time to pass between the parent system initialization and initialization of the child node. So at first the parent system starts to emit the particles, and only after the delay pause the generation of the child particles is activated. The delay can be set with some extent of randomization.

  • With the mean and spread value of 0, the parent and child systems are initialized synchronously.
  • With higher mean value, the initialization of child particle system will be delayed relative to the parent one for the strictly defined time period.
  • Providing spread value allows to define the range for randomization of the delay pause.

Rendering Options

The options described below determine particles system rendering specifics.


The particle system evolve with time, so after encountering it in the virtual world, the system only starts to be generated, particle by particle, until the whole system gains the intended look. When the character comes out on the glade, we will see the fire gradually burn up. Warm start for the particles enables rendering the full-grown particle system straight away.

The technical realization of warm start is the following: when the particle system is initialized on encountering, its life is computed starting from the generation of first particle to its disappearance. After that, the particle system is considered evolved and is rendered in this state. The calculations are taken at a fixed frame rate of 25  fps, which is the minimum required for correct simulation of particle systems (see also information about correlation between framerates).

Warm start can be enabled without any detrimental effect for any particles systems, except for huge ones.

Depth Sort

Deptho sorting is required, if particles use alpha blending. If not enabled, then basing on the depth buffer data, further positioned opaque objects can be wrongly rendered over the top of transparent particles. With depth sorting, geometry will be rendered in the order from back to front, which rules out visual artifacts.


Emitter is the source part of particle systems that generate particles. This section contains description of emitter parameters.

Types of Emitters

The emitter type define the shape of the volume within which the particles are generated:

  • Point — particles are emitted from a single point.
  • Sphere — particles are generated in a random point within a sphere, that has a certain radius.
  • Cylinder — particles are generated in a random point within a cylinder, that has specified radius and height.
  • Box — particles are generated in a random point within a cube, that has parameters of width (X axis), height (Y axis), and depth (Z axis).
  • Random — if the random emitter is chosen, the particles are generated on surface of the arbitrary parent mesh or over the particles surface. To use random emitter, you should set the particle system as a child node of the mesh. At rendering time, the random vertices of the mesh will be chosen to generate the particles.
  • Spark — this emitter generates particles in the conditioned points. It can be used to create particles that are able to spawn new particles themselves: when the first particles collide with the ground, in the point of collision new spark particles are born. In this case, the spark particle system should be made a child node of the parent first particles. Spark emitter can be used to simulate cascades of particles.
  • Also emitter can generate particles only when you move it. It called Shift Emitter, to enable it use the Emitter shift option. After that, particles are generated only when the system is moving. Particles can be shifted after the parent node (need to be assigned as a child), or their movement can be defined procedurally. Shift emitter has the following options:

    • Emitter based - particles are moving along with the emitter. If you start moving the emitter, particles will move too because their transformation depends on the transformation of the emitter.
    • Emitter continuous - enables continuous particles that follow the shift emitter.

The Emitter enabled option enables\disables the emitter.
The Emitter sync option enables the synchronization of child particle with the parent one, even if the child particle has the Emitter enabled option disabled.

Particle system with a teapot as an emitter

A teapot mesh used as a parent node for Random emitter.

Emitter Size

By using the emitter size parameter, you can specify the size of the particles source. The number of fields (whether it is radius or boundary dimensions) depend on the chosen type.

Limit per Frame

The maximum number of particles that emitter can spawn during one frame is controlled via the emitter limit parameter. This parameter specifies the exact number of particles to be emitted at once if emission Duration value is set to 0 (one-frame emission). In other cases, when particles are emitted constantly during some time period (non-zero Duration), it is used to avoid the performance drop in general.


This parameter sets the order of rendering for particle systems, especially when creating a complex effects like shots (with muzzle flash, smoke and the shot itself, each rendered with different particle systems). This parameter is very much the same as Order option in the Materials. But it allows to set a rendering sequence inside of the particle system hierarchy, to avoid such situations when the smoke from a distant shot is rendered atop of the fire of the foreground shot.

  • 0 means a default sorting according to bounding boxes of particle systems.
  • Particles with the lowest Sequence number are rendered first and are covered by the particles with the highest Sequence number, which are rendered last and above others.

Simulation Parameters

This section contains description of simulation parameters which can be used to obtain scene plausibility.

To simulate a unique particle system, the Unigine engine uses stochastic methods. Stochastic processes introduce some degree of randomness, allowing the deviations of the resulting value within a specified range. As a result, it gives the particles system shape and appearance the natural-looking freedom of change. For example, not all the particles in the flow will move with identical speed: some will move faster, some slower, imitating complex interactions.

Each of the simulation parameter has 2 values:

  • Mean value defines the average value. It sets setting milestones to control the parameter.
  • Spread value defines the range for possible variation. The higher the value, the more diversely the particles will behave.
    Spread value is optional: if set to 0, it will not influence the simulation process and only the mean value will be used.

After these values are specified, the following formula is used to calculate the final result for the parameter:

Result = Mean + Random * Spread
where Random is a random value in range from -1 to 1. This means, for each of the particles in the system the parameter will be different, but the value of this parameter of the one particle will be close to another.

Particle Radius

This parameters defines the radius of particle, in other words, size of particle. By using the spread value of the parameter, you can generate the flow of particles with different size.

Orientation Angle

When the particle is generated, its orientation in the space can be defined by the specific angle. By using this parameter, you can create particles systems of richer structure and higher visual complexity, by specifying mean and spread values.

  • If the angle spread value is set to 180  degrees, the particles will be randomly oriented in all directions.
This option is not available for particles of point and length types.

Spawn rate

If particles are enabled (Emitter Enabled checkbox is flagged), the emitter starts to create them with the specified rate. This parameter defines the number of particles emitted per second.

  • The value defines how many particles are generated in one second. For example, the value set to 5 equals spawning 5 particles per second.
  • 0 results no particles at all.
  • If the Emitter shift checkbox is enabled, the spawn rate correlates to generating the specified number of particles when emitter shifts one unit.

Let's say we have set the Spawn rate to 1 particle per second and Duration of emission to be less then one second, as well as any non-infinite value for the generation Period (for emission to be iterative rather than one-time one). Once the emitter is enabled, it counts off Duration intervals (the Period time is ignored) and when they make in sum 1 second, a particle is spawned. If the Spawn rate is set to 2 particles, they are simulated somewhere throughout this accumulated one-second period.

The way to calculate what spawn rate to set is basically as follows. If you set the Duration emission to 0.1 second and want to 1-3 particles to be spawned, set the Spawn rate to 10-15 particles. Particle system depend on the FPS and thus if set strictly to 10 particles, you may end up in a situation when no particle is spawned during one Duration interval (because due to the varied FPS the necessary Duration time did not accumulate enough). Increasing the Spawn rate to 15 particles will allow to be on the safe side.

Spawn threshold

The number of particles spawned by spark and random emitters can be additionally synchronized to the parent particle system. This parameter allows to regulate the number of particles depending on the velocity of the parent particles.

  • By the value of 0, the spawn rate of the spark emitter is independent of the parent particle system.
  • The higher the threshold value, the higher must be velocity of the parent particles for the sparks to be generated. If it is not high enough, there will be only few particles, if any.
Threshold for random emitter functions only with a particle system as a parent node.

Generation Duration


The emitter can generate particles not only constantly, but also in intervals. Duration parameter controls the time period, during which emission occurs.

  • The higher the value, the longer are the periods when particles are generated.
  • Setting the Duration to 0 means that particles are spawned over an infinitely small time interval, that is, only during one frame, simultaneously. This value can be used when you need to simulate a one-particle gun shot, for example. The exact number of particles to be emitted at once is controlled via the Limit parameter. (Set the Spawn rate very high in order to generate particles in this case).


After the generation cycle is over, the emitter can make a pause, duration of which is defined by the Period parameter:

  • If the mean value is set to 0, the particles are spawned constantly, without any pauses.
  • If infinity (inf) is specified, the particles emitter becomes inactive after one generation cycle.

Life Time

The Life Time parameter shows, how long will particles exist after emission in seconds. This parameter also has mean and spread values, that allow the particles flow to form a convincingly disappearing tail with changing density.

  • If the mean value is set to 0, the particles will not appear.

Fireball with a shift emitter with color changing and gradual tail disappearance.

Direction of Emission


The Direction parameter specifies the direction in which all the emitted particles move forming a flow.

  • Emitting direction is specified along the X, Y and Z axes. The values are relative to each other, which means the particles flow is deflected in the direction with greater value.
  • Negative values force the particles to move in the inverse direction of the axes.

If a Random emitter is used to generate particles on the mesh surface, it is possible to make the emitted particles move in the direction of the surface normal. For that, you need to set the following:

  • Direction values to 1, 1, 1.
  • Spread values to 0, 0, 0.

Spread of Emission

Shaping the particles flow allows to create different spawning models of the particles. Spread option introduces additional angular modulation of the emission direction. It represents the same spread values, that randomly vary direction of the emitted particles within the set limits.

  • Spread controls the scattering of the particles along the X, Y and Z axes. The values are also relative to each other and the direction values.
  • The higher the value, the wider the particles are scattered. If no direction values are specified, the scattering occurs in both the positive and the negative axis directions.

For example, to create the particles flow that is spread downwards and forms a 90   degree cone, the following values could be set:

  • Direction: 0, 0, -10. This will provide the overall movement down the Z axis. The same is achieved with the positive value after the particle system is rotated.
  • Spread: 10, 10, 0. The particles will be spread evenly along both the X and Y axes, scattering at an angle of 90  degrees and forming a cone.

Emission cone. Particle system with decal child node.

Particles Linear Velocity


The velocity determines the speed of particles movement in the set direction. To grant the natural-looking flow, the final velocity of each separate particle can differ, if the spread value is set.

  • The higher the mean value is, the faster the particles movement becomes.
  • Negative mean values set the particles movement in the opposite direction to the set one.
  • If the spread value is higher than the mean velocity value, the particles will move in two directions: the main flow in the specified direction, and some particles in the opposite one. To avoid it, the spread value should be less than or equal to the mean velocity value.


Particle velocity can be altered by the additional external force of gravity. With this parameter the particle direction can be interfered with, diverting the flow along the X, Y and Z axes.

  • Positive values equal gravity vector directed upwards.
  • Negative values equal gravity vector directed downwards.
The rotation of particle system node does not affect the gravity vector.

Linear damping

Linear damping specifies the decrease in particles linear velocity with the time and is used to simulate effect of the medium friction on particles. In other words, this parameter shows how quickly the particles stall their linear velocity.

  • If the value is set to 0, the velocity of the particles remains the same throughout all the particle life.
  • The higher the number is, the faster the particles velocity decreases with the time until it stops completely.

Particle Rotation


To add the angular velocity to particles, use the Rotation parameter. Starting from the initial orientation angle, particles can spin around their own axis. Rotation parameter determines the angular velocity of their spinning motion.

  • Positive numbers rotate the particles clockwise.
  • Negative numbers rotate the particles counterclockwise.

Angular damping

Angular damping is responsible for the gradual decrease of particle rotation. This parameter shows how quickly the particles stall their angular velocity, add by the Rotation parameter.

  • If 0 value is set, the particles will consistently rotate throughout all of their life.
  • The higher the number is, the faster the particles lose their angular velocity, until they become completely nonspinning.

Particle Growth


By using the Growth parameter, you can change the size of the particles dynamically, in spite of the particles radius range. The growth parameter introduces particle that change their initial size with the time. The growth can be either defined strictly (only mean value) or approximated with the range (by specifying also a spread value).

  • Positive numbers result in particles increasingly growing after they are spawned. For example, fireworks grow and blossom in the sky.
  • Negative number define the particles gradually lessening. For example, to imitate the smoke dissipating in air.

Growth Damping

To control the Growth parameter, use the Growth Damping parameter. It defines the gradual decrease in the particles enlargement in size with the time. For example, with this parameter you can simulate explosion effects: in the beginning the particles grow rapidly, while afterwards their growth slows down.

  • The value of 0 means the particles will be constantly increasing in size throughout all of their life time.
  • The higher the value is, the faster the growth of particles stops and they live out with the constant size.

Particles-Objects Interaction

When particles contact any object (it should have collision or interaction detection enabled), they can react in one of the ways described below.


If the Culling option of the particle system is enabled, the engine will not render the particle if the intersection or collision have occurred. It can be useful if you don't want to render particles after the interaction with the geometry.

If the option is disabled, the behavior of particles will depend on other parameters. For example, they can appear on the geometry surface as decal objects or reflect from the surface and continue the movement.


After hitting the obstacle (if the culling option is disabled), they can bounce off the surface rather than slipping along it. This option is very convenient if simulating some watter effects that include splashes. The strength of the effect of bouncing depends both on the restitution parameter of the particles and the restitution surface option for the colliding object (Properties ->Parameters tab -> Restitution).

  • With the minimum value of 0, the particles does not bounce off.
  • With the maximum value of 1, the angle of particles fall equals the angle of their bouncing off.


Another characteristic of the particles, showing up on their contact with the obstacle, is the roughness of their surface. It determines whether the particles scatter in different directions or react as a uniformly directed flow.

  • The minimum value of 0 means the trajectory of all particles after the collision is the same.
  • The maximum value of 1 means the particles will scatter in different directions and a bit angularly. This angle arising from particle roughness also affects bouncing behaviour.

Synchronizing Several Particle Systems

To synchronize several particle systems, for example, to create a shot effect (with three particle systems: muzzle flash, smoke and the bullet), you can do the following:

  1. Create the parent particle system that will be used as a dummy one, purely for synchronization purposes (you can even disable its surface). Its Duration time interval should cover all duration intervals and delay intervals (if any) of the children particle systems. Other parameters (Spawn rate, etc.) do not matter.

  2. Add the child particle systems. They can have any Duration time necessary (but it should be smaller than the one of the parent). For example, to synchronize all child particle systems at once and to spawn only one particle, you can set the following:

Additional Forces

More intricate changes in further movement of the particles may be performed by applying the forces. They have influence on the particles flow in the desired direction or on the contrary deflect it. The forces can be of three general types:

There is no limitation to the number of forces applied to one particle system and they can freely overlap, enabling to constitute complex trajectories easily and fast. If the Attached flag is set, point forces are dragged and rotated with the whole particles system (and their position is also defined relative to the system, that represents zero of force's coordinate system). If the flag is off, the forces are not affected by the system changes in position.

Point Forces

Point forces represent a force concentrated in a point, application of which is limited by the sphere. The point force sphere can be placed anywhere in the scene and rotated, if necessary. However, for the point force to affect the particles movement, it should include them in its radius.

Besides that, point force has two main properties, that define its influence.


Attractor property allows to correct the linear direction of particles movement.

  • If positive value is provided, the particles are repelled and move away from the force center point.
  • If negative value is provided, all the particles are attracted to move in the direction of the force center point.
  • By 0 value, the property is inactive and does not effect particles movement.


With Rotator property, the particles are spinned around the force center point.

  • Positive values spin the particles in the clockwise direction.
  • Negative values spin the particles counterclockwise.
  • By 0 value, the property is inactive and does not effect particles movement.

Point Force Attenuation

To get more plausible visual result, especially by applying a set of different forces, their influence on the particles can gradually decrease when moving to the boundary.

  • 0 equals no attenuation and the force's influence ceases abruptly when crossing the sphere boundary.
  • The higher the attenuation value is, the closer to the force center point starts to weaken.


A physical noise is a cuboid shaped area that adds a distribution flow based on a volumetric noise texture. Depending on the specified Position and Rotation parameters, it can be positioned and rotated to cover the necessary area.

Texture Sampling Parameters

The following parameters are used for pixel sampling from the generated noise texture:

  • Offset - sampling offset along the axes.
  • Step - size of the sampling step along the axes.

Force Multiplier

Force - is a force multiplier. The higher the value is, the higher the value of the resulting force that affects an object inside the noise volume will be.

Generation Parameters

The following parameters are used to generate a noise texture that will be used in run-time.

  • Scale - scale of the noise texture. The minimum value is 0, the maximum value is 1.
  • Frequency - number of octaves for the noise. The higher the value is, the more details the noise texture has. The minimum value is 0, the maximum value is 32.
  • Size - size of the noise texture image in pixels.


Deflector is a surface field that has no visual representation, but physically interacts with the particle system (no other objects are influenced, of course). Depending on the specified size, it can be either rectangular or square, plus arbitrarily positioned or rotated to cover the necessary area.

Deflectors are one-sided, meaning the particles can freely penetrate them through one side, and interact only with the opposite one, for example, when having fallen on it from above.

Deflectors can be of two types:


Reflector represents an invisible surface aimed for providing additional bouncing off and scattering of the particles.

Deflector Restitution

The restitution of the deflector is based on the same principle as the particles general restitution. After hitting the deflector surface, particles bounce off it at the angle, defined by set value:

  • The minimum value of 0 means the particles does not bounce off, but rather slide along deflector surface.
  • The maximum value of 1 proves the angle of bouncing that equals the angle of particles fall.
Deflector Roughness

Deflector roughness is also similar to the roughness characteristic of the particles. It simulates unevenness of the surface that results in particles scattering in different directions when hitting it.

  • The minimum value of 0 means the surface is smooth and the particles are scattered in a uniform direction.
  • The maximum value of 1 means the surface is harsh and the particles will scatter differently and angularly.


Clipper is a surface field that clips all the particles it comes in contacts with. If the particle system is accidentally dispersed into the unnecessary area, it can be clipped simply and trouble-free by adding a clipper, that does not render, without exerting additional effort of readjusting the whole particle system.

Mesh-Based Particles

It is possible to create mesh-based particle systems. For that, Mesh Cluster need to be added as a child node of ObjectParticles. After that, meshes are automatically spawned by the emitter. (Clear NodesSurfacesMaterial for particles if you do not want to spawn them together with meshes.)

Mesh Cluster-based particles
Last update: 2017-07-03
Build: ()