Merge pull request #9937 from mhilbrunner/3-6-backports

Manual 3.6 backports

AUTHORS.md

@@ -4,7 +4,7 @@ Godot Engine is developed by a community of voluntary contributors who
 contribute on all areas, including writing and maintaining the documentation.
 
 It is impossible to list them all; nevertheless, this file aims at listing
-the writers who contributed significant patches to this CC-BY licensed
+the writers who contributed significant patches to this CC BY licensed
 documentation on the `godot-docs` repository.
 
 GitHub usernames are indicated in parentheses, or as sole entry when no other

_static/css/custom.css

@@ -827,6 +827,7 @@ code,
 
 .highlight {
     background-color: var(--highlight-background-color);
+    tab-size: 4;
 }
 
 /* Emphasized lines */
@@ -1677,3 +1678,33 @@ p + .classref-constant {
 .wy-menu-vertical p.caption + ul.active {
     display: block;
 }
+
+/* Allow :abbr: tags' content to be displayed on mobile platforms by tapping the word */
+@media (hover: none),
+(hover: on-demand),
+(-moz-touch-enabled: 1),
+(pointer:coarse) {
+
+    /* Do not enable on desktop platforms to avoid doubling the tooltip */
+    abbr[title] {
+        position: relative;
+    }
+
+    abbr[title]:hover::after,
+    abbr[title]:focus::after {
+        content: attr(title);
+
+        position: absolute;
+        left: 0;
+        bottom: -32px;
+        width: auto;
+        white-space: nowrap;
+
+        background-color: #1e1e1e;
+        color: #fff;
+        border-radius: 3px;
+        box-shadow: 1px 1px 5px 0 rgba(0, 0, 0, 0.4);
+        font-size: 14px;
+        padding: 3px 5px;
+    }
+}

_static/js/custom.js

@@ -291,6 +291,23 @@ const registerOnScrollEvent = (function(){
       }
     }
 
+    // Change indentation from spaces to tabs for codeblocks.
+    const codeBlocks = document.querySelectorAll('.rst-content div[class^="highlight"] pre');
+    for (const codeBlock of codeBlocks) {
+      const classList = codeBlock.parentNode.parentNode.classList;
+      if (!classList.contains('highlight-gdscript') && !classList.contains('highlight-cpp')) {
+        // Only change indentation for GDScript and C++.
+        continue;
+      }
+      let html = codeBlock.innerHTML.replace(/^(<span class="w">)?( {4})/gm, '\t');
+      let html_old = "";
+      while (html != html_old) {
+        html_old = html;
+        html = html.replace(/\t( {4})/gm, '\t\t')
+      }
+      codeBlock.innerHTML = html;
+    }
+
     // See `godot_is_latest` in conf.py
     const isLatest = document.querySelector('meta[name=doc_is_latest]').content.toLowerCase() === 'true';
     if (isLatest) {

_tools/codespell-ignore.txt

@@ -7,3 +7,5 @@ uint
 subtile
 implementors
 thirdparty
+inout
+findn

about/faq.rst

@@ -17,7 +17,7 @@ In short:
 * You are free to modify, distribute, redistribute, and remix Godot to your heart's content, for any reason, both non-commercially and commercially.
 
 All the contents of this accompanying documentation are published under
-the permissive Creative Commons Attribution 3.0 (`CC-BY 3.0 <https://creativecommons.org/licenses/by/3.0/>`_) license, with attribution
+the permissive Creative Commons Attribution 3.0 (`CC BY 3.0 <https://creativecommons.org/licenses/by/3.0/>`_) license, with attribution
 to "Juan Linietsky, Ariel Manzur and the Godot Engine community."
 
 Logos and icons are generally under the same Creative Commons license. Note

about/introduction.rst

@@ -70,7 +70,7 @@ open source `Sphinx <http://www.sphinx-doc.org>`_ and `ReadTheDocs
           <https://hosted.weblate.org/projects/godot-engine/godot-docs/>`_.
 
 All the contents are under the permissive Creative Commons Attribution 3.0
-(`CC-BY 3.0 <https://creativecommons.org/licenses/by/3.0/>`_) license, with
+(`CC BY 3.0 <https://creativecommons.org/licenses/by/3.0/>`_) license, with
 attribution to "Juan Linietsky, Ariel Manzur and the Godot Engine community".
 
 Organization of the documentation

community/contributing/contributing_to_the_documentation.rst

@@ -180,8 +180,8 @@ License
 -------
 
 This documentation and every page it contains is published under the terms of
-the `Creative Commons Attribution 3.0 license (CC-BY-3.0)
-<https://tldrlegal.com/license/creative-commons-attribution-(cc)>`_, with
+the `Creative Commons Attribution 3.0 license (CC BY 3.0)
+<https://creativecommons.org/licenses/by/3.0/>`_, with
 attribution to "Juan Linietsky, Ariel Manzur and the Godot community".
 
 By contributing to the documentation on the GitHub repository, you agree that

community/contributing/documentation_guidelines.rst

@@ -135,7 +135,8 @@ License
 -------
 
 This documentation and every page it contains is published under the terms of
-the `Creative Commons Attribution 3.0 license (CC-BY-3.0) <https://tldrlegal.com/license/creative-commons-attribution-(cc)>`_, with attribution to "Juan Linietsky, Ariel Manzur and the Godot community".
+the `Creative Commons Attribution 3.0 license (CC BY 3.0) <https://creativecommons.org/licenses/by/3.0/>`_,
+with attribution to "Juan Linietsky, Ariel Manzur and the Godot community".
 
 By contributing to the documentation on the GitHub repository, you agree that
 your changes are distributed under this license.

development/cpp/custom_audiostreams.rst

@@ -23,7 +23,7 @@ References:
 ~~~~~~~~~~~
 
 -  `servers/audio/audio_stream.h <https://github.com/godotengine/godot/blob/master/servers/audio/audio_stream.h>`__
--  `scene/audio/audioplayer.cpp <https://github.com/godotengine/godot/blob/master/scene/audio/audio_player.cpp>`__
+-  `scene/audio/audio_stream_player.cpp <https://github.com/godotengine/godot/blob/master/scene/audio/audio_stream_player.cpp>`__
 
 What for?
 ---------
@@ -348,4 +348,4 @@ References:
 ~~~~~~~~~~~
 -  `core/math/audio_frame.h <https://github.com/godotengine/godot/blob/master/core/math/audio_frame.h>`__
 -  `servers/audio/audio_stream.h <https://github.com/godotengine/godot/blob/master/servers/audio/audio_stream.h>`__
--  `scene/audio/audioplayer.cpp <https://github.com/godotengine/godot/blob/master/scene/audio/audio_player.cpp>`__
+-  `scene/audio/audio_stream_player.cpp <https://github.com/godotengine/godot/blob/master/scene/audio/audio_stream_player.cpp>`__

tutorials/assets_pipeline/importing_images.rst

@@ -22,7 +22,7 @@ Godot can import the following image formats:
 - PNG (``.png``)
   - Precision is limited to 8 bits per channel upon importing (no HDR images).
 - Truevision Targa (``.tga``)
-- SVG (``.svg``, ``.svgz``)
+- SVG (``.svg``)
   - SVGs are rasterized using `NanoSVG <https://github.com/memononen/nanosvg>`__
   when importing them. Support is limited; complex vectors may not render correctly.
   For complex vectors, rendering them to PNGs using Inkscape is often a better solution.

tutorials/inputs/custom_mouse_cursor.rst

@@ -3,7 +3,9 @@
 Customizing the mouse cursor
 ============================
 
-You might want to change the appearance of the mouse cursor in your game in order to suit the overall design. There are two ways to customize the mouse cursor:
+You might want to change the appearance of the mouse cursor in your game in
+order to suit the overall design. There are two ways to customize the mouse
+cursor:
 
 1. Using project settings
 2. Using a script
@@ -13,8 +15,8 @@ Using project settings is a simpler (but more limited) way to customize the mous
 .. note::
 
     You could display a "software" mouse cursor by hiding the mouse cursor and
-    moving a Sprite to the cursor position in a ``_process`` method, but this
-    will add at least one frame of latency compared to an "hardware" mouse
+    moving a Sprite2D to the cursor position in a ``_process()`` method, but
+    this will add at least one frame of latency compared to an "hardware" mouse
     cursor. Therefore, it's recommended to use the approach described here
     whenever possible.
 
@@ -31,7 +33,12 @@ Open project settings, go to Display>Mouse Cursor. You will see Custom Image and
 Custom Image is the desired image that you would like to set as the mouse cursor.
 Custom Hotspot is the point in the image that you would like to use as the cursor's detection point.
 
-.. note:: The custom image **must** be less than 256x256.
+.. warning::
+
+    The custom image **must** be 256×256 pixels at most. To avoid rendering
+    issues, sizes lower than or equal to 128×128 are recommended.
+
+    On the web platform, the maximum allowed cursor image size is 128×128.
 
 Using a script
 --------------
@@ -73,8 +80,10 @@ Create a Node and attach the following script.
         Input.SetCustomMouseCursor(beam, Input.CursorShape.Ibeam);
     }
 
-.. note::
-    Check :ref:`Input.set_custom_mouse_cursor() <class_Input_method_set_custom_mouse_cursor>`.
+.. seealso::
+
+    Check :ref:`Input.set_custom_mouse_cursor() <class_Input_method_set_custom_mouse_cursor>`'s
+    documentation for more information on usage and platform-specific caveats.
 
 
 Demo project
@@ -86,4 +95,6 @@ https://github.com/guilhermefelipecgs/custom_hardware_cursor
 Cursor list
 -----------
 
-As documented in the :ref:`Input <class_Input>` class (see the **CursorShape** enum), there are multiple mouse cursors you can define. Which ones you want to use depends on your use case.
+As documented in the :ref:`Input <class_Input>` class (see the **CursorShape**
+enum), there are multiple mouse cursors you can define. Which ones you want to
+use depends on your use case.

tutorials/plugins/running_code_in_the_editor.rst

@@ -61,7 +61,7 @@ On the other hand, if you want to execute code only in game, simply negate the s
         // Code to execute when in game.
     }
 
