Merge branch 'master' into 3.2

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,6 @@
+blank_issues_enabled: false
+
+contact_links:
+  - name: Godot community channels
+    url: https://godotengine.org/community
+    about: Please ask for technical support on one of the other community channels, not here.

.github/ISSUE_TEMPLATE/support_question.md

@@ -1,18 +0,0 @@
----
-name: Support question
-about: Asking a question about the engine or something not working
-title: 'IMPORTANT: This repository does not accept support questions.'
-labels: archived
-assignees: ''
----
-
-**IMPORTANT, PLEASE READ**
-
-Support questions are not accepted on this repository.
-Please use one of the other community channels instead, such as Discord:
-
-https://godotengine.org/community
-
-Do not submit to this repository or your issue will be closed.
-
-**IMPORTANT, PLEASE READ**

README.md

@@ -4,6 +4,17 @@ This repository contains the source files of [Godot Engine](https://godotengine.
 
 They are meant to be parsed with the [Sphinx](https://www.sphinx-doc.org/) documentation builder to build the HTML documentation on [Godot's website](https://docs.godotengine.org).
 
+## Theming
+
+The Godot documentation uses the default ``sphinx_rtd_theme`` with many
+[customizations](_static/) applied on top. It will automatically switch between
+the light and dark theme depending on your browser/OS' theming preference.
+
+If you use Firefox and wish to use the dark theme regardless of your OS
+configuration, you can install the
+[Dark Website Forcer](https://addons.mozilla.org/en-US/firefox/addon/dark-mode-website-switcher/)
+add-on.
+
 ## Contributing changes
 
 **Pull Requests should use the `master` branch by default. Only make Pull Requests against other branches (e.g. `2.1` or `3.0`) if your changes only apply to that specific version of Godot.**

_static/css/custom.css

@@ -30,6 +30,7 @@
     --link-color-hover: #3091d1;
     --link-color-active: #105078;
     --link-color-visited: #9b59b6;
+    --external-reference-icon: url("data:image/svg+xml;base64,PHN2ZyBoZWlnaHQ9IjEyIiB3aWR0aD0iMTIiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGcgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMjk4MGI5Ij48cGF0aCBkPSJtNy41IDcuMXYzLjRoLTZ2LTZoMy40Ii8+PHBhdGggZD0ibTUuNzY1IDFoNS4yMzV2NS4zOWwtMS41NzMgMS41NDctMS4zMS0xLjMxLTIuNzI0IDIuNzIzLTIuNjktMi42ODggMi44MS0yLjgwOC0xLjMxMy0xLjMxeiIvPjwvZz48L3N2Zz4K");
 
     --hr-color: #e1e4e5;
     --table-row-odd-background-color: #f3f6f6;
@@ -115,6 +116,7 @@
         --link-color-hover: #9df;
         --link-color-active: #6ad;
         --link-color-visited: #cb99f6;
+        --external-reference-icon: url("data:image/svg+xml;base64,PHN2ZyBoZWlnaHQ9IjEyIiB3aWR0aD0iMTIiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGcgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjOGNmIj48cGF0aCBkPSJtNy41IDcuMXYzLjRoLTZ2LTZoMy40Ii8+PHBhdGggZD0ibTUuNzY1IDFoNS4yMzV2NS4zOWwtMS41NzMgMS41NDctMS4zMS0xLjMxLTIuNzI0IDIuNzIzLTIuNjktMi42ODggMi44MS0yLjgwOC0xLjMxMy0xLjMxeiIvPjwvZz48L3N2Zz4K");
 
         --hr-color: #555;
         --table-row-odd-background-color: #3b3e41;
@@ -267,6 +269,14 @@ a.btn:hover {
     text-decoration: none;
 }
 
+/* Style external links differently to make them easier to distinguish from internal links. */
+.reference.external {
+    background-position: center right;
+    background-repeat: no-repeat;
+    background-image: var(--external-reference-icon);
+    padding-right: 13px;
+}
+
 hr,
 #search-results .search li:first-child,
 #search-results .search li {

development/compiling/optimizing_for_size.rst

@@ -17,6 +17,13 @@ This tutorial aims to give an overview on different methods to create
 a smaller binary. Before continuing, it is recommended to read the previous tutorials
 on compiling Godot for each platform.
 
+.. seealso::
+
+    You can use the online
+    `Godot build options generator <https://godot-build-options-generator.github.io/>`__
+    to generate a ``custom.py`` file containing SCons options.
+    You can then save this file and place it at the root of your Godot source directory.
+
 Disabling 3D
 ------------
 
@@ -34,7 +41,7 @@ Disabling advanced GUI nodes
 ----------------------------
 
 Most small games don't require complex GUI controls such as Tree, ItemList,
-TextEditor or GraphEdit. They can be disabled using a build flag:
+TextEdit or GraphEdit. They can be disabled using a build flag:
 
 ::
 
@@ -70,7 +77,7 @@ following:
 .. code-block:: python
 
     # custom.py
-    
+
     module_arkit_enabled = "no"
     module_assimp_enabled = "no"
     module_bmp_enabled = "no"
@@ -104,7 +111,7 @@ following:
     module_webrtc_enabled = "no"
     module_websocket_enabled = "no"
     module_xatlas_unwrap_enabled = "no"
-    
+
 .. seealso::
 
     :ref:`doc_overriding_build_options`.

getting_started/scripting/c_sharp/c_sharp_basics.rst

@@ -56,15 +56,15 @@ Windows (JetBrains Rider)
 JetBrains Rider comes with bundled MSBuild, so nothing extra is required.
 Make sure to set the following preferences:
 
-- In Godot:
+- In Godot's Editor Settings:
 
-   - Mono External Editor to JetBrains Rider
-   - Mono Build Tool to JetBrains Mono.
+   - Set **Mono External Editor** to **JetBrains Rider**.
+   - set **Mono Build Tool** to **JetBrains Mono**.
 
 - In Rider:
 
-   - Set ``MSBuild version`` to either bundled with Rider or .NET Core.
-   - Install **Godot support** plugin.
+   - Set **MSBuild version** to either **Bundled with Rider** or **.NET Core**.
+   - Install the **Godot support** plugin.
 
 macOS and Linux
 ~~~~~~~~~~~~~~~
@@ -110,19 +110,23 @@ external editors:
 - Visual Studio for Mac
 - JetBrains Rider
 
-.. note:: If you are using Visual Studio Code, ensure you download and install
-          the `C# extension <https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp>`_
-          to enable features like syntax highlighting and IntelliSense.
+.. note::
+
+    If you are using Visual Studio Code, ensure you download and install the
+    `C# extension <https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp>`_
+    to enable features like syntax highlighting and IntelliSense.
 
+.. note::
 
-.. note:: If you are using Visual Studio 2019, you must follow the instructions found in the "Configure VS2019 for Debugging" section below.
+    If you are using Visual Studio 2019, you must follow the instructions found
+    in the `:ref:doc_c_sharp_configuring_vs_2019_for_debugging` section below.
 
 
 Creating a C# script
 --------------------
 
 After you successfully set up C# for Godot, you should see the following option
-when selecting ``Attach script`` in the context menu of a node in your scene:
+when selecting **Attach Script** in the context menu of a node in your scene:
 
 .. image:: img/attachcsharpscript.png
 
@@ -195,6 +199,16 @@ In general, the C# Godot API strives to be as idiomatic as is reasonably possibl
 
 For more information, see the :ref:`doc_c_sharp_differences` page.
 
+.. warning::
+
+    You need to (re)build the project assemblies whenever you want to see new
+    exported variables or signals in the editor. This build can be manually
+    triggered by clicking the word **Mono** at the bottom of the editor window
+    to reveal the Mono panel, then clicking the **Build Project** button.
+
+    You will also need to rebuild the project assemblies to apply changes in
+    "tool" scripts.
+
 Current gotchas and known issues
 --------------------------------
 
@@ -267,6 +281,8 @@ Profiling your C# code
 - `Mono log profiler <https://www.mono-project.com/docs/debug+profile/profile/profiler/>`_ is available for Linux and macOS. Due to a Mono change, it does not work on Windows currently.
 - External Mono profiler like `JetBrains dotTrace <https://www.jetbrains.com/profiler/>`_ can be used as described `here <https://github.com/godotengine/godot/pull/34382>`_.
 
+.. _doc_c_sharp_configuring_vs_2019_for_debugging:
+
 Configuring VS 2019 for debugging
 ---------------------------------
 

getting_started/scripting/c_sharp/c_sharp_differences.rst

@@ -121,7 +121,7 @@ This attribute should be used on a `delegate`, whose name signature will be used
     [Signal]
     delegate void MySignal(string willSendsAString);
 
-See also: :ref:`c_sharp_signals`
+See also: :ref:`doc_c_sharp_signals`.
 
 Singletons
 ----------

getting_started/scripting/c_sharp/c_sharp_features.rst

@@ -78,7 +78,7 @@ otherwise it returns true.
 
 For more advanced type checking, you can look into `Pattern Matching <https://docs.microsoft.com/en-us/dotnet/csharp/pattern-matching>`_.
 
-.. _c_sharp_signals:
+.. _doc_c_sharp_signals:
 
 C# signals
 ----------

getting_started/scripting/gdscript/gdscript_basics.rst

@@ -1315,7 +1315,7 @@ If a class inherits from :ref:`class_Reference`, then instances will be
 freed when no longer in use. No garbage collector exists, just
 reference counting. By default, all classes that don't define
 inheritance extend **Reference**. If this is not desired, then a class
-must inherit :ref:`class_Object` manually and must call instance.free(). To
+must inherit :ref:`class_Object` manually and must call ``instance.free()``. To
 avoid reference cycles that can't be freed, a ``weakref`` function is
 provided for creating weak references.
 

getting_started/scripting/gdscript/gdscript_exports.rst

@@ -179,7 +179,7 @@ from the FileSystem dock at once.
 
     # Exported arrays can specify type (using the same hints as before).
 
-    export(Array, int) var ints = [1,2,3]
+    export(Array, int) var ints = [1, 2, 3]
     export(Array, int, "Red", "Green", "Blue") var enums = [2, 1, 0]
     export(Array, Array, float) var two_dimensional = [[1.0, 2.0], [3.0, 4.0]]
 

getting_started/scripting/gdscript/gdscript_styleguide.rst

@@ -640,7 +640,7 @@ Start with the ``_init()`` callback method, that the engine will call upon
 creating the object in memory. Follow with the ``_ready()`` callback, that Godot
 calls when it adds a node to the scene tree.
 
-These function should come first because they show how the object is
+These functions should come first because they show how the object is
 initialized.
 
 Other built-in virtual callbacks, like ``_unhandled_input()`` and

getting_started/scripting/gdscript/static_typing.rst

@@ -248,7 +248,7 @@ Typed or dynamic: stick to one style
 ------------------------------------
 
 Typed GDScript and dynamic GDScript can coexist in the same project. But
-I recommended to stick to either style for consistency in your codebase,
+I recommend to stick to either style for consistency in your codebase,
 and for your peers. It's easier for everyone to work together if you
 follow the same guidelines, and faster to read and understand other
 people's code.

getting_started/step_by_step/intro_to_the_editor_interface.rst

@@ -7,6 +7,8 @@ This tutorial will run you through Godot's interface. We're going to
 look at the **Project Manager, docks, workspaces** and everything you
 need to know to get started with the engine.
 
+You can `download Godot Engine here <https://godotengine.org/download/>`_.
+
 Project manager
 ---------------
 

getting_started/step_by_step/scenes_and_nodes.rst

@@ -97,7 +97,7 @@ empty scene, as the "root" node).
     In an empty scene (without root node), the scene dock shows several
     options to quickly add a root node to the scene. "2D Scene" adds a
     Node2D node, "3D Scene" adds a Spatial node, "User Interface" adds a
-    Control node, and "Custom Node" which lets you select any node (so it
+    Control node, and "Other Node" which lets you select any node (so it
     is equivalent to pressing the "Add Child Node" button). You can also
     press the star-shaped icon to toggle the display of your favorited
     nodes.
@@ -107,7 +107,7 @@ empty scene, as the "root" node).
     node as its root node, likewise not every GUI or 2D scene needs a Control
     node or Node2D as their root node.
 
-Now, to add a label node to this scene you can click on the Custom Node
+Now, to add a label node to this scene you can click on the Other Node
 button or the Add Node button at the top. In scenes that aren't empty you
 use the add node button to create every child node.
 

getting_started/step_by_step/scripting.rst

@@ -97,9 +97,9 @@ demonstrate:
 - Hooking up UI elements via signals.
 - Writing a script that can access other nodes in the scene.
 
-Before continuing, please make sure to read the :ref:`GDScript<doc_gdscript>` reference.
-It's a language designed to be simple, and the reference is short, so it will not take more
-than a few minutes to get an overview of the concepts.
+Before continuing, make sure to skim and bookmark the :ref:`GDScript<doc_gdscript>` reference.
+It's a language designed to be simple, and the reference is structured into sections to make it
+easier to get an overview of the concepts.
 
 Scene setup
 ~~~~~~~~~~~

getting_started/step_by_step/singletons_autoload.rst

@@ -20,33 +20,42 @@ own limitations:
    that require it, but frequently saving and loading data is cumbersome and
    may be slow.
 
-The `Singleton Pattern <https://en.wikipedia.org/wiki/Singleton_pattern>`_ is
+The `Singleton pattern <https://en.wikipedia.org/wiki/Singleton_pattern>`_ is
 a useful tool for solving the common use case where you need to store
-persistent information between scenes. In our case it is possible re-use the
-same scene or class for multiple singletons, so long as they have different
+persistent information between scenes. In our case, it's possible to reuse the
+same scene or class for multiple singletons as long as they have different
 names.
 
 Using this concept, you can create objects that:
 
--  Are always loaded, no matter which scene is currently running
--  Can store global variables, such as player information
--  Can handle switching scenes and between-scene transitions
--  Act like a singleton, since GDScript does not support global variables by design
+- Are always loaded, no matter which scene is currently running.
+- Can store global variables such as player information.
+- Can handle switching scenes and between-scene transitions.
+- *Act* like a singleton, since GDScript does not support global variables by design.
 
 Autoloading nodes and scripts can give us these characteristics.
 
+.. note::
+
+    Godot won't make an AutoLoad a "true" singleton as per the singleton design
+    pattern. It may still be instanced more than once by the user if desired.
+
 AutoLoad
 --------
 
-You can use AutoLoad to load a scene or a script that inherits from
-:ref:`Node <class_Node>`. Note: when autoloading a script, a Node will be
-created and the script will be attached to it. This node will be added to the
-root viewport before any other scenes are loaded.
+You can create an AutoLoad to load a scene or a script that inherits from
+:ref:`class_Node`.
+
+.. note::
+
+    When autoloading a script, a :ref:`class_Node` will be created and the script will be
+    attached to it. This node will be added to the root viewport before any
+    other scenes are loaded.
 
 .. image:: img/singleton.png
 
-To autoload a scene or script, select ``Project -> Project Settings`` from the
-menu and switch to the "AutoLoad" tab.
+To autoload a scene or script, select **Project > Project Settings** from the
+menu and switch to the **AutoLoad** tab.
 
 .. image:: img/autoload_tab.png
 
@@ -70,8 +79,8 @@ This means that any node can access a singleton named "PlayerVariables" with:
     var playerVariables = (PlayerVariables)GetNode("/root/PlayerVariables");
     playerVariables.Health -= 10; // Instance field.
 
-If the "Enable" column is checked (default ``true``) then the singleton can simply
-be accessed directly:
+If the **Enable** column is checked (which is the default), then the singleton can
+be accessed directly without requiring ``get_node()``:
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -92,8 +101,8 @@ you'll see the autoloaded nodes appear:
 Custom scene switcher
 ---------------------
 
-This tutorial will demonstrate building a scene switcher using autoload. For
-basic scene switching, you can use the
+This tutorial will demonstrate building a scene switcher using autoloads.
+For basic scene switching, you can use the
 :ref:`SceneTree.change_scene() <class_SceneTree_method_change_scene>`
 method (see :ref:`doc_scene_tree` for details). However, if you need more
 complex behavior when changing scenes, this method provides more functionality.
@@ -109,15 +118,15 @@ scene contains a label displaying the scene name and a button with its
 Global.gd
 ~~~~~~~~~
 
-Switch to the "Script" tab and create a new script called Global.gd. Make sure
-it inherits from ``Node``:
+Switch to the **Script** tab and create a new script called ``Global.gd``.
+Make sure it inherits from ``Node``:
 
 .. image:: img/autoload_script.png
 
 The next step is to add this script to the autoLoad list. Open
-``Project > Project Settings`` from the menu, switch to the "AutoLoad" tab and
+**Project > Project Settings** from the menu, switch to the **AutoLoad** tab and
 select the script by clicking the browse button or typing its path:
-``res://Global.gd``. Press "Add" to add it to the autoload list:
+``res://Global.gd``. Press **Add** to add it to the autoload list:
 
 .. image:: img/autoload_tutorial1.png
 
@@ -125,7 +134,7 @@ Now whenever we run any scene in the project, this script will always be loaded.
 
 Returning to the script, it needs to fetch the current scene in the
 `_ready()` function. Both the current scene (the one with the button) and
-``global.gd`` are children of root, but autoloaded nodes are always first. This
+``Global.gd`` are children of root, but autoloaded nodes are always first. This
 means that the last child of root is always the loaded scene.
 
 .. tabs::
@@ -272,6 +281,13 @@ and
 Run the project and test that you can switch between scenes by pressing
 the button.
 
-Note: When scenes are small, the transition is instantaneous. However, if your
-scenes are more complex, they may take a noticeable amount of time to appear. To
-learn how to handle this, see the next tutorial: :ref:`doc_background_loading`
+.. note::
+
+    When scenes are small, the transition is instantaneous. However, if your
+    scenes are more complex, they may take a noticeable amount of time to appear.
+    To learn how to handle this, see the next tutorial: :ref:`doc_background_loading`.
+
+    Alternatively, if the loading time is relatively short (less than 3 seconds or so),
+    you can display a "loading plaque" by showing some kind of 2D element just before
+    changing the scene. You can then hide it just after the scene is changed. This can
+    be used to indicate to the player that a scene is being loaded.

getting_started/workflow/assets/importing_scenes.rst

@@ -52,7 +52,10 @@ text based format and the binary data in a separate binary file. This can be use
 changes in a text based format. The second is you need the texture files separate from the material file. If you don't need
 either of those glTF binary files are fine.
 
-.. note:: Blender does not export emissive textures with the glTF file. If your model uses one it must be brought in separately.
+.. note::
+
+    Blender does not export emissive textures with the glTF file. If your model
+    uses one, it must be brought in separately.
 
 Exporting DAE files from Blender
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -352,79 +355,103 @@ Import hints
 
 Many times, when editing a scene, there are common tasks that need to be done after exporting:
 
-* Adding collision detection to objects
-* Setting objects as navigation meshes
-* Deleting nodes that are not used in the game engine (like specific lights used for modelling)
+- Adding collision detection to objects.
+- Setting objects as navigation meshes.
+- Deleting nodes that are not used in the game engine (like specific lights used for modelling).
+
+To simplify this workflow, Godot offers several suffixes that can be added to
+the names of the objects in your 3D modelling software. When imported, Godot
+will detect suffixes in object names and will perform actions automatically.
 
-To simplify this workflow, Godot offers a few suffixes that can be added to the names of the
-objects in your 3D modelling software. When imported, Godot will detect them and perform
-actions automatically:
+.. note::
+
+    All the suffixes described below are *case-sensitive*.
 
 Remove nodes (-noimp)
 ~~~~~~~~~~~~~~~~~~~~~
 
-Node names that have this suffix will be removed at import time, no
-matter what their type is. They will not appear in the imported scene.
+Objects that have the ``-noimp`` suffix will be removed at import-time no matter
+what their type is. They will not appear in the imported scene.
 
 Create collisions (-col, -convcol, -colonly, -convcolonly)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Option "-col" will work only for Mesh nodes. If it is detected, a child
-static collision node will be added, using the same geometry as the mesh.
-
-Option "-convcol" will create a :ref:`class_convexpolygonshape` instead of a :ref:`class_concavepolygonshape`.
-
-However, it is often the case that the visual geometry is too complex or
-too un-smooth for collisions, which ends up not working well.
-
-To solve this, the "-colonly" modifier exists, which will remove the mesh upon
-import and create a :ref:`class_staticbody` collision instead.
+The option ``-col`` will work only for Mesh objects. If it is detected, a child
+static collision node will be added, using the same geometry as the mesh. This
+will create a triangle mesh collision shape, which is a slow, but accurate
+option for collision detection. This option is usually what you want for level
+geometry (but see also ``-colonly`` below).
+
+The option ``-convcol`` will create a :ref:`class_convexpolygonshape` instead of
+a :ref:`class_concavepolygonshape`. Unlike triangle meshes which can be concave,
+a convex shape can only accurately represent a shape that doesn't have any
+concave angles (a pyramid is convex, but a hollow box is concave). Due to this,
+convex collision shapes are generally not suited for level geometry. When
+representing simple enough meshes, convex collision shapes can result in better
+performance compared to a triangle collision shape. This option is ideal for
+simple or dynamic objects that require mostly-accurate collision detection.
+
+However, in both cases, the visual geometry may be too complex or not smooth
+enough for collisions. This can create physics glitches and slow down the engine
+unneccesarily.
+
+To solve this, the ``-colonly`` modifier exists. It will remove the mesh upon
+importing and will create a :ref:`class_staticbody` collision instead.
 This helps the visual mesh and actual collision to be separated.
 
-Option "-convcolonly" works in a similar way but will create a :ref:`class_convexpolygonshape` instead.
+The option ``-convcolonly`` works in a similar way, but will create a :ref:`class_convexpolygonshape` instead.
 
-Option "-colonly" can also be used with Blender's empty objects.
+The option ``-colonly`` can also be used with Blender's empty objects.
 On import, it will create a :ref:`class_staticbody` with
 a collision node as a child. The collision node will have one of a number of predefined shapes,
 depending on Blender's empty draw type:
 
 .. image:: img/3dimp_BlenderEmptyDrawTypes.png
 
--  Single arrow will create a :ref:`class_rayshape`
--  Cube will create a :ref:`class_boxshape`
--  Image will create a :ref:`class_planeshape`
--  Sphere (and the others not listed) will create a :ref:`class_sphereshape`
+-  Single arrow will create a :ref:`class_rayshape`.
+-  Cube will create a :ref:`class_boxshape`.
+-  Image will create a :ref:`class_planeshape`.
+-  Sphere (and the others not listed) will create a :ref:`class_sphereshape`.
+
+When possible, **try to use a few primitive collision shapes** instead of triangle
+mesh or convex shapes. Primitive shapes often have the best performance and
+reliability.
+
+.. note::
 
-For better visibility in Blender's editor, the user can set "X-Ray" option on collision
-empties and set some distinct color for them in User Preferences / Themes / 3D View / Empty.
+    For better visibility in Blender's editor, you can set the "X-Ray" option
+    on collision empties and set some distinct color for them in Blender's
+    **User Preferences > Themes > 3D View > Empty**.
 
 Create navigation (-navmesh)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A mesh node with this suffix will be converted to a navigation mesh. Original Mesh node will be
-removed.
+A mesh node with the ``-navmesh`` suffix will be converted to a navigation mesh.
+The original Mesh object will be removed at import-time.
 
 Create a VehicleBody (-vehicle)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A mesh node with this suffix will be imported as a child to a :ref:`VehicleBody <class_VehicleBody>` node.
+A mesh node with the ``-vehicle`` suffix will be imported as a child to a
+:ref:`class_VehicleBody` node.
 
 Create a VehicleWheel (-wheel)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A mesh node with this suffix will be imported as a child to a :ref:`VehicleWheel <class_VehicleWheel>` node.
+A mesh node with the ``-wheel`` suffix will be imported as a child to a
+:ref:`class_VehicleWheel` node.
 
 Rigid Body (-rigid)
 ~~~~~~~~~~~~~~~~~~~
 
-Creates a rigid body from this mesh.
+A mesh node with the ``-rigid`` suffix will be imported as a :ref:`class_RigidBody`.
 
 Animation loop (-loop, -cycle)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Animation clips in the COLLADA document that start or end with the token "loop" or "cycle"
-will be imported as a Godot Animation with the loop flag set. This is case-sensitive and
-does not require a hyphen.
+Animation clips in the COLLADA document that start or end with the token ``loop`` or ``cycle``
+will be imported as a Godot Animation with the loop flag set.
+**Unlike the other suffixes described above, this does not require a hyphen.**
 
-In Blender, this requires using the NLA Editor and naming the Action with the "loop" or
-"cycle" prefix or suffix.
+In Blender, this requires using the NLA Editor and naming the Action with the ``loop`` or
+``cycle`` prefix or suffix.

getting_started/workflow/export/exporting_for_dedicated_servers.rst

@@ -15,7 +15,8 @@ Platform support
 - **macOS:** :ref:`Compile a server binary from source for macOS <doc_compiling_for_osx>`.
 - **Windows:** There is no dedicated server build for Windows yet. As an alternative,
   you can use the ``--no-window`` command-line argument to prevent Godot from
-  spawning a window.
+  spawning a window. Note that even with the ``--no-window`` command-line argument,
+  you'll need to have OpenGL support available on the Windows machine.
 
 If your project uses C#, you'll have to use a Mono-enabled server binary.
 

getting_started/workflow/export/exporting_for_web.rst

@@ -17,7 +17,7 @@ in the user's browser.
                ``file://`` protocol. To get around this, use a local server.
 
                .. tip:: Python offers an easy method to start a local server.
-                        Use ``python -m http.server`` with Python 3 to serve the
+                        Use ``python -m http.server 8000 --bind 127.0.0.1`` with Python 3 to serve the
                         current working directory at ``http://localhost:8000``.
 
 .. attention:: `There are significant bugs when running HTML5 projects on iOS <https://github.com/godotengine/godot/issues/26554>`__

tutorials/3d/fps_tutorial/part_five.rst

@@ -521,7 +521,7 @@ If ``grabbed_object`` is ``null``, we want to see if we can pick up a :ref:`Rigi
 We first get the direct space state from the current :ref:`World <class_World>`. This is so we can cast a ray entirely from code, instead of having to
 use a :ref:`Raycast <class_Raycast>` node.
 
-.. note:: see :ref:`Ray-casting <doc_ray-casting>` for more information on raycasting in Godot.
+.. note:: See :ref:`Ray-casting <doc_ray-casting>` for more information on raycasting in Godot.
 
 Then we get the center of the screen by dividing the current :ref:`Viewport <class_Viewport>` size in half. We then get the ray's origin point and end point using
 ``project_ray_origin`` and ``project_ray_normal`` from the camera. If you want to know more about how these functions work, see :ref:`Ray-casting <doc_ray-casting>`.
@@ -537,6 +537,11 @@ the :ref:`RigidBody <class_RigidBody>` we collided with to ``MODE_STATIC`` so it
 Finally, we set the grabbed :ref:`RigidBody <class_RigidBody>`'s collision layer and collision mask to ``0``.
 This will make the grabbed :ref:`RigidBody <class_RigidBody>` have no collision layer or mask, which means it will not be able to collide with anything as long as we are holding it.
 
+.. note::
+
+    See :ref:`Physics introduction <doc_physics_introduction_collision_layer_code_example>`
+    for more information on Godot collision masks.
+
 ______
 
 If ``grabbed_object`` is not ``null``, then we need to throw the :ref:`RigidBody <class_RigidBody>` the player is holding.

tutorials/3d/lights_and_shadows.rst

@@ -1,7 +1,7 @@
 .. _doc_lights_and_shadows:
 
-Lights and shadows
-==================
+3D lights and shadows
+=====================
 
 Introduction
 ------------

tutorials/misc/jitter_stutter.rst

@@ -32,7 +32,7 @@ Jitter
 There can be many causes of jitter, the most typical one happens when the game *physics frequency* (usually 60 Hz) runs
 at a different resolution than the monitor refresh rate. Check whether your monitor refresh rate is different from 60 Hz.
 
-This is generally not a problem, given that refresh rates higher than 60 Hz are barely visible to the human eye, and
+This is generally not a problem, given that most monitors are 60 Hz, and
 starting with Godot 3.1, a frame timer was introduced that tries to synchronize with refresh as well as possible.
 
 Sometimes only some objects appear to jitter (character or background). This happens when they are processed in different

tutorials/misc/state_design_pattern.rst

@@ -207,10 +207,10 @@ will not change it makes sense to call this new script ``persistent_state.gd``.
 
         # Input code was placed here for tutorial purposes.
         func _process(_delta):
-        if Input.is_action_pressed("ui_left"):
-            move_left()
-        elif Input.is_action_pressed("ui_right"):
-            move_right()
+            if Input.is_action_pressed("ui_left"):
+                move_left()
+            elif Input.is_action_pressed("ui_right"):
+                move_right()
 
         func move_left():
             state.move_left()

tutorials/networking/high_level_multiplayer.rst

@@ -291,7 +291,8 @@ every peer and RPC will work great! Here is an example:
             get_node("/root/world/players").add_child(player)
 
         # Tell server (remember, server is always ID=1) that this peer is done pre-configuring.
-        rpc_id(1, "done_preconfiguring", selfPeerID)
+        # The server can call get_tree().get_rpc_sender_id() to find out who said they were done.
+        rpc_id(1, "done_preconfiguring")
 
 
 .. note:: Depending on when you execute pre_configure_game(), you may need to change any calls to ``add_child()``
@@ -314,7 +315,8 @@ When the server gets the OK from all the peers, it can tell them to start, as fo
 ::
 
     var players_done = []
-    remote func done_preconfiguring(who):
+    remote func done_preconfiguring():
+        var who = get_tree().get_rpc_sender_id()
         # Here are some checks you can do, for example
         assert(get_tree().is_network_server())
         assert(who in player_info) # Exists
@@ -326,8 +328,10 @@ When the server gets the OK from all the peers, it can tell them to start, as fo
             rpc("post_configure_game")
 
     remote func post_configure_game():
-        get_tree().set_pause(false)
-        # Game starts now!
+        # Only the server is allowed to tell a client to unpause
+        if 1 == get_tree().get_rpc_sender_id():
+            get_tree().set_pause(false)
+            # Game starts now!
 
 Synchronizing the game
 ----------------------
@@ -403,19 +407,43 @@ Example player code:
             return # Already stunned
 
         rpc("stun")
-        stun() # Stun myself, could have used remotesync keyword too.
+        
+        # Stun this player instance for myself as well; could instead have used
+        # the remotesync keyword above (in place of puppet) to achieve this.
+        stun()
 
-In the above example, a bomb explodes somewhere (likely managed by whoever is master). The bomb knows the bodies in the area, so it checks them
-and checks that they contain an ``exploded`` function.
+In the above example, a bomb explodes somewhere (likely managed by whoever is the master of this bomb-node, e.g. the host).
+The bomb knows the bodies (player nodes) in the area, so it checks that they contain an ``exploded`` method before calling it.
 
-If they do, the bomb calls ``exploded`` on it. However, the ``exploded`` method in the player has a ``master`` keyword. This means that only the player
-who is master for that instance will actually get the function.
+Recall that each peer has a complete set of instances of player nodes, one instance for each peer (including itself and the host).
+Each peer has set itself as the master of the instance corresponding to itself, and it has set a different peer as the master for
+each of the other instances.
 
-This instance, then, calls the ``stun`` method in the same instances of that same player (but in different peers), and only those which are set as puppet,
-making the player look stunned in all the peers (as well as the current, master one).
+Now, going back to the call to the ``exploded`` method, the bomb on the host has called it remotely on all bodies in the area
+that have the method. However, this method is in a player node and has a ``master`` keyword.
+
+The ``master`` keyword on the ``exploded`` method in the player node means two things for how this call is made.
+Firstly, from the perspective of the calling peer (the host), the calling peer will only attempt to remotely call the
+method on the peer that it has set as the network master of the player node in question.
+Secondly, from the perspective of the peer the host is sending the call to, the peer will only accept the call if it
+set itself as the network master of the player node with the method being called (which has the ``master`` keyword).
+This works well as long as all peers agree on who is the master of what.
+
+The above setup means that only the peer who owns the affected body will be responsible for telling all the other peers that its body
+was stunned, after being remotely instructed to do so by the host's bomb.
+The owning peer therefore (still in the ``exploded`` method) tells all the other peers that its player node was stunned.
+The peer does this by remotely calling the ``stun`` method on all instances of that player node (on the other peers).
+Because the ``stun`` method has the ``puppet`` keyword, only peers who did not set themselves as the network master of the node will
+call it (in other words, those peers are set as puppets for that node by virtue of not being the network master of it).
+
+The result of this call to ``stun`` is to make the player look stunned on the screen of all the peers, including the current
+network master peer (due to the local call to ``stun`` after ``rpc("stun")``).
+
+The master of the bomb (the host) repeats the above steps for each of the bodies in the area, such that all the instances of
+any player in the bomb area get stunned on the screens of all the peers.
 
 Note that you could also send the ``stun()`` message only to a specific player by using ``rpc_id(<id>, "exploded", bomb_owner)``.
-This may not make much sense for an area-of-effect case like the bomb, but in other cases, like single target damage.
+This may not make much sense for an area-of-effect case like the bomb, but might in other cases, like single target damage.
 
 ::
 
@@ -434,3 +462,12 @@ a dedicated server with no GPU available. See
     server. You'll have to modify them so the server isn't considered to be a
     player. You'll also have to modify the game starting mechanism so that the
     first player who joins can start the game.
+
+.. note::
+
+    The bomberman example here is largely for illustrational purposes, and does not
+    do anything on the host-side to handle the case where a peer uses a custom client
+    to cheat by for example refusing to to stun itself. In the current implementation
+    such cheating is perfectly possible because each client is the network master of
+    its own player, and the network master of a player is the one which decides whether
+    to call the I-was-stunned method (``stun``) on all of the other peers and itself.

tutorials/physics/physics_introduction.rst

@@ -95,6 +95,8 @@ it will typically be equal to ``0.01666...`` (but not always, see below).
     physics calculations, so that the game behaves correctly if you change the
     physics update rate or if the player's device can't keep up.
 
+.. _doc_physics_introduction_collision_layers_and_masks:
+
 Collision layers and masks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -123,7 +125,8 @@ be assigned in Project Settings -> Layer Names.
 
 .. image:: img/physics_layer_names.png
 
-**Example:**
+GUI example
+^^^^^^^^^^^
 
 You have four node types in your game: Walls, Player, Enemy, and Coin. Both
 Player and Enemy should collide with Walls. The Player node should detect
@@ -138,6 +141,35 @@ interact with. For example, the Player's settings would look like this:
 .. image:: img/player_collision_layers.png
 .. image:: img/player_collision_mask.png
 
+.. _doc_physics_introduction_collision_layer_code_example:
+
+Code example
+^^^^^^^^^^^^
+
+In function calls, layers are specified as a bitmask. Where a function enables
+all layers by default, the layer mask will be given as ``0x7fffffff``. Your code
+can use binary, hexadecimal, or decimal notation for layer masks, depending
+on your preference.
+
+The code equivalent of the above example where layers 1, 3 and 4 were enabled
+would be as follows::
+
+    # Example: Setting mask value for enabling layers 1, 3 and 4
+
+    # Binary - set the bit corresponding to the layers you want to enable (1, 3, and 4) to 1, set all other bits to 0.
+    # Note: Layer 20 is the first bit, layer 1 is the last. The mask for layers 4,3 and 1 is therefore
+    0b00000000000000001101
+    # (This can be shortened to 0b1101)
+
+    # Hexadecimal equivalent (1101 binary converted to hexadecimal)
+    0x000d
+    # (This value can be shortened to 0xd)
+
+    # Decimal - Add the results of 2 to the power of (layer be enabled-1).
+    # (2^(1-1)) + (2^(3-1)) + (2^(4-1)) = 1 + 4 + 8 = 13
+    pow(2, 1) + pow(2, 3) + pow(2, 4)
+
+
 Area2D
 ------
 

tutorials/physics/ragdoll_system.rst

@@ -83,4 +83,4 @@ Make sure to set up your collision layers and masks properly so the ``KinematicB
 
 .. image:: img/ragdoll_layer.png
 
-For more information, read :ref:`doc_physics_introduction`
+For more information, read :ref:`doc_physics_introduction_collision_layers_and_masks`.

tutorials/physics/ray-casting.rst

@@ -221,6 +221,7 @@ member variable:
         }
     }
 
+See :ref:`doc_physics_introduction_collision_layer_code_example` for details on how to set the collision mask.
 
 3D ray casting from screen
 --------------------------