Merge pull request #10597 from skyace65/Particles2DUpdate

Update 2D particles page for Godot 4.4

tutorials/2d/index.rst

@@ -33,6 +33,7 @@ Rendering
    2d_meshes
    2d_sprite_animation
    particle_systems_2d
+   particle_process_material_2d
    2d_antialiasing
    custom_drawing_in_2d
    2d_parallax

tutorials/2d/particle_process_material_2d.rst

@@ -0,0 +1,280 @@
+.. _doc_particle_process_material_2d:
+
+ParticleProcessMaterial 2D Usage
+================================
+
+Process material properties
+---------------------------
+
+The properties in this material control how particles behave and change over their lifetime.
+A lot of them have ``Min``, ``Max``, and ``Curve`` values that allow you to fine-tune
+their behavior. The relationship between these values is this: When a particle is spawned,
+the property is set with a random value between ``Min`` and ``Max``. If ``Min`` and ``Max`` are
+the same, the value will always be the same for every particle. If the ``Curve`` is also set,
+the value of the property will be multiplied by the value of the curve at the current point
+in a particle's lifetime. Use the curve to change a property over the particle lifetime. Very
+complex behavior can be expressed this way.
+
+.. note::
+  This page covers how to use ParticleProcessMaterial for 2D scenes specifically.
+  For information on how to use it in a 3D scene see :ref:`doc_process_material_properties`.
+
+Lifetime Randomness
+~~~~~~~~~~~~~~~~~~~
+
+The ``Lifetime Randomness`` property controls how much randomness to apply to each particle's
+lifetime. A value of ``0`` means there is no randomness at all and all particles live for
+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
+--------------
+
+Spawn
+-----
+
+Angle
+~~~~~
+
+Determines the initial angle of the particle (in degrees). This parameter
+is mostly useful randomized.
+
+.. image:: img/paranim11.gif
+
+Velocity
+~~~~~~~~
+
+Direction
+^^^^^^^^^
+
+This is the base direction at which particles emit. The default is
+``Vector3(1, 0, 0)`` which makes particles emit to the right. However,
+with the default gravity settings, particles will go straight down.
+
+.. image:: img/direction1.png
+
+For this property to be noticeable, you need an *initial velocity* greater
+than 0. Here, we set the initial velocity to 40. You'll notice that
+particles emit toward the right, then go down because of gravity.
+
+.. image:: img/direction2.png
+
+Spread
+^^^^^^
+
+This parameter is the angle in degrees which will be randomly added in
+either direction to the base ``Direction``. A spread of ``180`` will emit
+in all directions (+/- 180). For spread to do anything the "Initial Velocity"
+parameter must be greater than 0.
+
+.. image:: img/paranim3.gif
+
+Flatness
+^^^^^^^^
+
+This property is only useful for 3D particles.
+
+Initial Velocity
+^^^^^^^^^^^^^^^^
+
+Initial velocity is the speed at which particles will be emitted (in
+pixels/sec). Speed might later be modified by gravity or other
+accelerations (as described further below).
+
+.. image:: img/paranim4.gif
+
+Animated Velocity
+-----------------
+
+Angular Velocity
+~~~~~~~~~~~~~~~~
+
+Angular velocity is the speed at which particles rotate around their center
+(in degrees/sec).
+
+.. image:: img/paranim5.gif
+
+Orbit Velocity
+~~~~~~~~~~~~~~
+
+Orbit velocity is used to make particles turn around their center.
+
+.. image:: img/paranim6.gif
+
+Accelerations
+-------------
+
+Gravity
+~~~~~~~
+
+The gravity applied to every particle.
+
+.. image:: img/paranim7.gif
+
+Linear Acceleration
+~~~~~~~~~~~~~~~~~~~
+
+The linear acceleration applied to each particle.
+
+Radial Acceleration
+~~~~~~~~~~~~~~~~~~~
+
+If this acceleration is positive, particles are accelerated away from
+the center. If negative, they are absorbed towards it.
+
+.. image:: img/paranim8.gif
+
+Tangential Acceleration
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This acceleration will use the tangent vector to the center. Combining
+with radial acceleration can do nice effects.
+
+.. image:: img/paranim9.gif
+
+Damping
+~~~~~~~
+
+Damping applies friction to the particles, forcing them to stop. It is
+especially useful for sparks or explosions, which usually begin with a
+high linear velocity and then stop as they fade.
+
+.. image:: img/paranim10.gif
+
+Display
+-------
+
+Scale
+~~~~~
+
+Determines the initial scale of the particles.
+
+.. image:: img/paranim12.gif
+
+Color Curves
+~~~~~~~~~~~~
+
+Color
+^^^^^
+
+Used to change the color of the particles being emitted.
+
+Hue Variation
+~~~~~~~~~~~~~
+
+The ``Variation`` value sets the initial hue variation applied to each
+particle. The ``Variation Random`` value controls the hue variation
+randomness ratio.
+
+.. _doc_particle_systems_2d_animation:
+
+Animation
+~~~~~~~~~
+
+.. note::
+
+    Particle flipbook animation is only effective if the CanvasItemMaterial used
+    on the GPUParticles2D or CPUParticles2D node has been
+    :ref:`configured accordingly <doc_particle_systems_2d_using_flipbook>`.
+
+To set up the particle flipbook for linear playback, set the **Speed Min** and **Speed Max** values to 1:
+
+.. figure:: img/particles_flipbook_configure_animation_speed.webp
+   :align: center
+   :alt: Setting up particle animation for playback during the particle's lifetime
+
+   Setting up particle animation for playback during the particle's lifetime
+
+By default, looping is disabled. If the particle is done playing before its
+lifetime ends, the particle will keep using the flipbook's last frame (which may
+be fully transparent depending on how the flipbook texture is designed). If
+looping is enabled, the animation will loop back to the first frame and resume
+playing.
+
+Depending on how many images your sprite sheet contains and for how long your
+particle is alive, the animation might not look smooth. The relationship between
+particle lifetime, animation speed, and number of images in the sprite sheet is
+this:
+
+.. note::
+
+   At an animation speed of ``1.0``, the animation will reach the last image
+   in the sequence just as the particle's lifetime ends.
+
+   .. math::
+      Animation\ FPS = \frac{Number\ of\ images}{Lifetime}
+
+If you wish the particle flipbook to be used as a source of random particle
+textures for every particle, keep the speed values at 0 and set **Offset Max**
+to 1 instead:
+
+.. figure:: img/particles_flipbook_configure_animation_offset.webp
+   :align: center
+   :alt: Setting up particle animation for random offset on emission
+
+   Setting up particle animation for random offset on emission
+
+Note that the GPUParticles2D node's **Fixed FPS** also affects animation
+playback. For smooth animation playback, it's recommended to set it to 0 so that
+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).
+
+Emission Shapes
+---------------
+
+ParticleProcessMaterials allow you to set an Emission Mask, which dictates
+the area and direction in which particles are emitted.
+These can be generated from textures in your project.
+
+Ensure that a ParticleProcessMaterial is set, and the GPUParticles2D node is selected.
+A "Particles" menu should appear in the Toolbar:
+
+.. image:: img/emission_shapes1.webp
+
+Open it and select "Load Emission Mask":
+
+.. image:: img/emission_shapes2.webp
+
+Then select which texture you want to use as your mask:
+
+.. image:: img/emission_shapes3.webp
+
+A dialog box with several settings will appear.
+
+Emission Mask
+~~~~~~~~~~~~~
+
+Three types of emission masks can be generated from a texture:
+
+-  Solid Pixels: Particles will spawn from any area of the texture,
+   excluding transparent areas.
+
+.. image:: img/emission_mask_solid.gif
+
+-  Border Pixels: Particles will spawn from the outer edges of the texture.
+
+.. image:: img/emission_mask_border.gif
+
+-  Directed Border Pixels: Similar to Border Pixels, but adds extra
+   information to the mask to give particles the ability to emit away
+   from the borders. Note that an ``Initial Velocity`` will need to
+   be set in order to utilize this.
+
+.. image:: img/emission_mask_directed_border.gif
+
+Emission Colors
+~~~~~~~~~~~~~~~
+
+``Capture from Pixel`` will cause the particles to inherit the color of the mask at their spawn points.
+
+Once you click "OK", the mask will be generated and set to the
+ParticleProcessMaterial, under ``Spawn`` and  then ``Position``
+
+.. image:: img/emission_shapes4.webp
+
+All of the values within this section have been automatically generated by the
+"Load Emission Mask" menu, so they should generally be left alone.
+
+.. note:: An image should not be added to ``Point Texture`` or ``Color Texture`` directly.
+          The "Load Emission Mask" menu should always be used instead.

