Add 3D particles documentation (#5535)

Co-authored-by: Hugo Locurcio <[email protected]>

tutorials/3d/index.rst

@@ -22,6 +22,7 @@ Rendering
    lights_and_shadows
    using_decals
    physical_light_and_camera_units
+   particles/index
    high_dynamic_range
    global_illumination/index
    environment_and_post_processing

tutorials/3d/particles/attractors.rst

@@ -0,0 +1,171 @@
+.. _doc_3d_particles_attractors:
+
+3D Particle attractors
+----------------------
+
+.. figure:: img/particle_attractor.webp
+   :alt: Particle attractors
+
+Particle attractors are nodes that apply a force to all particles within their reach. They pull
+particles closer or push them away based on the direction of that force. There are three types
+of attractors: :ref:`class_GPUParticlesAttractorBox3D`, :ref:`class_GPUParticlesAttractorSphere3D`,
+and :ref:`class_GPUParticlesAttractorVectorField3D`. You can instantiate them at runtime and
+change their properties from gameplay code; you can even animate and combine them for complex
+attraction effects.
+
+.. note::
+
+   Particle attractors are not yet implemented for 2D particle systems.
+
+The first thing you have to do if you want to use attractors is enable the ``Attractor Interaction``
+property on the ParticleProcessMaterial. Do this for every particle system that needs to react to attractors.
+Like most properties in Godot, you can also change this at runtime.
+
+Common properties
+~~~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_attractor_common.webp
+   :alt: Common particle attractor properties
+   :align: right
+
+   Common attractor properties
+
+There are some properties that you can find on all attractors. They're located in the
+``GPUParticlesAttractor3D`` section in the inspector.
+
+``Strength`` controls how strong the attractor force is. A positive value pulls particles
+closer to the attractor's center, while a negative value pushes them away.
+
+``Attenuation`` controls the strength falloff within the attractor's influence region. Every
+particle attractor has a boundary. Its strength is weakest at the border of this boundary
+and strongest at its center. Particles outside of the boundary are not affected by the attractor
+at all. The attenuation curve controls how the strength weakens over that distance. A straight
+line means that the strength is proportional to the distance: if a particle is halfway
+between the boundary and the center, the attractor strength will be half of what it is
+at the center. Different curve shapes change how fast particles accelerate towards the
+attractor.
+
+.. figure:: img/particle_attractor_curve.webp
+   :alt: Different attractor attenuation curves
+
+   Strength increase variations: constantly over the distance to the attractor (left), fast
+   at the boundary border and slowly at the center (middle), slowly at the boundary and
+   fast at the center (right).
+
+The ``Directionality`` property changes the direction towards which particles are pulled.
+At a value of ``0.0``, there is no directionality, which means that particles are pulled towards
+the attractor's center. At ``1.0``, the attractor is fully directional, which means particles
+will be pulled along the attractor's local ``-Z``-axis. You can change the global direction
+by rotating the attractor. If ``Strength`` is negative, particles are instead pulled along
+the ``+Z``-axis.
+
+.. figure:: img/particle_attractor_direction.webp
+   :alt: Different attractor directionality values
+
+   No directionality (left) vs. full directionality (right). Notice how the particles move along
+   the attractor's local Z-axis.
+
+The ``Cull Mask`` property controls which particle systems are affected by an attractor based
+on each system's :ref:`visibility layers <class_VisualInstance3D>`. A particle system is only
+affected by an attractor if at least one of the system's visibility layers is enabled in the
+attractor's cull mask.
+
+.. warning::
+
+   There is a `known issue <https://github.com/godotengine/godot/issues/61014>`_ with
+   GPU particle attractors that prevent the cull mask from working properly in Godot 4.0. We will
+   update the documentation as soon as it is fixed.
+
+Box attractors
+~~~~~~~~~~~~~~
+
+.. figure:: img/particle_attractor_box_entry.webp
+   :alt: Particle attractor box
+   :align: right
+
+   Box attractor in the node list
+
+Box attractors have a box-shaped influence region. You control their size with the ``Extents``
+property. Box extents always measure half of the sides of its bounds, so a value of
+``(X=1.0,Y=1.0,Z=1.0)`` creates a box with an influence region that is 2 meters wide on each side.
+
+To create a box attractor, add a new child node to your scene and select ``GPUParticlesAttractorBox3D``
+from the list of available nodes. You can animate the box position or attach it to a
+moving node for more dynamic effects.
+
+.. figure:: img/particle_attractor_box.webp
+   :alt: Box attractor parts particle field
+
+   A box attractor with a negative strength value parts a particle field as it moves through it.
+
+Sphere attractors
+~~~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_attractor_sphere_entry.webp
+   :alt: Particle attractor sphere
+   :align: right
+
+   Sphere attractor in the node list
+
+Sphere attractors have a spherical influence region. You control their size with the ``Radius``
+property. While box attractors don't have to be perfect cubes, sphere attractors will always be
+spheres: You can't set width independently from height. If you want to use a sphere attractor for
+elongated shapes, you have to change its ``Scale`` in the attractor's ``Node3D`` section.
+
+To create a sphere attractor, add a new child node to your scene and select ``GPUParticlesAttractorSphere3D``
+from the list of available nodes. You can animate the sphere position or attach it to a
+moving node for more dynamic effects.
+
+.. figure:: img/particle_attractor_sphere.webp
+   :alt: Sphere attractor parts particle field
+
+   A sphere attractor with a negative strength value parts a particle field as it moves through it.
+
+Vector field attractors
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_attractor_vector_entry.webp
+   :alt: Particle attractor vector field
+   :align: right
+
+   Vector field attractor in the node list
+
+A vector field is a 3D area that contains vectors positioned on a grid. The grid density controls
+how many vectors there are and how far they're spread apart. Each vector in a vector field points
+in a specific direction. This can be completely random or aligned in a way that forms distinct
+patterns and paths.
+
+When particles interact with a vector field, their movement direction changes to match the nearest vector
+in the field. As a particle moves closer to the next vector in the field, it changes
+direction to match that vector's direction. The particle's speed depends on the vector's length.
+
+Like box attractors, vector field attractors have a box-shaped influence region. You control their size with the ``Extents``
+property, where a value of ``(X=1.0,Y=1.0,Z=1.0)`` creates a box with an influence region that is
+2 meters wide on each side. The ``Texture`` property takes a :ref:`3D texture <class_Texture3D>`
+where every pixel represents a vector with the pixel's color interpreted as the vector's direction and size.
+
+.. note::
+
+   When a texture is used as a vector field, there are two types of conversion you need to be aware of:
+
+   1. The texture coordinates map to the attractor bounds. The image below shows which part of the texture
+      corresponds to which part of the vector field volume. For example, the bottom half of the texture
+      affects the top half of the vector field attractor because ``+Y`` points down in the texture UV space,
+      but up in Godot's world space.
+   2. The pixel color values map to direction vectors in space. The image below provides an overview. Since
+      particles can move in two directions along each axis, the lower half of the color range represents
+      negative direction values while the upper half represents positive direction values. So a yellow pixel
+      ``(R=1,G=1,B=0)`` maps to the vector ``(X=1,Y=1,Z=-1)`` while a neutral gray ``(R=0.5,G=0.5,B=0.5)``
+      results in no movement at all.
+
+   .. figure:: img/particle_attractor_vector_mapping.webp
+      :alt: Mapping from texture to vector field
+
+To create a vector field attractor, add a new child node to your scene and select ``GPUParticlesAttractorVectorField3D``
+from the list of available nodes. You can animate the attractor's position or attach it to a
+moving node for more dynamic effects.
+
+.. figure:: img/particle_attractor_vector.webp
+   :alt: Vector field attractor in a field of particles
+
+   Two particle systems are affected by the same vector field attractor. :download:`Click here to download the 3D texture <img/particle_vector_field_16x16x16.bmp>`.

tutorials/3d/particles/collision.rst

@@ -0,0 +1,177 @@
+.. _doc_3d_particles_collision:
+
+3D Particle collisions
+----------------------
+
+.. figure:: img/particle_collision.webp
+   :alt: Particle collisions
+
+Since GPU particles are processed entirely on the GPU, they don't have access to the game's physical
+world. If you need particles to collide with the environment, you have to set up particle collision nodes.
+There are four of them: :ref:`class_GPUParticlesCollisionBox3D`, :ref:`class_GPUParticlesCollisionSphere3D`,
+:ref:`class_GPUParticlesCollisionSDF3D`, and :ref:`class_GPUParticlesCollisionHeightField3D`.
+
+.. note::
+
+   GPU Particle collision is not yet implemented for 2D particle systems.
+
+Common properties
+~~~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_collision_common.webp
+   :alt: Common particle collision properties
+   :align: right
+
+   Common collision properties
+
+There are some properties that you can find on all collision nodes. They're located in the
+``GPUParticlesCollision3D`` section in the inspector.
+
+The ``Cull Mask`` property controls which particle systems are affected by a collision node based
+on each system's :ref:`visibility layers <class_VisualInstance3D>`. A particle system collides with a
+collision node only if at least one of the system's visibility layers is enabled in the
+collider's cull mask.
+
+.. warning::
+
+   There is a `known issue <https://github.com/godotengine/godot/issues/61014>`_ with
+   GPU particle collision that prevent the cull mask from working properly in Godot 4.0. We will
+   update the documentation as soon as it is fixed.
+
+Box collision
+~~~~~~~~~~~~~
+
+.. figure:: img/particle_collision_box_entry.webp
+   :alt: Particle collision box
+   :align: right
+
+   Box collision in the node list
+
+Box collision nodes are shaped like a solid, rectangular box. You control their size with the ``Extents``
+property. Box extents always measure half of the sides of its bounds, so a value of ``(X=1.0,Y=1.0,Z=1.0)``
+creates a box that is 2 meters wide on each side. Box collision nodes are useful for simulating floor
+and wall geometry that particles should collide against.
+
+To create a box collision node, add a new child node to your scene and select ``GPUParticlesCollisionBox3D``
+from the list of available nodes. You can animate the box position or attach it to a
+moving node for more dynamic effects.
+
+.. figure:: img/particle_collision_box.webp
+   :alt: Box collision with particle systems
+
+   Two particle systems collide with a box collision node
+
+Sphere collision
+~~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_collision_sphere_entry.webp
+   :alt: Particle collision sphere
+   :align: right
+
+   Sphere collision in the node list
+
+Sphere collision nodes are shaped like a solid sphere. The ``Radius`` property controls the size of the sphere.
+While box collision nodes don't have to be perfect cubes, sphere collision nodes will always be
+spheres. If you want to set width independently from height, you have to change the ``Scale``
+property in the ``Node3D`` section.
+
+To create a sphere collision node, add a new child node to your scene and select ``GPUParticlesCollisionSphere3D``
+from the list of available nodes. You can animate the sphere's position or attach it to a
+moving node for more dynamic effects.
+
+.. figure:: img/particle_collision_sphere.webp
+   :alt: Sphere collision with particle systems
+
+   Two particle systems collide with a sphere collision node
+
+Height field collision
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_collision_height.webp
+   :alt: Particle collision height field
+   :align: right
+
+   Height field collision in the node list
+
+Height field particle collision is very useful for large outdoor areas that need to collide with particles.
+At runtime, the node creates a height field from all the meshes within its bounds that match its cull mask.
+Particles collide against the mesh that this height field represents. Since the height field generation is
+done dynamically, it can follow the player camera around and react to changes in the level. Different
+settings for the height field density offer a wide range of performance adjustments.
+
+To create a height field collision node, add a new child node to your scene and select ``GPUParticlesCollisionHeightField3D``
+from the list of available nodes.
+
+A height field collision node is shaped like a box. The ``Extents`` property controls its size. Extents
+always measure half of the sides of its bounds, so a value of ``(X=1.0,Y=1.0,Z=1.0)`` creates a box that
+is 2 meters wide on each side. Anything outside of the node's extents is ignored for height field creation.
+
+The ``Resolution`` property controls how detailed the height field is. A lower resolution performs faster
+at the cost of accuracy. If the height field resolution is too low, it may look like particles penetrate level geometry
+or get stuck in the air during collision events. They might also ignore some smaller meshes completely.
+
+.. figure:: img/particle_heightfield_res.webp
+   :alt: Height field resolutions
+
+   At low resolutions, height field collision misses some finer details (left)
+
+The ``Update Mode`` property controls when the height field is recreated from the meshes within its
+bounds. Set it to ``When Moved`` to make it refresh only when it moves. This performs well and is
+suited for static scenes that don't change very often. If you need particles to collide with dynamic objects
+that change position frequently, you can select ``Always`` to refresh every frame. This comes with a
+cost to performance and should only be used when necessary.
+
+.. note::
+
+   It's important to remember that when ``Update Mode`` is set to ``When Moved``, it is the *height field node*
+   whose movement triggers an update. The height field is not updated when one of the meshes inside it moves.
+
+The ``Follow Camera Enabled`` property makes the height field follow the current camera when enabled. It will
+update whenever the camera moves. This property can be used to make sure that there is always particle collision
+around the player while not wasting performance on regions that are out of sight or too far away.
+
+SDF collision
+~~~~~~~~~~~~~
+
+.. figure:: img/particle_collision_sdf_entry.webp
+   :alt: Particle collision SDF
+   :align: right
+
+   SDF collision in the node list
+
+SDF collision nodes create a `signed distance field <https://www.reddit.com/r/explainlikeimfive/comments/k2zbos/eli5_what_are_distance_fields_in_graphics>`_
+that particles can collide with. SDF collision is similar to height field collision in that it turns multiple
+meshes within its bounds into a single collision volume for particles. A major difference is that signed distance
+fields can represent holes, tunnels and overhangs, which is impossible to do with height fields alone. The
+performance overhead is larger compared to height fields, so they're best suited for small-to-medium-sized environments.
+
+To create an SDF collision node, add a new child node to your scene and select ``GPUParticlesCollisionSDF3D``
+from the list of available nodes. SDF collision nodes have to be baked in order to have any effect on particles
+in the level. To do that, click the ``Bake SDF`` button in the viewport toolbar
+while the SDF collision node is selected and choose a directory to store the baked data. Since SDF collision needs
+to be baked in the editor, it's static and cannot change at runtime.
+
+.. figure:: img/particle_collision_sdf.webp
+   :alt: SDF particle collision
+
+   SDF particle collision allows for very detailed 3-dimensional collision shapes
+
+An SDF collision node is shaped like a box. The ``Extents`` property controls its size. Extents
+always measure half of the sides of its bounds, so a value of ``(X=1.0,Y=1.0,Z=1.0)`` creates a box that
+is 2 meters wide on each side. Anything outside of the node's extents is ignored for collision.
+
+The ``Resolution`` property controls how detailed the distance field is. A lower resolution performs faster
+at the cost of accuracy. If the resolution is too low, it may look like particles penetrate level geometry
+or get stuck in the air during collision events. They might also ignore some smaller meshes completely.
+
+.. figure:: img/particle_collision_sdf_res.webp
+   :alt: Resolution comparison
+
+   The same area covered by a signed distance field at different resolutions: 16 (left) and 256 (right)
+
+The ``Thickness`` property gives the distance field, which is usually hollow on the inside, a thickness to
+prevent particles from penetrating at high speeds. If you find that some particles don't collide with the
+level geometry and instead shoot right through it, try setting this property to a higher value.
+
+The ``Bake Mask`` property controls which meshes will be considered when the SDF is baked. Only meshes that
+render on the active layers in the bake mask contribute to particle collision.

tutorials/3d/particles/complex_shapes.rst

@@ -0,0 +1,93 @@
+.. _doc_3d_particles_complex_shapes:
+
+Complex emission shapes
+-----------------------
+
+.. figure:: img/particle_complex_emission.webp
+   :alt: Complex emission shapes
+
+When it is not enough to emit particles from one of the simple shapes available
+in the :ref:`process material <doc_process_material_properties_shapes>`, Godot provides
+a way to emit particles from arbitrary, complex shapes. The shapes are generated from
+meshes in the scene and stored as textures in the particle process material. This is a
+very versatile workflow that has allowed users to use particle systems for things that
+go beyond traditional use cases, like foliage, leaves on a tree, or complex
+holographic effects.
+
+.. note::
+
+    When you create emission points from meshes, you can only select a single node as
+    emission source. If you want particles to emit from multiple shapes, you either
+    have to create several particle systems or combine the meshes into one in an
+    external DCC software.
+
+.. figure:: img/particle_create_emission_points.webp
+   :alt: Creating emission points
+   :align: right
+
+   Create particle emission points...
+
+.. figure:: img/particle_select_emission_mesh.webp
+   :alt: Select mesh for emission
+   :align: right
+
+   \...from a mesh instance as the source
+
+.. figure:: img/particle_emission_density.webp
+   :alt: Set emission density
+   :align: right
+
+   More points = higher particle density
+
+To make use of this feature, start by creating a particle system in the current scene.
+Add a mesh instance that serves as the source of the particle emission points. With the
+particle system selected, navigate to the viewport menu and select the *GPUParticles3D*
+entry. From there, select ``Create Emission Points From Node``.
+
+A dialog window will pop up and ask you to select a node as the emission source.
+Choose one of the mesh instances in the scene and confirm your selection. The next
+dialog window deals with the amount of points and how to generate them.
+
+``Emission Points`` controls the total number of points that you are about to generate.
+Particles will spawn from these points, so what to enter here depends on the
+size of the source mesh (how much area you have to cover) and the desired density of
+the particles.
+
+``Emission Source`` offers 3 different options for how the points are generated.
+Select ``Surface Points`` if all you want to do is distribute the emission points across the
+surface of the mesh. Select ``Surface Points + Normal (Directed)`` if you also want to
+generate information about the surface normals and make particles move in the direction
+that the normals point at. The last option, ``Volume``, creates emission points everywhere
+inside the mesh, not just across its surface.
+
+The emission points are stored in the particle system's local coordinate system, so
+you can move the particle node around and the emission points will follow. This might be
+useful when you want to use the same particle system in several different places. On the
+other hand, you might have to regenerate the emission points when you move either
+the particle system or the source mesh.
+
+Emission shape textures
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_emission_textures.webp
+   :alt: Emission textures
+   :align: right
+
+   The available emission shape textures
+
+All the data for complex particle emission shapes is stored in a set of textures. How
+many, depends on the type of emission shape you use. If you set the ``Shape`` property
+in the ``Emission Shape`` group on the particle process material to ``Points``, you
+have access to 2 texture properties, the ``Point Texture`` and the ``Color Texture``.
+Set it to ``Directed Points`` and there is a third property called ``Normal Texture``.
+
+``Point Texture`` contains all possible emission points that were generated in the
+previous step. A point is randomly selected for every particle when it spawns.
+``Normal Texture``, if it exists, provides a direction vector at that same location.
+If the ``Color Texture`` property is also set, it provides color for the particle,
+sampled at the same location as the other two textures and modulating any other color
+that was set up on the process material.
+
+There is also the ``Point Count`` property that you can use to change the number of
+emission points at any time after creating the emission shape. This includes dynamically
+at runtime while the playing the game.

tutorials/3d/particles/creating_a_3d_particle_system.rst

@@ -0,0 +1,85 @@
+.. _doc_creating_3d_particle_system:
+
+Creating a 3D particle system
+-----------------------------
+
+.. figure:: img/particle_node_new.webp
+   :align: right
+
+   Required particle node properties
+
+To get started with particles, the first thing we need to do is add a ``GPUParticles3D``
+node to the scene. Before we can actually see any particles, we have to set up two parameters on the node:
+the ``Process Material`` and at least one ``Draw Pass``.
+
+The process material
+~~~~~~~~~~~~~~~~~~~~
+
+To add a process material to your particles node, go to ``Process Material`` in the inspector panel.
+Click on the box next to ``Process Material`` and from the dropdown menu select ``New ParticleProcessMaterial``.
+
+.. figure:: img/particle_new_process_material.webp
+   :align: right
+
+   Creating a process material
+
+:ref:`class_ParticleProcessMaterial` is a special kind of material. We don't use it to draw any objects.
+We use it to update particle data and behavior on the GPU instead of the CPU, which comes with a massive performance
+boost. A click on the newly added material displays a long list of properties that you can set to
+control each particle's behavior.
+
+Draw passes
+~~~~~~~~~~~
+
+.. figure:: img/particle_first_draw_pass.webp
+   :align: right
+
+   At least one draw pass is required
+
+In order to render any particles, at least one draw pass needs to be defined. To do that, go to
+``Draw Passes`` in the inspector panel. Click on the box next to ``Pass 1`` and select ``New QuadMesh``
+from the dropdown menu. After that, click on the mesh and set its ``Size`` to 0.1 for both ``x``
+and ``y``. Reducing the mesh's size makes it a little easier to tell the individual particle
+meshes apart at this stage.
+
+You can use up to 4 draw passes per particle system. Each pass can render a different
+mesh with its own unique material. All draw passes use the data that is computed by the process material,
+which is an efficient method for composing complex effects: Compute particle
+behavior once and feed it to multiple render passes.
+
+.. figure:: img/particle_two_draw_passes.webp
+
+   Using multiple draw passes: yellow rectangles (pass1) and blue spheres (pass 2)
+
+If you followed the steps above, your particle system should now be emitting particles in a waterfall-like fashion,
+making them move downwards and disappear after a few seconds. This is the foundation for all
+particle effects. Take a look at the documentation for :ref:`particle <doc_3d_particles_properties>` and
+:ref:`particle material <doc_process_material_properties>` properties to
+learn how to make particle effects more interesting.
+
+.. figure:: img/particle_basic_system.webp
+
+Particle conversion
+~~~~~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_convert_cpu.webp
+   :align: right
+
+   Turning GPU into CPU particles
+
+You can convert GPU particles to CPU particles at any time using the entry in the viewport
+menu. When you do so, keep in mind that not every feature of GPU particles is available for
+CPU particles, so the resulting particle system will look and behave differently from the
+original.
+
+Some of the most notable features that are lost during the conversion include:
+
+- multiple draw passes
+- turbulence
+- sub-emitters
+- trails
+- attractors
+- collision
+
+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.

tutorials/3d/particles/index.rst

@@ -0,0 +1,98 @@
+.. _doc_3d_particles:
+
+Particle systems (3D)
+=====================
+
+This section of the tutorial covers (3D) GPU-accelerated particle systems. Most of the things
+discussed here apply to CPU particles as well.
+
+Introduction
+------------
+
+You can use particle systems to simulate complex physical effects like fire, sparks,
+smoke, magical effects, and many more. They are very well suited for creating dynamic and organic
+behavior and adding "life" to your scenes.
+
+The idea is that a particle is emitted at a fixed interval and with a fixed lifetime. During
+its lifetime, every particle will have the same base behavior. What makes each particle different
+from the others and creates the organic look is the randomness that you can add to most of its
+parameters and behaviors.
+
+Every particle system you create in Godot consists of two main parts: particles and emitters.
+
+Particles
+~~~~~~~~~
+
+A partice is the visible part of a particle system. It's what you see on the screen when a particle
+system is active: The tiny specks of dust, the flames of a fire, the glowing orbs of a magical
+effect. You can have anywhere between a couple hundred and tens of thousands of particles in a
+single system. You can randomize a particle's size, its speed and movement direction, and change its
+color over the course of its lifetime. When you think of a fire, you can think of all the little
+embers flying away from it as individual particles.
+
+Emitters
+~~~~~~~~
+
+An emitter is what's creating the particles. Emitters are usually not visible, but they can have
+a shape. That shape controls where and how particles are spawned, for example whether they should fill
+a room like dust or shoot away from a single point like a fountain. Going back to the fire example,
+an emitter would be the heat at the center of the fire that creates the embers and the flames.
+
+Node overview
+~~~~~~~~~~~~~
+
+.. figure:: img/particle_nodes.webp
+   :alt: A list of nodes related to 3D particles
+   :align: right
+
+   All 3D particle nodes available in Godot
+
+There are two types of 3D particle systems in Godot: :ref:`class_GPUParticles3D`, which are processed on the GPU,
+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.
+
+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
+also make them interact with the environment by using attractor and collision nodes.
+
+There are three particle attractor nodes: :ref:`class_GPUParticlesAttractorBox3D`, :ref:`class_GPUParticlesAttractorSphere3D`,
+and :ref:`class_GPUParticlesAttractorVectorField3D`. An attractor node applies a force to all particles
+in its reach and pulls them closer or pushes them away based on the direction of that force.
+
+There are several particle collision nodes. :ref:`class_GPUParticlesCollisionBox3D` and
+:ref:`class_GPUParticlesCollisionSphere3D` are the simple ones. You can use them to create basic
+shapes like boxes, a floor, or a wall that particles collide with. The other two nodes provide
+more complex collision behavior. The :ref:`class_GPUParticlesCollisionSDF3D` is useful when you want
+indoor scenes to collide with particles without having to create all the individual box and sphere
+colliders by hand. If you want particles to collide with large outdoor scenes, you would use the
+:ref:`class_GPUParticlesCollisionHeightField3D` node. It creates a heightmap of your world and the
+objects in it and uses that for large-scale particle collisions.
+
+
+Basic usage
+-----------
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-particles-basic
+
+   creating_a_3d_particle_system
+   properties
+   process_material_properties
+
+Advanced topics
+---------------
+
+.. toctree::
+   :maxdepth: 1
+   :name: toc-particles-advanced
+
+   subemitters
+   trails
+   turbulence
+   attractors
+   collision
+   complex_shapes

tutorials/3d/particles/process_material_properties.rst

@@ -0,0 +1,425 @@
+.. _doc_process_material_properties:
+
+Process material properties
+---------------------------
+
+.. figure:: img/particle_minmaxcurve.webp
+   :alt: ParticleProcessMaterial properties
+   :align: right
+
+   Min, max, and curve 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.
+
+Time
+~~~~
+
+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``].
+
+.. _doc_process_material_properties_shapes:
+
+Emission shape
+~~~~~~~~~~~~~~
+
+Particles can emit from a single point in space or in a way that they fill out a shape.
+The ``Shape`` property controls that shape. ``Point`` is the default value. All
+particles emit from a single point in the center of the particle system. When set to ``Sphere``
+or ``Box``, particles emit in a way that they fill out a sphere or a box shape evenly.
+You have full control over the size of these shapes. ``Sphere Surface`` works like ``Sphere``,
+but instead of filling it out, all particles spawn on the sphere's surface.
+
+.. figure:: img/particle_shapes_simple.webp
+   :alt: Simple particle emission shapes
+
+   Particles emitting from a point (left), in a sphere (middle), and in a box (right)
+
+.. figure:: img/particle_ring.webp
+   :alt: Ring-shaped particle system
+   :align: right
+
+   A ring-shaped particle system
+
+The ``Ring`` emission shape makes particles emit in the shape of a ring. You can control the ring's
+direction by changing the ``Ring Axis`` property. ``Ring Height`` controls the thickness
+of the ring along its axis. ``Ring Radius`` and ``Ring Inner Radius`` control how wide
+the ring is and how large the hole in the middle should be. The image shows a particle
+system with a radius of ``2`` and an inner radius of ``1.5``, the axis points along the
+global Z-axis.
+
+In addition to these relatively simple shapes, you can select the ``Points`` or
+``Directed Points`` option to create highly complex emission shapes. See the
+: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
+
+   Left\: (X=0,Y=-9.8,Z=0), middle\: (X=0,Y=9.8,Z=0), right\: (X=4,Y=2,Z=0).
+
+Direction
+~~~~~~~~~
+
+.. note::
+
+   The ``Direction`` property alone is not enough to see any particle movement. Whatever
+   values you set here only take effect once velocity or acceleration properties are set, too.
+
+The ``Direction`` property is a vector that controls each particle's direction of movement
+at the moment it is spawned. A value of ``(X=1,Y=0,Z=0)`` would make all particles move
+sideways along the X-axis. For something like a fountain where particles shoot out up in the
+air, a value of ``(X=0,Y=1,Z=0)`` would be a good starting point.
+
+.. figure:: img/particle_direction.webp
+   :alt: Different values for particle direction
+
+   Different direction values: Y-axis only (left), equal values for X and Y (middle), X and Y with gravity enabled (right)
+
+After setting a direction, you will notice that all particles move in the same direction in
+a straight line. The ``Spread`` property adds some variation and randomness to each particle's
+direction. The higher the value, the stronger the deviation from the original path. A value
+of ``0`` means there is no spread at all while a value of ``180`` makes particles shoot out in
+every direction. You could use this for something like pieces of debris during an explosion effect.
+
+.. figure:: img/particle_spread.webp
+   :alt: Different values for particle spread
+
+   No spread (left), 45 degree angle (middle), full 180 degrees (right)
+
+The ``Flatness`` property limits the spread along the Y-axis. A value of ``0`` means there
+is no limit and a value of ``1`` will eliminate all particle movement along the Y-axis. The
+particles will spread out completely "flat".
+
+You won't see any actual movement until you also set some values for the velocity and
+acceleration properties below, so let's take a look at those next.
+
+Initial velocity
+~~~~~~~~~~~~~~~~
+
+While the ``Direction`` property controls a particle's movement direction, the ``Initial Velocity``
+controls how fast it goes. It's separated into ``Velocity Min`` and ``Velocity Max``, both
+set to ``0`` by default, which is why you don't see any movement initially. As soon as you set
+values for either of these properties `as described above <#process-material-properties>`__, the
+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.
+
+Linear acceleration
+~~~~~~~~~~~~~~~~~~~
+
+A particle's velocity is a constant value: once it's set, it doesn't change and the particle will
+always move at the same speed. You can use the ``Linear Accel`` property to
+change the speed of movement over a particle's lifetime `as described above <#process-material-properties>`__.
+Positive values will speed up the particle and make it move faster. Negative values will slow it
+down until it stops and starts moving in the other direction.
+
+.. figure:: img/particle_accel_linear.webp
+   :alt: Different values for particle linear acceleration
+
+   Negative (top) and positive (bottom) linear acceleration
+
+It's important to keep in mind that when we change acceleration, we're not changing the velocity
+directly, we're changing the *change* in velocity. A value of ``0`` on the acceleration curve
+does not stop the particle's movement, it stops the change in the particle's movement. Whatever
+its velocity was at that moment, it will keep moving at that velocity until the acceleration is
+changed again.
+
+Radial acceleration
+~~~~~~~~~~~~~~~~~~~
+
+The ``Radial Accel`` property adds a gravity-like force to all particles, with the origin
+of that force at the particle system's current location. Negative values make particles move
+towards the center, like the force of gravity from a planet on objects in its orbit. Positive
+values make particles move away from the center.
+
+.. figure:: img/particle_accel_radial.webp
+   :alt: Different values for particle radial acceleration
+
+   Negative (left) and positive (right) radial acceleration
+
+Tangential acceleration
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_tangent.webp
+   :alt: Tangents on a circle
+   :align: right
+
+   Tangents on a circle
+
+This property adds particle acceleration in the direction of the tangent to a circle on the particle
+system's XZ-plane with the origin at the system's center and a radius the distance between each
+particle's current location and the system's center projected onto that plane.
+
+Let's unpack that.
+
+A tangent to a circle is a straight line that "touches" the circle in a right angle to the circle's
+radius at the touch point. A circle on the particle system's XZ-plane is the circle that you see
+when you look straight down at the particle system from above.
+
+.. figure:: img/particle_accel_tangent.webp
+   :alt: Tangential acceleration from above
+   :align: right
+
+   Tangential acceleration from above
+
+``Tangential Accel`` is always limited to that plane and never move particles along the system's Y-axis.
+A particle's location is enough to define such a circle where the distance to the system's center is
+the radius if we ignore the vector's Y component.
+
+The ``Tangential Accel`` property will make particles orbit the particle system's center, but the
+radius will increase constantly. Viewed from above, particles will move away from the center
+in a spiral. Negative values reverse the direction.
+
+Damping
+~~~~~~~
+
+The ``Damping`` property gradually stops all movement. Each frame, a particle's movement
+is slowed down a little unless the total acceleration is greater than the damping effect. If
+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>`.
+
+.. note::
+
+   The `Damping <#damping>`__ property has no effect on the angular velocity.
+
+Scale
+~~~~~
+
+``Scale`` controls a particle's size `as described above <#process-material-properties>`__. You can set
+different values for ``Scale Min`` and ``Scale Max`` to randomize each particle's size. Negative values
+are not allowed, so you won't be able to flip particles with this property. If you emit particles as
+billboards, the ``Keep Size`` property on the :ref:`Standard Material <doc_standard_material_3d>`
+in your draw passes has to be enabled for any scaling to have an effect.
+
+Color
+~~~~~
+
+The ``Color`` property controls a particle's initial color. It will have an effect only after the
+``Use As Albedo`` property in the ``Vertex Color`` group of the :ref:`Standard Material <doc_standard_material_3d>`
+is enabled. This property is multiplied with color coming from the particle material's
+own ``Color`` or ``Texture`` property.
+
+.. figure:: img/particle_ramp.webp
+   :alt: Particle color ramp
+   :align: right
+
+   Setting up a color ramp
+
+There are two ``Ramp`` properties in the ``Color`` group. These allow you to define a range of colors
+that are used to set the particle's color. The ``Color Ramp`` property changes a particle's color
+over the course of its lifetime. It moves through the entire range of colors you defined.
+The ``Color Initial Ramp`` property selects the particle's initial color from a random
+position on the color ramp.
+
+To set up a color ramp, click on the box next to the property name and from the dropdown menu
+select ``New GradientTexture1D``. Click on the box again to open the texture's details.
+Find the ``Gradient`` property, click on the box next to it and select ``New Gradient``.
+Click on that box again and you will see a color range. Click anywhere on that range
+to insert a new marker. You can move the marker with the mouse and delete it by clicking
+the right mouse button. When a marker is selected, you can use the color picker next to
+the range to change its color.
+
+Hue variation
+~~~~~~~~~~~~~
+
+Like the ``Color`` property, ``Hue Variation`` controls a particle's color, but in a
+different way. It does so not by setting color values directly, but by
+*shifting the color's hue*.
+
+Hue describes a color's pigment: red, orange, yellow, green and so on. It does not
+tell you anything about how bright or how saturated the color is. The ``Hue Variation``
+property controls the range of available hues `as described above <#process-material-properties>`__.
+
+It works on top of the particle's current color. The values you set for
+``Variation Min`` and ``Variation Max`` control how far the hue is allowed to shift
+in either direction. A higher value leads to more color variation while a low value
+limits the available colors to the closest neighbors of the original color.
+
+.. figure:: img/particle_hue.webp
+   :alt: Different values for hue variation
+
+   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>`.
+
+Animation
+~~~~~~~~~
+
+The ``Animation`` property group controls the behavior of sprite
+sheet animations in the particle's :ref:`Standard Material <doc_standard_material_3d>`.
+The ``Min``, ``Max``, and ``Curve`` values work `as described above <#process-material-properties>`__.
+
+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.
+These are the steps to create an animated particle system:
+
+.. figure:: img/particle_sprite.webp
+   :alt: A sprite sheet
+   :align: right
+
+   An 8x8 animated smoke sprite sheet
+
+#. Import a sprite sheet texture into the engine. If you don't have one at hand, you can download the :download:`high-res version of the example image <img/particle_sprite_smoke.webp>`.
+#. Set up a particle system with at least one draw pass and assign a ``Standard Material`` to the mesh in that draw pass.
+#. Assign the sprite sheet to the ``Texture`` property in the ``Albedo`` group
+#. Set the material's ``Billboard`` property to ``Particle Billboard``. Doing so makes the ``Particles Anim`` group available in the material.
+#. Set ``H Frames`` to the number of columns and ``V Frames`` to the number of rows in the sprite sheet.
+#. Check ``Loop`` if you want the animation to keep repeating.
+
+That's it for the Standard Material. You won't see any animation right away. This is
+where the ``Animation`` properties come in. The ``Speed`` properties control how fast
+the sprite sheet animates. Set ``Speed Min`` and ``Speed Max`` to ``1`` and you should see the
+animation playing. The ``Offset`` properties control where the animation starts on a
+newly spawned particle. By default, it will always be the first image in the sequence.
+You can add some variety by changing ``Offset Min`` and ``Offset Max`` to randomize
+the starting position.
+
+.. figure:: img/particle_animate.webp
+   :alt: Animated particles
+
+   Three different particle systems using the same smoke sprite sheet
+
+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{Lifetime}{Number\ Of\ Images}
+
+If your sprite sheet contains
+64 (8x8) images and the particle's lifetime is set to ``1 second``, the animation
+will be very smooth at **64 FPS** (1 second / 64 images). if the lifetime is set to ``2 seconds``, it
+will still be fairly smooth at **32 FPS**. But if the particle is alive for
+``8 seconds``, the animation will be visibly choppy at **8 FPS**. In order to make the
+animation smooth again, you need to increase the animation speed to something like ``3``
+to reach an acceptable framerate.
+
+.. figure:: img/particle_animate_lifetime.webp
+   :alt: Animated particles lifetimes
+
+   The same particle system at different lifetimes: 1 second (left), 2 seconds (middle), 8 seconds (right)
+
+.. _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.
+
+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.
+
+Attractor interaction
+~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+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``
+if you want particles to disappear as soon as they collide. Set it to ``Constant`` to make
+particles collide and bounce around. You will see two new properties appear in the inspector.
+They control how particles behave during collision events.
+
+A high ``Friction`` value will reduce sliding along surfaces. This is especially
+helpful if particles collide with sloped surfaces and you want them to stay in
+place instead of sliding all the way to the bottom, like snow falling on a mountain.
+A high ``Bounce`` value will make particles bounce off surfaces they collide with,
+like rubber balls on a solid floor.
+
+If the ``Use Scale`` property is enabled, the :ref:`collision base size <doc_3d_particles_properties_collision>`
+is multiplied by the particle's `current scale <#scale>`__. You can use this to
+make sure that the rendered size and the collision size match for particles
+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.

