Merge branch 'master' into 4.0

.github/workflows/build_offline_docs.yml

@@ -8,12 +8,12 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     strategy:
       matrix:
         branch:
           - master
-          - stable
+          - 3.6
     steps:
       - uses: actions/checkout@v3
         with:
@@ -23,8 +23,10 @@ jobs:
         run: |
           sudo pip3 install -r requirements.txt
           sudo pip3 install codespell
+          sudo apt update
+          sudo apt install parallel libwebp7
 
-      - name: Sphinx build HTML
+      - name: Sphinx - Build HTML
         run: make SPHINXOPTS='--color' html
 
       - uses: actions/upload-artifact@v3
@@ -34,3 +36,25 @@ jobs:
           # Keep the current build and the previous build (in case a scheduled build failed).
           # This makes it more likely to have at least one successful build available at all times.
           retention-days: 15
+
+      - name: Sphinx - Build ePub
+        run: |
+          # Convert WebP images to PNG and replace references, so that ePub readers can display those images.
+          # The ePub 3.0 specification has WebP support, but it's not widely supported by apps and e-readers yet.
+          shopt -s globstar nullglob
+          parallel --will-cite convert {} {.}.png ::: {about,community,contributing,getting_started,img,tutorials}/**/*.webp
+          parallel --will-cite sed -i "s/\\.webp$/\\.png/g" ::: {about,community,contributing,getting_started,tutorials}/**/*.rst
+
+          # Remove banners at the top of each page when building `latest`.
+          sed -i 's/"godot_is_latest": True/"godot_is_latest": False/' conf.py
+          sed -i 's/"godot_show_article_status": True/"godot_show_article_status": False/' conf.py
+
+          make SPHINXOPTS='--color' epub
+
+      - uses: actions/upload-artifact@v3
+        with:
+          name: godot-docs-epub-${{ matrix.branch }}
+          path: _build/epub/GodotEngine.epub
+          # Keep the current build and the previous build (in case a scheduled build failed).
+          # This makes it more likely to have at least one successful build available at all times.
+          retention-days: 15

.github/workflows/sync_class_ref.yml

@@ -10,7 +10,7 @@ on:
 
 # Make sure jobs cannot overlap.
 concurrency:
-  group: classref-sync-ci
+  group: classref-sync-ci-master
   cancel-in-progress: true
 
 jobs:
@@ -48,7 +48,7 @@ jobs:
 
       - name: Build new documentation
         run: |
-          ./.engine-src/doc/tools/make_rst.py --color -o ./classes -l en ./.engine-src/doc/classes ./.engine-src/modules
+          ./.engine-src/doc/tools/make_rst.py --color -o ./classes -l en ./.engine-src/doc/classes ./.engine-src/modules ./.engine-src/platform
 
       - name: Submit a pull-request
         uses: peter-evans/create-pull-request@v5

.readthedocs.yml

@@ -5,7 +5,9 @@
 version: 2
 
 build:
-  image: latest
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
 
 sphinx:
   configuration: conf.py

README.md

