Merge pull request #10363 from mhilbrunner/4.3-cherry-picks

4.3 cherry picks

about/list_of_features.rst

@@ -486,7 +486,7 @@ Scripting
    - Use any build system and language features you wish.
 
 - Actively developed GDExtension bindings for `D <https://github.com/godot-dlang/godot-dlang>`__,
-  `Haxe <https://hxgodot.github.io/>`__, `Swift <https://github.com/migueldeicaza/SwiftGodot>`__, and `Rust <https://github.com/godot-rust/gdextension>`__
+  `Swift <https://github.com/migueldeicaza/SwiftGodot>`__, and `Rust <https://github.com/godot-rust/gdextension>`__
   bindings provided by the community. (Some of these bindings may be experimental and not production-ready).
 
 Audio

conf.py

@@ -170,6 +170,11 @@ html_theme_options = {
     "logo_only": True,
     # Collapse navigation (False makes it tree-like)
     "collapse_navigation": False,
+    # Remove version and language picker beneath the title
+    "version_selector": False,
+    "language_selector": False,
+    # Set Flyout menu to attached
+    "flyout_display": "attached",
 }
 
 html_title = supported_languages[language] % ( "(" + version + ")" )

tutorials/2d/2d_antialiasing.rst

@@ -77,8 +77,8 @@ affect** the following kinds of aliasing in any way:
 - Aliasing in font rendering.
 
 MSAA can be enabled in the Project Settings by changing the value of the
-**Rendering > Anti Aliasing > Quality > MSAA 2D** setting. It's important to change
-the value of the **MSAA 2D** setting and not **MSAA 3D**, as these are entirely
+:ref:`Rendering > Anti Aliasing > Quality > MSAA 2D<class_ProjectSettings_property_rendering/anti_aliasing/quality/msaa_2d>`
+setting. It's important to change the value of the **MSAA 2D** setting and not **MSAA 3D**, as these are entirely
 separate settings.
 
 Comparison between no antialiasing (left) and various MSAA levels (right). The

tutorials/2d/2d_parallax.rst

@@ -78,8 +78,11 @@ do?
 Make the viewport smaller
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The simplest answer is to make the viewport the same size or smaller than your textures. Click on
-``Project -> Project Settings -> Window`` and change the viewport height and width to match your background.
+The simplest answer is to make the viewport the same size or smaller than your textures. 
+In **Project Settings > Display > Window**, change the
+:ref:`Viewport Width<class_ProjectSettings_property_display/window/size/viewport_width>`
+and :ref:`Viewport Height<class_ProjectSettings_property_display/window/size/viewport_height>`
+settings to match your background.
 
 .. image:: img/2d_parallax_size_viewport.webp
 

tutorials/2d/custom_drawing_in_2d.rst

@@ -254,9 +254,9 @@ You will have to code a function to perform this and draw it yourself.
 
     The following instructions use a fixed set of coordinates that could be too small
     for high resolution screens (larger than 1080p). If that is your case, and the
-    drawing is too small consider increasing your window scale in
-    ``Menu > Project > Project settings > display/window/stretch/scale`` to adjust
-    the project to a higher resolution (a 2 or 4 scale tends to work well).
+    drawing is too small consider increasing your window scale in the project setting
+    :ref:`Display > Window > Stretch > Scale<class_ProjectSettings_property_display/window/stretch/scale>`
+    to adjust the project to a higher resolution (a 2 or 4 scale tends to work well).
 
 Drawing a custom polygon shape
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

tutorials/2d/index.rst

@@ -7,6 +7,7 @@
    :maxdepth: 1
    :name: toc-learn-features-2d
 
+   introduction_to_2d
    canvas_layers
    2d_transforms
 

tutorials/2d/introduction_to_2d.rst