tutorials/3d/particles/properties.rst

@@ -0,0 +1,181 @@
+.. _doc_3d_particles_properties:
+
+3D Particle system properties
+-----------------------------
+
+Emitter properties
+~~~~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_props_emitter.webp
+   :align: right
+
+The checkbox next to the ``Emitting`` property activates and deactivates the particle system. Particles will
+only be processed and rendered if the box is checked. You can set this property at runtime if you
+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.
+
+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.
+
+.. _doc_3d_particles_properties_time:
+
+Time properties
+~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_props_time.webp
+   :align: right
+
+The ``Lifetime`` property controls how long each particle exists before it disappears again. It
+is measured in seconds. A lot of particle properties can be set to change over the particle's
+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
+would use:
+
+.. math::
+
+   particlesPerSecond = \frac{Amount}{Lifetime}
+
+Example: Emitting 32 particles with a lifetime of 4 seconds each would mean the system emits
+8 particles per second.
+
+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
+effects that react to a single event, like item pickups or splinters that burst away when a bullet hits a wall.
+
+The ``Preprocess`` property is a way to fast-forward to a point in the middle of the
+particle system's lifetime and start rendering from there. It is measured in seconds. A value of
+``1`` means that when the particle system starts, it will look as if it has been
+running for one second already.
+
+This can be useful if you want the particle system to look like it has been active for a while even
+though it was just loaded into the scene. Consider the example below. Both particle systems simulate
+dust flying around in the area. With a preprocess value of ``0``, there wouldn't be any dust for the
+first couple of seconds because the system has not yet emitted enough particles for the effect to
+become noticeable. This can be seen in the video on the left. Compare that to the video on the
+right where the particle system is preprocessed for ``4`` seconds. The dust is fully visible from
+the very beginning because we skipped the first four seconds of "setup" time.
+
+.. figure:: img/particle_preprocess.webp
+
+   No preprocess (left) vs. 4 seconds of preprocess (right)
+
+You can slow down or speed up the particle system with the ``Speed Scale`` property. This applies
+to processing the data as well as rendering the particles. Set it to ``0`` to pause the particle
+system completely or set it to something like ``2`` to make it move twice as fast.
+
+.. figure:: img/particle_speed_scale.webp
+
+   Different speed scale values: 0.1 (left), 0.5 (middle), 1.0 (right)
+
+The ``Explosiveness`` property controls whether particles are emitted sequentially or simultaneously.
+A value of ``0`` means that particles emit one after the other.
+A value of ``1`` means that all ``amount`` particles emit at the same time, giving
+the effect a more "explosive" appearance.
+
+The ``Randomness`` property adds some randomness to the particle emission timing. When set to ``0``,
+there is no randomness at all and the interval between the emission of one particle and
+the next is always the same: the particles are emitted at *regular* intervals. A ``Randomness``
+value of ``1`` makes the interval completely random. You can use this property to break
+up some of the uniformity in your effects. When ``Explosiveness`` is set to ``1``, this
+property has no effect.
+
+.. figure:: img/particle_interpolate.webp
+   :alt: Particles running at low FPS
+   :align: right
+
+   Interpolation on (left) vs. off (right)
+
+The ``Fixed FPS`` property limits how often the particle system is processed. This includes
+property updates as well as collision and attractors. This can improve performance a lot,
+especially in scenes that make heavy use of particle collision. Note that this does not
+change the speed at which particles move or rotate. You would use the ``Speed Scale``
+property for that.
+
+When you set ``Fixed FPS`` to very low values, you will notice that
+the particle animation starts to look choppy. This can sometimes be desired if it fits
+the art direction, but most of the time, you'll want particle systems to animate smoothly.
+That's what the ``Interpolate`` property does. It blends particle properties between
+updates so that even a particle system running at ``10`` FPS appears as smooth as
+running at ``60``.
+
+.. _doc_3d_particles_properties_collision:
+
+Collision properties
+~~~~~~~~~~~~~~~~~~~~
+
+The ``Base Size`` property defines each particle's default collision size, which is used
+to check whether a particle is currently colliding with the environment. You would usually want this
+to be about the same size as the particle. It can make sense to increase this value
+for particles that are very small and move very fast to prevent them from clipping
+through the collision geometry.
+
+.. _doc_3d_particles_properties_draw:
+
+Drawing properties
+~~~~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_drawing.webp
+   :alt: Particle drawing properties
+   :align: right
+
+The ``Visibility AABB`` property defines a box around the particle system's origin.
+As long as any part of this box is in the camera's field of view, the particle system
+is visible. As soon as it leaves the camera's field of view, the particle system stops
+being rendered at all. You can use this property to boost performance by keeping the
+box as small as possible.
+
+One thing to keep in mind when you set a size for the ``Visibility AABB`` is that particles
+that are outside of its bounds disappear instantly when it leaves the camera's field of view.
+This, while not technically a bug, can have a negative effect on the visual experience.
+
+When the ``Local Coords`` property is checked, all particle calculations use the local
+coordinate system to determine things like up and down, gravity, and movement direction.
+Up and down, for example, would follow the particle system's or its parent node's rotation.
+When the property is unchecked, the global world space is used for these calculations:
+Down will always be -Y in world space, regardless of the particle system's rotation.
+
+.. figure:: img/particle_coords.webp
+
+   Local space coordinates (left) vs. world space coordinates (right)
+
+The ``Draw Order`` property controls the order in which individual particles are drawn. ``Index`` means
+that they are drawn in the order of emission: particles that are spawned later are drawn
+on top of earlier ones. ``Lifetime`` means that they are drawn in the order of their
+remaining lifetime. ``Reverse Lifetime`` reverses the ``Lifetime`` draw order. ``View Depth``
+means particles are drawn according to their distance from the camera: The ones closer
+to the camera on top of those farther away.
+
+The ``Transform Align`` property controls the particle's default rotation. ``Disabled``
+means they don't align in any
+particular way. Instead, their rotation is determined by the values set in the process
+material. ``Z-Billboard`` means that the particles will always face the camera. This is
+similar to the ``Billboard`` property in the :ref:`Standard Material <doc_standard_material_3d>`.
+``Y to Velocity`` means that each particle's Y-axis aligns with its movement
+direction. This can be useful for things like bullets or arrows, where you want particles
+to always point "forward". ``Z-Billboard + Y to Velocity`` combines the previous two modes.
+Each particle's Z-axis will point towards the camera while its Y-axis will align with
+their velocity.
+
+Trail properties
+~~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_trail.webp
+   :alt: Particle trails
+   :align: right
+
+   Particle trail properties
+
+The ``Enabled`` property controls whether particles are rendered as trails. The box needs
+to be checked if you want to make use of particle trails.
+
+The ``Length Secs`` property controls for how long a trail should be emitted. The longer
+this duration is, the longer the trail will be.
+
+See the :ref:`Particle trails <doc_3d_particles_trails>` section in this manual for a detailed
+explanation of how particle trails work and how to set them up.