-Pieces of code do not have either of the 2 conditions above will run both in-editor and in-game.
+Pieces of code that do not have either of the 2 conditions above will run both in-editor and in-game.
 
 Here is how a ``_process()`` function might look for you:
 

tutorials/scripting/debug/debugger_panel.rst

@@ -17,8 +17,24 @@ The Debugger tab opens automatically when the GDScript compiler reaches
 a breakpoint in your code.
 
 It gives you a `stack trace <https://en.wikipedia.org/wiki/Stack_trace>`__,
-information about the state of the object, and buttons to control
-the program's execution.
+information about the state of the object, and buttons to control the program's
+execution. When the debugger breaks on a breakpoint, a green triangle arrow is
+visible in the script editor's gutter. This arrow indicates the line of code the
+debugger broke on.
+
+.. tip::
+
+    You can create a breakpoint by clicking the gutter in the left of the script
+    editor (on the left of the line numbers). When hovering this gutter, you
+    will see a transparent red dot appearing, which turns into an opaque red dot
+    after the breakpoint is placed by clicking. Click the red dot again to
+    remove the breakpoint. Breakpoints created this way persist across editor
+    restarts, even if the script wasn't saved when exiting the editor.
+
+    You can also use the ``breakpoint`` keyword in GDScript to create a
+    breakpoint that is stored in the script itself. Unlike breakpoints created by
+    clicking in the gutter, this keyword-based breakpoint is persistent across
+    different machines when using version control.
 
 You can use the buttons in the top-right corner to:
 

