Merge pull request #1012 from skyace65/Update_ParticleSystems(2D)

Update Particle Systems (2D) page

learning/features/2d/particle_systems_2d.rst

@@ -22,9 +22,21 @@ Particles2D
 
 Particle systems are added to the scene via the
 :ref:`Particles2D <class_Particles2D>`
-node. They are enabled by default and start emitting white points
-downwards (as affected by the gravity). This provides a reasonable
-starting point to start adapting it to our needs.
+node. However, after creating that node you will notice that only a white dot was created, 
+and that there is a warning icon next to your Particles2D node in the inspector. This 
+is because the node needs a ParticlesMaterial to function.
+
+ParticlesMaterial
+~~~~~~~~~~~~~~~~~
+
+To add a process material to your particles node, go to Process Material in
+your inspector panel. Click on the box next to material, and from the dropdown
+menu select New Particles Material. 
+
+.. image:: img/particles_material.png
+
+Your Particles2D node should now be emitting
+white points downward.
 
 .. image:: img/particles1.png
 
@@ -37,11 +49,113 @@ the relevant texture property:
 
 .. image:: img/particles2.png
 
-Physics variables
------------------
+Time Parameters
+===============
+
+Lifetime
+--------
+
+The time in seconds that every particle will stay alive. When lifetime
+ends, a new particle is created to replace it.
+
+Lifetime: 0.5
+
+.. image:: img/paranim14.gif
+
+Lifetime: 4.0
+
+.. image:: img/paranim15.gif
+
+One Shot
+--------
+
+When enabled, a Particles2D node will emit all of it's particles once 
+and then never again.
+
+Preprocess
+----------
+
+Particle systems begin with 0 particles emitted, then start emitting.
+This can be an inconvenience when just loading a scene and systems like
+a torch, mist, etc begin emitting the moment you enter. Preprocess is
+used to let the system process a given amount of seconds before it is
+actually shown the first time.
+
+Speed Scale
+-----------
+
+The speed scale has a default value of 1, and is used to adjust the 
+speed of a particle system. Lowering the value will make the particles 
+slower, increaseing the value will make the particles much faster.
+
+Explosiveness
+-------------
+
+If lifetime is 1 and there are 10 particles, it means every particle
+will be emitted every 0.1 seconds. The explosiveness parameter changes
+this, and forces particles to be emitted all together. Ranges are:
+
+-  0: Emit all particles together.
+-  1: Emit particles at equal interval.
+
+Values in the middle are also allowed. This feature is useful for
+creating explosions or sudden bursts of particles:
+
+.. image:: img/paranim18.gif
+
+Randomness
+----------
+
+All physics parameters can be randomized. Random variables go from 0 to
+1. The formula to randomize a parameter is:
+
+::
 
-Before taking a look at the global parameters for the particle system,
-let's first see what happens when the physics variables are tweaked.
+    initial_value = param_value + param_value*randomness
+
+Fixed FPS
+---------
+
+This setting can be used to set the particle system to render at a fixed 
+FPS. For instance, changing the FPS to 2 will make the particles render 
+every 2 frames a second, however it will not slow down. 
+
+Fract Delta
+-----------
+
+This can be used to turn Fract Delta on or off.
+
+Drawing Parameters 
+==================
+
+Visability Rect
+---------------
+ 
+The W and H values control width and height of the visability rectnagle 
+respectively. The X and Y values control the position of the Upper left 
+corner of the visability rectangle relative to the particle emitter.
+
+Local Coords
+------------
+
+By default this option is on, and it means that the space that particles
+are emitted to is contained within the node. If the node is moved, all
+particles are moved with it:
+
+.. image:: img/paranim20.gif
+
+If disabled, particles will emit to global space, meaning that if the
+node is moved, the emissor is moved too:
+
+.. image:: img/paranim21.gif
+
+Draw Order
+----------
+
+The particle draw order can be set to index or lifetime.
+
+ParticlesMaterial settings
+==========================
 
 Direction
 ---------
@@ -67,8 +181,15 @@ in all directions.
 
 .. image:: img/paranim3.gif
 
-Linear velocity
----------------
+Gravity
+-------
+
+The gravity applied to every particle. 
+
+.. image:: img/paranim7.gif
+
+Initial Velocity
+----------------
 
 Linear velocity is the speed at which particles will be emitted (in
 pixels/sec). Speed might later be modified by gravity or other
@@ -76,7 +197,12 @@ accelerations (as described further below).
 
 .. image:: img/paranim4.gif
 
-Spin velocity
+Angular Velocity
+----------------
+
+Angular velocity is the inital angular velocity applied to particles.
+
+Spin Velocity
 -------------
 
 Spin velocity is the speed at which particles turn around their center