tutorials/3d/particles/subemitters.rst

@@ -0,0 +1,76 @@
+.. _doc_3d_particles_subemitters:
+
+Particle sub-emitters
+---------------------
+
+.. figure:: img/particle_sub_chain.webp
+   :alt: Chained sub-emitters
+
+Sometimes a visual effect cannot be created with a single particle system alone.
+Sometimes a particle system needs to be spawned as a response to something that happens in
+another particle system. Fireworks are a good example of that. They usually consist of
+several stages of explosions that happen in sequence. Sub-emitters are a good way to achieve
+this kind of effect.
+
+.. figure:: img/particle_sub_assign.webp
+   :alt: Assign sub-emitter
+   :align: right
+
+   Click to assign a sub-emitter...
+
+.. figure:: img/particle_sub_list.webp
+   :alt: List particle systems
+   :align: right
+
+   \...and select one from the scene
+
+A sub-emitter is a particle system that spawns as a child of another particle system.
+You can add sub-emitters to sub-emitters, chaining particle effects as deep as you like.
+
+To create a sub-emitter, you need at least two particle systems in the same scene. One of them will be the
+parent and one will be set as the child. Find the ``Sub Emitter`` property on the parent
+and click the box next to it to assign the sub-emitter. You will see a list of available particle
+systems in the scene. Select one and click the confirmation button.
+
+Particle systems from instanced scenes can be set as sub-emitters too, as long as the
+``Editable Children`` property is enabled on the instanced scene. This also works the other
+way around: You can assign a sub-emitter to a particle system in an instanced scene,
+even one coming from a different instanced scene.
+
+.. note::
+
+   When you set a particle system as the sub-emitter of another, the system stops
+   emitting, even if the ``Emitting`` property was checked. Don't worry, it didn't break. This happens
+   to every particle system as soon as it becomes a sub-emitter. You also won't be able to
+   re-enable the property as long as the particle system is used as a sub-emitter.
+
+.. warning::
+
+   Even though the parent particle system can be selected from the list of available particle
+   systems, a particle system which is its own sub-emitter does not work in Godot. It will
+   simply not spawn. The same is true for any other kind of recursive or self-referential
+   sub-emitter setup.
+
+Emitter mode
+~~~~~~~~~~~~
+
+When you assign a sub-emitter, you don't see it spawn right away. Emitting is disabled
+by default and needs to be enabled first. Set the ``Mode`` property in the ``Sub Emitter`` group
+of the :ref:`ParticleProcessMaterial <doc_process_material_properties_subemitter>` to something other than ``Disabled``.
+
+The emitter mode also determines how many sub-emitter particles are spawned. ``Constant``
+spawns a single particle at a frequency set by the ``Frequency`` property. For ``At End``
+and ``At Collision`` you can set the amount directly with the ``Amount At End`` and the
+``Amount At Collision`` properties.
+
+Limitations
+~~~~~~~~~~~
+
+One thing to keep in mind is that the total number of active particles from the sub-emitter
+is always capped by the ``Amount`` property on the sub-emitter particle system. If you find
+that there are not enough particles spawned from the sub-emitter, you might have to increase
+the amount in the particle system.
+
+Some emitter properties are ignored when a particle system is spawned as a sub-emitter.
+The ``Explosiveness`` property, for example, has no effect. Depending on the emitter mode,
+the particles are either spawned sequentially at fixed intervals or explosively all at once.

