Learn what Felgo offers to help your business succeed. Start your free evaluation today! Felgo for Your Business

GameParticle

The GameParticle component allows visual effects like fire, explosions, smoke or rain. More...

Import Statement: import Felgo 4.0

Properties

Methods

Detailed Description

These particle effects are rendered in an efficient way and you can use an existing set of effects that are customizable to serve your game's needs.

A particle effect is made up of a particle emitter and an image. The emitter spawns multiple particles that get affected by the emitterType. For every particle an image specified with the textureFileName property is drawn and these images and emitter properties are modified over time by the Felgo particle system. By changing the particle emitter properties and the image file, you can achieve very different effects.

Most of the particle properties also have an according variance property. The variance property is the amount how much the initial property varies for every created particle. So the higher the variance setting is, the more random the effect looks like.

Example Usage

Following examples demonstrate the usage of the GameParticle element.

Particle Effect from File

This example shows a flame particle that is loaded from file, but its x, y and rotation properties are overridden locally to center it in the middle of the screen and let it point downwards.

 import Felgo
 import QtQuick

 GameWindow {
   id: gameWindow

  Scene {
   id: scene

   GameParticle {
     id: fireParticle

     // Particle location properties
     x: scene.width/2
     y: scene.height/2
     rotation: 90

     // particle file
     fileName: Qt.resolvedUrl("fireParticle.json")

     // start when finished loading
     autoStart: true
   }
  } // end of Scene
 } // end of GameWindow

This is how the the above particle effect looks like:

Particle Effect from Scratch

This example shows a flame particle that originates from the clicked mouse position and changes its direction by 45 degrees at every click:

 import Felgo
 import QtQuick

 GameWindow {
   id: gameWindow

  Scene {
   id: scene

   GameParticle {
     id: fireParticle

     // Particle location properties
     x: scene.width/2
     y: scene.height/2
     sourcePositionVariance: Qt.point(0,0)

     // Particle configuration properties
     maxParticles: 38
     particleLifespan: 0.9
     particleLifespanVariance: 0.2
     startParticleSize: 7
     startParticleSizeVariance: 2
     finishParticleSize: 45
     finishParticleSizeVariance: 10
     rotation: 0
     angleVariance: 0
     rotationStart: 0
     rotationStartVariance: 0
     rotationEnd: 0
     rotationEndVariance: 0

     // Emitter Behavior
     emitterType: 0
     duration: 0
     positionType: 1

     // Gravity Mode (Gravity + Tangential Accel + Radial Accel)
     gravity: Qt.point(0,0)
     speed: 85
     speedVariance: 2
     tangentialAcceleration: 0
     tangentialAccelVariance: 0
     radialAcceleration: 0
     radialAccelVariance: 0

     // Radiation Mode (circular movement)
     minRadius: 0
     minRadiusVariance: 0
     maxRadius: 0
     maxRadiusVariance: 0
     rotatePerSecond: 0
     rotatePerSecondVariance: 0

     // Appearance
     startColor: Qt.rgba(0.76, 0.25, 0.12, 1)
     startColorVariance: Qt.rgba(0, 0, 0, 0)
     finishColor: Qt.rgba(0, 0, 0, 1)
     finishColorVariance: Qt.rgba(0,0,0,0)
     textureFileName: Qt.resolvedUrl("particleFire.png")


     // start when finished loading
     autoStart: true
   }


   MouseArea {
     anchors.fill: parent

     onClicked: {
       // position the fire particle emitter (=origin) to the position of the mouse
       fireParticle.x = mouseX
       fireParticle.y = mouseY

       // this rotates the fire particle direction 45 degrees clockwise with every click
       fireParticle.rotation += 45

     }

     onPositionChanged: {
       // while the mouse is pressed (=dragged), also change the position
       fireParticle.x = mouseX
       fireParticle.y = mouseY
     }
   }

  } // end of Scene

 } // end of GameWindow

For testing different particle effects, you can use the Particle Editor Demo and modify the properties at runtime to immediately see the changes and test the performance impact. Navigate to the folder where you installed the Qt SDK and then to Examples/Felgo/demos/ParticleEditor and open the ParticleEditor.pro file.

EmitterType

There are 2 types, or modes of particle emitters:

Only the properties that belong to the specific mode will have an effect. So if you set the radius mode for example, changing the gravity property will not do anything.

Gravity

In mode ParticleBase.Gravity, the particles are affected by gravitational force. These are the properties that are only valid in gravity mode:

You can set this mode for any effects that should be based on gravitational effects. Examples are fire, smoke, snow, rain, etc. The gravity mode is the default setting.

