Update 3D particles pages for 4.2

skyace65 · skyace65 · commit 617026ac702f · 2023-11-04T16:09:52.000-04:00
diff --git a/tutorials/3d/particles/creating_a_3d_particle_system.rst b/tutorials/3d/particles/creating_a_3d_particle_system.rst
@@ -72,6 +72,9 @@ menu. When you do so, keep in mind that not every feature of GPU particles is av
 CPU particles, so the resulting particle system will look and behave differently from the
 original.
 
+You can also convert CPU particles to GPU particles if you no longer need to use CPU particles.
+This is also done from the viewport menu.
+
 Some of the most notable features that are lost during the conversion include:
 
 - multiple draw passes
@@ -81,5 +84,19 @@ Some of the most notable features that are lost during the conversion include:
 - attractors
 - collision
 
+You also lose the following properties:
+
+- ``Ammount Ratio``
+- ``Interp to End``
+- ``Damping as Friction``
+- ``Emission Shape Offset``
+- ``Emission Shape Scale``
+- ``Inherit Velocity Ratio``
+- ``Velocity Pivot``
+- ``Directional Velocity``
+- ``Radial Velocity``
+- ``Velocity Limit``
+- ``Scale Over Velocity``
+
 Converting GPU particles to CPU particles can become necessary when you want to release a game
 on older devices that don't support modern graphics APIs.
diff --git a/tutorials/3d/particles/img/particle_props_emitter.webp b/tutorials/3d/particles/img/particle_props_emitter.webp
diff --git a/tutorials/3d/particles/img/particle_props_time.webp b/tutorials/3d/particles/img/particle_props_time.webp
diff --git a/tutorials/3d/particles/index.rst b/tutorials/3d/particles/index.rst
@@ -53,6 +53,7 @@ and :ref:`class_CPUParticles3D`, which are processed on the CPU.
 CPU particle systems are less flexible than their GPU counterpart, but they work on a wider range of hardware and
 provide better support for older devices and mobile phones. Because they are processed on the CPU,
 they are not as performant as GPU particle systems and can't render as many individual particles.
+In addition they currently do not have all the available options GPU particles have for control.
 
 GPU particle systems run on the GPU and can render hundreds of thousands of particles on modern
 hardware. You can write custom particle shaders for them, which makes them very flexible. You can
diff --git a/tutorials/3d/particles/process_material_properties.rst b/tutorials/3d/particles/process_material_properties.rst
@@ -26,6 +26,30 @@ lifetime. A value of ``0`` means there is no randomness at all and all particles
 the same amount of time, set by the :ref:`Lifetime <doc_3d_particles_properties_time>` property. A value of ``1`` means
 that a particle's lifetime is completely random within the range of [0.0, ``Lifetime``].
 
+Particle flags
+--------------
+
+The ``Align Y`` property aligns each particle's Y-axis with its velocity. Enabling this
+property is the same as setting the :ref:`Transform Align <doc_3d_particles_properties_draw>` property to
+``Y to Velocity``.
+
+The ``Rotate Y`` property works with the properties in the `Angle <#angle>`__ and
+`Angular Velocity <#angular-velocity>`__ groups to control particle rotation. ``Rotate Y``
+has to be enabled if you want to apply any rotation to particles. The exception to this
+is any particle that uses the :ref:`Standard Material <doc_standard_material_3d>`
+where the ``Billboard`` property is set to ``Particle Billboard``. In that case, particles
+rotate even without ``Rotate Y`` enabled.
+
+When the ``Disable Z`` property is enabled, particles will not move along the Z-axis.
+Whether that is going to be the particle system's local Z-axis or the world Z-axis is
+determined by the :ref:`Local Coords <doc_3d_particles_properties_draw>` property.
+
+The ``Daming as Friction`` property changes the behavior of damping from a constant
+deceleration to a deceleration based on speed.
+
+Spawn
+-----
+
 .. _doc_process_material_properties_shapes:
 
 Emission shape