tutorials/3d/particles/trails.rst

@@ -0,0 +1,141 @@
+.. _doc_3d_particles_trails:
+
+3D Particle trails
+------------------
+
+.. figure:: img/particle_trails.webp
+   :alt: Particle trails
+
+.. figure:: img/particle_trail_params.webp
+   :alt: Particle trail params
+   :align: right
+
+   Setting up particle trails
+
+Godot provides several types of trails you can add to a particle system. Before you can
+work with trails, you need to set up a couple of parameters first. Create a new particle
+system and assign a process material :ref:`as described before <doc_creating_3d_particle_system>`.
+In the ``Trails`` group of the particle system, check the box next to ``Enabled`` and
+increase the emission duration by setting ``Length Secs`` to something like ``0.8``. On
+the process material, set ``Direction`` to ``(X=0,Y=1.0,Z=0)`` and ``Initial Velocity`` to
+``10.0`` for both ``Min`` and ``Max``.
+
+The only thing that's still missing is a mesh for the draw pass. The type of mesh that you
+set here controls what kind of particle trail you will end up with.
+
+Ribbon trails
+~~~~~~~~~~~~~
+
+.. figure:: img/particle_ribbon_mesh.webp
+   :alt: Particle ribbon
+   :align: right
+
+   Important ribbon mesh parameters
+
+The simplest type of particle trail is the ribbon trail. Navigate to the ``Draw Passes``
+section and select ``New RibbonTrailMesh`` from the options for ``Pass 1``. A
+:ref:`RibbonTrailMesh <class_RibbonTrailMesh>` is a simple quad that is divided into
+sections and then stretched and repeated along those sections.
+
+Assign a new :ref:`Standard Material <doc_standard_material_3d>` to the ``Material``
+property and enable ``Use Particle Trails`` in the ``Transform`` property group. The
+particles should now be emitting in trails.
+
+You have two options for the ribbon mesh ``Shape`` parameter. ``Cross`` creates two
+perpendicular quads, making the particle trail a little more three-dimensional. This
+really only makes sense if you don't draw the trails in ``Particle Billboard`` mode
+and helps when looking at the particles from different angles. The ``Flat`` option
+limits the mesh to a single quad and works best with billboard particles.
+
+The ``Size`` parameter controls the trail's width. Use it to make trails wider or
+more narrow.
+
+``Sections``, ``Section Length`` and ``Section Segments`` all work together to
+control how smooth the particle trail looks. When a particle trail does not travel
+in a straight line, the more sections it has the smoother it looks as it bends and swirls.
+``Section Length`` controls the length of each section. Multiply this value by
+the number of sections to know the trail's total length.
+
+.. figure:: img/particle_ribbon_sections.webp
+   :alt: Particle ribbon sections
+
+   3 sections, 1m section length (left) vs. 12 sections, 0.25m section length (right). Notice how the total length of the trails stays the same.
+
+The ``Section Segments`` parameter further subdivides each section into segments.
+It has no effect on the smoothness of the trail's sections, though. Instead, it controls
+the smoothness of the particle trail's overall shape. The ``Curve`` property defines
+this shape. Click the box next to ``Curve`` and assign or create a new curve. The
+trail will be shaped just like the curve with the curve's value at ``0.0`` at the
+trail's head and the curve's value at ``1.0`` at the trail's tail.
+
+.. figure:: img/particle_ribbon_curve.webp
+   :alt: Particle ribbon curves
+
+   Particle trails shaped by different curves. The trails move from left to right.
+
+Depending on the complexity of the curve, the particle trail's shape will not look
+very smooth when the number of sections is low. This is where the ``Section Segments`` property
+comes in. Increasing the amount of section segments adds more vertices to the trail's
+sides so that it can follow the curve more closely.
+
+.. figure:: img/particle_ribbon_segments.webp
+   :alt: Particle ribbon segments
+
+   Particle trail shape smoothness: 1 segment per section (top), 12 segments per section (bottom)
+
+Tube trails
+~~~~~~~~~~~
+
+Tube trails share a lot of their properties with ribbon trails. The big difference between them
+is that tube trails emit cylindrical meshes instead of quads.
+
+.. figure:: img/particle_tube.webp
+   :alt: Particle tube trails
+
+   Tube trails emit cylindrical particles
+
+To create a tube trail, navigate to the ``Draw Passes`` section and select ``New TubeTrailMesh``
+from the options for ``Pass 1``. A :ref:`TubeTrailMesh <class_TubeTrailMesh>` is a cylinder
+that is divided into sections and then stretched and repeated along those sections. Assign a
+new :ref:`Standard Material <doc_standard_material_3d>` to the ``Material`` property and enable
+``Use Particle Trails`` in the ``Transform`` property group. The particles should now be emitting
+in long, cylindrical trails.
+
+.. figure:: img/particle_tube_mesh.webp
+   :alt: Particle tube
+   :align: right
+
+   Important tube mesh parameters
+
+The ``Radius`` and ``Radial Steps`` properties are to tube trails what ``Size`` is to ribbon trails.
+``Radius`` defines the radius of the tube and increases or decreases its overall size. ``Radial Steps``
+controls the number of sides around the tube's circumference. A higher value increases the resolution
+of the tube's cap.
+
+``Sections`` and ``Section Length`` work the same for tube trails and ribbon trails. They control how
+smooth the tube trail looks when it is bending and twisting instead of moving in a straight line.
+Increasing the number of sections will make it look smoother. Change the ``Section Length`` property
+to change the length of each section and with it the total length of the trail. ``Section Rings``
+is the tube equivalent of the ``Section Segments`` property for ribbons. It subdivides the sections
+and adds more geometry to the tube to better fit the custom shape defined in the ``Curve`` property.
+
+You can shape tube trails with curves, just as you can with ribbon trails. Click the box next to the
+``Curve`` property and assign or create a new curve. The trail will be shaped like the curve with
+the curve's value at ``0.0`` at the trail's head and the curve's value at ``1.0`` at the trail's tail.
+
+.. figure:: img/particle_tube_curve.webp
+   :alt: Particle tubes
+
+   Particle tube trails with a custom curve shape: 4 radial steps, 3 sections, 1 section ring (left),
+   12 radial steps, 9 sections, 3 section rings (right)
+
+An important property you might want to set is ``Transform Align`` in the particle
+system's ``Drawing`` group. If you leave it as is, the tubes will not preserve volume; they
+flatten out as they move because their Y-axis keeps pointing up even as they change direction.
+This can cause a lot of rendering artifacts. Set the property to ``Y to Velocity`` instead
+and each particle trail keeps its Y-axis aligned along the direction of its movement.
+
+.. figure:: img/particle_tube_align.webp
+   :alt: Particle tubes aligned
+
+   Particle tube trails without alignment (left) and with Y-axis aligned to velocity (right)