@@ -0,0 +1,316 @@
+.. _doc_introduction_to_2d:
+
+Introduction to 2D
+==================
+
+Godot's 2D game development tools include a dedicated 2D rendering engine, physics system, 
+and features tailored specifically for creating 2D experiences. You can efficiently design 
+levels with the TileMap system, animate characters with 2D sprite or Cutout animation, 
+and leverage 2D lighting for dynamic scene illumination. The built-in 2D particle system 
+allows you to create complex visual effects, and Godot also supports custom shaders to 
+enhance your graphics. These features, combined with Godot's accessibility and 
+flexibility, provide a solid foundation for creating engaging 2D games.
+
+.. figure:: img/2d_platformer_demo.webp
+   
+   2D Platformer Demo available on the Asset Library.
+
+This page will show you the 2D workspace and how you can get to know it.
+
+.. tip:: If you would like to get an introduction to 3D, see :ref:`doc_introduction_to_3d`.
+
+2D workspace
+~~~~~~~~~~~~
+
+You will use the 2D workspace to work with 2D scenes, design levels, or create user 
+interfaces.
+To switch to the 2D workspace, you can either select a 2D node from the scene tree, 
+or use the workspace selector located at the top edge of the editor:
+
+.. image:: img/2d_editor_viewport.webp
+
+Similar to 3D, you can use the tabs below the workspace selector to change between currently 
+opened scenes or create a new one using the plus (+) button. The left and right docks should 
+be familiar from :ref:`editor introduction <toc-editor-interface>`.
+
+Below the scene selector is the main toolbar, and beneath the main toolbar
+is the 2D viewport.
+
+You can drag and drop compatible nodes from the FileSystem dock to add them to the 
+viewport as nodes.
+Dragging and dropping adds the dragged node as a sibling of the selected node 
+(if the root node is selected, adds as a child).
+Keeping :kbd:`Shift` pressed when dropping adds the node as a child of the selected node.
+Holding :kbd:`Alt` when dropping adds the node as a child of the root node.
+If :kbd:`Alt + Shift` is held when dropping, the node type can be selected if 
+applicable.
+
+
+Main toolbar
+------------
+
+Some buttons in the main toolbar are the same as those in the 3D workspace. A brief explanation
+is given with the shortcut if the mouse cursor is hovered over a button for one second. 
+Some buttons may have additional functionality if another keypress is performed. 
+A recap of main functionality of each button with its default shortcut is provided below 
+from left to right:
+
+.. image:: img/2d_toolbar.webp
+
+- **Select Mode** (:kbd:`Q`): Allows selection of nodes in the viewport. Left clicking on a node 
+  in the viewport selects it.
+  Left clicking and dragging a rectangle selects all nodes within the rectangle's boundaries,
+  once released.
+  Holding :kbd:`Shift` while selecting adds more nodes to the selection.
+  Clicking on a selected node while holding :kbd:`Shift` deselects the node.
+  In this mode, you can drag the selected node(s) to move, press :kbd:`Ctrl` to switch to the 
+  rotation mode temporarily, or use the red circles to scale it. If multiple nodes are 
+  selected, only movement and rotation are possible. In this mode, rotation and scaling 
+  will not use the snapping options if snapping is enabled.
+- **Move Mode** (:kbd:`W`): Enables move (or translate) mode for the selected nodes. See 
+  :ref:`doc_introduction_to_2d_the_viewport` for more details.
+- **Rotate Mode** (:kbd:`E`): Enables rotation mode for the selected nodes. See 
+  :ref:`doc_introduction_to_2d_the_viewport` for more details.
+- **Scale Mode** (:kbd:`R`): Enables scaling and displays scaling gizmos in both 
+  axes for the selected node(s). See :ref:`doc_introduction_to_2d_the_viewport` for more details.
+- **Show list of selectable nodes at position clicked**: As the description suggests, 
+  this provides a list of selectable nodes at the clicked position as a context menu, if 
+  there is more than one node in the clicked area.
+- **Rotation pivot**: Sets the rotation pivot to rotate node(s) around.
+  An added node has its rotation pivot at ``x: 0``, ``y: 0``, by default, with
+  exceptions. For example, the default pivot for a :ref:`Sprite2D <class_Sprite2D>` is its 
+  center if the ``centered`` property is set to ``true``. If you would like to change the 
+  rotation pivot of a node, click this button and choose a new location by left clicking. 
+  The node rotates considering this point. If you have multiple nodes selected, this icon 
+  will add a temporary pivot to be used commonly by all selected nodes. Pressing :kbd:`Shift` 
+  and clicking this button will create the pivot at the center of selected nodes. If any of 
+  the snap options are enabled, the pivot will also snap to them it when dragged.
+- **Pan Mode** (:kbd:`G`): Allows you to navigate in the viewport without accidentally selecting any nodes.
+  In other modes, you can also hold :kbd:`Space` and drag with the left mouse button to do the same.
+- **Ruler Mode**: After enabling, click on the viewport to display the current global 
+  x and y coordinates. Dragging from a position to another one measures the distance in pixels.
+  If you drag diagonally, it will draw a triangle and show the separate distances in terms 
+  of x, y, and total distance to the target, including the angles to the axes in degrees.
+  The :kbd:`R` key also activates the ruler. If snapping is enabled, it also displays the 
+  measurements in terms of grid count:
+
+.. figure:: img/2d_ruler_with_snap.webp
+   
+   Using ruler with snapping enabled.
+
+- **Use Smart Snap**: Toggles smart snapping for move, rotate, and scale modes; and 
+  the rotation pivot. Customize it using the three-dot menu next to the snap tools.
+- **Use Grid Snap**: Toggles snapping to grid for move and scale mode, rotation pivot, 
+  and the ruler. Customize it using the three-dot menu next to the snap tools.
+
+You can customize the grid settings so that move mode, rotate mode, scale mode, ruler, 
+and rotation pivot uses snapping.
+Use the three-dot menu for this:
+
+.. image:: img/2d_snapping_options_menu.webp
+
+- **Use Rotation Snap**: Toggles snapping using the configured rotation setting.
+- **Use Scale Snap**: Toggles snapping using the configured scaling step setting.
+- **Snap Relative**: Toggles the usage of snapping based on the selected node's current 
+  transform values. For example, if the grids are set to 32x32 pixels and if the selected node 
+  is located at ``x: 1, y: 1``, then, enabling this option will temporarily shift the grids by 
+  ``x: 1, y: 1``.
+- **Use Pixel Snap**: Toggles the use of subpixels for snapping. If enabled, the position values 
+  will be integers, disabling will enable subpixel movement as decimal values. For the runtime 
+  property, consider checking `Project Settings > Rendering > 2D > Snapping` property for 
+  Node2D nodes, and `Project Settings > GUI > General > Snap Controls to Pixels` for 
+  Control nodes.
+- **Smart Snapping**: Provides a set of options to snap to specific positions if they are enabled:
+
+  - Snap to Parent: Snaps to parent's edges. For example, scaling a child control node while 
+    this is enabled will snap to the boundaries of the parent.
+  - Snap to Node Anchor: Snaps to the node's anchor. For example, if anchors of a control 
+    node is positioned at different positions, enabling this will snap to the sides and 
+    corners of the anchor.
+  - Snap to Node Sides: Snaps to the node's sides, such as for the rotation pivot or anchor 
+    positioning.
+  - Snap to Node Center: Snaps to the node's center, such as for the rotation pivot or 
+    anchor positioning.
+  - Snap to Other Nodes: Snaps to other nodes while moving or scaling. Useful to align nodes 
+    in the editor.
+  - Snap to Guides: Snaps to custom guides drawn using the horizontal or vertical ruler. More 
+    on the ruler and guides below.
+
+.. image:: img/2d_snapping_options.webp
+
+- **Configure Snap**: Opens the window shown above, offering a set of snapping parameters.
+
+  - Grid Offset: Allows you to shift grids with respect to the origin. ``x`` and ``y`` can 
+    be adjusted separately.
+  - Grid Step: The distance between each grid in pixels. ``x`` and ``y`` can be adjusted separately.
+  - Primary Line Every: The number of grids in-between to draw infinite lines as indication of 
+    main lines.
+  - Rotation Offset: Sets the offset to shift rotational snapping.
+  - Rotation Step: Defines the snapping degree. E.g., 15 means the node will rotate and snap 
+    at multiples of 15 degrees if rotation snap is enabled and the rotate mode is used.
+  - Scale Step: Determines the scaling increment factor. For example, if it is 0.1, it will 
+    change the scaling at 0.1 steps if scaling snap is enabled and the scaling mode is used.
+
+- **Lock selected nodes** (:kbd:`Ctrl + L`). Locks the selected nodes, preventing selection and movement in the 
+  viewport. Clicking the button again (or using :kbd:`Ctrl + Shift + L`) unlocks the selected 
+  nodes. Locked nodes can only be selected in the scene tree.
+  They can easily be identified by a padlock next to their node names in the scene tree. 
+  Clicking on this padlock also unlocks the nodes.
+- **Group selected nodes** (:kbd:`Ctrl + G`). This allows selection of the root node if any 
+  of the children are selected. Using :kbd:`Ctrl + G` ungroups them. Additionally, clicking 
+  the ungroup button in the scene tree performs the same action.
+- **Skeleton Options**: Provides options to work with Skeleton2D and Bone2D.
+
+  - Show Bones: Toggles the visibility of bones for the selected node.
+  - Make Bone2D Node(s) from Node(s): Converts selected node(s) into Bone2D. 
+
+.. seealso:: To learn more about Skeletons, see :ref:`doc_cutout_animation`.
+
+- **Project Camera Override**: Temporarily replaces the active camera in the level 
+  (e.g., the camera following the player) with the camera in the editor's viewport, allowing
+  you to move freely and inspect the level's different parts, while the game is running.
+  
+- **View** menu: Provides options to control the viewport view. Since its options 
+  depend heavily on the viewport, it is covered in the :ref:`doc_introduction_to_2d_the_viewport` 
+  section.
+
+Next to the View menu, additional buttons may be visible. In the toolbar image
+at the beginning of this chapter, an additional *Sprite2D* button appears because a
+Sprite2D is selected. This menu provides some quick actions and tools to
+work on a specific node or selection. For example, while drawing a polygon, it
+provides buttons to add, modify, or remove points.
+
+
+Coordinate system
+-----------------
+
+In the 2D editor, unlike 3D, there are only two axes: ``x`` and ``y``. Also, the viewing 
+angle is fixed.
+
+In the viewport, you will see two lines in two colors going across the screen infinitely: 
+red for the x-axis, and green for the y-axis.
+In Godot, going right and down are positive directions.
+Where these two lines intersect is the origin: ``x: 0, y: 0``.
+
+A root node will have its origin at this position once added.
+Switching to the `move` or `scale` modes after selecting a node will display the gizmos at the 
+node's offset position.
+The gizmos will point to the positive directions of the x and y axes.
+In the move mode, you can drag the green line to move only in the ``y`` axis.
+Similarly, you can hold the red line to move only in the ``x`` axis.
+
+In the scale mode, the gizmos will have a square shape. You can hold and drag the green and 
+red squares to scale the nodes in the ``y`` or ``x`` axes.
+Dragging in a negative direction flips the node horizontally or vertically.
+
+.. _doc_introduction_to_2d_the_viewport:
+
+2D Viewport
+-----------
+
+The viewport will be the area you spend the most time if you plan to design levels or user 
+interfaces visually:
+
+.. image:: img/2d_editor_viewport_with_viewmenu.webp
+
+Middle-clicking and dragging the mouse will pan the view. 
+The scrollbars on the right or bottom of the viewport also move the view.
+Alternatively, the :kbd:`G` or :kbd:`Space` keys can be used.
+If you enable `Editor Settings > Editors > Panning > Simple Panning`, you can activate
+panning directly with :kbd:`Space` only, without requiring dragging.
+
+The viewport has buttons on the top-left.
+**Center View** centers the selected node(s) in the screen. Useful if you have a large scene 
+with many nodes, and want to see the node selected in the scene tree.
+Next to it are the zoom controls. **-** zooms out, **+** zooms in, and clicking on the number 
+with percentage defaults to 100%.
+Alternatively, you can use middle-mouse scrolling to zoom in (scroll up) and out (scroll down).
+
+The black bars at the viewport's left and top edges are the **rulers**. You can use them to 
+orient yourself in the viewport.
+By default, the rulers will display the pixel coordinates of the viewport, numbered at 
+100 pixel steps. Changing the zoom factor will change the shown values.
+Enabling `Grid Snap` or changing the snapping options will update the ruler's scaling and 
+the shown values.
+
+You can also create multiple custom guides to help you make measurements or align 
+nodes with them:
+
+.. image:: img/2d_editor_guidelines.webp
+
+If you have at least one node in the scene, you can create guides by dragging from the horizontal 
+or vertical ruler towards the viewport. A purple guide will appear, showing its position, and will 
+remain there when you release the mouse. You can create both horizontal and vertical guides 
+simultaneously by dragging from the gray square at the rulers' intersection. Guides can be 
+repositioned by dragging them back to their respective rulers, and they can be removed by 
+dragging them all the way back to the ruler.
+
+You can also enable snapping to the created guides using the `Smart Snap` menu.
+
+.. note:: If you cannot create a line, or do not see previously created guides, make sure that 
+          they are visible by checking the `View` menu of the viewport. :kbd:`Y` toggles their visibility, 
+          by default. Also, make sure you have at least one node in the scene.
+
+Depending on the tool chosen in the toolbar, left-clicking will have a primary action in the 
+viewport.
+For example, the `Select Mode` will select the left-clicked node in the viewport.
+Sometimes, left-clicking can be combined with a modifier (e.g., :kbd:`Ctrl`, or :kbd:`Shift`) to 
+perform secondary actions.
+For example, keeping :kbd:`Shift` pressed while dragging a node in the Select or Move modes will 
+try to snap the node in a single axis while moving.
+
+Right clicking in the viewport provides two options to create a node or instantiate a scene 
+at the chosen position.
+If at least one node is selected, right clicking also provides the option to move the selected 
+node(s) to this position.
+
+
+Viewport has a **View** menu which provides several options to change the look of the viewport:
+
+- **Grid**: Allows you to show grids all the time, only when using snapping, or not at all. You 
+  can also toggle them with the provided option.
+- **Show Helpers**: Toggles the temporary display of an outline of the node, with the previous 
+  transform properties (position, scaling, or rotation) if a transform operation has been 
+  initiated. For `Control` nodes, it also shows the sizing parameters. Useful to see the deltas.
+- **Show Rulers**: Toggles the visibility of horizontal and vertical rulers. See 
+  :ref:`doc_introduction_to_2d_the_viewport` more on rulers.
+- **Show Guides**: Toggles the visibility of created guides. See 
+  :ref:`doc_introduction_to_2d_the_viewport` for on how to create them.
+- **Show Origin**: Toggles the display of the green and red origin lines drawn at ``x: 0, y: 0``.
+- **Show Viewport**: Toggles the visibility of the game's default 
+  viewport, indicated by an indigo-colored rectangle. It is also the default window size on desktop 
+  platforms, which can be changed by going to `Project Settings > Display > Window > Size` and 
+  setting `Viewport Width` and `Viewport Height`.
+- **Gizmos**: Toggles the visibility of `Position` (shown with cross icon), `Lock` 
+  (shown with padlock), `Groups` (shown with two squares), and `Transformation` (shown with 
+  green and red lines) indicators.
+- **Center Selection**: The same as the **Center View** button inside the viewport. Centers the selected 
+  node(s) in the view. :kbd:`F` is the default shortcut.
+- **Frame to Selection**: Similar to `Center Selection`, but also changes the zoom factor to fit the 
+  contents in the screen. :kbd:`Shift + F` is the default shortcut.
+- **Clear Guides**: Deletes all guides from the screen. You will need to recreate them if 
+  you plan to use them later. 
+- **Preview Canvas Scale**: Toggles the preview for scaling of canvas in the editor when the zoom 
+  factor or view of the viewport changes. Useful to see how the controls will look like after scaling 
+  and moving, without running the game.
+- **Preview Theme**: Allows to choose from the available themes to change the look of control items 
+  in the editor, without requiring to run the game.
+
+
+Node2D and Control node
+~~~~~~~~~~~~~~~~~~~~~~~
+
+:ref:`CanvasItem <class_CanvasItem>` is the base node for 2D. :ref:`Node2D <class_Node2D>` is the base node
+for 2D game objects, and :ref:`Control <class_Control>` is the base node 
+for everything GUI. For 3D, Godot uses the :ref:`Node3D <class_Node3D>` node.
+
+3D in 2D
+--------
+
+It is possible to display 3D scenes in 2D screen. This is achieved by adding a 
+:ref:`SubViewport <class_SubViewport>` as a child.
+Then, you can drag a 3D scene as a child of the SubViewport:
+
+.. image:: img/3d_in_2d_demo_editor.webp
+
+.. seealso:: You can check the demo on: `3D in 2D Viewport demo <https://godotengine.org/asset-library/asset/2804>`__.

