Merge pull request #9345 from mhilbrunner/4.2-cherrypicks-part-two

4.2 cherrypicks

README.md

@@ -54,7 +54,7 @@ Here are some quick links to the areas you might be interested in:
 
 ## License
 
-At the exception of the `classes/` folder, all the content of this repository is licensed under the Creative Commons Attribution 3.0 Unported license ([CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)) and is to be attributed to "Juan Linietsky, Ariel Manzur and the Godot community".
+With the exception of the `classes/` folder, all the content of this repository is licensed under the Creative Commons Attribution 3.0 Unported license ([CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)) and is to be attributed to "Juan Linietsky, Ariel Manzur and the Godot community".
 See [LICENSE.txt](/LICENSE.txt) for details.
 
 The files in the `classes/` folder are derived from [Godot's main source repository](https://github.com/godotengine/godot) and are distributed under the MIT license, with the same authors as above.

_static/css/custom.css

@@ -533,6 +533,14 @@ html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(
 html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .k {
     font-style: normal;
 }
+html.writer-html5 .rst-content dl:not(.docutils) > dt, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt {
+    border-top-color: var(--highlight-background-emph-color);
+    background: var(--highlight-background-color);
+}
+html.writer-html5 .rst-content dl:not(.docutils) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt, html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) dl:not(.option-list):not(.field-list):not(.footnote):not(.citation):not(.glossary):not(.simple) > dt {
+    border-left-color: var(--highlight-background-emph-color);
+    background: var(--highlight-background-color);
+}
 html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-param,
 html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).class dt > .optional ~ em,
 html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple).function dt > .optional ~ em,

_tools/redirects/README.md

@@ -17,21 +17,21 @@ For more information on the scripts themselves, see their help output.
 To install requirements: `pip3 install -r requirements.txt`.
 Git is also required and needs to be available in the `PATH`.
 To interact with the Read the Docs API, a valid API key must be set as