@@ -61,38 +85,14 @@ In addition to these relatively simple shapes, you can select the ``Points`` or
 :ref:`Complex emission shapes <doc_3d_particles_complex_shapes>` section for a detailed
 explanation of how to set these up.
 
-Particle flags
-~~~~~~~~~~~~~~
-
-The ``Align Y`` property aligns each particle's Y-axis with its velocity. Enabling this
-property is the same as setting the :ref:`Transform Align <doc_3d_particles_properties_draw>` property to
-``Y to Velocity``.
-
-The ``Rotate Y`` property works with the properties in the `Angle <#angle>`__ and
-`Angular Velocity <#angular-velocity>`__ groups to control particle rotation. ``Rotate Y``
-has to be enabled if you want to apply any rotation to particles. The exception to this
-is any particle that uses the :ref:`Standard Material <doc_standard_material_3d>`
-where the ``Billboard`` property is set to ``Particle Billboard``. In that case, particles
-rotate even without ``Rotate Y`` enabled.
-
-When the ``Disable Z`` property is enabled, particles will not move along the Z-axis.
-Whether that is going to be the particle system's local Z-axis or the world Z-axis is
-determined by the :ref:`Local Coords <doc_3d_particles_properties_draw>` property.
-
-Gravity
-~~~~~~~
-
-The next few property groups work closely together to control particle movement and rotation.
-``Gravity`` drags particles in the direction it points at, which is straight down at the strength
-of Earth's gravity by default. Gravity affects all particle movement.
-If your game uses physics and the world's gravity can change at runtime, you can use this property
-to keep the game's gravity in sync with particle gravity. A ``Gravity`` value of ``(X=0,Y=0,Z=0)`` means
-no particle will ever move at all if none of the other movement properties are set.
-
-.. figure:: img/particle_gravity.webp
-   :alt: Different values for particle gravity
+Angle
+~~~~~
 
-   Left\: (X=0,Y=-9.8,Z=0), middle\: (X=0,Y=9.8,Z=0), right\: (X=4,Y=2,Z=0).
+The ``Angle`` property controls a particle's starting rotation `as described above <#process-material-properties>`__.
+In order to have an actual effect on the particle, you have to enable one of two properties: `Rotate Y <#particle-flags>`__
+rotates the particle around the particle system's Y-axis. The ``Billboard`` property in
+the :ref:`Standard Material <doc_standard_material_3d>`, if it is set to ``Particle Billboard``, rotates
+the particle around the axis that points from the particle to the camera.
 
 Direction
 ~~~~~~~~~
@@ -140,6 +140,36 @@ values for either of these properties `as described above <#process-material-pro
 particles begin to move. The direction is multiplied by these values, so you can make particles
 move in the opposite direction by setting a negative velocity.
 
+Accelerations
+-------------
+
+Gravity
+~~~~~~~
+
+The next few property groups work closely together to control particle movement and rotation.
+``Gravity`` drags particles in the direction it points at, which is straight down at the strength
+of Earth's gravity by default. Gravity affects all particle movement.
+If your game uses physics and the world's gravity can change at runtime, you can use this property
+to keep the game's gravity in sync with particle gravity. A ``Gravity`` value of ``(X=0,Y=0,Z=0)`` means
+no particle will ever move at all if none of the other movement properties are set.
+
+.. figure:: img/particle_gravity.webp
+   :alt: Different values for particle gravity
+
+   Left\: (X=0,Y=-9.8,Z=0), middle\: (X=0,Y=9.8,Z=0), right\: (X=4,Y=2,Z=0).
+
+Angular velocity
+~~~~~~~~~~~~~~~~
+
+``Angular Velocity`` controls a particle's speed of rotation `as described above <#process-material-properties>`__.
+You can reverse the direction by using negative numbers for ``Velocity Min`` or ``Velocity Max``. Like the
+`Angle <#angle>`__ property, the rotation will only be visible if the `Rotate Y <#particle-flags>`__ flag is set
+or the ``Particle Billboard`` mode is selected in the :ref:`Standard Material <doc_standard_material_3d>`.
+
+.. note::
+
+   The `Damping <#damping>`__ property has no effect on the angular velocity.
+
 Linear acceleration
 ~~~~~~~~~~~~~~~~~~~
 