tutorials/2d/using_tilesets.rst

@@ -168,7 +168,7 @@ sounds), particle effects, and more.
    Scene tiles come with a greater performance overhead compared to atlases, as
    every scene is instanced individually for every placed tile.
 
-   It's recommended to use only scene tiles when necessary. To draw sprites in a
+   It's recommended to only use scene tiles when necessary. To draw sprites in a
    tile without any kind of advanced manipulation,
    :ref:`use atlases instead <doc_creating_tilesets_using_tilesheet>`.
 
@@ -257,7 +257,7 @@ TileSet resource, choose **Merge (Keep Original Atlases)** instead.
 Adding collision, navigation and occlusion to the TileSet
 ---------------------------------------------------------
 
-We've now successfully created a basic TileSet. We could start using in the
+We've now successfully created a basic TileSet. We could start using it in the
 TileMapLayer node now, but it currently lacks any form of collision detection.
 This means the player and other objects could walk straight through the floor or
 walls.
@@ -436,7 +436,7 @@ corners or edges of platforms, floors, etc. While these can be placed manually,
 this quickly becomes tedious. Handling this situation with procedurally
 generated levels can also be difficult and require a lot of code.
 
-Godot offers *terrains* to perform this kind of tile connections automatically.
+Godot offers *terrains* to perform this kind of tile connection automatically.
 This allows you to have the "correct" tile variants automatically used.
 
 Terrains are grouped into terrain sets. Each terrain set is assigned a mode from