tutorials/2d/particle_systems_2d.rst

@@ -32,12 +32,20 @@ While GPUParticles2D is configured via a :ref:`class_ParticleProcessMaterial`
 (and optionally with a custom shader), the matching options are provided via
 node properties in CPUParticles2D (with the exception of the trail settings).
 
-You can convert a GPUParticles2D node into a CPUParticles2D node by clicking on
-the node in the inspector, selecting the 2D viewport, and selecting
-**GPUParticles2D > Convert to CPUParticles2D** in the viewport toolbar.
+Going forward there are no plans to add new features to CPUParticles2D, though
+pull requests to add features already in GPUParticles2D will be accepted. For
+that reason we recommend using GPUParticles3D unless you have an explicit reason
+not to.
+
+You can convert a CPUParticles2D node into a GPUParticles2D node by clicking on
+the node in the scene tree, selecting the 2D workspace, and selecting
+**CPUParticles2D > Convert to GPUParticles2D** in the toolbar.
 
 .. image:: img/particles_convert.webp
 
+It is also possible to convert a GPUParticles2D node to a CPUParticles2D node,
+however there may be issues if you use GPU-only features.
+
 The rest of this tutorial is going to use the GPUParticles2D node. First, add a GPUParticles2D
 node to your scene. After creating that node you will notice that only a white dot was created,
 and that there is a warning icon next to your GPUParticles2D node in the scene dock. This