tutorials/scripting/debug/overview_of_debugging_tools.rst

@@ -79,6 +79,20 @@ The script editor has its own set of debug tools for use with breakpoints and
 two options. The breakpoint tools can also be found in the **Debugger** tab
 of the debugger.
 
+.. tip::
+
+    You can create a breakpoint by clicking the gutter in the left of the script
+    editor (on the left of the line numbers). When hovering this gutter, you
+    will see a transparent red dot appearing, which turns into an opaque red dot
+    after the breakpoint is placed by clicking. Click the red dot again to
+    remove the breakpoint. Breakpoints created this way persist across editor
+    restarts, even if the script wasn't saved when exiting the editor.
+
+    You can also use the ``breakpoint`` keyword in GDScript to create a
+    breakpoint that is stored in the script itself. Unlike breakpoints created by
+    clicking in the gutter, this keyword-based breakpoint is persistent across
+    different machines when using version control.
+
 .. image:: img/overview_script_editor.png
 
 The **Break** button causes a break in the script like a breakpoint would.
@@ -90,6 +104,10 @@ The **Keep Debugger Open** option keeps the debugger open after a scene
 has been closed. And the **Debug with External Editor** option lets you
 debug your game with an external editor.
 
+When the debugger breaks on a breakpoint, a green triangle arrow is visible in
+the script editor's gutter. This arrow indicates the line of code the debugger
+broke on.
+
 .. warning::
 
     Breakpoints won't break on code if it's