tutorials/3d/3d_antialiasing.rst

@@ -65,8 +65,8 @@ moderate performance cost, but it's effective at reducing aliasing on
 transparent materials without introducing any blurriness.
 
 MSAA can be enabled in the Project Settings by changing the value of the
-**Rendering > Anti Aliasing > Quality > MSAA 3D** setting. It's important to change
-the value of the **MSAA 3D** setting and not **MSAA 2D**, as these are entirely
+:ref:`Rendering > Anti Aliasing > Quality > MSAA 3D<class_ProjectSettings_property_rendering/anti_aliasing/quality/msaa_3d>`
+setting. It's important to change the value of the **MSAA 3D** setting and not **MSAA 2D**, as these are entirely
 separate settings.
 
 Comparison between no antialiasing (left) and various MSAA levels (right).
@@ -103,8 +103,9 @@ downside of TAA is that it can exhibit *ghosting* artifacts behind moving
 objects. Rendering at a higher framerate will allow TAA to converge faster,
 therefore making those ghosting artifacts less visible.
 
-Temporal antialiasing can be enabled in the Project Settings by changing the
-value of the **Rendering > Anti Aliasing > Quality > Use TAA** setting.
+Temporal antialiasing can be enabled in the Project Settings by changing the value of the
+:ref:`Rendering > Anti Aliasing > Quality > TAA<class_ProjectSettings_property_rendering/anti_aliasing/quality/use_taa>`
+setting.
 
 Comparison between no antialiasing (left) and TAA (right):
 
