Created 3D particle documentation

tutorials/3d/index.rst

@@ -21,6 +21,7 @@ Rendering
    standard_material_3d
    lights_and_shadows
    physical_light_and_camera_units
+   particles/index
    high_dynamic_range
    global_illumination/index
    environment_and_post_processing

tutorials/3d/particles/complexshapes.rst

@@ -0,0 +1,92 @@
+.. _doc_complexemissionshapes3d:
+
+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_particleprocessmaterial3d_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.png
+   :alt: Creating emission points
+   :align: right
+
+   Create particle emission points...
+
+.. figure:: img/particle_select_emission_mesh.png
+   :alt: Select mesh for emission
+   :align: right
+
+   \...from a mesh instance as the source
+
+.. figure:: img/particle_emission_density.png
+   :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.png
+   :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/creation.rst

@@ -0,0 +1,85 @@
+.. _doc_particlecreation3d:
+
+Creating a particle system
+--------------------------
+
+.. figure:: img/particle_node_new.png
+   :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.png
+   :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_particleproperties3d>` and
+:ref:`particle material <doc_particleprocessmaterial3d>` properties to
+learn how to make particle effects more interesting.
+
+.. figure:: img/particle_basic_system.gif
+
+Particle conversion
+~~~~~~~~~~~~~~~~~~~
+
+.. figure:: img/particle_convert_cpu.png
+   :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.