tutorials/scripting/gdnative/gdnative_cpp_example.rst

@@ -154,7 +154,7 @@ directories in your GDNative module.
 In the ``src`` folder, we'll start with creating our header file for the
 GDNative node we'll be creating. We will name it ``gdexample.h``:
 
-.. code-block:: C++
+.. code-block:: cpp
 
     #ifndef GDEXAMPLE_H
     #define GDEXAMPLE_H
@@ -212,7 +212,7 @@ our object. It has to exist even if you don't place any code in it.
 
 Let's implement our functions by creating our ``gdexample.cpp`` file:
 
-.. code-block:: C++
+.. code-block:: cpp
 
     #include "gdexample.h"
 
@@ -261,7 +261,7 @@ and source file like we've implemented ``GDExample`` up above. What we need now
 is a small bit of code that tells Godot about all the NativeScripts in our
 GDNative plugin.
 
-.. code-block:: C++
+.. code-block:: cpp
 
     #include "gdexample.h"
 
@@ -432,7 +432,7 @@ allows us to control the amplitude of our wave.
 
 In our ``gdexample.h`` file we simply need to add a member variable like so:
 
-.. code-block:: C++
+.. code-block:: cpp
 
     ...
     private:
@@ -443,7 +443,7 @@ In our ``gdexample.h`` file we simply need to add a member variable like so:
 In our ``gdexample.cpp`` file we need to make a number of changes, we will only
 show the methods we end up changing, don't remove the lines we're omitting:
 