@@ -164,9 +165,9 @@ as an in-game option may still be worthwhile for players with low-end GPUs.
 FXAA introduces a moderate amount of blur when enabled (more than TAA when
 still, but less than TAA when the camera is moving).
 
-FXAA can be enabled in the Project Settings by changing the
-value of the **Rendering > Anti Aliasing > Quality > Screen Space AA** setting to
-**FXAA**.
+FXAA can be enabled in the Project Settings by changing the value of the
+:ref:`Rendering > Anti Aliasing > Quality > Screen Space AA<class_ProjectSettings_property_rendering/anti_aliasing/quality/screen_space_aa>`
+setting to ``FXAA``.
 
 Comparison between no antialiasing (left) and FXAA (right):
 
@@ -187,9 +188,11 @@ The downside of SSAA is its *extremely* high cost. This cost generally makes
 SSAA difficult to use for game purposes, but you may still find supersampling
 useful for :ref:`offline rendering <doc_creating_movies>`.
 
-Supersample antialiasing is performed by increasing the **Rendering > Scaling 3D
-> Scale** advanced project setting above ``1.0`` while ensuring
-**Rendering > Scaling 3D > Mode** is set to **Bilinear** (the default).
+Supersample antialiasing is performed by increasing the
+:ref:`Rendering > Scaling 3D > Scale<class_ProjectSettings_property_rendering/scaling_3d/scale>`
+advanced project setting above ``1.0`` while ensuring
+:ref:`Rendering > Scaling 3D > Mode<class_ProjectSettings_property_rendering/scaling_3d/mode>`
+is set to ``Bilinear`` (the default).
 Since the scale factor is defined per-axis, a scale factor of ``1.5`` will result
 in 2.25× SSAA while a scale factor of ``2.0`` will result in 4× SSAA. Since Godot
 uses the hardware's own bilinear filtering to perform the downsampling, the result

tutorials/3d/3d_rendering_limitations.rst

@@ -46,8 +46,9 @@ rendering, where banding may be visible when using smooth gradient textures.
 
 There are two main ways to alleviate banding:
 