@@ -214,26 +244,15 @@ is slowed down a little unless the total acceleration is greater than the dampin
 it isn't, the particle will keep slowing down until it doesn't move at all. The greater the value, the less
 time it takes to bring particles to a complete halt.
 
-Angle
-~~~~~
-
-The ``Angle`` property controls a particle's starting rotation `as described above <#process-material-properties>`__.
-In order to have an actual effect on the particle, you have to enable one of two properties: `Rotate Y <#particle-flags>`__
-rotates the particle around the particle system's Y-axis. The ``Billboard`` property in
-the :ref:`Standard Material <doc_standard_material_3d>`, if it is set to ``Particle Billboard``, rotates
-the particle around the axis that points from the particle to the camera.
-
-Angular velocity
-~~~~~~~~~~~~~~~~
-
-``Angular Velocity`` controls a particle's speed of rotation `as described above <#process-material-properties>`__.
-You can reverse the direction by using negative numbers for ``Velocity Min`` or ``Velocity Max``. Like the
-`Angle <#angle>`__ property, the rotation will only be visible if the `Rotate Y <#particle-flags>`__ flag is set
-or the ``Particle Billboard`` mode is selected in the :ref:`Standard Material <doc_standard_material_3d>`.
+Attractor interaction
+~~~~~~~~~~~~~~~~~~~~~
 
-.. note::
+If you want the particle system to interact with :ref:`particle attractors <doc_3d_particles_attractors>`,
+you have to check the ``Enabled`` property. When it is disabled, the particle system
+ignores all particle attractors.
 
-   The `Damping <#damping>`__ property has no effect on the angular velocity.
+Display
+-------
 
 Scale
 ~~~~~
@@ -293,17 +312,6 @@ limits the available colors to the closest neighbors of the original color.
 
    Different values for hue variation, both times with blue as base color: 0.6 (left) and 0.1 (right)
 
-.. _doc_process_material_properties_turbulence:
-
-Turbulence
-~~~~~~~~~~
-
-Turbulence adds noise to particle movement, creating interesting and lively patterns.
-Check the box next to the ``Enabled`` property to activate it. A number
-of new properties show up that control the movement speed, noise pattern and overall influence
-on the particle system. You can find a detailed explanation of these in the section on
-:ref:`particle turbulence <doc_3d_particles_turbulence>`.
-
 .. _doc_process_material_properties_animation:
 
 Animation
@@ -376,41 +384,21 @@ the particle is simulated on every rendered frame. If this is not an option for
 your use case, set **Fixed FPS** to be equal to the effective framerate used by
 the flipbook animation (see above for the formula).
 
-.. _doc_process_material_properties_subemitter:
-
-Sub-emitter
-~~~~~~~~~~~
-
-.. figure:: img/particle_sub_mode.webp
-   :alt: Sub-emitter modes
-   :align: right
-
-   The available sub-emitter modes
-
-The ``Mode`` property controls how and when sub-emitters are spawned. Set it to ``Disabled``
-and no sub-emitters will ever be spawned. Set it to ``Constant`` to make sub-emitters
-spawn continuously at a constant rate. The ``Frequency`` property controls how often
-that happens within the span of one second. Set the mode to ``At End`` to make the sub-emitter
-spawn at the end of the parent particle's lifetime, right before it is destroyed. The
-``Amount At End`` property controls how many sub-emitters will be spawned. Set the
-mode to ``At Collision`` to make sub-emitters spawn when a particle collides with the
-environment. The ``Amount At Collision`` property controls how many sub-emitters will be spawned.
-
-When the ``Keep Velocity`` property is enabled, the newly spawned sub-emitter starts off
-with the parent particle's velocity at the time the sub-emitter is created.
+.. _doc_process_material_properties_turbulence:
 
