Document particle flipbook animation in 2D, improve existing 3D flipbook docs

tutorials/2d/particle_systems_2d.rst

@@ -60,12 +60,74 @@ white points downward.
 Texture
 ~~~~~~~
 
-A particle system uses a single texture (in the future this might be
-extended to animated textures via spritesheet). The texture is set via
-the relevant texture property:
+A particle system can use a single texture or an animation *flipbook*. A
+flipbook is a texture that contains several frames of animation that can be
+played back, or chosen at random during emission. This is equivalent to a
+spritesheet for particles.
+
+The texture is set via the **Texture** property:
 
 .. image:: img/particles2.png
 
+.. _doc_particle_systems_2d_using_flipbook:
+
+Using an animation flipbook
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Particle flipbooks are suited to reproduce complex effects such as smoke, fire,
+explosions. They can also be used to introduce random texture variation, by
+making every particle use a different texture. You can find existing particle
+flipbook images online, or pre-render them using external tools such as `Blender
+<https://www.blender.org/>`__ or `EmberGen <https://jangafx.com/software/embergen/>`__.
+
+.. figure:: img/particles_flipbook_result.webp
+   :align: center
+   :alt: Example of a particle system that uses a flipbook texture
+
+   Example of a particle system that uses a flipbook texture
+
+Using an animation flipbook requires additional configuration compared to a
+single texture. For demonstration purposes, we'll use this texture with 5
+columns and 7 rows (right-click and choose **Save as…**):
+
+.. figure:: img/particles_flipbook_example.webp
+   :align: center
+   :width: 240
+   :alt: Particle flipbook texture example
+
+   Credit: `JoesAlotofthings <https://opengameart.org/content/alot-of-particles-indispersal-special-effect-alotofparticles30>`__
+   (CC BY 4.0)
+
+To use an animation flipbook, you must create a new CanvasItemMaterial in the
+Material section of the GPUParticles2D (or CPUParticles2D) node:
+
+.. figure:: img/particles_flipbook_create_canvasitemmaterial.webp
+   :align: center
+   :alt: Creating a CanvasItemMaterial at the bottom of the particles node inspector
+
+   Creating a CanvasItemMaterial at the bottom of the particles node inspector
+
+In this CanvasItemMaterial, enable **Particle Animation** and set **H Frames** and **V Frames**
+to the number of columns and rows present in your flipbook texture:
+
+.. figure:: img/particles_flipbook_configure_canvasitemmaterial.webp
+   :align: center
+   :alt: Configuring the CanvasItemMaterial for the example flipbook texture
+
+   Configuring the CanvasItemMaterial for the example flipbook texture
+
+Once this is done, the :ref:`Animation section <doc_particle_systems_2d_animation>`
+in ParticleProcessMaterial (for GPUParticles2D) or in the CPUParticles2D inspector
+will be effective.
+
+.. tip::
+
+    If your flipbook texture has a black background instead of a transparent
+    background, you will also need to set the blend mode to **Add** instead of
+    **Mix** for correct display. Alternatively, you can modify the texture to
+    have a transparent background in an image editor. In `GIMP <https://gimp.org>`__,
+    this can be done using the **Color > Color to Alpha** menu.
+
 Time parameters
 ---------------
 
@@ -299,13 +361,66 @@ Color
 
 Used to change the color of the particles being emitted.
 
-Hue variation
+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 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
 ---------------
 

tutorials/3d/particles/process_material_properties.rst

@@ -304,6 +304,8 @@ of new properties show up that control the movement speed, noise pattern and ove
 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
 ~~~~~~~~~
 
@@ -313,7 +315,7 @@ The ``Min``, ``Max``, and ``Curve`` values work `as described above <#process-ma
 
 An animated sprite sheet is a texture that contains several smaller images aligned on a grid.
 The images are shown one after the other so fast that they combine to play a short
-animation, like a flip book. You can use them for animated particles like smoke or fire.
+animation, like a flipbook. You can use them for animated particles like smoke or fire.
 These are the steps to create an animated particle system:
 
 .. figure:: img/particle_sprite.webp
@@ -349,11 +351,11 @@ this:
 
 .. note::
 
-   At an animation speed of ``1.0`` the animation will reach the last image
+   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{Lifetime}{Number\ Of\ Images}
+      Animation\ FPS = \frac{Number\ of\ images}{Lifetime}
 
 If your sprite sheet contains
 64 (8x8) images and the particle's lifetime is set to ``1 second``, the animation
@@ -368,6 +370,12 @@ to reach an acceptable framerate.
 
    The same particle system at different lifetimes: 1 second (left), 2 seconds (middle), 8 seconds (right)
 
+Note that the GPUParticles3D 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).
+
 .. _doc_process_material_properties_subemitter:
 
 Sub-emitter

tutorials/3d/particles/properties.rst

@@ -33,12 +33,12 @@ is measured in seconds. A lot of particle properties can be set to change over t
 lifetime and blend smoothly from one value to another.
 
 ``Lifetime`` and ``Amount`` are related. They determine the particle system's emission rate.
-Whenever you want to know how many particles are spawned per second, this is the formular you
+Whenever you want to know how many particles are spawned per second, this is the formula you
 would use:
 
 .. math::
 
-   particlesPerSecond = \frac{Amount}{Lifetime}
+   Particles per second = \frac{Amount}{Lifetime}
 
 Example: Emitting 32 particles with a lifetime of 4 seconds each would mean the system emits
 8 particles per second.

tutorials/3d/standard_material_3d.rst

@@ -517,15 +517,15 @@ Enables billboard mode for drawing materials. This controls how the object
 faces the camera:
 
 * **Disabled:** Billboard mode is disabled.
-* **Enabled:** Billboard mode is enabled, the object's -Z axis will always
-  face the camera.
-* **Y-Billboard:** The object's X axis will always be aligned with the camera.
-* **Particles:** Most suited for particle systems, because it allows
-  specifying animation options.
+* **Enabled:** Billboard mode is enabled. The object's -Z axis will always
+  face the camera's viewing plane.
+* **Y-Billboard:** The object's X axis will always be aligned with the camera's viewing plane.
+* **Particle Billboard:** Most suited for particle systems, because it allows
+  specifying :ref:`flipbook animation <doc_process_material_properties_animation>`.
 
 .. image:: img/spatial_material9.png
 
-The above options are only enabled for Particle Billboard.
+The **Particles Anim** section is only visible when the billboard mode is **Particle Billboard**.
 
 Billboard Keep Scale
 ~~~~~~~~~~~~~~~~~~~~