-- If using the Forward+ or Forward Mobile rendering methods, enable **Use
-  Debanding** in the advanced Project Settings. This applies a fullscreen debanding
+- If using the Forward+ or Forward Mobile rendering methods, enable 
+  :ref:`Use Debanding<class_ProjectSettings_property_rendering/anti_aliasing/quality/use_debanding>`
+  in **Project Settings > Rendering > Anti Aliasing**. This applies a fullscreen debanding
   shader as a post-processing effect and is very cheap.
 - Alternatively, bake some noise into your textures. This is mainly effective in
   2D, e.g. for vignetting effects. In 3D, you can also use a `custom debanding

tutorials/3d/environment_and_post_processing.rst

@@ -653,7 +653,8 @@ There are 2 ways to use glow in 2D:
   rendering output.
 
   - To enable HDR in 2D, open the Project Settings, enable
-    **Rendering > Viewport > HDR 2D** then restart the editor.
+    :ref:`Rendering > Viewport > HDR 2D<class_ProjectSettings_property_rendering/viewport/hdr_2d>`
+    then restart the editor.
 
 - If you want to maximize performance, you can leave HDR disabled for 2D
   rendering. However, you will have less control on which objects glow.
@@ -676,10 +677,10 @@ There are 2 ways to use glow in 2D:
 .. warning::
 
     The 2D renderer renders in linear color space if the
-    **Rendering > Viewport > HDR 2D** project setting is enabled, so
-    ``source_color`` must also be used for uniform samplers that are
-    used as color input in ``canvas_item`` shaders. If this is not done,
-    the texture will appear washed out.
+    :ref:`Rendering > Viewport > HDR 2D<class_ProjectSettings_property_rendering/viewport/hdr_2d>`
+    project setting is enabled, so the ``source_color`` hint must also be used
+    for uniform samplers that are used as color input in ``canvas_item`` shaders.
+    If this is not done, the texture will appear washed out.
 
     If 2D HDR is disabled, ``source_color`` will keep working correctly in
     ``canvas_item`` shaders, so it's recommend to use it when relevant either

tutorials/3d/global_illumination/reflection_probes.rst

@@ -187,9 +187,9 @@ reflection probe rendering. As many reflection probes as desired can be added (a
 performance allows). However, there's still a default limit of 512 *clustered
 elements* that can be present in the current camera view. A clustered element is
 an omni light, a spot light, a :ref:`decal <doc_using_decals>` or a
-:ref:`reflection probe <doc_reflection_probes>`. This limit can be increased by
-adjusting the **Rendering > Limits > Cluster Builder > Max Clustered Elements**
-advanced project setting.
+:ref:`reflection probe <doc_reflection_probes>`. This limit can be increased by adjusting
+:ref:`Max Clustered Elements<class_ProjectSettings_property_rendering/limits/cluster_builder/max_clustered_elements>`
+in **Project Settings > Rendering > Limits > Cluster Builder**.
 
 When using the Forward Mobile backend, only 8 reflection probes can be applied on each
 individual Mesh *resource*. If there are more reflection probes affecting a single mesh,

tutorials/3d/lights_and_shadows.rst

@@ -61,9 +61,9 @@ real-time lighting. As many lights as desired can be added (as long as
 performance allows). However, there's still a default limit of 512 *clustered
 elements* that can be present in the current camera view. A clustered element is
 an omni light, a spot light, a :ref:`decal <doc_using_decals>` or a
-:ref:`reflection probe <doc_reflection_probes>`. This limit can be increased by
-adjusting the **Rendering > Limits > Cluster Builder > Max Clustered Elements**
-advanced project setting.
+:ref:`reflection probe <doc_reflection_probes>`. This limit can be increased by adjusting
+:ref:`Max Clustered Elements<class_ProjectSettings_property_rendering/limits/cluster_builder/max_clustered_elements>`
+in **Project Settings > Rendering > Limits > Cluster Builder**.
 
 When using the Forward Mobile renderer, there is a limitation of 8 OmniLights +
 8 SpotLights per mesh resource. There is also a limit of 256 OmniLights + 256
@@ -72,10 +72,12 @@ currently cannot be changed.
 
 When using the Compatibility renderer, up to 8 OmniLights + 8 SpotLights can be
 rendered per mesh resource. This limit can be increased in the advanced Project
-Settings by adjusting **Rendering > Limits > OpenGL > Max Renderable Lights**
-and/or **Rendering > Limits > OpenGL > Max Lights Per Object** at the cost of
-performance and longer shader compilation times. The limit can also be decreased
-to reduce shader compilation times and improve performance slightly.
+Settings by adjusting
+:ref:`Max Renderable Elements<class_ProjectSettings_property_rendering/limits/opengl/max_renderable_elements>`
+and/or :ref:`Max Lights per Object<class_ProjectSettings_property_rendering/limits/opengl/max_lights_per_object>`
+in **Rendering > Limits > OpenGL**, at the cost of performance and longer shader
+compilation times. The limit can also be decreased to reduce shader compilation
+times and improve performance slightly.
 
 With all rendering methods, up to 8 DirectionalLights can be visible at a time.
 However, each additional DirectionalLight with shadows enabled will reduce the

tutorials/3d/using_decals.rst

@@ -234,8 +234,9 @@ away from the camera (and may have little to no impact on the final scene
 rendering). Using node groups, you can also prevent non-essential decorative
 decals from spawning based on user configuration.
 
-The way decals are rendered also has an impact on performance. The **Rendering >
-Textures > Decals > Filter** advanced project setting lets you control how decal
+The way decals are rendered also has an impact on performance. The
+:ref:`Rendering > Textures > Decals > Filter<class_ProjectSettings_property_rendering/textures/decals/filter>`
+advanced project setting lets you control how decal
 textures should be filtered. **Nearest/Linear** does not use mipmaps. However,
 decals will look grainy at a distance. **Nearest/Linear Mipmaps** will look
 smoother at a distance, but decals will look blurry when viewed from oblique
@@ -262,9 +263,9 @@ decal rendering. As many decals as desired can be added (as long as
 performance allows). However, there's still a default limit of 512 *clustered
 elements* that can be present in the current camera view. A clustered element is
 an omni light, a spot light, a :ref:`decal <doc_using_decals>` or a
-:ref:`reflection probe <doc_reflection_probes>`. This limit can be increased by
-adjusting the **Rendering > Limits > Cluster Builder > Max Clustered Elements**
-advanced project setting.
+:ref:`reflection probe <doc_reflection_probes>`. This limit can be increased by adjusting
+:ref:`Max Clustered Elements<class_ProjectSettings_property_rendering/limits/cluster_builder/max_clustered_elements>`
+in **Project Settings > Rendering > Limits > Cluster Builder**.
 
 When using the Forward Mobile backend, only 8 decals can be applied on each
 individual Mesh *resource*. If there are more decals affecting a single mesh,

tutorials/audio/recording_with_microphone.rst

@@ -12,7 +12,7 @@ A simple demo is included in the official demo projects and will be used as
 support for this tutorial:
 `<https://github.com/godotengine/godot-demo-projects/tree/master/audio/mic_record>`_.
 