@@ -50,7 +58,7 @@ 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 ParticleProcessMaterial``.
 
-.. image:: img/particles_material.png
+.. image:: img/particles_material.webp
 
 Your GPUParticles2D node should now be emitting
 white points downward.
@@ -67,7 +75,7 @@ spritesheet for particles.
 
 The texture is set via the **Texture** property:
 
-.. image:: img/particles2.png
+.. image:: img/particles2.webp
 
 .. _doc_particle_systems_2d_using_flipbook:
 
@@ -257,240 +265,7 @@ This controls the order in which individual particles are drawn. ``Index``
 means particles are drawn according to their emission order (default).
 ``Lifetime`` means they are drawn in order of remaining lifetime.
 
-ParticleProcessMaterial settings
---------------------------------
-
-Direction
-~~~~~~~~~
-
-This is the base direction at which particles emit. The default is
-``Vector3(1, 0, 0)`` which makes particles emit to the right. However,
-with the default gravity settings, particles will go straight down.
-
-.. image:: img/direction1.png
-
-For this property to be noticeable, you need an *initial velocity* greater
-than 0. Here, we set the initial velocity to 40. You'll notice that
-particles emit toward the right, then go down because of gravity.
-
-.. image:: img/direction2.png
-
-Spread
-~~~~~~
-
-This parameter is the angle in degrees which will be randomly added in
-either direction to the base ``Direction``. A spread of ``180`` will emit
-in all directions (+/- 180). For spread to do anything the "Initial Velocity"
-parameter must be greater than 0.
-
-.. image:: img/paranim3.gif
-
-Flatness
-~~~~~~~~
-
-This property is only useful for 3D particles.
-
-Gravity
-~~~~~~~
-
-The gravity applied to every particle.
-
-.. image:: img/paranim7.gif
-
-Initial Velocity
-~~~~~~~~~~~~~~~~
-
-Initial velocity is the speed at which particles will be emitted (in
-pixels/sec). Speed might later be modified by gravity or other
-accelerations (as described further below).
-
-.. image:: img/paranim4.gif
-
-Angular Velocity
-~~~~~~~~~~~~~~~~
-
-Angular velocity is the initial angular velocity applied to particles.
-
-Spin Velocity
-~~~~~~~~~~~~~
-
-Spin velocity is the speed at which particles turn around their center
-(in degrees/sec).
-
-.. image:: img/paranim5.gif
-
-Orbit Velocity
-~~~~~~~~~~~~~~
-
-Orbit velocity is used to make particles turn around their center.
-
-.. image:: img/paranim6.gif
-
-Linear Acceleration
-~~~~~~~~~~~~~~~~~~~
-
-The linear acceleration applied to each particle.
-
-Radial Acceleration
-~~~~~~~~~~~~~~~~~~~
-
-If this acceleration is positive, particles are accelerated away from
-the center. If negative, they are absorbed towards it.
-
-.. image:: img/paranim8.gif
-
-Tangential Acceleration
-~~~~~~~~~~~~~~~~~~~~~~~
-
-This acceleration will use the tangent vector to the center. Combining
-with radial acceleration can do nice effects.
-
-.. image:: img/paranim9.gif
-
-Damping
-~~~~~~~
-
-Damping applies friction to the particles, forcing them to stop. It is
-especially useful for sparks or explosions, which usually begin with a
-high linear velocity and then stop as they fade.
-
-.. image:: img/paranim10.gif
-
-Angle
-~~~~~
-
-Determines the initial angle of the particle (in degrees). This parameter
-is mostly useful randomized.
-
-.. image:: img/paranim11.gif
-
-Scale
-~~~~~
-
-Determines the initial scale of the particles.
-
-.. image:: img/paranim12.gif
-
-Color
-~~~~~
-
-Used to change the color of the particles being emitted.
-
-Hue Variation
-~~~~~~~~~~~~~
-
-The ``Variation`` value sets the initial hue variation applied to each
-particle. The ``Variation Random`` value controls the hue variation
-randomness ratio.
-
-.. _doc_particle_systems_2d_animation:
-
-Animation
-~~~~~~~~~
-
-.. note::
-
-    Particle flipbook animation is only effective if the CanvasItemMaterial used
-    on the GPUParticles2D or CPUParticles2D node has been
-    :ref:`configured accordingly <doc_particle_systems_2d_using_flipbook>`.
-
-To set up the particle flipbook for linear playback, set the **Speed Min** and **Speed Max** values to 1:
-
-.. figure:: img/particles_flipbook_configure_animation_speed.webp
-   :align: center
-   :alt: Setting up particle animation for playback during the particle's lifetime
-
-   Setting up particle animation for playback during the particle's lifetime
-
-By default, looping is disabled. If the particle is done playing before its
-lifetime ends, the particle will keep using the flipbook's last frame (which may
-be fully transparent depending on how the flipbook texture is designed). If
-looping is enabled, the animation will loop back to the first frame and resume
-playing.
-
-Depending on how many images your sprite sheet contains and for how long your
-particle is alive, the animation might not look smooth. The relationship between
-particle lifetime, animation speed, and number of images in the sprite sheet is
-this:
-
-.. note::
-
-   At an animation speed of ``1.0``, the animation will reach the last image
-   in the sequence just as the particle's lifetime ends.
-
-   .. math::
-      Animation\ FPS = \frac{Number\ of\ images}{Lifetime}
-
-If you wish the particle flipbook to be used as a source of random particle
-textures for every particle, keep the speed values at 0 and set **Offset Max**
-to 1 instead:
-
-.. figure:: img/particles_flipbook_configure_animation_offset.webp
-   :align: center
-   :alt: Setting up particle animation for random offset on emission
-
-   Setting up particle animation for random offset on emission
-
-Note that the GPUParticles2D node's **Fixed FPS** also affects animation
-playback. For smooth animation playback, it's recommended to set it to 0 so that
-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).
-
-Emission Shapes
----------------
-
-ParticleProcessMaterials allow you to set an Emission Mask, which dictates
-the area and direction in which particles are emitted.
-These can be generated from textures in your project.
-
-Ensure that a ParticleProcessMaterial is set, and the GPUParticles2D node is selected.
-A "Particles" menu should appear in the Toolbar:
-
-.. image:: img/emission_shapes1.png
-
-Open it and select "Load Emission Mask":
-
-.. image:: img/emission_shapes2.png
-
-Then select which texture you want to use as your mask:
-
-.. image:: img/emission_shapes3.png
-
-A dialog box with several settings will appear.
-
-Emission Mask
-~~~~~~~~~~~~~
-
-Three types of emission masks can be generated from a texture:
-
--  Solid Pixels: Particles will spawn from any area of the texture,
-   excluding transparent areas.
-
-.. image:: img/emission_mask_solid.gif
-
--  Border Pixels: Particles will spawn from the outer edges of the texture.
-
-.. image:: img/emission_mask_border.gif
-
--  Directed Border Pixels: Similar to Border Pixels, but adds extra
-   information to the mask to give particles the ability to emit away
-   from the borders. Note that an ``Initial Velocity`` will need to
-   be set in order to utilize this.
-
-.. image:: img/emission_mask_directed_border.gif
-
-Emission Colors
-~~~~~~~~~~~~~~~
-
-``Capture from Pixel`` will cause the particles to inherit the color of the mask at their spawn points.
-
-Once you click "OK", the mask will be generated and set to the ParticleProcessMaterial, under the ``Emission Shape`` section:
-
-.. image:: img/emission_shapes4.png
-
-All of the values within this section have been automatically generated by the
-"Load Emission Mask" menu, so they should generally be left alone.
+Particle Process Material Settings
+----------------------------------
 
-.. note:: An image should not be added to ``Point Texture`` or ``Color Texture`` directly.
-          The "Load Emission Mask" menu should always be used instead.
+For information on the settings in the ParticleProcessMaterial see :ref:`this page<doc_particle_process_material_2d>`.

tutorials/3d/particles/process_material_properties.rst

@@ -18,6 +18,10 @@ the value of the property will be multiplied by the value of the curve at the cu
 in a particle's lifetime. Use the curve to change a property over the particle lifetime. Very
 complex behavior can be expressed this way.
 
+.. note::
+  This page covers how to use ParticleProcessMaterial for 3D scenes specifically.
+  For information on how to use it in a 2D Scene see :ref:`doc_particle_process_material_2d`.
+
 Time
 ~~~~