Note: The tangential acceleration is currently not fully implemented in Felgo 2. If you need this feature, please contact us here.

Radius

With the mode ParticleBase.Radius, you can simulate radial effects like spirals. These are the properties that are only valid in radius mode:

The remaining properties are valid in both modes.

PositionType

You can choose from 3 different PositionType values:

  • ParticleBase.Free - When parent is moving: Particle emitter moves parallel to the parent - particles emit from the particle emitter position but live there until death uninfluenced by the position change of the parent and the emitter position. Moving the particle emitter manually - particles emit from the particle emitter position but live there until death uninfluenced by the position change of the parent or the particle emitter.
  • ParticleBase.Relative - When parent is moving: Particle emitter moves parallel to the parent and particles emit around the particle emitter. Moving the particle emitter manually- particles emit from the particle emitter position but live there influenced by the position change of the parent but uninfluenced by the emitter position.
  • ParticleBase.Grouped - When parent is moving: Particle emitter moves parallel and particles emit around the particle emiter. Moving the particle emiter manually - particles emit around the particle emmiter.

The positionType only has an impact, when you change the position of a parent item of the Particle component! Most often, you will add the GameParticle element as a child of a game entity. And if this entity moves, also the particle emitter position will move with it. The positionType then specifies what happens with the already emitted particles.

When you choose the type ParticleBase.Free, the already emitted particles are only affected by the gravity or radial mode properties and float freely. The ParticleBase.Relative and ParticleBase.Grouped type force the particles to follow the entity. These two modes are the recommended ones when you have a scrolling level or layer where the particle is attached to. However, the best approach is to try the different PositionTypes and set the one that looks best. so it is kind of trial and error to get the best result for each individual game. You can try different settings without restarting the application with the Particle Editor Demo and then dragging the particle effect around.

BlendFunction

In older versions of Felgo and in other engines or particle creation tools the blend modes where used to define the blending states of source and destination blend factor. Based on the new rendering technology in Qt 5, which is highly optimized for mobiles and overall performance, we decided that the Particle component does not support different blend modes. The default blend mode is source: 1 (GL_ONE) with destination: 771 (GL_ONE_MINUS_SRC_ALPHA). This is also the best solution for particles with alpha values. The default blend mode will be applied to all particles you use within the Particle component. If you use old particles which use different blend modes, they might look different now, and you have to tweak them a little bit to look amazing again. The benefit is a big performance boost.

Duration

Used to define the infinite duration of a particle effect.

  • ParticleBase.Infinite - usable for the duration parameter in case the particle emitter should emit endless.

Importing Particle Effects from Particle Creation Tools

Although you can change the properties of the particle during runtime with Felgo, you might already have particles created with other tools i.e. Particle Editor Demo. You can set the fileName property to load the JSON-based file in the following format:

 { "DeathParticle" : { "angleVariance" : 360, ... , "textureFileName" : "particles/particleBlood.png", "visible" : true, "x" : 0, "y" : 0 }}

With this code you can import the file, but you still can override data from the file in your local qml file, demonstrated with the angleVariance property.

 GameParticle {
   filename: Qt.resolvedUrl("DeathParticle.json")

   // this would overwrite the setting from the json file
   angleVariance: 20
 }

If you load a particle file from your Documents directory instead of your application storage you can still use relative paths, but FileUtils.getMultiPathUrl() is necessary to succeed.

Platform DocumentsLocation
Linux /home/<Username>/.local/share/data//<Applicationname>/particles
Windows C:\Users\<Username>\AppData\Local\<Applicationname>\particles
macOS /Users/<Username>/Library/Application Support/<Applicationname>/particles
MeeGo Harmattan /home/user/.local/share//data//<Applicationname>/particles
Symbian /Private/e2681898/particles
iOS /var/mobile/Applications/<Packagename>/Documents/particles
Android /data/data/<Packagename>/files/particles

When you load particles/DeathParticle.json from your Documents directory you need to wrap it in the call FileUtils.getMultiPathUrl().

 GameParticle {
   filename: FileUtils.getMultiPathUrl("particles/DeathParticle.json")

   // this would overwrite the setting from the json file
   angleVariance: 20
 }

If you need more information on particle creation and loading you should also see the sources of Particle Editor Demo.

Particle Performance Considerations