-You will need to enable audio input in the project settings ``Project Settings -> Audio -> Driver -> Enable Input``, or you'll just get empty audio files.
+You will need to enable audio input in the :ref:`Audio > Driver > Enable Input<class_ProjectSettings_property_audio/driver/enable_input>` project setting, or you'll just get empty audio files.
 
 The structure of the demo
 -------------------------

tutorials/performance/thread_safe_apis.rst

@@ -55,7 +55,9 @@ Rendering
 ---------
 
 Instancing nodes that render anything in 2D or 3D (such as Sprite) is *not* thread-safe by default.
-To make rendering thread-safe, set the **Rendering > Driver > Thread Model** project setting to **Multi-Threaded**.
+To make rendering thread-safe, set the
+:ref:`Rendering > Driver > Thread Model<class_ProjectSettings_property_rendering/driver/threads/thread_model>`
+project setting to **Multi-Threaded**.
 
 Note that the Multi-Threaded thread model has several known bugs, so it may not be usable
 in all scenarios.

tutorials/physics/physics_introduction.rst

@@ -132,7 +132,7 @@ These properties can be configured via code, or by editing them in the Inspector
 
 Keeping track of what you're using each layer for can be difficult, so you
 may find it useful to assign names to the layers you're using. Names can
-be assigned in Project Settings -> Layer Names.
+be assigned in **Project Settings > Layer Names**.
 
 .. image:: img/physics_layer_names.png
 
@@ -235,7 +235,7 @@ You can modify a rigid body's behavior via properties such as "Mass",
 "Friction", or "Bounce", which can be set in the Inspector.
 
 The body's behavior is also affected by the world's properties, as set in
-`Project Settings -> Physics`, or by entering an :ref:`Area2D <class_Area2D>`
+**Project Settings > Physics**, or by entering an :ref:`Area2D <class_Area2D>`
 that is overriding the global physics properties.
 
 When a rigid body is at rest and hasn't moved for a while, it goes to sleep.

tutorials/physics/troubleshooting_physics_issues.rst

@@ -27,7 +27,8 @@ other solutions you can try:
   speed. The faster the object moves, the larger the collision shape should
   extend outside of the object to ensure it can collide with thin walls more
   reliably.