-`RTD_AUTH_TOKEN` (either as a environment variable or in a [.env file](https://pypi.org/project/python-dotenv/)).
+`RTD_AUTH_TOKEN` (either as an environment variable or in a [.env file](https://pypi.org/project/python-dotenv/)).
 
 ## Usage
 
-Lets say we recently renamed some files in the Git branch `3.4` (compared to the `stable` branch), and now we want to create redirects for these.
+Let's say we recently renamed some files in the Git branch `3.4` (compared to the `stable` branch), and now we want to create redirects for these.
 For this, we would (after setting up the API token and requirements, see Setup above):
 
 > python convert_git_renames_to_csv.py stable 3.4
 
-This should output a list of the redirects to create. Lets append these to the redirects file:
+This should output a list of the redirects to create. Let's append these to the redirects file:
 
 > python convert_git_renames_to_csv.py stable 3.4 >> redirects.csv
 
-After this, redirects for renamed files should have been appended to `redirects.csv`. You may want to double check that!
-Now lets submit these to ReadTheDocs and create redirects there:
+After this, redirects for renamed files should have been appended to `redirects.csv`. You may want to double-check that!
+Now let's submit these to ReadTheDocs and create redirects there:
 
 > python create_redirects.py
 

contributing/development/compiling/compiling_for_windows.rst

@@ -132,7 +132,9 @@ Running SCons
 ~~~~~~~~~~~~~
 
 After opening a command prompt, change to the root directory of
-the engine source code (using ``cd``) and type::
+the engine source code (using ``cd``) and type:
+
+.. code-block:: doscon
 
     C:\godot> scons platform=windows
 
@@ -268,7 +270,9 @@ Creating Windows export templates
 ---------------------------------
 
 Windows export templates are created by compiling Godot without the editor,
-with the following flags::
+with the following flags:
+
+.. code-block:: doscon
 
     C:\godot> scons platform=windows target=template_debug arch=x86_32
     C:\godot> scons platform=windows target=template_release arch=x86_32
@@ -277,7 +281,9 @@ with the following flags::
 
 If you plan on replacing the standard export templates, copy these to the
 following location, replacing ``<version>`` with the version identifier
-(such as ``3.1.1.stable`` or ``3.2.dev``)::
+(such as ``3.1.1.stable`` or ``3.2.dev``):
+
+.. code-block:: none
 
     %USERPROFILE%\AppData\Roaming\Godot\templates\<version>\
 

contributing/development/compiling/introduction_to_the_buildsystem.rst

@@ -93,7 +93,9 @@ generally with this naming convention::
 
     godot.<platform>.<target>[.dev][.double].<arch>[.<extra_suffix>][.<ext>]
 
-For the previous build attempt, the result would look like this::
+For the previous build attempt, the result would look like this:
+
+.. code-block:: console
 
     ls bin
     bin/godot.linuxbsd.editor.x86_64
@@ -103,7 +105,7 @@ whole editor compiled in, and is meant for 64 bits.
 
 A Windows binary with the same configuration will look like this:
 
-.. code-block:: console
+.. code-block:: doscon
 
     C:\godot> dir bin/
     godot.windows.editor.64.exe

contributing/development/core_and_modules/2d_coordinate_systems.rst

@@ -141,5 +141,5 @@ effects of each of them.
 - **SubViewportContainer shrink transform**
     :ref:`stretch <class_SubViewportContainer_property_stretch>` together with
     :ref:`stretch_shrink <class_SubViewportContainer_property_stretch_shrink>` declare for a
-    *SubViewportContaner* if and by what integer factor the contained *SubViewport* should be
+    *SubViewportContainer* if and by what integer factor the contained *SubViewport* should be
     scaled in comparison to the container's size.

contributing/documentation/contributing_to_the_documentation.rst

@@ -139,7 +139,7 @@ Write your titles like plain sentences, without capitalizing each word:
 -  **Good:** Understanding signals in Godot
 -  **Bad:** Understanding Signals In Godot
 
-Only propers nouns, projects, people, and node class names should have their
+Only proper nouns, projects, people, and node class names should have their
 first letter capitalized.
 
 Sphinx and reStructuredText syntax

contributing/documentation/docs_image_guidelines.rst

@@ -43,7 +43,7 @@ editing, such as precise cropping or adding outlines, Squoosh can be used.
 `Squoosh <https://squoosh.app/>`_ is a converter developed by Google, is open
 source, and doesn't give Google any image rights by using it. When choosing
 compression if you can get an image that's under 300KB in size use lossless
-compression. If it's over 300KB use just enough lossy compression to get it
+compression. If it's over 300KB, use just enough lossy compression to get it
 under that size. If this results in noticable compression artifacts using less
 compression is fine, even if the file size is bigger.
 
@@ -107,7 +107,7 @@ means the image will not lose detail and will be as small as possible.
 
 If the image is over 300KB in size try compressing it losslessly using `Squoosh <https://squoosh.app/>`_.
 If it's still over 300KB change to lossy compression and slowly increase the compression until it's under
-300KB. If this results in noticable compression artifacts using less compression is fine, even if the file
+300KB. If this results in noticeable compression artifacts using less compression is fine, even if the file
 size is bigger.
 
 Outlines arrows and text

contributing/workflow/bug_triage_guidelines.rst

@@ -165,7 +165,7 @@ use the following labels:
 -  *Discussion*: the issue is not consensual and needs further
    discussion to define what exactly should be done to address the
    topic.
--  *Enhancememnt*: new information to be added in an existing page.
+-  *Enhancement*: new information to be added in an existing page.
 -  *Good first issue*: the issue is *assumed* to be an easy one to fix, which makes
    it a great fit for new contributors who want to become familiar with
    the code base. It should be removed while an active PR is available, that

contributing/workflow/testing_pull_requests.rst

@@ -61,7 +61,7 @@ to generate a universal download link.
 .. image:: img/testing_pull_requests_access_fork.png
 
 - Now that you are on the fork's branch page, click the ``.github`` folder at the top of the file list.
-  Then, click on the ``workflows`` folder (whicb is inside the ``.github`` folder).
+  Then, click on the ``workflows`` folder (which is inside the ``.github`` folder).
   Click the workflow file for the platform you wish to download artifacts for.
   *After* clicking on the file (which opens the file view), copy the page URL from your browser's address bar.
 

tutorials/3d/occlusion_culling.rst

@@ -85,7 +85,7 @@ In Godot, occlusion culling works by rasterizing the scene's occluder geometry
 to a low-resolution buffer on the CPU. This is done using
 the software raytracing library `Embree <https://github.com/embree/embree>`__.
 
-The engine then uses this low-resolution buffer to test occludees'
+The engine then uses this low-resolution buffer to test the occludee's
 :abbr:`AABB (Axis-Aligned Bounding Box)` against the occluder shapes.
 The occludee's :abbr:`AABB (Axis-Aligned Bounding Box)` must be *fully occluded*
 by the occluder shape to be culled.

tutorials/3d/particles/properties.rst

@@ -19,7 +19,7 @@ value to spawn more particles at the cost of performance.
 The ``Amount Ratio`` property is the radio of particles compared to the ammount that will be emitted.
 If it's less than ``1.0`` the ammount of particles emitted through the lifetime will be the ``Ammount`` *
 ``Amount Ratio``. Changing this value while emitted doesn't affect already created particles and doesn't
-cause the particle system to restart. It's useful for making effects where the number of emitted particels
+cause the particle system to restart. It's useful for making effects where the number of emitted particles
 varies over time.
 
 You can set another particle node as a ``Sub Emitter``, which will be spawned as a child of each

tutorials/3d/visibility_ranges.rst

@@ -111,7 +111,7 @@ choose from:
 - **Disabled:** Uses hysteresis to switch between LOD levels instantly. This
   prevents situations where LOD levels are switched back and forth quickly when
   the player moves forward and then backward at the LOD transition point. The
-  hystereis distance is determined by **Visibility Range > Begin Margin** and
+  hysteresis distance is determined by **Visibility Range > Begin Margin** and
   **Visibility Range > End Margin**. This mode provides the best performance as
   it doesn't force rendering to become transparent during the fade transition.
 - **Self:** Uses alpha blending to smoothly fade between LOD levels. The node

tutorials/assets_pipeline/escn_exporter/animation.rst

@@ -62,7 +62,7 @@ Animation Mode
 ---------------------------
 Godot and Blender have different structure to store animation data.
 In Godot animation data is stored in an AnimationPlayer node, instead
-of in each animated node. In order to fix this inconsistence and still
+of in each animated node. In order to fix this inconsistency and still
 make the animation play versatile, this add-on has three animation exporting
 modes.
 

tutorials/best_practices/scene_organization.rst

@@ -231,7 +231,7 @@ in another context without any extra changes to its API.
   satisfied? Other programmers, and especially designers and writers, will need
   clear instructions in the messages telling them what to do to configure it.
 
-So, why does all this complex switcharoo work? Well, because scenes operate
+So, why does all this complex switcheroo work? Well, because scenes operate
 best when they operate alone. If unable to work alone, then working with
 others anonymously (with minimal hard dependencies, i.e. loose coupling)
 is the next best thing. Inevitably, changes may need to be made to a class and

tutorials/navigation/navigation_different_actor_locomotion.rst

@@ -14,8 +14,8 @@ or crawling actors so they can find paths through those narrow sections in your
 When an actor changes locomotion state, e.g. stands up, starts 
 crouching or crawling, query the appropriate map for a path.
 
-If the avoidance behavior should also change with the locomotion e.g. only avoid while standing or only avoid 
-other agents in the same locomotion state, switch the actors's avoidance agent to another avoidance map with each locomotion change.
+If the avoidance behavior should also change with the locomotion e.g. only avoid while standing or only avoid
+other agents in the same locomotion state, switch the actor's avoidance agent to another avoidance map with each locomotion change.
 
 .. tabs::
  .. code-tab:: gdscript GDScript

tutorials/navigation/navigation_introduction_2d.rst

@@ -94,7 +94,7 @@ It uses the NavigationServer2D and a NavigationAgent2D for path movement.
 
    .. image:: img/nav_2d_min_setup_step1.png
 
-#. Define the moveable navigation area with the NavigationPolygon draw tool. Then click
+#. Define the movable navigation area with the NavigationPolygon draw tool. Then click
    the `Bake NavigationPolygon`` button on the toolbar.
 
    .. image:: img/nav_2d_min_setup_step2.png

tutorials/navigation/navigation_using_navigationobstacles.rst

@@ -49,8 +49,8 @@ Ideally when an obstacle is moving the static vertices are removed and instead t
 Similar to agents the obstacles can make use of the ``avoidance_layers`` bitmask.
 All agents with a matching bit on their own avoidance mask will avoid the obstacle.
 
-Procedual obstacles
-~~~~~~~~~~~~~~~~~~~
+Procedural obstacles
+~~~~~~~~~~~~~~~~~~~~
 
 New obstacles can be created without a Node directly on the NavigationServer.
 

tutorials/navigation/navigation_using_navigationpathqueryobjects.rst

@@ -17,7 +17,7 @@ for the query and a ``NavigationPathQueryResult`` that receives (regular) update
 :ref:`NavigationPathQueryParameters3D<class_NavigationPathQueryParameters3D>` respectively.
 
 2D and 3D versions of ``NavigationPathQueryResult`` are available as
-:ref:`NavigationPathQuerResult2D<class_NavigationPathQueryResult2D>` and
+:ref:`NavigationPathQueryResult2D<class_NavigationPathQueryResult2D>` and
 :ref:`NavigationPathQueryResult3D<class_NavigationPathQueryResult3D>` respectively.
 
 Both parameters and result are used as a pair with the ``NavigationServer.query_path()`` function.

tutorials/physics/large_world_coordinates.rst

@@ -51,7 +51,7 @@ This is the range where individual integer values can be represented in a
 floating-point number:
 
 - **Single-precision float range (represent all integers):** Between -16,777,216 and 16,777,216
-- **Double-precision float range (represent all integers):** Between -9 quadrillon and 9 quadrillon
+- **Double-precision float range (represent all integers):** Between -9 quadrillion and 9 quadrillion
 
 +----------------------+-----------------------+-----------------------+-----------------------------------------------------------------------------+
 | Range                | Single step           | Double step           | Comment                                                                     |

tutorials/platform/android/android_plugin.rst

@@ -312,7 +312,7 @@ Using a v2 Android plugin as an Android library
 
 Since they are also Android libraries, Godot v2 Android plugins can be stripped from their ``EditorExportPlugin`` packaging and provided as raw ``AAR`` binaries for use as libraries alongside the :ref:`Godot Android library <doc_android_library>` by Android apps.
 
-If targetting this use-case, make sure to include additional instructions for how the ``AAR`` binaries should be included (e.g: custom additions to the Android app's manifest).
+If targeting this use-case, make sure to include additional instructions for how the ``AAR`` binaries should be included (e.g: custom additions to the Android app's manifest).
 
 Reference implementations
 -------------------------

tutorials/rendering/jitter_stutter.rst

@@ -167,7 +167,7 @@ default ``60``, or set ``Engine.physics_ticks_per_second`` at run-time in a
 script. Values that are a multiple of the monitor refresh rate (typically
 ``60``) work best when physics interpolation is disabled, as they will avoid
 jitter. This means values such as ``120``, ``180`` and ``240`` are good starting
-points. As a bonus, higher physics FPSes make tunneling and physics unstability
+points. As a bonus, higher physics FPSes make tunneling and physics instability
 issues less likely to occur.
 
 The downside of increasing physics FPS is that CPU usage will increase, which

tutorials/rendering/multiple_resolutions.rst

@@ -72,6 +72,14 @@ that are different from this base size. Godot offers many ways to
 control how the viewport will be resized and stretched to different
 screen sizes.
 
+.. note::
+
+   On this page, *window* refers to the screen area allotted to your game
+   by the system, while *viewport* refers to the root object (accessible
+   from ``get_tree().root``) which the game controls to fill this screen area.
+   This viewport is a :ref:`Window <class_Window>` instance. Recall from the
+   :ref:`introduction <doc_viewports>` that *all* Window objects are viewports.
+
 To configure the stretch base size at runtime from a script, use the
 ``get_tree().root.content_scale_size`` property (see
 :ref:`Window.content_scale_size <class_Window_property_content_scale_size>`).
@@ -469,18 +477,34 @@ Non-game application
 hiDPI support
 -------------
 
-By default, Godot projects aren't considered DPI-aware by the operating system.
-This is done to improve performance on low-end systems, since the operating
-system's DPI fallback scaling will be faster than letting the application scale
-itself (even when using the ``viewport`` stretch mode).
+By default, Godot projects are considered DPI-aware by the operating system.
+This is controlled by the **Display > Window > Dpi > Allow Hidpi** project setting,
+which should be left enabled whenever possible. Disabling DPI awareness can break
+fullscreen behavior on Windows.
 
-However, the OS-provided DPI fallback scaling doesn't play well with fullscreen
-mode. If you want crisp visuals on hiDPI displays or if project uses fullscreen,
-it's recommended to enable **Display > Window > Dpi > Allow Hidpi** in the
-Project Settings.
+Since Godot projects are DPI-aware, they may appear at a very small window size
+when launching on an hiDPI display (proportionally to the screen resolution).
+For a game, the most common way to work around this issue is to make them
+fullscreen by default. Alternatively, you could set the window size in an
+:ref:`autoload <doc_singletons_autoload>`'s ``_ready()`` function according to
+the screen size.
 
-**Allow Hidpi** is only effective on Windows and macOS. It's ignored on all
-other platforms.
+To ensure 2D elements don't appear too small on hiDPI displays:
+
+- For games, use the ``canvas_items`` or ``viewport`` stretch modes so that 2D
+  elements are automatically resized according to the current window size.
+- For non-game applications, use the ``disabled`` stretch mode and set the
+  stretch scale to a value corresponding to the display scale factor in an
+  :ref:`autoload <doc_singletons_autoload>`'s ``_ready()`` function.
+  The display scale factor is set in the operating system's settings and can be queried
+  using :ref:`screen_get_scale<class_DisplayServer_method_screen_get_scale>`. This
+  method is currently only implemented on macOS. On other operating systems, you
+  will need to implement a method to guess the display scale factor based on the
+  screen resolution (with a setting to let the user override this if needed). This
+  is the approach currently used by the Godot editor.
+
+The **Allow Hidpi** setting is only effective on Windows and macOS. It's ignored
+on all other platforms.
 
 .. note::
 

tutorials/scripting/creating_script_templates.rst

@@ -33,9 +33,11 @@ templates are determined per each OS:
 -  Linux: ``$HOME/.config/godot/script_templates/``
 -  macOS: ``$HOME/Library/Application Support/Godot/script_templates/``
 
-If no ``script_templates`` is detected, Godot will create a default set of
-built-in templates automatically, so this logic can be used to reset the default
-templates in case you've accidentally overwritten them.
+If you're getting Godot from somewhere other than the official website, such
+as Steam, the folder might be in a different location. You can find it using
+the Godot editor. Go to ``Editor > Open Editor Data/Settings Folder`` and it
+will open a folder in your file browser, inside that folder is the
+``script_templates`` folder.
 
 Project-defined templates
 ~~~~~~~~~~~~~~~~~~~~~~~~~

tutorials/xr/xr_action_map.rst

@@ -201,7 +201,7 @@ OpenXR defines a number of bindable input poses that are commonly available for
 There are no rules for which poses are supported for different controllers.
 The poses OpenXR currently defines are:
 
-  * The aim pose on most controllers is positioned slightly infront of the controller and aims forward.
+  * The aim pose on most controllers is positioned slightly in front of the controller and aims forward.
     This is a great pose to use for laser pointers or to align the muzzle of a weapon with.
   * The grip pose on most controllers is positioned where the grip button is placed on the controller.
     The orientation of this pose differs between controllers and can differ for the same controller on different XR runtimes.