@@ -84,22 +210,19 @@ Spin velocity is the speed at which particles turn around their center
 
 .. image:: img/paranim5.gif
 
-Orbit velocity
+Orbit Velocity
 --------------
 
 Orbit velocity is used to make particles turn around their center.
 
 .. image:: img/paranim6.gif
 
-Gravity direction & strength
-----------------------------
-
-Gravity can be modified as in direction and strength. Gravity affects
-every particle currently alive.
+Linear Acceleration
+-------------------
 
-.. image:: img/paranim7.gif
+The linear acceleration applied to each particle.
 
-Radial acceleration
+Radial Acceleration
 -------------------
 
 If this acceleration is positive, particles are accelerated away from
@@ -107,7 +230,7 @@ the center. If negative, they are absorbed towards it.
 
 .. image:: img/paranim8.gif
 
-Tangential acceleration
+Tangential Acceleration
 -----------------------
 
 This acceleration will use the tangent vector to the center. Combining
@@ -124,137 +247,29 @@ high linear velocity and then stop as they fade.
 
 .. image:: img/paranim10.gif
 
-Initial angle
--------------
+Angle
+-----
 
 Determines the initial angle of the particle (in degress). This parameter
 is mostly useful randomized.
 
 .. image:: img/paranim11.gif
 
-Initial & final size
---------------------
+Scale
+-----
 
-Determines the initial and final scales of the particle.
+Determines the initial scale of the particles.
 
 .. image:: img/paranim12.gif
 
-Color phases
-------------
-
-Particles can use up to 4 color phases. Each color phase can include
-transparency.
-
-Phases must provide an offset value from 0 to 1, and always in
-ascending order. For example, a color will begin at offset 0 and end
-in offset 1, but 4 colors might use different offsets, such as 0, 0.2,
-0.8 and 1.0 for the different phases:
-
-.. image:: img/particlecolorphases.png
-
-Will result in:
-
-.. image:: img/paranim13.gif
-
-Global parameters
------------------
-
-These parameters affect the behavior of the entire system.
-
-Lifetime
---------
-
-The time in seconds that every particle will stay alive. When lifetime
-ends, a new particle is created to replace it.
-
-Lifetime: 0.5
-
-.. image:: img/paranim14.gif
-
-Lifetime: 4.0
-
-.. image:: img/paranim15.gif
-
-Timescale
----------
-
-It happens often that the effect achieved is perfect, except too fast or
-too slow. Timescale helps adjust the overall speed.
-
-Timescale everything 2x:
-
-.. image:: img/paranim16.gif
-
-Preprocess
-----------
-
-Particle systems begin with 0 particles emitted, then start emitting.
-This can be an inconvenience when just loading a scene and systems like
-a torch, mist, etc begin emitting the moment you enter. Preprocess is
-used to let the system process a given amount of seconds before it is
-actually shown the first time.
-
-Emit timeout
-------------
-
-This variable will switch emission off after given amount of seconds
-being on. When zero, it is disabled.
-
-Offset
-------
-
-Allows to move the emission center away from the center
-
-Half extents
-------------
-
-Makes the center (by default 1 pixel) wider, to the size in pixels
-desired. Particles will emit randomly inside this area.
-
-.. image:: img/paranim17.gif
-
-It is also possible to set an emission mask by using this value. Check
-the "Particles" menu on the 2D scene editor viewport and select your
-favorite texture. Opaque pixels will be used as potential emission
-location, while transparent ones will be ignored:
-
-.. image:: img/paranim19.gif
-
-Local space
------------
-
-By default this option is on, and it means that the space that particles
-are emitted to is contained within the node. If the node is moved, all
-particles are moved with it:
-
-.. image:: img/paranim20.gif
-
-If disabled, particles will emit to global space, meaning that if the
-node is moved, the emissor is moved too:
+Color
+-----
 
-.. image:: img/paranim21.gif
+Used to change the color of the particles being emitted.
 
-Explosiveness
+Hue variation
 -------------
 
-If lifetime is 1 and there are 10 particles, it means every particle
-will be emitted every 0.1 seconds. The explosiveness parameter changes
-this, and forces particles to be emitted all together. Ranges are:
-
--  0: Emit all particles together.
--  1: Emit particles at equal interval.
-
-Values in the middle are also allowed. This feature is useful for
-creating explosions or sudden bursts of particles:
-
-.. image:: img/paranim18.gif
-
-Randomness
-----------
-
-All physics parameters can be randomized. Random variables go from 0 to
-1. The formula to randomize a parameter is:
-
-::
-
-    initial_value = param_value + param_value*randomness
+The variation value sets the inital hue variation applied to each 
+particle. The Variation rand value controls the hue variation
+randomness ratio.