<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- affectors.qdoc -->
<title>Qt Quick Particles Examples - Affectors | Qt Quick 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qtquick-index.html">Qt Quick</a></td><td >Qt Quick Particles Examples - Affectors</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar"><div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Quick Particles Examples - Affectors</h1>
<span class="subtitle"></span>
<!-- $$$particles/affectors-description -->
<div class="descr"> <a name="details"></a>
<p class="centerAlign"><img src="images/qml-affectors-example.png" alt="" /></p><p>This is a collection of small QML examples relating to using Affectors in the particle system. Each example is a small QML file emphasizing a particular type or feature.</p>
<p>Age demonstrates using an Age affector to prematurely end the lives of particles.</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-age.html">Age</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">system</span>: <span class="name">particles</span>
<span class="name">once</span>: <span class="number">true</span>
<span class="name">lifeLeft</span>: <span class="number">1200</span>
<span class="name">advancePosition</span>: <span class="number">false</span>
}
</pre>
<p>As you move the affector around the screen, the particles inside it (which haven't already been affected) jump to a period near the end of their life. This gives them a short period to finish fading out, but changing lifeLeft to 0 (the default), would cause them to reach the end of their life instantly.</p>
<p>Attractor demonstrates using an Attractor affector to simulate a black hole</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-attractor.html">Attractor</a></span> {
<span class="name">id</span>: <span class="name">gs</span>; <span class="name">pointX</span>: <span class="name">root</span>.<span class="name">width</span><span class="operator">/</span><span class="number">2</span>; <span class="name">pointY</span>: <span class="name">root</span>.<span class="name">height</span><span class="operator">/</span><span class="number">2</span>; <span class="name">strength</span>: <span class="number">4000000</span>;
<span class="name">affectedParameter</span>: <span class="name">Attractor</span>.<span class="name">Acceleration</span>
<span class="name">proportionalToDistance</span>: <span class="name">Attractor</span>.<span class="name">InverseQuadratic</span>
}
</pre>
<p>All particles in the scene, including the rocket ship's exhaust and pellets, are pulled towards the black hole. This effect is stronger closer to the black hole, so the asteroids near the top of the screen are barely affected at all, while the ones towards the middle sometimes curve drastically. To complete the effect, an Age affector covers the black hole to destroy particles which come in contact with it.</p>
<p>Custom Affector manipulates the properties of the particles directly in javascript. One Affector is used to make the leaves rock back and forth as they fall, looking more leaf-like than just spinning in circles:</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-affector.html">Affector</a></span> {
property <span class="type">real</span> <span class="name">coefficient</span>: <span class="number">0.1</span>
property <span class="type">real</span> <span class="name">velocity</span>: <span class="number">1.5</span>
<span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span>
<span class="name">height</span>: <span class="name">parent</span>.<span class="name">height</span> <span class="operator">-</span> <span class="number">100</span>
<span class="name">onAffectParticles</span>: {
<span class="comment">/* //Linear movement
if (particle.r == 0) {
particle.r = Math.random() > 0.5 ? -1 : 1;
} else if (particle.r == 1) {
particle.rotation += velocity * dt;
if (particle.rotation >= maxAngle)
particle.r = -1;
} else if (particle.r == -1) {
particle.rotation -= velocity * dt;
if (particle.rotation <= -1 * maxAngle)
particle.r = 1;
}
*/</span>
<span class="comment">//Wobbly movement</span>
<span class="keyword">for</span> (<span class="keyword">var</span> <span class="name">i</span>=<span class="number">0</span>; <span class="name">i</span><span class="operator"><</span><span class="name">particles</span>.<span class="name">length</span>; i++) {
var <span class="name">particle</span> = <span class="name">particles</span>[<span class="name">i</span>];
<span class="keyword">if</span> (<span class="name">particle</span>.<span class="name">r</span> <span class="operator">==</span> <span class="number">0.0</span>) {
<span class="name">particle</span>.<span class="name">r</span> <span class="operator">=</span> <span class="name">Math</span>.<span class="name">random</span>() <span class="operator">+</span> <span class="number">0.01</span>;
}
<span class="name">particle</span>.<span class="name">rotation</span> <span class="operator">+=</span> <span class="name">velocity</span> <span class="operator">*</span> <span class="name">particle</span>.<span class="name">r</span> <span class="operator">*</span> <span class="name">dt</span>;
<span class="name">particle</span>.<span class="name">r</span> <span class="operator">-=</span> <span class="name">particle</span>.<span class="name">rotation</span> <span class="operator">*</span> <span class="name">coefficient</span>;
<span class="keyword">if</span> (<span class="name">particle</span>.<span class="name">r</span> <span class="operator">==</span> <span class="number">0.0</span>)
<span class="name">particle</span>.<span class="name">r</span> <span class="operator">-=</span> <span class="name">particle</span>.<span class="name">rotation</span> <span class="operator">*</span> <span class="number">0.000001</span>;
<span class="name">particle</span>.<span class="name">update</span> <span class="operator">=</span> <span class="number">1</span>;
}
}
}
</pre>
<p>Another is used to provide a slightly varying friction to the leaves as they 'land', to look more natural:</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-affector.html">Affector</a></span> {<span class="comment">//Custom Friction, adds some 'randomness'</span>
<span class="name">x</span>: -<span class="number">60</span>
<span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span> <span class="operator">+</span> <span class="number">120</span>
<span class="name">height</span>: <span class="number">100</span>
<span class="name">anchors</span>.bottom: <span class="name">parent</span>.<span class="name">bottom</span>
<span class="name">onAffectParticles</span>: {
<span class="keyword">for</span> (<span class="keyword">var</span> <span class="name">i</span>=<span class="number">0</span>; <span class="name">i</span><span class="operator"><</span><span class="name">particles</span>.<span class="name">length</span>; i++) {
var <span class="name">particle</span> = <span class="name">particles</span>[<span class="name">i</span>];
var <span class="name">pseudoRand</span> = (<span class="name">Math</span>.<span class="name">floor</span>(<span class="name">particle</span>.<span class="name">t</span><span class="operator">*</span><span class="number">1327</span>) <span class="operator">%</span> <span class="number">10</span>) <span class="operator">+</span> <span class="number">1</span>;
var <span class="name">yslow</span> = <span class="name">dt</span> <span class="operator">*</span> <span class="name">pseudoRand</span> <span class="operator">*</span> <span class="number">0.5</span> <span class="operator">+</span> <span class="number">1</span>;
var <span class="name">xslow</span> = <span class="name">dt</span> <span class="operator">*</span> <span class="name">pseudoRand</span> <span class="operator">*</span> <span class="number">0.05</span> <span class="operator">+</span> <span class="number">1</span>;
<span class="keyword">if</span> (<span class="name">particle</span>.<span class="name">vy</span> <span class="operator"><</span> <span class="number">1</span>)
<span class="name">particle</span>.<span class="name">vy</span> <span class="operator">=</span> <span class="number">0</span>;
<span class="keyword">else</span>
<span class="name">particle</span>.<span class="name">vy</span> <span class="operator">=</span> (<span class="name">particle</span>.<span class="name">vy</span> <span class="operator">/</span> <span class="name">yslow</span>);
<span class="keyword">if</span> (<span class="name">particle</span>.<span class="name">vx</span> <span class="operator"><</span> <span class="number">1</span>)
<span class="name">particle</span>.<span class="name">vx</span> <span class="operator">=</span> <span class="number">0</span>;
<span class="keyword">else</span>
<span class="name">particle</span>.<span class="name">vx</span> <span class="operator">=</span> (<span class="name">particle</span>.<span class="name">vx</span> <span class="operator">/</span> <span class="name">xslow</span>);
<span class="name">particle</span>.<span class="name">update</span> <span class="operator">=</span> <span class="number">true</span>;
}
}
}
</pre>
<p>Friction is similar to the falling leaves in the custom affector, except that it uses a flat friction the whole way down instead of custom affectors.</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-friction.html">Friction</a></span> {
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">anchors</span>.margins: -<span class="number">40</span>
<span class="name">factor</span>: <span class="number">0.4</span>
}
</pre>
<p>Gravity is a convenience affector for applying a constant acceleration to particles inside it</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-gravity.html">Gravity</a></span> {
<span class="name">system</span>: <span class="name">sys</span>
<span class="name">magnitude</span>: <span class="number">32</span>
<span class="name">angle</span>: <span class="name">ground</span>.<span class="name">rotation</span> <span class="operator">+</span> <span class="number">90</span>
}
</pre>
<p><a href="qml-qtquick-particles-groupgoal.html">GroupGoal</a> sets up two particle groups for flaming and non-flaming balls, and gives you various ways to transition between them.</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-particlegroup.html">ParticleGroup</a></span> {
<span class="name">name</span>: <span class="string">"unlit"</span>
<span class="name">duration</span>: <span class="number">1000</span>
<span class="name">to</span>: {"lighting":<span class="number">1</span>, "unlit":<span class="number">99</span>}
<span class="type"><a href="qml-qtquick-particles-imageparticle.html">ImageParticle</a></span> {
<span class="name">source</span>: <span class="string">"../../images/particleA.png"</span>
<span class="name">colorVariation</span>: <span class="number">0.1</span>
<span class="name">color</span>: <span class="string">"#2060160f"</span>
}
<span class="type"><a href="qml-qtquick-particles-groupgoal.html">GroupGoal</a></span> {
<span class="name">whenCollidingWith</span>: [<span class="string">"lit"</span>]
<span class="name">goalState</span>: <span class="string">"lighting"</span>
<span class="name">jump</span>: <span class="number">true</span>
}
}
</pre>
<p>The non-flaming balls have a one in a hundred chance of lighting on their own each second, but they also have a <a href="qml-qtquick-particles-groupgoal.html">GroupGoal</a> set on the whole group. This affector affects all particles of the unlit group, when colliding with particles in the lit group, and cause them to move to the lighting group.</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-particlegroup.html">ParticleGroup</a></span> {
<span class="name">name</span>: <span class="string">"lighting"</span>
<span class="name">duration</span>: <span class="number">100</span>
<span class="name">to</span>: {"lit":<span class="number">1</span>}
}
</pre>
<p>lighting is an intermediate group so that the glow builds up and the transition is less jarring. So it automatically moves into the lit group after 100ms.</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-particlegroup.html">ParticleGroup</a></span> {
<span class="name">name</span>: <span class="string">"lit"</span>
<span class="name">duration</span>: <span class="number">10000</span>
<span class="name">onEntered</span>: score++;
<span class="type"><a href="qml-qtquick-particles-trailemitter.html">TrailEmitter</a></span> {
<span class="name">id</span>: <span class="name">fireballFlame</span>
<span class="name">group</span>: <span class="string">"flame"</span>
<span class="name">emitRatePerParticle</span>: <span class="number">48</span>
<span class="name">lifeSpan</span>: <span class="number">200</span>
<span class="name">emitWidth</span>: <span class="number">8</span>
<span class="name">emitHeight</span>: <span class="number">8</span>
<span class="name">size</span>: <span class="number">24</span>
<span class="name">sizeVariation</span>: <span class="number">8</span>
<span class="name">endSize</span>: <span class="number">4</span>
}
<span class="type"><a href="qml-qtquick-particles-trailemitter.html">TrailEmitter</a></span> {
<span class="name">id</span>: <span class="name">fireballSmoke</span>
<span class="name">group</span>: <span class="string">"smoke"</span>
</pre>
<p>The lit group also has TrailEmitters on it for additional fire and smoke, but does not transition anywhere. There are two more <a href="qml-qtquick-particles-groupgoal.html">GroupGoal</a> objects that allow particles in the unlit group to transition to the lighting group (and then to the lit group).</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-groupgoal.html">GroupGoal</a></span> {
<span class="name">groups</span>: [<span class="string">"unlit"</span>]
<span class="name">goalState</span>: <span class="string">"lit"</span>
<span class="name">jump</span>: <span class="number">true</span>
<span class="name">system</span>: <span class="name">particles</span>
<span class="name">x</span>: -<span class="number">15</span>
<span class="name">y</span>: -<span class="number">55</span>
<span class="name">height</span>: <span class="number">75</span>
<span class="name">width</span>: <span class="number">30</span>
<span class="name">shape</span>: <span class="name">MaskShape</span> {<span class="name">source</span>: <span class="string">"../../images/matchmask.png"</span>}
}
</pre>
<p>The first is just an area bound to the location of an image of a pilot flame. When unlit balls pass through the flame, they go straight to lit because the pilot flame is so hot.</p>
<pre class="qml">
<span class="comment">//Click to enflame</span>
<span class="type"><a href="qml-qtquick-particles-groupgoal.html">GroupGoal</a></span> {
<span class="name">groups</span>: [<span class="string">"unlit"</span>]
<span class="name">goalState</span>: <span class="string">"lighting"</span>
<span class="name">jump</span>: <span class="number">true</span>
<span class="name">enabled</span>: <span class="name">ma</span>.<span class="name">pressed</span>
<span class="name">width</span>: <span class="number">18</span>
<span class="name">height</span>: <span class="number">18</span>
<span class="name">x</span>: <span class="name">ma</span>.<span class="name">mouseX</span> <span class="operator">-</span> <span class="name">width</span><span class="operator">/</span><span class="number">2</span>
<span class="name">y</span>: <span class="name">ma</span>.<span class="name">mouseY</span> <span class="operator">-</span> <span class="name">height</span><span class="operator">/</span><span class="number">2</span>
}
</pre>
<p>The second is bound to the location of the last pointer interaction, so that touching or clicking on unlit balls (which is hard due to their constant movement) causes them to move to the lighting group.</p>
<p>Move shows some simple effects you can get by altering trajectory midway. The red particles have an affector that affects their position, jumping them forwards by 120px.</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-affector.html">Affector</a></span> {
<span class="name">groups</span>: [<span class="string">"A"</span>]
<span class="name">x</span>: <span class="number">120</span>
<span class="name">width</span>: <span class="number">80</span>
<span class="name">height</span>: <span class="number">80</span>
<span class="name">once</span>: <span class="number">true</span>
<span class="name">position</span>: <span class="name">PointDirection</span> { <span class="name">x</span>: <span class="number">120</span>; }
}
</pre>
<p>The green particles have an affector that affects their velocity, but with some angle variation. By adding some random direction velocity to their existing forwards velocity, they begin to spray off in a cone.</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-affector.html">Affector</a></span> {
<span class="name">groups</span>: [<span class="string">"B"</span>]
<span class="name">x</span>: <span class="number">120</span>
<span class="name">y</span>: <span class="number">240</span>
<span class="name">width</span>: <span class="number">80</span>
<span class="name">height</span>: <span class="number">80</span>
<span class="name">once</span>: <span class="number">true</span>
<span class="name">velocity</span>: <span class="name">AngleDirection</span> { <span class="name">angleVariation</span>:<span class="number">360</span>; <span class="name">magnitude</span>: <span class="number">72</span> }
}
</pre>
<p>The blue particles have an affector that affects their acceleration, and because it sets relative to false this resets the acceleration instead of adding to it. Once the blue particles reach the affector, their horizontal velocity stops increasing as their vertical velocity decreases.</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-affector.html">Affector</a></span> {
<span class="name">groups</span>: [<span class="string">"C"</span>]
<span class="name">x</span>: <span class="number">120</span>
<span class="name">y</span>: <span class="number">400</span>
<span class="name">width</span>: <span class="number">80</span>
<span class="name">height</span>: <span class="number">120</span>
<span class="name">once</span>: <span class="number">true</span>
<span class="name">relative</span>: <span class="number">false</span>
<span class="name">acceleration</span>: <span class="name">PointDirection</span> { <span class="name">y</span>: -<span class="number">80</span>; }
}
</pre>
<p><a href="qml-qtquick-particles-spritegoal.html">SpriteGoal</a> has an affector which interacts with the sprite engine of particles, if they are being drawn as sprites by <a href="qml-qtquick-particles-imageparticle.html">ImageParticle</a>.</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-spritegoal.html">SpriteGoal</a></span> {
<span class="name">groups</span>: [<span class="string">"meteor"</span>]
<span class="name">system</span>: <span class="name">sys</span>
<span class="name">goalState</span>: <span class="string">"explode"</span>
<span class="name">jump</span>: <span class="number">true</span>
<span class="name">anchors</span>.fill: <span class="name">rocketShip</span>
<span class="name">width</span>: <span class="number">60</span>
<span class="name">height</span>: <span class="number">60</span>
}
</pre>
<p>The <a href="qml-qtquick-particles-spritegoal.html">SpriteGoal</a> follows the image of the rocket ship on screen, and when it interacts with particles drawn by <a href="qml-qtquick-particles-imageparticle.html">ImageParticle</a> as sprites, it instructs them to move immediately to the "explode" state, which in this case is the animation of the asteroid breaking into many pieces.</p>
<p>Turbulence has a flame with smoke, and both sets of particles being affected by a Turbulence affector. This gives a faint wind effect.</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-turbulence.html">Turbulence</a></span> {
<span class="name">id</span>: <span class="name">turb</span>
<span class="name">enabled</span>: <span class="number">true</span>
<span class="name">height</span>: (<span class="name">parent</span>.<span class="name">height</span> <span class="operator">/</span> <span class="number">2</span>) <span class="operator">-</span> <span class="number">4</span>
<span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span>
<span class="name">x</span>: <span class="name">parent</span>. <span class="name">width</span> <span class="operator">/</span> <span class="number">4</span>
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">strength</span>: <span class="number">32</span>
NumberAnimation on <span class="name">strength</span>{<span class="name">from</span>: <span class="number">16</span>; <span class="name">to</span>: <span class="number">64</span>; <span class="name">easing</span>.type: <span class="name">Easing</span>.<span class="name">InOutBounce</span>; <span class="name">duration</span>: <span class="number">1800</span>; <span class="name">loops</span>: -<span class="number">1</span>}
}
</pre>
<p>To make the wind change direction, subsitute a black and white noise image in the noiseSource parameter (it currently uses a default noise source).</p>
<p>Wander uses a Wander affector to add some horizontal drift to snowflakes as they fall down.</p>
<pre class="qml">
<span class="type"><a href="qml-qtquick-particles-wander.html">Wander</a></span> {
<span class="name">id</span>: <span class="name">wanderer</span>
<span class="name">system</span>: <span class="name">particles</span>
<span class="name">anchors</span>.fill: <span class="name">parent</span>
<span class="name">xVariance</span>: <span class="number">360</span><span class="operator">/</span>(<span class="name">wanderer</span>.<span class="name">affectedParameter</span><span class="operator">+</span><span class="number">1</span>);
<span class="name">pace</span>: <span class="number">100</span><span class="operator">*</span>(<span class="name">wanderer</span>.<span class="name">affectedParameter</span><span class="operator">+</span><span class="number">1</span>);
}
</pre>
<p>There are different movements given by applying the Wander to different attributes of the trajectory, so the example makes it easy to play around and see the difference.</p>
<p>Files:</p>
<ul>
<li><a href="qtquick-particles-affectors-affectors-qml.html">particles/affectors/affectors.qml</a></li>
<li><a href="qtquick-particles-affectors-content-greybutton-qml.html">particles/affectors/content/GreyButton.qml</a></li>
<li><a href="qtquick-particles-affectors-content-age-qml.html">particles/affectors/content/age.qml</a></li>
<li><a href="qtquick-particles-affectors-content-attractor-qml.html">particles/affectors/content/attractor.qml</a></li>
<li><a href="qtquick-particles-affectors-content-customaffector-qml.html">particles/affectors/content/customaffector.qml</a></li>
<li><a href="qtquick-particles-affectors-content-friction-qml.html">particles/affectors/content/friction.qml</a></li>
<li><a href="qtquick-particles-affectors-content-gravity-qml.html">particles/affectors/content/gravity.qml</a></li>
<li><a href="qtquick-particles-affectors-content-groupgoal-qml.html">particles/affectors/content/groupgoal.qml</a></li>
<li><a href="qtquick-particles-affectors-content-move-qml.html">particles/affectors/content/move.qml</a></li>
<li><a href="qtquick-particles-affectors-content-spritegoal-qml.html">particles/affectors/content/spritegoal.qml</a></li>
<li><a href="qtquick-particles-affectors-content-turbulence-qml.html">particles/affectors/content/turbulence.qml</a></li>
<li><a href="qtquick-particles-affectors-content-wander-qml.html">particles/affectors/content/wander.qml</a></li>
<li><a href="qtquick-particles-affectors-main-cpp.html">particles/affectors/main.cpp</a></li>
<li><a href="qtquick-particles-affectors-affectors-pro.html">particles/affectors/affectors.pro</a></li>
<li><a href="qtquick-particles-affectors-affectors-qmlproject.html">particles/affectors/affectors.qmlproject</a></li>
<li><a href="qtquick-particles-affectors-affectors-qrc.html">particles/affectors/affectors.qrc</a></li>
</ul>
</div>
<!-- @@@particles/affectors -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