-- Increase **Physics Ticks Per Second** in the advanced Project Settings. While
+- Increase :ref:`Physics Ticks per Second<class_ProjectSettings_property_physics/common/physics_ticks_per_second>`
+  in the advanced Project Settings. While
   this has other benefits (such as more stable simulation and reduced input
   lag), this increases CPU utilization and may not be viable for mobile/web
   platforms. Multipliers of the default value of ``60`` (such as ``120``, ``180``
@@ -44,7 +45,8 @@ causes the simulation to become wobbly, making the objects unable to rest on top
 of each other without moving.
 
 Increasing the physics simulation rate can help alleviate this issue. To do so,
-increase **Physics Ticks Per Second** in the advanced Project Settings. Note
+increase :ref:`Physics Ticks per Second<class_ProjectSettings_property_physics/common/physics_ticks_per_second>`
+in the advanced Project Settings. Note
 that increases CPU utilization and may not be viable for mobile/web platforms.
 Multipliers of the default value of ``60`` (such as ``120``, ``180`` or ``240``)
 should be preferred for a smooth appearance on most displays.
@@ -83,7 +85,9 @@ simulation rate (as making the shape thicker would cause a disconnect between
 the RigidBody's visual representation and its collision).
 
 In both cases, increasing the physics simulation rate can also help alleviate
-this issue. To do so, increase **Physics Ticks Per Second** in the advanced
+this issue. To do so, increase
+:ref:`Physics Ticks per Second<class_ProjectSettings_property_physics/common/physics_ticks_per_second>`
+in the advanced
 Project Settings. Note that this increases CPU utilization and may not be viable
 for mobile/web platforms. Multipliers of the default value of ``60`` (such as
 ``120``, ``180`` or ``240``) should be preferred for a smooth appearance on most
@@ -115,7 +119,9 @@ vehicle (due to tunneling), but also that the simulation has little data to work
 with in general at such a high speed.
 
 Fast-moving vehicles can benefit a lot from an increased physics simulation
-rate. To do so, increase **Physics Ticks Per Second** in the advanced Project
+rate. To do so, increase
+:ref:`Physics Ticks per Second<class_ProjectSettings_property_physics/common/physics_ticks_per_second>`
+in the advanced Project
 Settings. Note that this increases CPU utilization and may not be viable for
 mobile/web platforms. Multipliers of the default value of ``60`` (such as
 ``120``, ``180`` or ``240``) should be preferred for a smooth appearance on most
@@ -156,6 +162,22 @@ geometry as a collider. Not only this will improve physics simulation
 performance significantly, but this can also improve stability by letting you
 remove small fixtures and crevices from being considered by collision.
 
+Framerate suddenly drops to a very low value beyond a certain amount of physics simulation
+------------------------------------------------------------------------------------------
+
+This occurs because the physics engine can't keep up with the expected
+simulation rate. In this case, the framerate will start dropping, but the engine
+is only allowed to simulate a certain number of physics steps per rendered
+frame. This snowballs into a situation where framerate keeps dropping until it
+reaches a very low framerate (typically 1-2 FPS) and is called the *physics
+spiral of death*.
+
+To avoid this, you should check for situations in your project that can cause
+excessive number of physics simulations to occur at the same time (or with
+excessively complex collision shapes). If these situations cannot be avoided,
+you can increase the **Max Physics Steps per Frame** project setting and/or
+reduce **Physics Ticks per Second** to alleviate this.
+
 Physics simulation is unreliable when far away from the world origin
 --------------------------------------------------------------------
 

tutorials/platform/android/android_library.rst

@@ -94,7 +94,10 @@ Below we break-down the steps used to create the GLTF Viewer app.
 
 - If using ``gradle``, include the following ``aaptOptions`` configuration under the ``android > defaultConfig`` section of the app's gradle build file. Doing so allows ``gradle`` to include Godot's hidden directories when building the app binary.
 
-  - If your build system does not support including hidden directories, you can `configure the Godot project to not use hidden directories <https://docs.godotengine.org/en/stable/classes/class_projectsettings.html#class-projectsettings-property-application-config-use-hidden-project-data-directory>`_ by deselecting ``Project Settings... > Application > Config > Use Hidden Project Data Directory``.
+  - If your build system does not support including hidden directories, you can
+    configure the Godot project to not use hidden directories by deselecting 
+    :ref:`Application > Config > Use Hidden Project Data Directory<class_ProjectSettings_property_application/config/use_hidden_project_data_directory>`
+    in the Project Settings.
 
 .. code-block:: groovy
 

tutorials/scripting/creating_script_templates.rst

@@ -43,9 +43,9 @@ Project-defined templates
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The default path to search for templates is the
-``res://script_templates/`` directory. The path can be changed by configuring
-the ``editor/script_templates_search_path`` setting in the
-:ref:`ProjectSettings <class_ProjectSettings>`, both via code and the editor.
+``res://script_templates/`` directory. The path can be changed by configuring the project setting
+:ref:`Editor > Script > Templates Search Path<class_ProjectSettings_property_editor/script/templates_search_path>`,
+both via code and the editor.
 
 If no ``script_templates`` directory is found within a project, it is simply
 ignored.

tutorials/ui/bbcode_in_richtextlabel.rst

@@ -812,11 +812,17 @@ Font options
 Named colors
 ~~~~~~~~~~~~
 
-For tags that allow specifying a color by name you can use names of the constants from
+For tags that allow specifying a color by name, you can use names of the constants from
 the built-in :ref:`class_Color` class. Named classes can be specified in a number of
 styles using different casings: ``DARK_RED``, ``DarkRed``, and ``darkred`` will give
 the same exact result.
 
+See this image for a list of color constants:
+
+.. image:: /img/color_constants.png
+
+`View at full size <https://raw.githubusercontent.com/godotengine/godot-docs/master/img/color_constants.png>`__
+
 .. _doc_bbcode_in_richtextlabel_hex_colors:
 
 Hexadecimal color codes

tutorials/ui/gui_skinning.rst

@@ -190,8 +190,8 @@ with a custom theme. Custom themes can be applied in two ways: as a project sett
 and as a node property throughout the tree of control nodes.
 
 There are two project settings that can be adjusted to affect your entire project:
-:ref:`gui/theme/custom<class_ProjectSettings_property_gui/theme/custom>` allows you to
-set a custom project-wide theme, and :ref:`gui/theme/custom_font<class_ProjectSettings_property_gui/theme/custom_font>`
+:ref:`GUI > Theme > Custom<class_ProjectSettings_property_gui/theme/custom>` allows you to
+set a custom project-wide theme, and :ref:`GUI > Theme > Custom Font<class_ProjectSettings_property_gui/theme/custom_font>`
 does the same to the default fallback font. When a theme item is requested by a control
 node the custom project theme, if present, is checked first. Only if it doesn't have
 the item the default theme is checked.