diff --git a/tutorials/2d/img/particles_flipbook_configure_animation_offset.webp b/tutorials/2d/img/particles_flipbook_configure_animation_offset.webp new file mode 100644 index 00000000000..e5d3fd8ec5f Binary files /dev/null and b/tutorials/2d/img/particles_flipbook_configure_animation_offset.webp differ diff --git a/tutorials/2d/img/particles_flipbook_configure_animation_speed.webp b/tutorials/2d/img/particles_flipbook_configure_animation_speed.webp new file mode 100644 index 00000000000..850a3a9b346 Binary files /dev/null and b/tutorials/2d/img/particles_flipbook_configure_animation_speed.webp differ diff --git a/tutorials/2d/img/particles_flipbook_configure_canvasitemmaterial.webp b/tutorials/2d/img/particles_flipbook_configure_canvasitemmaterial.webp new file mode 100644 index 00000000000..31353fa00d6 Binary files /dev/null and b/tutorials/2d/img/particles_flipbook_configure_canvasitemmaterial.webp differ diff --git a/tutorials/2d/img/particles_flipbook_create_canvasitemmaterial.webp b/tutorials/2d/img/particles_flipbook_create_canvasitemmaterial.webp new file mode 100644 index 00000000000..0e362339b61 Binary files /dev/null and b/tutorials/2d/img/particles_flipbook_create_canvasitemmaterial.webp differ diff --git a/tutorials/2d/img/particles_flipbook_example.webp b/tutorials/2d/img/particles_flipbook_example.webp new file mode 100644 index 00000000000..5a7249d4e07 Binary files /dev/null and b/tutorials/2d/img/particles_flipbook_example.webp differ diff --git a/tutorials/2d/img/particles_flipbook_result.webp b/tutorials/2d/img/particles_flipbook_result.webp new file mode 100644 index 00000000000..db71e8da562 Binary files /dev/null and b/tutorials/2d/img/particles_flipbook_result.webp differ diff --git a/tutorials/2d/particle_systems_2d.rst b/tutorials/2d/particle_systems_2d.rst index ddf968437eb..41c1440b758 100644 --- a/tutorials/2d/particle_systems_2d.rst +++ b/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 +`__ or `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 `__ + (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 ` +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 `__, + 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 `. + +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 --------------- diff --git a/tutorials/3d/particles/process_material_properties.rst b/tutorials/3d/particles/process_material_properties.rst index 60a144624d0..1f96b2b490c 100644 --- a/tutorials/3d/particles/process_material_properties.rst +++ b/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_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 diff --git a/tutorials/3d/particles/properties.rst b/tutorials/3d/particles/properties.rst index 51f86fcd9f9..45de78467ef 100644 --- a/tutorials/3d/particles/properties.rst +++ b/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. diff --git a/tutorials/3d/standard_material_3d.rst b/tutorials/3d/standard_material_3d.rst index 58af4da7e68..f550cb34e34 100644 --- a/tutorials/3d/standard_material_3d.rst +++ b/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 `. .. 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 ~~~~~~~~~~~~~~~~~~~~