Particles are very performance sensitive especially on mobile devices and thus need special treatment. There are multiple very important properties of a particle which influence the particle performance the most. These properties are highlighted with red color in the Particle Editor and explained in the following list:

  • GameParticle::maxParticles - This is the most critical property. The more particles are used for a particle effect the better it might look but the worse the performance. Therefore, an optimal particle count should be encountered. Most effects look good between 30 and 60 particles. But this highly depends on the particle texture. You can try to make the colors darker to simulate a higher particle count for better performance.
  • GameParticle::particleLifespan - The time how long a particle lasts.
  • GameParticle::emissionRate - The rate at which particles get emitted during their particleLifespan. By default, this gets set to maxParticles / particleLifespan. You usually do not need to set this property, instead modify maxParticles and particleLifespan!
  • GameParticle::speed - The movement speed of the particle is a crucial factor for the visual smoothness.
  • GameParticle::startParticleSize and GameParticle::finishParticleSize - The size of particles can have a great influence on the performance. The smaller the size the better the performance, but this also depends on the used texture.
  • GameParticle::textureFileName - The size of the particle texture and the used alpha channels are also important. The performance increases with smaller textures and no alpha channel. Therefore the texture should be as small as possible.

See also Particle Performance section of Particle Editor Demo.

API Changes Between the New Particle Component and the Old Particle Component

The new Particle component of Felgo 2 is based on the QtQuick Particles component to gain performance of the SceneGraph and offer the possibility to use all old particles from Felgo 1.0 and other engines or particle creation tools. Therefore, you can not only use the amazing QtQuick particles to create even better apps and games but also use your existend effects. There are no API changes to the short and user-friendly API from the Felgo 1.0 Particle component. The Particle component also allows to change all properties at runtime. This makes it compatible to the use with the Particle Editor Demo.

Note: Blend modes are not supported anymore. Furthermore, tangential acceleration is not fully supported at the moment.

Further Resources About Particle Systems

Property Documentation

angleVariance : qreal

The angle variance. The default value is 0.


autoStart : bool

This property defines if the particle effect should start emitting particles after it finished loading without manually calling start(). The default value is false.

See also start().


duration : Duration

This property holds how many seconds the emitter will run after a call of start(). Set this property to an enum value of Duration. For looping, so endlessly running emitters, set it to ParticleBase.Infinite. The default is 0, so a call of start() will have no effect if no duration is set explicitly!

There is a significant difference between the duration and the particleLifespan properties: the duration sets how long new particles are emitted, and the particleLifespan defines how long each of the created particle will live.


emissionRate : qreal

The rate at which particles get emitted during their particleLifespan. By default, this gets set to maxParticles / particleLifespan. You usually should not set this property - instead, modify maxParticles and particleLifespan!

See also maxParticles and particleLifespan.


emitterType : EmitterType

This property holds the mode of the emitter. Set this property to an enum value of EmitterType.

Depending on which mode is set, different properties are valid. In most cases, the default emitterType setting of ParticleBase.Gravity will be sufficient.

These properties are valid in mode ParticleBase.Gravity:

These properties are valid in mode ParticleBase.Radius:

See also EmitterType.


fileName : QUrl

The JSON file generated by a particle editor, for instance the Particle Editor Demo, to load a finished particle effect.

If this property is set, all properties will be loaded from the file. You can still set properties in QML. In that case, the property read from the JSON file is overwritten.

The default is an empty url.

See also Importing Particle Effects from Particle Creation Tools.


finishColor : QColor

Finish color of the particle. The default value is black which equals Qt.rgba(0,0,0,0).


finishColorVariance : QColor

Finish color variance of the particle. The default value is black which equals Qt.rgba(0,0,0,0).


finishParticleSize : qreal

The finish size of the particle image in pixels. The default value is 0.

The particle texture always is a square texture, so with a size of 64 for example, the texture is scaled to 64x64 pixels.


finishParticleSizeVariance : qreal

The finish size variance of the particle image in pixels. The default value is 0.


gravity : QPointF

The gravity property is the particle gravitational force. The default value is (0,0). Only valid in mode ParticleBase.Gravity.


maxParticles : int

The maximum number of particles that get created during their particleLifespan. The emissionRate is calculated based on this property.

Note: Particles do have a performance impact. Try to use as few particles as possible to achieve a good-looking result and test the performance on mobile devices.

See also Particle Performance Considerations.


maxRadius : qreal

The ending radius of the particles. The default value is 0. Only valid in mode ParticleBase.Radius.


maxRadiusVariance : qreal

The maxRadius variance. The default is 0. Only valid in mode ParticleBase.Radius.


minRadius : qreal

The starting radius of the particles. The default value is 0. Only valid in mode ParticleBase.Radius.


minRadiusVariance : qreal

The minRadius variance. The default value is 0. Only valid in mode ParticleBase.Radius.


particleLifespan : qreal