-See the :ref:`Sub-emitters <doc_3d_particles_subemitters>` section in this manual for a detailed explanation of how
-to add a sub-emitter to a particle system.
+Turbulence
+~~~~~~~~~~
 
-Attractor interaction
-~~~~~~~~~~~~~~~~~~~~~
+Turbulence adds noise to particle movement, creating interesting and lively patterns.
+Check the box next to the ``Enabled`` property to activate it. A number
+of new properties show up that control the movement speed, noise pattern and overall influence
+on the particle system. You can find a detailed explanation of these in the section on
+:ref:`particle turbulence <doc_3d_particles_turbulence>`.
 
-If you want the particle system to interact with :ref:`particle attractors <doc_3d_particles_attractors>`,
-you have to check the ``Enabled`` property. When it is disabled, the particle system
-ignores all particle attractors.
+.. _doc_process_material_properties_subemitter:
 
 Collision
-~~~~~~~~~
+---------
 
 The ``Mode`` property controls how and if emitters collide with particle collision nodes. Set it
 to ``Disabled`` to disable any collision for this particle system. Set it to ``Hide On Contact``
@@ -431,3 +419,27 @@ with random scale or scale that varies over time.
 
 You can learn more about particle collisions in the :ref:`Collisions <doc_3d_particles_collision>`
 section in this manual.
+
+Sub-emitter
+-----------
+
+.. figure:: img/particle_sub_mode.webp
+   :alt: Sub-emitter modes
+   :align: right
+
+   The available sub-emitter modes
+
+The ``Mode`` property controls how and when sub-emitters are spawned. Set it to ``Disabled``
+and no sub-emitters will ever be spawned. Set it to ``Constant`` to make sub-emitters
+spawn continuously at a constant rate. The ``Frequency`` property controls how often
+that happens within the span of one second. Set the mode to ``At End`` to make the sub-emitter
+spawn at the end of the parent particle's lifetime, right before it is destroyed. The
+``Amount At End`` property controls how many sub-emitters will be spawned. Set the
+mode to ``At Collision`` to make sub-emitters spawn when a particle collides with the
+environment. The ``Amount At Collision`` property controls how many sub-emitters will be spawned.
+
+When the ``Keep Velocity`` property is enabled, the newly spawned sub-emitter starts off
+with the parent particle's velocity at the time the sub-emitter is created.
+
+See the :ref:`Sub-emitters <doc_3d_particles_subemitters>` section in this manual for a detailed explanation of how
+to add a sub-emitter to a particle system.
diff --git a/tutorials/3d/particles/properties.rst b/tutorials/3d/particles/properties.rst
@@ -16,6 +16,12 @@ want to activate or deactivate particle systems dynamically.
 The ``Amount`` property controls the maximum number of particles visible at any given time. Increase the
 value to spawn more particles at the cost of performance.
 
+The ``Amount Ratio`` property is the radio of particles compared to the ammount that will be emitted.
+If it's less than ``1.0`` the ammount of particles emitted through the lifetime will be the ``Ammount`` *
+``Amount Ratio``. Changing this value while emitted doesn't affect already created particles and doesn't
+cause the particle system to restart. It's useful for making effects where the number of emitted particels
+varies over time.
+
 You can set another particle node as a ``Sub Emitter``, which will be spawned as a child of each
 particle. See the :ref:`Sub-emitters <doc_3d_particles_subemitters>` section in this manual for a detailed explanation of how
 to add a sub-emitter to a particle system.
@@ -43,6 +49,9 @@ would use:
 Example: Emitting 32 particles with a lifetime of 4 seconds each would mean the system emits
 8 particles per second.
 
+The ``Interp to End`` property causes all the particles in the node to interpolate towards
+the end of their lifetime.
+
 If the checkbox next to the ``One Shot`` property is checked, the particle system will emit ``amount`` particles
 and then disable itself. It "runs" only once. This property is unchecked by default, so the system will
 keep emitting particles until it is disabled or destroyed manually. One-shot particles are a good fit for
