The Particle component allows visual effects like fire, explosions, smoke or rain. More...
| Import Statement: | import Felgo 3.0 |
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.
Following examples demonstrate the usage of the Particle element.
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 3.0 import QtQuick 2.0 GameWindow { id: gameWindow Scene { id: scene Particle { id: fireParticle // Particle location properties x: scene.width/2 y: scene.height/2 rotation: 90 // particle file fileName: "fireParticle.json" // start when finished loading autoStart: true } } // end of Scene } // end of GameWindow
This is how the the above particle effect looks like:
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 3.0 import QtQuick 2.0 GameWindow { id: gameWindow Scene { id: scene Particle { 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: "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.
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.
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.
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.
You can choose from 3 different PositionType values:
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 ParticlesVPlay 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.
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.
Used to define the infinite duration of a particle effect.
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.
Particle { filename: "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().
Particle { 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.
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:
maxParticles / particleLifespan. You usually do not need to set this property, instead modify maxParticles and particleLifespan!
See also Particle Performance section of Particle Editor Demo.
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.
|
autoStart : bool |
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.
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.
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.
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.
Finish color of the particle. The default value is black which equals Qt.rgba(0,0,0,0).
Finish color variance of the particle. The default value is black which equals Qt.rgba(0,0,0,0).
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.
The finish size variance of the particle image in pixels. The default value is 0.
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.
The ending radius of the particles. The default value is 0. Only valid in mode ParticleBase.Radius.
The maxRadius variance. The default is 0. Only valid in mode ParticleBase.Radius.
The starting radius of the particles. The default value is 0. Only valid in mode ParticleBase.Radius.
The minRadius variance. The default value is 0. Only valid in mode ParticleBase.Radius.
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.
The particleLifespan variance. The default value is 0.
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.
The radialAcceleration variance. The default value is 0. Only valid in mode ParticleBase.Gravity.
The radial acceleration. The default value is 0. Only valid in mode ParticleBase.Gravity.
Number of degrees to rotate a particle around the source position per second. The default value is 0. Only valid in mode ParticleBase.Radius.
The rotatePerSecond variance in degrees. The default value is 0. Only valid in mode ParticleBase.Radius.
The end rotation for spinning particles that rotate around its axis. The default value is 0.
The rotationEnd variance. The default value is 0.
The start rotation for spinning particles that rotate around its axis. The default value is 0.
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.
The emitter source position variance. The default value is Qt.point(0/0).
The speed of the particles. The default value is 0. Only valid in mode ParticleBase.Gravity.
The speed variance. The default value is 0. Only valid in mode ParticleBase.Gravity.
Start color of the particle. The default value is black which equals Qt.rgba(0,0,0,0).
Start color variance of the particle. The default value is black which equals Qt.rgba(0,0,0,0).
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.
The start size variance of the particle image in pixels. The default value is 0.
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.
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.
The url to the image that is used as a singe particle.
This is a required property, the default url is empty.
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.
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.