The duration in seconds how long one created particle lives. The emissionRate is calculated based on this property.

There is a significant difference between the duration and the particleLifespan properties: the duration sets how long new particles are emitted, and the particleLifespan defines how long each of the created particle will live.


particleLifespanVariance : qreal

The particleLifespan variance. The default value is 0.


positionType : PositionType

This property defines how the already emitted particles behave when one of the parent items moves or rotates.

Set this property to an enum value of PositionType.

When you set positionType to ParticleBase.Free, already emitted particles are unaffected by emitter repositioning. Use this setting if you do not want the particles follow the position change. With positionType set to ParticleBase.Relative, emitted particles follow the emitter repositioning. Use that setting when the particle is added to a moving background layer which it should follow, or when attached to an entity. The positionType ParticleBase.Grouped is very similar to ParticleBase.Relative and also attaches the particles to the emitter and its translation. The particles are forced to stay closer together with this setting than with ParticleBase.Relative.

It is hard to generalize what works or looks best for a game. So the recommended approach is to try each value of this setting. You can do that for example with the Particle Editor Demo by dragging the particle effects around.

The default position type is ParticleBase.Free.

See also PositionType.


radialAccelVariance : qreal

The radialAcceleration variance. The default value is 0. Only valid in mode ParticleBase.Gravity.


radialAcceleration : qreal

The radial acceleration. The default value is 0. Only valid in mode ParticleBase.Gravity.


rotatePerSecond : qreal

Number of degrees to rotate a particle around the source position per second. The default value is 0. Only valid in mode ParticleBase.Radius.


rotatePerSecondVariance : qreal

The rotatePerSecond variance in degrees. The default value is 0. Only valid in mode ParticleBase.Radius.


rotationEnd : qreal

The end rotation for spinning particles that rotate around its axis. The default value is 0.


rotationEndVariance : qreal

The rotationEnd variance. The default value is 0.


rotationStart : qreal

The start rotation for spinning particles that rotate around its axis. The default value is 0.


rotationStartVariance : qreal

The rotationStart variance. The default value is 0.


running : bool

This property indicates if the particle effect is currently running. It can also be used to start() and stop() the effect. The default value is false.

Set this property to true for starting the particle effect and to stop it use false. If the duration is set to ParticleBase.Infinite and the particle was starting by setting the property to true, further calls to start() will not have any effect. If autoStart is set to true you do not have to call start or set it to true because the particle should emit from startup.

See also start, stop, stopLivingParticles, and autoStart.


sourcePositionVariance : QPointF

The emitter source position variance. The default value is Qt.point(0/0).


speed : qreal

The speed of the particles. The default value is 0. Only valid in mode ParticleBase.Gravity.


speedVariance : qreal

The speed variance. The default value is 0. Only valid in mode ParticleBase.Gravity.


startColor : QColor

Start color of the particle. The default value is black which equals Qt.rgba(0,0,0,0).


startColorVariance : QColor

Start color variance of the particle. The default value is black which equals Qt.rgba(0,0,0,0).


startParticleSize : qreal

The start size of the particle image in pixels. The default value is 0.

The particle texture always is a square texture, so with a size of 64 for example, the texture is scaled to 64x64 pixels.


startParticleSizeVariance : qreal

The start size variance of the particle image in pixels. The default value is 0.


tangentialAccelVariance : qreal

The tangentialAcceleration variance. The default value is 0. Only valid in mode ParticleBase.Gravity.

Note: The tangential acceleration is currently not fully implemented in Felgo 2. If you need this feature, please contact us here.


tangentialAcceleration : qreal

The tangential acceleration. The default value is 0. Only valid in mode ParticleBase.Gravity.

Note: The tangential acceleration is currently not fully implemented in Felgo 2. If you need this feature, please contact us here.


textureFileName : QUrl

The url to the image that is used as a singe particle.

This is a required property, the default url is empty.


Method Documentation

void start()

Call this function to start the particle effect. If the duration is set to ParticleBase.Infinite, further calls to start() will not have any effect. If autoStart is set to true you do not have to call start because the particle should emit from startup.

See also stop, stopLivingParticles, and autoStart.


void stop()

Call this function to stop the particle effect. The already living particles remain remain until the end of their particleLifespan.

See also start and stopLivingParticles.


void stopLivingParticles()

Call this function when the particle effect should stop emitting new particles, and also the already living particles are destroyed. This can be useful when you want to immediately stop the effect, when the entity is used for pooling for example.

See also start and stop.


Qt_Technology_Partner_RGB_475 Qt_Service_Partner_RGB_475_padded