-.. code-block:: C++
+.. code-block:: cpp
 
     void GDExample::_register_methods() {
         register_method("_process", &GDExample::_process);
@@ -486,7 +486,7 @@ Let's do the same but for the speed of our animation and use a setter and getter
 function. Our ``gdexample.h`` header file again only needs a few more lines of
 code:
 
-.. code-block:: C++
+.. code-block:: cpp
 
     ...
         float amplitude;
@@ -500,7 +500,7 @@ code:
 This requires a few more changes to our ``gdexample.cpp`` file, again we're only
 showing the methods that have changed so don't remove anything we're omitting:
 
-.. code-block:: C++
+.. code-block:: cpp
 
     void GDExample::_register_methods() {
         register_method("_process", &GDExample::_process);
@@ -565,7 +565,7 @@ would need to showcase a far more complete example.
 
 This is the required syntax:
 
-.. code-block:: C++
+.. code-block:: cpp
 
     some_other_node->connect("the_signal", this, "my_method");
 
@@ -578,7 +578,7 @@ emit a signal every time a second has passed and pass the new location along.
 
 In our ``gdexample.h`` header file, we need to define a new member ``time_emit``:
 
-.. code-block:: C++
+.. code-block:: cpp
 
     ...
         float time_passed;
@@ -593,7 +593,7 @@ constructor. We'll look at the other 2 needed changes one by one.
 In our ``_register_methods`` method, we need to declare our signal. This is done
 as follows:
 
-.. code-block:: C++
+.. code-block:: cpp
 
     void GDExample::_register_methods() {
         register_method("_process", &GDExample::_process);
@@ -609,7 +609,7 @@ type of each parameter we'll send along with this signal.
 
 Next, we'll need to change our ``_process`` method:
 
-.. code-block:: C++
+.. code-block:: cpp
 
     void GDExample::_process(float delta) {
         time_passed += speed * delta;

tutorials/scripting/gdscript/gdscript_basics.rst

@@ -192,7 +192,8 @@ in case you want to take a look under the hood.
 +------------+---------------------------------------------------------------------------------------------------------------+
 | setget     | Defines setter and getter functions for a variable.                                                           |
 +------------+---------------------------------------------------------------------------------------------------------------+
-| breakpoint | Editor helper for debugger breakpoints.                                                                       |
+| breakpoint | Editor helper for debugger breakpoints. Unlike breakpoints created by clicking in the gutter, ``breakpoint``  |
+|            | is stored in the script itself. This makes it persistent across different machines when using version control.|
 +------------+---------------------------------------------------------------------------------------------------------------+
 | preload    | Preloads a class or variable. See `Classes as resources`_.                                                    |
 +------------+---------------------------------------------------------------------------------------------------------------+

tutorials/scripting/resources.rst

@@ -206,7 +206,7 @@ Let's see some examples.
     export(Resource) var sub_resource
     export(Array, String) var strings
 
-    # Make sure that every parameter has a default value. 
+    # Make sure that every parameter has a default value.
     # Otherwise, there will be problems with creating and editing
     # your resource via the inspector.
     func _init(p_health = 0, p_sub_resource = null, p_strings = []):
@@ -230,7 +230,7 @@ Let's see some examples.
         using Godot;
 
         namespace ExampleProject {
-            public class BotStats : Resource
+            public partial class BotStats : Resource
             {
                 [Export]
                 public int Health { get; set; }
@@ -239,16 +239,20 @@ Let's see some examples.
                 public Resource SubResource { get; set; }
 
                 [Export]
-                public String[] Strings { get; set; }
+                public string[] Strings { get; set; }
 
-                // Make sure that every parameter has a default value. 
-                // Otherwise, there will be problems with creating and editing
-                // your resource via the inspector.
-                public BotStats(int health = 0, Resource subResource = null, String[] strings = null)
+                // Make sure you provide a parameterless constructor.
+                // In C#, a parameterless constructor is different from a
+                // constructor with all default values.
+                // Without a parameterless constructor, Godot will have problems
+                // creating and editing your resource via the inspector.
+                public BotStats() : this(0, null, null) {}
+
+                public BotStats(int health, Resource subResource, string[] strings)
                 {
                     Health = health;
                     SubResource = subResource;
-                    Strings = strings ?? new String[0];
+                    Strings = strings ?? Array.Empty<string>();
                 }
             }
         }
@@ -304,7 +308,7 @@ Let's see some examples.
         using System;
         using Godot;
 
-        public class BotStatsTable : Resource
+        public partial class BotStatsTable : Resource
         {
             private Godot.Dictionary<String, BotStats> _stats = new Godot.Dictionary<String, BotStats>();
 
@@ -357,9 +361,9 @@ Let's see some examples.
         using System;
         using Godot;
 
-        public class MyNode : Node
+        public partial class MyNode : Node
         {
-            public class MyResource : Resource
+            public partial class MyResource : Resource
             {
                 [Export]
                 public int Value { get; set; } = 5;

tutorials/shaders/shader_reference/shading_language.rst

@@ -380,7 +380,14 @@ Godot can't protect you from this, so be careful not to make this mistake!
 Discarding
 ----------
 
-Fragment and light functions can use the **discard** keyword. If used, the fragment is discarded and nothing is written.
+Fragment and light functions can use the ``discard`` keyword. If used, the
+fragment is discarded and nothing is written.
+
+Beware that ``discard`` has a performance cost when used, as it will prevent the
+depth prepass from being effective on any surfaces using the shader. Also, a
+discarded pixel still needs to be rendered in the vertex shader, which means a
+shader that uses ``discard`` on all of its pixels is still more expensive to
+render compared to not rendering any object in the first place.
 
 Functions
 ---------
@@ -400,8 +407,9 @@ It is possible to define functions in a Godot shader. They use the following syn
     }
 
 
-You can only use functions that have been defined above (higher in the editor) the function from which you are calling
-them.
+You can only use functions that have been defined above (higher in the editor)
+the function from which you are calling them. Redefining a function that has
+already been defined above (or is a built-in function name) will cause an error.
 
 Function arguments can have special qualifiers:
 
@@ -417,6 +425,14 @@ Example below:
         result = a + b;
     }
 
+.. note::
+
+    Unlike GLSL, Godot's shader language does **not** support function
+    overloading. This means that a function cannot be defined several times with
+    different argument types or numbers of arguments. As a workaround, use
+    different names for functions that accept a different number of arguments or
+    arguments of different types.
+
 Varyings
 ~~~~~~~~
 

tutorials/shaders/your_first_shader/your_second_3d_shader.rst

@@ -141,7 +141,7 @@ watery effect.
 
 .. image:: img/rim.png
 
-In order to add fresnal reflectance, we will compute a fresnel term in our
+In order to add fresnel reflectance, we will compute a fresnel term in our
 fragment shader. Here, we aren't going to use a real fresnel term for
 performance reasons. Instead, we'll approximate it using the dot product of the
 ``NORMAL`` and ``VIEW`` vectors. The ``NORMAL`` vector points away from the