tutorials/3d/particles/turbulence.rst

@@ -0,0 +1,116 @@
+.. _doc_3d_particles_turbulence:
+
+Particle turbulence
+-------------------
+
+.. figure:: img/particle_turbulence.webp
+   :alt: Particle turbulence
+
+Turbulence uses a noise texture to add variation and interesting patterns to particle movement.
+It can be combined with :ref:`particle attractors <doc_3d_particles_attractors>` and
+:ref:`collision <doc_3d_particles_collision>` nodes to create even more complex looking behavior.
+
+.. figure:: img/particle_turbulence_properties.webp
+   :alt: Turbulence properties
+   :align: right
+
+   Particle turbulence properties
+
+There are two things you have to do before turbulence has any effect on a particle system. First you must
+add movement to the particle system. Turbulence modifies a particle's movement
+direction and speed, but it doesn't create any. It is enough to give the particle system some
+gravity, but you can just as well create a number of attractors if you want the particles
+to follow a more complex movement path. Second, you need to :ref:`enable turbulence in the particle process material <doc_process_material_properties_turbulence>`.
+Once enabled, you have access to all the turbulence properties.
+
+.. warning::
+
+	Turbulence makes use of 3D noise, which has a high performance cost on the GPU.
+	Only enable turbulence on a few particle systems on screen at most.
+	Using turbulence is not recommended when targeting mobile/web platforms.
+
+Noise properties
+~~~~~~~~~~~~~~~~
+
+The basis for particle turbulence is a noise pattern. There are several
+properties that allow you to manipulate different attributes of this pattern.
+
+The ``Noise Strength`` property controls the pattern's contrast, which affects the overall turbulence
+sharpness. A lower value creates a softer pattern where individual movement paths are
+not as sharply separated from another. Set this to a higher number to make the pattern more
+distinct.
+
+.. figure:: img/particle_turbulence_strength.webp
+   :alt: Turbulence noise strength
+
+   At a value of 1 (left), the noise strength produces softer turbulence patterns than at 20 (right)
+
+The ``Noise Scale`` property controls the pattern's frequency. It basically changes the noise texture's UV scale
+where a smaller value produces finer detail, but repeating patterns become noticeable faster. A larger value
+results in a weaker turbulence pattern overall, but the particle system can cover a larger area before repetition
+starts to become an issue.
+
+.. figure:: img/particle_turbulence_scale.webp
+   :alt: Turbulence noise scale
+
+   Turbulence noise scale produces finer details at a value of 1.5 (left) than at 6 (right)
+
+The ``Noise Speed`` property takes a vector and controls the noise panning speed and direction.
+This allows you to move the noise pattern over time, which adds another layer of movement
+variation to the particle system.
+
+.. warning::
+
+   Don't mix up particle movement speed and noise panning speed! They are two different things.
+   Particle movement is determined by a number of properties, including the turbulence noise.
+   The ``Noise Speed`` property moves the pattern itself, which in turn changes where the
+   noise affects the particles.
+
+At a value of ``(X=0,Y=0,Z=0)``, the noise pattern doesn't move at all. The influence on particle
+movement stays the same at any given point. Set the speed to ``(X=1,Y=0,Z=0)`` instead, and the
+noise pattern moves along the X-axis.
+
+.. figure:: img/particle_turbulence_speed.webp
+   :alt: Turbulence noise speed
+
+   Different noise speed values. Left\: (X=0,Y=0,Z=0), middle\: (X=0.5,Y=0.5,Z=0.5), right\: (X=0,Y=-2,Z=0).
+
+The ``Noise Speed Random`` property adds some randomness to the noise panning speed. This helps
+with breaking up visible patterns, especially at higher panning speeds when repetition becomes
+noticeable faster.
+
+Influence properties
+~~~~~~~~~~~~~~~~~~~~
+
+The influence properties determine how much each particle is affected by turbulence. Use
+``Influence Min`` to set a minimum value and ``Influence Max`` to set a maximum value. When a
+particle spawns, the influence is randomly chosen from within this range. You can
+also set up a curve with the ``Influence Over Life`` property that modifies that value
+over each particle's lifetime. These three properties together control the strength of
+the turbulence's effect on the particle system :ref:`as described before <doc_process_material_properties>`.
+
+Since these properties affect the overall influence of the turbulence over a particle system,
+both movement direction and speed change as you set different values. A stronger influence causes
+a particle to move faster and all particles to follow along narrower paths as a result of that.
+
+.. figure:: img/particle_turbulence_influence.webp
+   :alt: Turbulence influence
+
+   Notice how the particle paths are more narrow and less spread out at high influence values (right)
+
+Displacement properties
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Displacement changes a particle's starting position. Use ``Initial Displacement Min`` to set a
+lower limit and ``Initial Displacement Max`` to set an upper limit. When a particle spawns, the
+amount of displacement is randomly chosen from within this range and multiplied by a random
+direction.
+
+Displacement is very useful to break up regular shapes or to create complex shapes from simpler
+ones. The only difference between the particle systems in the screenshot below is the value
+given to the displacement properties.
+
+.. figure:: img/particle_turbulence_displacement.webp
+   :alt: Turbulence displacement
+
+   No displacement (left), displacement value of 5 (middle), displacement range [-20, 20] (right)