diff --git a/tutorials/2d/img/emission_shapes1.png b/tutorials/2d/img/emission_shapes1.png deleted file mode 100644 index e93b8fcda..000000000 Binary files a/tutorials/2d/img/emission_shapes1.png and /dev/null differ diff --git a/tutorials/2d/img/emission_shapes1.webp b/tutorials/2d/img/emission_shapes1.webp new file mode 100644 index 000000000..0eade5d58 Binary files /dev/null and b/tutorials/2d/img/emission_shapes1.webp differ diff --git a/tutorials/2d/img/emission_shapes2.png b/tutorials/2d/img/emission_shapes2.png deleted file mode 100644 index e6b147b0e..000000000 Binary files a/tutorials/2d/img/emission_shapes2.png and /dev/null differ diff --git a/tutorials/2d/img/emission_shapes2.webp b/tutorials/2d/img/emission_shapes2.webp new file mode 100644 index 000000000..d01adf6f9 Binary files /dev/null and b/tutorials/2d/img/emission_shapes2.webp differ diff --git a/tutorials/2d/img/emission_shapes3.png b/tutorials/2d/img/emission_shapes3.png deleted file mode 100644 index f5f8e77d8..000000000 Binary files a/tutorials/2d/img/emission_shapes3.png and /dev/null differ diff --git a/tutorials/2d/img/emission_shapes3.webp b/tutorials/2d/img/emission_shapes3.webp new file mode 100644 index 000000000..407b38006 Binary files /dev/null and b/tutorials/2d/img/emission_shapes3.webp differ diff --git a/tutorials/2d/img/emission_shapes4.png b/tutorials/2d/img/emission_shapes4.png deleted file mode 100644 index ca657331a..000000000 Binary files a/tutorials/2d/img/emission_shapes4.png and /dev/null differ diff --git a/tutorials/2d/img/emission_shapes4.webp b/tutorials/2d/img/emission_shapes4.webp new file mode 100644 index 000000000..c66670f01 Binary files /dev/null and b/tutorials/2d/img/emission_shapes4.webp differ diff --git a/tutorials/2d/img/particles2.png b/tutorials/2d/img/particles2.png deleted file mode 100644 index 84a6b0ef9..000000000 Binary files a/tutorials/2d/img/particles2.png and /dev/null differ diff --git a/tutorials/2d/img/particles2.webp b/tutorials/2d/img/particles2.webp new file mode 100644 index 000000000..8d4e45d84 Binary files /dev/null and b/tutorials/2d/img/particles2.webp differ diff --git a/tutorials/2d/img/particles_convert.webp b/tutorials/2d/img/particles_convert.webp index bc1385bef..82fcb4da2 100644 Binary files a/tutorials/2d/img/particles_convert.webp and b/tutorials/2d/img/particles_convert.webp differ diff --git a/tutorials/2d/img/particles_flipbook_create_canvasitemmaterial.webp b/tutorials/2d/img/particles_flipbook_create_canvasitemmaterial.webp index 0e362339b..4a9030967 100644 Binary files a/tutorials/2d/img/particles_flipbook_create_canvasitemmaterial.webp and b/tutorials/2d/img/particles_flipbook_create_canvasitemmaterial.webp differ diff --git a/tutorials/2d/img/particles_material.png b/tutorials/2d/img/particles_material.png deleted file mode 100644 index 860e10d30..000000000 Binary files a/tutorials/2d/img/particles_material.png and /dev/null differ diff --git a/tutorials/2d/img/particles_material.webp b/tutorials/2d/img/particles_material.webp new file mode 100644 index 000000000..fc99f6d8e Binary files /dev/null and b/tutorials/2d/img/particles_material.webp differ diff --git a/tutorials/2d/index.rst b/tutorials/2d/index.rst index 2bc60e0de..9203c19e5 100644 --- a/tutorials/2d/index.rst +++ b/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 diff --git a/tutorials/2d/particle_process_material_2d.rst b/tutorials/2d/particle_process_material_2d.rst new file mode 100644 index 000000000..08a9d46e1 --- /dev/null +++ b/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 ` 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 `. + +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. diff --git a/tutorials/2d/particle_systems_2d.rst b/tutorials/2d/particle_systems_2d.rst index 4e9e152a4..5e67109c4 100644 --- a/tutorials/2d/particle_systems_2d.rst +++ b/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 --------------------------------- +Particle Process Material 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 `. - -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. - -.. 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`. diff --git a/tutorials/3d/particles/process_material_properties.rst b/tutorials/3d/particles/process_material_properties.rst index 5b6220011..4ee3604f2 100644 --- a/tutorials/3d/particles/process_material_properties.rst +++ b/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 ~~~~