• Home
• Felgo
• GameParticle

GameParticle

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

• List of all members, including inherited members

Properties

• angleVariance : qreal
• autoStart : bool
• duration : Duration
• emissionRate : qreal
• emitterType : EmitterType
• fileName : QUrl
• finishColor : QColor
• finishColorVariance : QColor
• finishParticleSize : qreal
• finishParticleSizeVariance : qreal
• gravity : QPointF
• maxParticles : int
• maxRadius : qreal
• maxRadiusVariance : qreal
• minRadius : qreal
• minRadiusVariance : qreal
• particleLifespan : qreal
• particleLifespanVariance : qreal
• positionType : PositionType
• radialAccelVariance : qreal
• radialAcceleration : qreal
• rotatePerSecond : qreal
• rotatePerSecondVariance : qreal
• rotationEnd : qreal
• rotationEndVariance : qreal
• rotationStart : qreal
• rotationStartVariance : qreal
• running : bool
• sourcePositionVariance : QPointF
• speed : qreal
• speedVariance : qreal
• startColor : QColor
• startColorVariance : QColor
• startParticleSize : qreal
• startParticleSizeVariance : qreal
• tangentialAccelVariance : qreal
• tangentialAcceleration : qreal
• textureFileName : QUrl

Methods

• void start()
• void stop()
• void stopLivingParticles()

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:

• ParticleBase.Gravity - Includes particle behavior of Gravity + Tangential Accel + Radial Accel.
• ParticleBase.Radius - Inlcudes particle behavior of circular movement.

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:

• gravity
• speed
• speedVariance
• tangentialAcceleration
• tangentialAccelVariance
• radialAcceleration
• radialAccelVariance

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.

Radius

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

• minRadius
• minRadiusVariance
• maxRadius
• maxRadiusVariance
• rotatePerSecond
• rotatePerSecondVariance

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.

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.

Further Resources About Particle Systems

• Qt Quick Particle Effects Overview
• QML Book Chapter about Particles
• Wikipedia Article about Particle Systems
• Cocos2d Programming Guide about Particle Systems
• Online Flash version of a particle editor for testing different particle effects properties and support for exporting the effect
• A Very good Particle Designer for Mac by 71 Squared that comes with a free version

Property Documentation

Method Documentation