@@ -6,10 +6,26 @@ They are meant to be parsed with the [Sphinx](https://www.sphinx-doc.org/) docum
 
 ## Download for offline use
 
-You can [download an HTML copy](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-master.zip)
+To browse the documentation offline, you can use the mirror of the documentation
+hosted on [DevDocs](https://devdocs.io/godot/). To enable offline browsing on
+DevDocs, you need to:
+
+- Click the three dots in the top-left corner, choose **Preferences**.
+- Enable the desired version of the Godot documentation by checking the box
+  next to it in the sidebar.
+- Click the three dots in the top-left corner, choose **Offline data**.
+- Click the **Install** link next to the Godot documentation.
+
+You can also
+[download an HTML copy](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-html-master.zip)
 for offline reading (updated every Monday). Extract the ZIP archive then open
 the top-level `index.html` in a web browser.
 
+For mobile devices or e-readers, you can also
+[download an ePub copy](https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-epub-master.zip)
+for offline reading (updated every Monday). Extract the ZIP archive then open
+the `GodotEngine.epub` file in an e-book reader application.
+
 ## Theming
 
 The Godot documentation uses the default `sphinx_rtd_theme` with many

contributing/development/compiling/compiling_for_android.rst

@@ -62,13 +62,13 @@ Setting up the buildsystem
 
     ::
 
-        tools/bin/sdkmanager --sdk_root=<android_sdk_path> --licenses
+        cmdline-tools/latest/bin/sdkmanager --sdk_root=<android_sdk_path> --licenses
 
     -  Complete setup by running the following command where ``android_sdk_path`` is the path to the Android SDK.
 
     ::
 
-        tools/bin/sdkmanager --sdk_root=<android_sdk_path> "platform-tools" "build-tools;30.0.3" "platforms;android-29" "cmdline-tools;latest" "cmake;3.10.2.4988404"
+        cmdline-tools/latest/bin/sdkmanager --sdk_root=<android_sdk_path> "platform-tools" "build-tools;30.0.3" "platforms;android-29" "cmdline-tools;latest" "cmake;3.10.2.4988404"
 
 .. seealso::   To set the environment variable on Windows, press :kbd:`Windows + R`, type
             "control system", then click on **Advanced system settings** in the left

contributing/development/compiling/compiling_for_linuxbsd.rst

@@ -379,6 +379,16 @@ created in the ``bin/`` folder.
 It's still recommended to use GCC for production builds as they can be compiled using
 link-time optimization, making the resulting binaries smaller and faster.
 
+If this error occurs::
+
+    /usr/bin/ld: cannot find -l:libatomic.a: No such file or directory
+
+There are two solutions:
+
+- In your SCons command, add the parameter ``use_static_cpp=no``.
+- Follow `these instructions <https://github.com/ivmai/libatomic_ops#installation-and-usage>`__ to configure, build, and
+  install ``libatomic_ops``. Then, copy ``/usr/lib/libatomic_ops.a`` to ``/usr/lib/libatomic.a``.
+
 Using mold for faster development
 ---------------------------------
 

contributing/development/configuring_an_ide/visual_studio_code.rst

@@ -35,8 +35,7 @@ Importing the project
 
 - Within the ``tasks.json`` file find the ``"tasks"`` array and add a new section to it:
 
-.. tabs::
-  .. code-tab:: js LinuxBSD
+  .. code-block:: js
 
     {
       "label": "build",
@@ -50,19 +49,6 @@ Importing the project
       "problemMatcher": "$msCompile"
     }
 
-  .. code-tab:: js Windows
-
-    {
-      "label": "build",
-      "group": "build",
-      "type": "shell",
-      "command": "scons",
-      "args": [
-        "dev_build=yes",
-      ],
-      "problemMatcher": "$msCompile"
-    }
-
 .. figure:: img/vscode_3_tasks.json.png
    :figclass: figure-w480
    :align: center

contributing/documentation/contributing_to_the_documentation.rst

@@ -165,15 +165,31 @@ a meaningful name and include them in your page with:
 
 .. code:: rst
 
-   .. image:: img/image_name.png
+   .. image:: img/image_name.webp
 
-Similarly, you can include attachments, like assets as support material for a
-tutorial, by placing them into a ``files/`` folder next to the ``.rst`` file, and
-using this inline markup:
+Alternatively, you can use the `figure` directive, which gives the image a contrasting
+border and allows centering it on the page.
 
 .. code:: rst
 
-   :download:`myfilename.zip <files/myfilename.zip>`
+    .. figure:: img/image_name.webp
+        :align: center
+
+You can also include attachments as support material for a tutorial, by placing them
+into a ``files/`` folder next to the ``.rst`` file, and using this inline markup:
+
+.. code:: rst
+
+   :download:`file_name.zip <files/file_name.zip>`
+
+Consider using the `godot-docs-project-starters <https://github.com/godotengine/godot-docs-project-starters>`
+repository for hosting support materials, such as project templates and asset packs.
+You can use a direct link to the generated archive from that repository with the regular
+link markup:
+
+.. code:: rst
+
+   `file_name.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/file_name.zip>`_
 
 
 License

contributing/ways_to_contribute.rst

@@ -144,50 +144,9 @@ Filing an issue on GitHub
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Godot uses `GitHub's issue tracker <https://github.com/godotengine/godot/issues>`_
-for bug reports and enhancement suggestions. You will need a GitHub account to
-be able to open a new issue there, and click on the **New issue** button.
-
-When you report a bug, you should keep in mind that the process is similar
-to an appointment with your doctor. You noticed *symptoms* that make you think
-that something might be wrong (the engine crashes, some features don't work as
-expected, etc.). It's the role of the bug triaging team and the developers to
-then help make the diagnosis of the issue you met, so that the actual cause of
-the bug can be identified and addressed.
-
-You should therefore always ask yourself: what is relevant information to
-give so that other Godot contributors can understand the bug, identify it and
-hopefully fix it. Here are some of the most important infos that you should
-always provide:
-
--  **Operating system.** Sometimes bugs are system-specific, i.e. they happen
-   only on Windows, or only on Linux, etc. That's particularly relevant for all
-   bugs related to OS interfaces, such as file management, input, window
-   management, audio, etc.
-
--  **Hardware.** Sometimes bugs are hardware-specific, i.e. they happen
-   only on certain processors, graphic cards, etc. If you are able to,
-   it can be helpful to include information on your hardware.
-
--  **Godot version.** This is a must-have. Some issues might be relevant in the
-   current stable release, but fixed in the development branch, or the other
-   way around. You might also be using an obsolete version of Godot and
-   experiencing a known issue fixed in a later version, so knowing this from
-   the start helps to speed up the diagnosis.
-
--  **How to reproduce the bug.** In the majority of cases, bugs are
-   reproducible, i.e. it is possible to trigger them reliably by following some
-   steps. Please always describe those steps as clearly as possible, so that
-   everyone can try to reproduce the issue and confirm it. Ideally, make a demo
-   project that reproduces this issue out of the box, zip it and attach it to
-   the issue (you can do this by drag and drop).
-   Even if you think that the issue is trivial to reproduce, adding a minimal
-   project that lets everyone reproduce it is a big added value. You have to keep in
-   mind that there are thousands of issues in the tracker, and developers can
-   only dedicate little time to each issue.
-
-When you click the **New issue** button, you should be presented with a text area
-prefilled with our issue template. Please try to follow it so that all issues
-are consistent and provide the required information.
+for bug reports. When you start filing a bug report, you’ll be given a form to
+fill out. Please try to follow it so that all issues are consistent and provide
+the required information.
 
 Contributing to the documentation
 ---------------------------------

contributing/workflow/pr_workflow.rst

@@ -347,9 +347,16 @@ do:
 
     $ git push origin better-project-manager
 
-Git will ask you for your username and password, and the changes will be sent
-to your remote. If you check the fork's page on GitHub, you should see a new
-branch with your added commits.
+Git will ask you for your username and password. For your password, enter your
+GitHub Personal Access Token (PAT). If you do not have a GitHub Personal Access
+Token, or do not have one with the correct permissions for your newly forked
+repository, you will need to create one. Follow this link to create your Personal
+Access Token: `Creating a personal access token
+<https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token>`_.
+
+After you have successfully verified your account using your PAT, the changes
+will be sent to your remote repository. If you check the fork's page on GitHub,
+you should see a new branch with your added commits.
 
 Issuing a pull request
 ----------------------

getting_started/first_2d_game/01.project_setup.rst

@@ -12,14 +12,14 @@ Launch Godot and create a new project.
 .. tabs::
  .. tab:: GDScript
 
-    Download :download:`dodge_assets.zip <files/dodge_assets.zip>`.
+    Download `dodge_the_creeps_2d_assets.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/dodge_the_creeps_2d_assets.zip>`_.
     The archive contains the images and sounds you'll be using
     to make the game. Extract the archive and move the ``art/``
     and ``fonts/`` directories to your project's directory.
 
  .. tab:: C#
 
-    Download :download:`dodge_assets.zip <files/dodge_assets.zip>`.
+    Download `dodge_the_creeps_2d_assets.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/dodge_the_creeps_2d_assets.zip>`_.
     The archive contains the images and sounds you'll be using
     to make the game. Extract the archive and move the ``art/``
     and ``fonts/`` directories to your project's directory.

getting_started/first_2d_game/05.the_main_game_scene.rst

@@ -289,7 +289,7 @@ the other two timers. ``ScoreTimer`` will increment the score by 1.
         godot::register_property("mob_scene", &Main::mob_scene, (godot::Ref<godot::PackedScene>)nullptr);
     }
 
-In ``_on_MobTimer_timeout()``, we will create a mob instance, pick a random
+In ``_on_mob_timer_timeout()``, we will create a mob instance, pick a random
 starting location along the ``Path2D``, and set the mob in motion. The
 ``PathFollow2D`` node will automatically rotate as it follows the path, so we
 will use that to select the mob's direction as well as its position.
@@ -392,8 +392,8 @@ Note that a new instance must be added to the scene using ``add_child()``.
                not degrees. Pi represents a half turn in radians, about
                ``3.1415`` (there is also ``TAU`` which is equal to ``2 * PI``).
                If you're more comfortable working with degrees, you'll need to
-               use the ``deg2rad()`` and ``rad2deg()`` functions to convert
-               between the two.
+               use the ``deg_to_rad()`` and ``rad_to_deg()`` functions to
+               convert between the two.
 
 Testing the scene
 ~~~~~~~~~~~~~~~~~

getting_started/first_2d_game/06.heads_up_display.rst

@@ -354,6 +354,9 @@ window and selecting the ``new_game()`` method or type "new_game" below "Receive
 in the window. Verify that the green connection icon now appears next to
 ``func new_game()`` in the script.
 
+Remember to remove the call to ``new_game()`` from
+``_ready()``.
+
 In ``new_game()``, update the score display and show the "Get Ready" message:
 
 .. tabs::
@@ -391,7 +394,7 @@ In ``game_over()`` we need to call the corresponding ``HUD`` function:
 Just a reminder: we don't want to start the new game automatically, so
 remove the call to ``new_game()`` in ``_ready()`` if you haven't yet.
 
-Finally, add this to ``_on_ScoreTimer_timeout()`` to keep the display in sync
+Finally, add this to ``_on_score_timer_timeout()`` to keep the display in sync
 with the changing score:
 
 .. tabs::

getting_started/first_2d_game/index.rst

@@ -17,7 +17,7 @@ a 2D game.
           programming entirely, you should start here: :ref:`doc_scripting`.
 
 The game is called "Dodge the Creeps!". Your character must move and avoid the
-enemies for as long as possible. 
+enemies for as long as possible.
 
 You will learn to:
 
@@ -57,7 +57,7 @@ the code.
 
 You can download them by clicking the link below.
 
-:download:`dodge_assets.zip <files/dodge_assets.zip>`.
+`dodge_the_creeps_2d_assets.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/dodge_the_creeps_2d_assets.zip>`_.
 
 Contents
 --------

getting_started/first_3d_game/01.game_setup.rst

@@ -1,3 +1,5 @@
+:article_outdated: True
+
 .. _doc_first_3d_game_game_area:
 
 Setting up the game area
@@ -99,7 +101,7 @@ You should see a wide grey slab that covers the grid and blue and red axes in
 the viewport.
 
 We're going to move the ground down so we can see the floor grid. Select the
-``Ground`` node, hold the :kbd:`Ctrl` key down to turn on grid snapping (:kbd:`Cmd` on macOS),
+``Ground`` node, hold the :kbd:`Ctrl` key down to turn on grid snapping,
 and click and drag down on the Y axis. It's the green arrow in the move gizmo.
 
 .. image:: img/01.game_setup/move_gizmo_y_axis.webp

getting_started/first_3d_game/02.player_input.rst

@@ -1,3 +1,5 @@
+:article_outdated: True
+
 .. _doc_first_3d_game_player_scene_and_input:
 
 Player scene and input actions

getting_started/first_3d_game/03.player_movement_code.rst

@@ -1,3 +1,5 @@
+:article_outdated: True
+
 .. _doc_first_3d_game_player_movement:
 
 Moving the player with code

getting_started/first_3d_game/04.mob_scene.rst

@@ -1,3 +1,5 @@
+:article_outdated: True
+
 .. _doc_first_3d_game_designing_the_mob_scene:
 
 Designing the mob scene
@@ -237,7 +239,7 @@ method. This function destroy the instance it's called on.
 .. tabs::
  .. code-tab:: gdscript GDScript
 
-   func _on_VisibilityNotifier_screen_exited():
+   func _on_visible_on_screen_notifier_3d_screen_exited():
        queue_free()
 
  .. code-tab:: csharp

getting_started/first_3d_game/05.spawning_mobs.rst

@@ -1,3 +1,5 @@
+:article_outdated: True
+
 .. _doc_first_3d_game_spawning_monsters:
 
 Spawning monsters

getting_started/first_3d_game/06.jump_and_squash.rst

@@ -1,3 +1,5 @@
+:article_outdated: True
+
 .. _doc_first_3d_game_jumping_and_squashing_monsters:
 
 Jumping and squashing monsters

getting_started/first_3d_game/07.killing_player.rst

@@ -1,3 +1,5 @@
+:article_outdated: True
+
 .. _doc_first_3d_game_killing_the_player:
 
 Killing the player

getting_started/first_3d_game/08.score_and_replay.rst

@@ -1,3 +1,5 @@
+:article_outdated: True
+
 .. _doc_first_3d_game_score_and_replay:
 
 Score and replay

getting_started/first_3d_game/09.adding_animations.rst

@@ -1,3 +1,5 @@
+:article_outdated: True
+
 .. _doc_first_3d_game_character_animation:
 
 Character animation
@@ -257,10 +259,12 @@ node structure, you can copy them to different scenes.
 For example, both the ``Mob`` and the ``Player`` scenes have a ``Pivot`` and a
 ``Character`` node, so we can reuse animations between them.
 
-Open the ``Player.tscn`` scene, select the ``AnimationPlayer`` node and open the "float" animation.
-Next, click on **Animation > Copy**. Then open ``Mob.tscn`` and open its animation
-player. Click **Animation > Paste**. That's it; all monsters will now play the float
-animation.
+Open the *Player* scene, select the AnimationPlayer node and open the "float" 
+animation. Next, click on **Animation > Copy**. Then open ``Mob.tscn``, 
+create an AnimationPlayer child node and select it. Click **Animation > Paste** 
+and make sure that the button with an "A+" icon (Autoplay on Load) and the 
+looping arrows (Animation looping) are also turned on in the animation editor 
+in the bottom panel. That's it; all monsters will now play the float animation.
 
 We can change the playback speed based on the creature's ``random_speed``. Open
 the *Mob*'s script and at the end of the ``initialize()`` function, add the

getting_started/first_3d_game/going_further.rst

@@ -1,3 +1,5 @@
+:article_outdated: True
+
 .. _doc_first_3d_game_going_further:
 
 Going further

getting_started/first_3d_game/index.rst

@@ -1,3 +1,5 @@
+:article_outdated: True
+
 .. _doc_your_first_3d_game:
 
 Your first 3D game

getting_started/introduction/godot_design_philosophy.rst

@@ -78,7 +78,7 @@ the ability to hot-reload locally and on remote devices, etc.
 
 The goal is to offer a full package to create games and a continuous
 user experience. You can still work with external programs as long as
-there is an import plugin for it. Or you can create one, like the `Tiled
+there is an import plugin available in Godot for it. Or you can create one, like the `Tiled
 Map Importer <https://github.com/vnen/godot-tiled-importer>`__.
 
 That is also partly why Godot offers its own programming language

getting_started/step_by_step/instancing.rst

@@ -42,7 +42,7 @@ In practice
 
 Let's use instancing in practice to see how it works in Godot. We invite
 you to download the ball's sample project we prepared for you:
-:download:`instancing.zip <files/instancing.zip>`.
+`instancing_starter.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/instancing_starter.zip>`_.
 
 Extract the archive on your computer. To import it, you need the Project Manager.
 The Project Manager is accessed by opening Godot, or if you already have Godot opened, click on *Project -> Quit to Project List* (:kbd:`Ctrl + Shift + Q`, :kbd:`Ctrl + Option + Cmd + B` on macOS)

getting_started/step_by_step/nodes_and_scenes.rst

@@ -59,7 +59,7 @@ you or a player runs the game.
 On top of acting like nodes, scenes have the following characteristics:
 
 1. They always have one root node, like the "Character" in our example.
-2. You can save them to your hard drive and load them later.
+2. You can save them to your local drive and load them later.
 3. You can create as many instances of a scene as you'd like. You could have
    five or ten characters in your game, created from your Character scene.
 

index.rst

@@ -65,6 +65,9 @@ You can also `download an HTML copy <https://nightly.link/godotengine/godot-docs
 for offline reading (updated every Monday). Extract the ZIP archive then open
 the top-level ``index.html`` in a web browser.
 
+For mobile devices or e-readers, you can also `download an ePub copy <https://nightly.link/godotengine/godot-docs/workflows/build_offline_docs/master/godot-docs-epub-master.zip>`__
+for offline reading (updated every Monday). Extract the ZIP archive then open
+the ``GodotEngine.epub`` file in an e-book reader application.
 
 .. Below is the main table-of-content tree of the documentation website.
    It is hidden on the page itself, but it makes up the sidebar for navigation.

tutorials/2d/2d_movement.rst

@@ -289,4 +289,4 @@ You may find these code samples useful as starting points for your own projects.
 Feel free to use them and experiment with them to see what you can make.
 
 You can download this sample project here:
-:download:`2D_movement_demo.zip <files/2D_movement_demo.zip>`
+`2d_movement_starter.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/2d_movement_starter.zip>`_

tutorials/2d/2d_sprite_animation.rst

@@ -7,12 +7,16 @@ Introduction
 ------------
 
 In this tutorial, you'll learn how to create 2D animated
-characters with the AnimatedSprite2D class and the AnimationPlayer. Typically, when you create or download an animated character, it
-will come in one of two ways: as individual images or as a single sprite sheet
-containing all the animation's frames. Both can be animated in Godot with the AnimatedSprite2D class.
+characters with the AnimatedSprite2D class and the AnimationPlayer.
+Typically, when you create or download an animated character,
+it will come in one of two ways: as individual images or as a single sprite sheet
+containing all the animation's frames.
+Both can be animated in Godot with the AnimatedSprite2D class.
 
 First, we'll use :ref:`AnimatedSprite2D <class_AnimatedSprite2D>` to
-animate a collection of individual images. Then we will animate a sprite sheet using this class. Finally, we will learn another way to animate a sprite sheet
+animate a collection of individual images.
+Then we will animate a sprite sheet using this class.
+Finally, we will learn another way to animate a sprite sheet
 with :ref:`AnimationPlayer <class_AnimationPlayer>` and the *Animation*
 property of :ref:`Sprite2D <class_Sprite2D>`.
 
@@ -28,7 +32,7 @@ animation:
 .. image:: img/2d_animation_run_preview.gif
 
 You can download the images here:
-:download:`run_animation.zip <files/run_animation.zip>`
+`2d_sprite_animation_assets.zip <https://github.com/godotengine/godot-docs-project-starters/releases/download/latest-4.x/2d_sprite_animation_assets.zip>`_
 
 Unzip the images and place them in your project folder. Set up your scene tree
 with the following nodes:
@@ -45,7 +49,7 @@ with the following nodes:
 Now select the ``AnimatedSprite2D`` and in its *SpriteFrames* property, select
 "New SpriteFrames".
 
-.. image:: img/2d_animation_new_spriteframes.png
+.. image:: img/2d_animation_new_spriteframes.webp
 
 Click on the new SpriteFrames resource and you'll see a new panel appear at the
 bottom of the editor window:
@@ -58,11 +62,12 @@ of the animation from "default" to "run".
 
 .. image:: img/2d_animation_spriteframes_done.webp
 
-Back in the Inspector, check the box for the *Playing* property. You should
-now see the animation playing in the viewport. However, it is a bit slow. To
-fix this, change the *Speed (FPS)* setting in the SpriteFrames panel to 10.
+Use the "Play" buttons on the top-right of the *Filter Animations* input to preview the animation.
+You should now see the animation playing in the viewport.
+However, it is a bit slow. To fix this,
+change the *Speed (FPS)* setting in the SpriteFrames panel to 10.
 
-You can add additional animations by clicking the "New Animation" button and
+You can add additional animations by clicking the "Add Animation" button and
 adding additional images.
 
 Controlling the animation
@@ -116,30 +121,37 @@ released.
 Sprite sheet with AnimatedSprite2D
 ----------------------------------
 
-You can also easily animate from a sprite sheet with the class ``AnimatedSprite2D``. We will use this public domain sprite sheet:
+You can also easily animate from a sprite sheet with the class ``AnimatedSprite2D``.
+We will use this public domain sprite sheet:
 
 .. image:: img/2d_animation_frog_spritesheet.png
 
-Right-click the image and choose "Save Image As" to download it, and then copy the image into your project folder.
+Right-click the image and choose "Save Image As" to download it,
+and then copy the image into your project folder.
 
-Set up your scene tree the same way you did previously when using individual images. Select the ``AnimatedSprite2D`` and in its *SpriteFrames* property, select
-"New SpriteFrames".
+Set up your scene tree the same way you did previously when using individual images.
+Select the ``AnimatedSprite2D`` and in its *SpriteFrames* property, select "New SpriteFrames".
 
-Click on the new SpriteFrames resource. This time, when the bottom panel appears, select "Add frames from a Sprite Sheet".
+Click on the new SpriteFrames resource.
+This time, when the bottom panel appears, select "Add frames from a Sprite Sheet".
 
 .. image:: img/2d_animation_add_from_spritesheet.webp
 
 You will be prompted to open a file. Select your sprite sheet.
 
-A new window will open, showing your sprite sheet. The first thing you will need to do is to change the number of vertical and horizontal images in your sprite sheet. In this sprite sheet, we have four images horizontally and two images vertically.
+A new window will open, showing your sprite sheet.
+The first thing you will need to do is to change the number of vertical and horizontal images in your sprite sheet.
+In this sprite sheet, we have four images horizontally and two images vertically.
 
 .. image:: img/2d_animation_spritesheet_select_rows.webp
 
-Next, select the frames from the sprite sheet that you want to include in your animation. We will select the top four, then click "Add 4 frames" to create the animation.
+Next, select the frames from the sprite sheet that you want to include in your animation.
+We will select the top four, then click "Add 4 frames" to create the animation.
 
 .. image:: img/2d_animation_spritesheet_selectframes.webp
 
-You will now see your animation under the list of animations in the bottom panel. Double click on default to change the name of the animation to jump.
+You will now see your animation under the list of animations in the bottom panel.
+Double click on default to change the name of the animation to jump.
 
 .. image:: img/2d_animation_spritesheet_animation.webp
 
@@ -180,7 +192,7 @@ expand the *Animation* section in the Inspector and set the *Hframes* to ``6``.
 *Hframes* and *Vframes* are the number of horizontal and vertical frames in
 your sprite sheet.
 
-.. image:: img/2d_animation_setframes.png
+.. image:: img/2d_animation_setframes.webp
 
 Now try changing the value of the *Frame* property. You'll see that it ranges
 from ``0`` to ``5`` and the image displayed by the Sprite2D changes accordingly.
@@ -190,17 +202,17 @@ Select the ``AnimationPlayer`` and click the "Animation" button followed by
 "New". Name the new animation "walk". Set the animation length to ``0.6`` and
 click the "Loop" button so that our animation will repeat.
 
-.. image:: img/2d_animation_new_animation.png
+.. image:: img/2d_animation_new_animation.webp
 
 Now select the ``Sprite2D`` node and click the key icon to add a new track.
 
-.. image:: img/2d_animation_new_track.png
+.. image:: img/2d_animation_new_track.webp
 
 Continue adding frames at each point in the timeline (``0.1`` seconds by
 default), until you have all the frames from 0 to 5. You'll see the frames
 actually appearing in the animation track:
 
-.. image:: img/2d_animation_full_animation.png
+.. image:: img/2d_animation_full_animation.webp
 
 Press "Play" on the animation to see how it looks.
 
@@ -266,7 +278,9 @@ released.
 Summary
 -------
 
-These examples illustrate the two classes you can use in Godot for
-2D animation. ``AnimationPlayer`` is
-a bit more complex than ``AnimatedSprite2D``, but it provides additional functionality, since you can also
-animate other properties like position or scale. The class ``AnimationPlayer`` can also be used with an ``AnimatedSprite2D``. Experiment to see what works best for your needs.
+These examples illustrate the two classes you can use in Godot for 2D animation.
+``AnimationPlayer`` is a bit more complex than ``AnimatedSprite2D``,
+but it provides additional functionality, since you can also
+animate other properties like position or scale.
+The class ``AnimationPlayer`` can also be used with an ``AnimatedSprite2D``.
+Experiment to see what works best for your needs.

tutorials/2d/custom_drawing_in_2d.rst

@@ -227,7 +227,7 @@ In our example, we will simply use a fixed number of points, no matter the radiu
         var points_arc = PackedVector2Array()
 
         for i in range(nb_points + 1):
-            var angle_point = deg2rad(angle_from + i * (angle_to-angle_from) / nb_points - 90)
+            var angle_point = deg_to_rad(angle_from + i * (angle_to-angle_from) / nb_points - 90)
             points_arc.push_back(center + Vector2(cos(angle_point), sin(angle_point)) * radius)
 
         for index_point in range(nb_points):
@@ -242,7 +242,7 @@ In our example, we will simply use a fixed number of points, no matter the radiu
 
         for (int i = 0; i <= nbPoints; i++)
         {
-            float anglePoint = Mathf.Deg2Rad(angleFrom + i * (angleTo - angleFrom) / nbPoints - 90f);
+            float anglePoint = Mathf.DegToRad(angleFrom + i * (angleTo - angleFrom) / nbPoints - 90f);
             pointsArc[i] = center + new Vector2(Mathf.Cos(anglePoint), Mathf.Sin(anglePoint)) * radius;
         }
 

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.