Merge branch 'master' into InputEventKey.keycode

.gitattributes

@@ -0,0 +1,2 @@
+# Properly detect languages on GitHub
+*.rst linguist-detectable=true

.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**

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: Continuous integration
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Install dependencies
+        run: |
+          # Install tools used by `_tools/format.sh`.
+          sudo apt-get -qq update
+          sudo apt-get -qq install dos2unix recode
+          sudo pip3 install -r requirements.txt
+          sudo pip3 install codespell
+
+      - name: Linter checks
+        run: |
+          bash _tools/format.sh
+          codespell -I _tools/codespell-ignore.txt -x _tools/codespell-ignore-lines.txt {about,community,development,getting_started,tutorials}/**/*.rst
+
+      - name: Sphinx build
+        run: |
+          # Use dummy builder to improve performance.
+          sphinx-build --color -b dummy -d _build/doctrees -W . _build/html

.readthedocs.yml

@@ -1,10 +1,27 @@
-# Reference: https://docs.readthedocs.io/en/latest/yaml-config.html
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
 
 build:
   image: latest
 
+sphinx:
+  configuration: conf.py
+
 # Possible options: htmlzip, pdf, epub
-# Disable (single) htmlzip as it's way too big to be useful,
-# and leads to excessive memory usage on build
-# Disable epub and pdf for now to speed up builds
+# All disabled for now:
+# - single-page htmlzip is too big to be usable, and requires too much memory.
+# - pdf generates too many latex warnings and the build is killed once logs
+#   reach 4 MB. Could likely be improved if someone is motivated.
+# - epub is too big, and has tons of validation errors which make most readers
+#   treat it as invalid (GH-3862). Also, it's ugly.
+# Hopefully one day we'll have a multi-page HTML zip option, but until
+# then, all offline download options are worthless.
+# (Track https://github.com/readthedocs/readthedocs.org/issues/3242)
 formats: []
+
+python:
+  install:
+    - requirements: requirements.txt

.travis.yml

@@ -1,34 +0,0 @@
-os: linux
-dist: bionic
-language: python - "3.8"
-
-env:
-  global:
-    - SPHINX_NO_GDSCRIPT=1
-    - SPHINX_NO_SEARCH=1
-    - SPHINX_NO_DESCRIPTIONS=1
-
-matrix:
-  include:
-    - name: Static checks (format.sh) + Sphinx build
-      stage: build
-      os: linux
-      addons:
-        apt:
-          packages:
-            - dos2unix
-            - recode
-
-install:
-  - pip install -r requirements.txt
-  - pip install codespell
-
-script:
-  - bash _tools/format.sh
-
-  # Check for possible typos
-  - codespell -I _tools/codespell-ignore.txt {about,community,development,getting_started,tutorials}/**/*.rst
-
-  # TODO: Add `-W` to turn warnings into errors.
-  # This can only be done once all warnings have been fixed.
-  - sphinx-build --color -b dummy -d _build/doctrees . _build/html

Makefile

@@ -13,10 +13,6 @@ ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
 $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD make variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
 endif
 
-# check for latex dependencies
-E := $(foreach exec, $(LATEXDEPS),\
-	$(if $(shell which $(exec)), some string,$(warning The $(exec) command was not found: math formulas will not be built. LaTeX is required for math formula support. If you don't have LaTeX installed, grab it from https://www.latex-project.org/get/)))
-
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter

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.**
@@ -114,6 +125,16 @@ pip install -r requirements.txt
 
 Then do `make html` like above.
 
+### Rebuilding automatically on changes
+
+To build the documentation every time you save your changes, install
+[watchexec](https://github.com/watchexec/watchexec) then run the following
+command in this directory:
+
+```sh
+watchexec make html
+```
+
 ## 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".

_extensions/godot_descriptions.py

@@ -78,6 +78,9 @@ class DescriptionGenerator:
         # Replace multiple spaces with single spaces
         desc = re.sub("\\s+", " ", desc)
 
+        # Escape double quotes for HTML
+        desc = re.sub('"', """, desc)
+
         return desc
 
     def create_description(self, cutoff_suffix="..."):

_static/css/custom.css

@@ -30,6 +30,8 @@
     --link-color-hover: #3091d1;
     --link-color-active: #105078;
     --link-color-visited: #9b59b6;
+    --external-reference-icon: url("data:image/svg+xml;base64,PHN2ZyBoZWlnaHQ9IjEyIiB3aWR0aD0iMTIiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGcgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjMjk4MGI5Ij48cGF0aCBkPSJtNy41IDcuMXYzLjRoLTZ2LTZoMy40Ii8+PHBhdGggZD0ibTUuNzY1IDFoNS4yMzV2NS4zOWwtMS41NzMgMS41NDctMS4zMS0xLjMxLTIuNzI0IDIuNzIzLTIuNjktMi42ODggMi44MS0yLjgwOC0xLjMxMy0xLjMxeiIvPjwvZz48L3N2Zz4K");
+    --classref-badge-text-color: hsl(0, 0%, 45%);
 
     --hr-color: #e1e4e5;
     --table-row-odd-background-color: #f3f6f6;
@@ -115,6 +117,8 @@
         --link-color-hover: #9df;
         --link-color-active: #6ad;
         --link-color-visited: #cb99f6;
+        --external-reference-icon: url("data:image/svg+xml;base64,PHN2ZyBoZWlnaHQ9IjEyIiB3aWR0aD0iMTIiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+PGcgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjOGNmIj48cGF0aCBkPSJtNy41IDcuMXYzLjRoLTZ2LTZoMy40Ii8+PHBhdGggZD0ibTUuNzY1IDFoNS4yMzV2NS4zOWwtMS41NzMgMS41NDctMS4zMS0xLjMxLTIuNzI0IDIuNzIzLTIuNjktMi42ODggMi44MS0yLjgwOC0xLjMxMy0xLjMxeiIvPjwvZz48L3N2Zz4K");
+        --classref-badge-text-color: hsl(0, 0%, 70%);
 
         --hr-color: #555;
         --table-row-odd-background-color: #3b3e41;
@@ -267,6 +271,40 @@ 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;
+}
+
+/* Distinguish class reference page links from "user manual" page links with a "ref" badge. */
+a[href*="classes/"]::before {
+    content: "ref";
+    color: var(--classref-badge-text-color);
+    background-color: hsla(0, 0%, 50%, 0.3);
+    font-weight: 700;
+    font-size: 80%;
+    border-radius: 9999px;
+    padding: 0.125rem 0.375rem;
+    margin-right: 0.25rem;
+}
+
+/* Prevent the "ref" badge from appearing twice in the instant search results (not testable locally). */
+.wy-body-for-nav .search__result__single a[href*="classes/"]::before {
+    display: none;
+}
+
+.wy-body-for-nav .search__result__single a[href*="classes/"]:first-child::before {
+    display: inline;
+}
+
+/* Prevent the "ref" badge from appearing several times per item in the dedicated search results page. */
+#search-results .context a[href*="classes/"]::before {
+    display: none;
+}
+
 hr,
 #search-results .search li:first-child,
 #search-results .search li {

_tools/codespell-ignore-lines.txt

@@ -0,0 +1 @@
+| te           | Telugu                             |

_tools/move_rst_files.py

@@ -0,0 +1,108 @@
+import re
+from argparse import ArgumentParser
+from os.path import isfile, isdir, join, realpath, split, dirname, relpath
+import os
+import shutil
+
+
+def parse_and_get_arguments():
+    """Creates and returns an object with parsed arguments, using argparse."""
+    parser: ArgumentParser = ArgumentParser(
+        prog="move_rst_files",
+        description="Moves reST documents and their dependencies from one folder to another. Outputs required redirections in the ReadTheDocs backend.",
+    )
+    parser.add_argument(
+        "documents", nargs="+", help="Paths of documents to move.",
+    )
+    parser.add_argument(
+        "output_path", help="Path to the target output directory.",
+    )
+    return parser.parse_args()
+
+
+def find_project_root_path(document_path):
+    """Returns the path to the repository's root directory by looking for the file conf.py, starting
+from the path of any file in the project."""
+    full_path = realpath(document_path)
+    dirpath = split(full_path)[0]
+
+    root_path = ""
+    current = dirpath
+    iterations = 0
+    while root_path == "":
+        if isfile(join(current, "conf.py")):
+            root_path = current
+        else:
+            current = split(current)[0]
+            if current == "":
+                break
+        iterations += 1
+        if iterations > 20:
+            break
+    return root_path
+
+
+def find_images(document):
+    """Returns the list of image filepaths used by the `document`."""
+    images = []
+    for line in document:
+        match = re.match(r"\.\. image::\s+(img\/.+)", line)
+        if match:
+            images.append(match[1])
+    return list(set(images))
+
+
+def find_document_dependencies(documents):
+    """For each document path in `documents`, finds all pictures it depends on and returns a dict with the form { document: [images] }."""
+    data = {}
+    for path in documents:
+        with open(path, "r") as rst_file:
+            images = find_images(rst_file)
+            data[path] = images
+    return data
+
+
+def move_documents(paths, output_path):
+    """Moves .rst files and all their image dependencies to `output_path`"""
+    data = find_document_dependencies(paths)
+    for path in data:
+        directory = dirname(path)
+        shutil.move(path, output_path)
+        for image in data[path]:
+            image_in_path = join(directory, image)
+            image_out_path = join(output_path, image)
+            image_out_dirpath = dirname(image_out_path)
+            if not isdir(image_out_dirpath):
+                os.makedirs(image_out_dirpath)
+            shutil.move(image_in_path, image_out_path)
+
+
+def print_redirects(paths):
+    """Prints redirects we need to make on the ReadTheDocs backend with the form "input -> output".
+    Moving the file /learning/features/viewports/viewports.rst to /tutorials/viewports/viewports.rst
+    Requires the following redirect:
+    /learning/features/viewports/viewports.html -> /tutorials/viewports/viewports.html
+    """
+    redirects = ""
+    project_root_path = find_project_root_path(paths[0])
+    out_path_relative = relpath(args.output_path, project_root_path)
+    for document in paths:
+        in_path_relative = relpath(document, project_root_path)
+        in_directory, filename_rst = split(in_path_relative)
+        filename_html = filename_rst.rsplit(".rst", 1)[0] + ".html"
+
+        in_path = join(in_directory, filename_html)
+        out_path = join(out_path_relative, filename_html)
+        redirects += in_path + " -> " + out_path + "\n"
+    print(redirects)
+
+
+if __name__ == "__main__":
+    args = parse_and_get_arguments()
+    assert isdir(args.output_path)
+
+    documents = [
+        path for path in args.documents if isfile(path) and path.endswith(".rst")
+    ]
+    move_documents(documents, args.output_path)
+    print_redirects(documents)

about/docs_changelog.rst

@@ -50,7 +50,7 @@ Shading
 ^^^^^^^
 
 - Your First Shader Series:
-    - :ref:`doc_what_are_shaders`
+    - :ref:`doc_introduction_to_shaders`
     - :ref:`doc_your_first_canvasitem_shader`
     - :ref:`doc_your_first_spatial_shader`
     - :ref:`doc_your_second_spatial_shader`
@@ -169,13 +169,12 @@ Viewports
 Shading
 ^^^^^^^
 
-- :ref:`doc_intro_to_shaders_water_workshop`
-- :ref:`doc_migrating_to_godot_shader_language`
+- :ref:`doc_converting_glsl_to_godot_shaders`
 - :ref:`doc_advanced_postprocessing`
 
 Shading Reference:
 
-- :ref:`doc_shaders`
+- :ref:`doc_introduction_to_shaders`
 - :ref:`doc_shading_language`
 - :ref:`doc_spatial_shader`
 - :ref:`doc_canvas_item_shader`

about/faq.rst

@@ -152,16 +152,22 @@ The main reasons for creating a custom scripting language for Godot were:
 
 GDScript was designed to curtail the issues above, and more.
 
-What type of 3D model formats does Godot support?
--------------------------------------------------
+What 3D model formats does Godot support?
+-----------------------------------------
+
+Godot supports the following formats:
 
-Godot supports Collada via the `OpenCollada <https://github.com/KhronosGroup/OpenCOLLADA/wiki/OpenCOLLADA-Tools>`_ exporter (Maya, 3DSMax).
-If you are using Blender, take a look at our own `Better Collada Exporter <https://godotengine.org/download>`_.
+- glTF 2.0 *(recommended)*
+- Collada
+- OBJ
+- FBX (static meshes only)
 
-As of Godot 3.0, glTF is supported.
+FBX support is the fruit of reverse engineering via the Open Asset Import library.
+However, FBX is proprietary so we recommend using other formats listed above,
+if suitable for your workflow.
 
-FBX is supported via the Open Asset Import library. However, FBX is proprietary
-so we recommend using other formats listed above, if suitable for your workflow.
+You can find more detailed information on supported formats, and how to export
+and import them for Godot :ref:`here <doc_importing_3d_scenes>`.
 
 Will [insert closed SDK such as FMOD, GameWorks, etc.] be supported in Godot?
 -----------------------------------------------------------------------------
@@ -183,6 +189,24 @@ free and open-source integration, consider starting the integration work yoursel
 Godot is not owned by one person; it belongs to the community, and it grows along
 with ambitious community contributors like you.
 
+Why does Godot use Vulkan or OpenGL instead of Direct3D?
+--------------------------------------------------------
+
+Godot aims for cross-platform compatibility and open standards first and
+foremost. OpenGL and Vulkan are the technologies that are both open and
+available (nearly) on all platforms. Thanks to this design decision, a project
+developed with Godot on Windows will run out of the box on Linux, macOS, and
+more.
+
+Since Godot only has a few people working on its renderer, we would prefer
+having fewer rendering backends to maintain. On top of that, using a single API
+on all platforms allows for greater consistency with fewer platform-specific
+issues.
+
+In the long term, we may develop a Direct3D 12 renderer for Godot (mainly for
+the Xbox's purposes), but Vulkan and OpenGL will remain the default rendering
+backends on all platforms, including Windows.
+
 How should assets be created to handle multiple resolutions and aspect ratios?
 ------------------------------------------------------------------------------
 
@@ -243,6 +267,12 @@ as well as the `unofficial Python support <https://github.com/touilleMan/godot-p
 This would be a good starting point to see how another third-party library
 integrates with Godot.
 
+When is the next release of Godot out?
+--------------------------------------
+
+When it's ready! See :ref:`doc_release_policy_when_is_next_release_out` for more
+information.
+
 I would like to contribute! How can I get started?
 --------------------------------------------------
 
@@ -289,6 +319,35 @@ developer experiences as a whole.
 Bonus points for bringing screenshots, concrete numbers, test cases, or example
 projects (if applicable).
 
+Is it possible to use Godot to create non-game applications?
+------------------------------------------------------------
+
+Yes! Godot features an extensive built-in UI system, and its small distribution
+size can make it a suitable alternative to frameworks like Electron or Qt.
+
+When creating a non-game application, make sure to enable
+:ref:`low-processor mode <class_ProjectSettings_property_application/run/low_processor_mode>`
+in the Project Settings to decrease CPU and GPU usage.
+
+That said, we wouldn't recommend using Godot to create a *mobile* application
+since low-processor mode isn't supported on mobile platforms yet.
+
+Check out `Material Maker <https://github.com/RodZill4/material-maker>`__ and
+`Pixelorama <https://github.com/Orama-Interactive/Pixelorama>`__ for examples of
+open source applications made with Godot.
+
+Is it possible to use Godot as a library?
+-----------------------------------------
+
+Godot is meant to be used with its editor. We recommend you give it a try, as it
+will most likely save you time in the long term. There are no plans to make
+Godot usable as a library, as it would make the rest of the engine more
+convoluted and difficult to use for casual users.
+
+If you want to use a rendering library, look into using an established rendering
+engine instead. Keep in mind rendering engines usually have smaller communities
+compared to Godot. This will make it more difficult to find answers to your
+questions.
 
 Why does Godot not use STL (Standard Template Library)
 ------------------------------------------------------

about/index.rst

@@ -7,7 +7,11 @@ About
 
    introduction
    faq
+   troubleshooting
+   list_of_features
    docs_changelog
+   release_policy
+   complying_with_licenses
 
 .. history
 .. authors

about/list_of_features.rst

@@ -0,0 +1,582 @@
+.. _doc_list_of_features:
+
+List of features
+================
+
+This page aims to list all features currently supported by Godot.
+
+.. note::
+
+    This page lists features supported by the current development version of
+    Godot (4.0.dev). Some of these features may not be available in the current
+    stable release series (3.2).
+
+Features
+--------
+
+Platforms
+^^^^^^^^^
+
+**Can run both the editor and exported projects:**
+
+- Windows 7 and later (64-bit and 32-bit).
+- macOS 10.12 and later (64-bit, x86 and ARM).
+- Linux (64-bit, x86 and ARM).
+
+   - Binaries are statically linked and can run on any distribution if compiled
+     on an old enough base distribution.
+   - Official binaries are compiled on Ubuntu 14.04.
+   - 32-bit binaries can be compiled from source.
+
+**Runs exported projects:**
+
+- Android 4.4 and later.
+- iOS 10.0 and later.
+- HTML5 via WebAssembly (Firefox, Chrome, Edge, Opera).
+- :ref:`Consoles <doc_consoles>`.
+
+Godot aims to be as platform-independent as possible and can be ported to new
+platforms with relative ease.
+
+Editor
+^^^^^^
+
+**Features:**
+
+- Scene tree editor.
+- Script editor.
+- Support for :ref:`external script editors <doc_external_editor>` such as
+  Visual Studio Code or Vim.
+- GDScript :ref:`debugger <doc_debugger_panel>`.
+
+   - No support for debugging in threads yet.
+- Visual profiler with CPU and GPU time indications.
+- Performance monitoring tools.
+- Live script reloading.
+- Live scene editing.
+
+   - Changes will reflect in the editor and will be kept after closing the running project.
+
+- Remote inspector.
+
+   - Changes won't reflect in the editor and won't be kept after closing the running project.
+
+- Live camera replication.
+
+   - Move the in-editor camera and see the result in the running project.
+
+- Use the editor in dozens of languages contributed by the community.
+
+**Plugins:**
+
+- Editor plugins can be downloaded from the
+  :ref:`asset library <doc_what_is_assetlib>` to extend editor functionality.
+- Create your own plugins using GDScript to add new features or speed up your workflow.
+- Download projects from the asset library in the project manager and import them directly.
+
+2D graphics
+^^^^^^^^^^^
+
+Vulkan renderer.
+
+- Sprite, polygon and line rendering.
+
+   - High-level tools to draw lines and polygons such as Polygon2D and Line2D.
+
+- AnimatedSprite as a helper for creating animated sprites.
+- Parallax layers.
+
+   - Pseudo-3D support by automatically duplicating a layer several times.
+
+- 2D lighting with normal maps and specular maps.
+
+   - Hard or soft shadows.
+
+- Font rendering using bitmaps (BitmapFont) or rasterization using FreeType (DynamicFont).
+
+   - Bitmap fonts can be exported using tools like BMFont.
+   - DynamicFont supports monochrome fonts as well as colored fonts.
+     Supported formats are TTF and OTF.
+   - DynamicFont supports optional font outlines with adjustable width and color.
+   - Support for font oversampling to keep fonts sharp at higher resolutions.
+
+- GPU-based particles with support for custom particle shaders.
+- CPU-based particles.
+
+2D tools
+^^^^^^^^
+
+- 2D camera with built-in smoothing and drag margins.
+- Path2D node to represent a path in 2D space.
+
+   - Can be drawn in the editor or generated procedurally.
+   - PathFollow2D node to make nodes follow a Path2D.
+
+- 2D geometry helper class.
+- Line2D node to draw textured 2D lines.
+
+2D physics
+^^^^^^^^^^
+
+**Physics bodies:**
+
+- Static bodies.
+- Rigid bodies.
+- Kinematic bodies.
+- Joints.
+- Areas to detect bodies entering or leaving it.
+
+**Collision detection:**
+
+- Built-in shapes: line, box, circle, capsule.
+- Collision polygons (can be drawn manually or generated from a sprite in the editor).
+
+3D graphics
+^^^^^^^^^^^
+
+Vulkan renderer.
+
+- HDR rendering with sRGB.
+- Perspective, orthographic and frustum-offset cameras.
+
+**Physically-based rendering:**
+
+- Follows the Disney PBR model.
+- Uses a roughness-metallic workflow with support for ORM textures.
+- Normal mapping.
+- Parallax/relief mapping with automatic level of detail based on distance.
+- Sub-surface scattering and transmittance.
+- Proximity fade (soft particles) and distance fade.
+- Distance fade can use alpha blending or dithering to avoid going through
+  the transparent pipeline.
+- Dithering can be determined on a per-pixel or per-object basis.
+
+**Real-time lighting:**
+
+- Directional lights (sun/moon). Up to 4 per scene.
+- Omnidirectional lights.
+- Spot lights with adjustable cone angle and attenuation.
+- Adjustable light "size" for fake area lights (will also make shadows blurrier).
+- Lights are rendered with clustered forward optimizations to decrease their
+  individual cost.
+
+**Shadow mapping:**
+
+- *DirectionalLight:* Orthogonal (fastest), PSSM 2-split and 4-split.
+  Supports blending between splits.
+- *OmniLight:* Dual paraboloid (fast) or cubemap (slower but more accurate).
+  Supports colored projector textures in the form of panoramas.
+- *SpotLight:* Single texture. Supports colored projector textures.
+- Shadow pancaking to decrease the amount of visible shadow acne and peter-panning.
+- PCSS-like shadow blur based on the light size and distance from the surface
+  the shadow is casted on.
+- Adjustable blur on a per-light basis.
+
+**Global illumination with indirect lighting:**
+
+- Baked lightmaps (fast, but can't be updated at run-time).
+
+   - Lightmaps are baked on the GPU using compute shaders.
+
+- GI probes (slower, fully real-time). Supports reflections.
+- Signed distance field GI (intermediate, supports dynamic lights but not
+  dynamic occluders). Supports reflections.
+- Global illumination uses a deferred pass to allow for adaptive subsampling.
+
+**Reflections:**
+
+- Voxel-based reflections (when using GI probes) and SDF-based reflections (when using signed distance field GI).
+- Fast baked reflections or slow real-time reflections using ReflectionProbe.
+  Parallax correction can optionally be enabled.
+- Screen-space reflections.
+- Reflection techniques can be mixed together for greater accuracy.
+
+**Sky:**
+
+- Panorama sky (using an HDRI).
+- Procedural sky and Physically-based sky that respond to the DirectionalLights in the scene.
+- Support for custom sky shaders.
+- Radiance can be updated in real-time depending on the quality settings chosen.
+
+**Fog:**
+
+- Depth fog (exponential or with custom attenuation).
+- Height fog (floor or ceiling) with adjustable attenuation.
+- Support for automatic depth fog color depending on the camera direction
+  (to match the sun color).
+- Optional transmittance to make lights more visible in the fog.
+
+**Particles:**
+
+- GPU-based particles with support for custom particle shaders.
+- CPU-based particles.
+
+**Post-processing:**
+
+- Tonemapping (Linear, Reinhard, Filmic, ACES).
+- Automatic exposure adjustments based on viewport brightness.
+- Near and far depth of field with adjustable bokeh simulation.
+- Screen-space ambient occlusion at half or full resolution.
+- Glow/bloom with optional bicubic upscaling and several blend modes available:
+  Screen, Soft Light, Add, Replace, Mix.
+- Color correction using an one-dimensional ramp.
+- Roughness limiter to reduce the impact of specular aliasing.
+- Brightness, contrast and saturation adjustments.
+
+**Texture filtering:**
+
+- Nearest, bilinear, trilinear or anisotropic filtering.
+- Filtering options are defined on a per-use basis, not a per-texture basis.
+
+**Texture compression:**
+
+- Basis Universal (slow, but results in smaller files).
+- BPTC for high-quality compression (not supported on macOS).
+- ETC2 (not supported on macOS).
+- S3TC (not supported on mobile/Web platforms).
+
+**Anti-aliasing:**
+
+- Fast approximate antialiasing (FXAA).
+- Multi-sample antialiasing (MSAA).
+
+Most of these effects can be adjusted for better performance or to further
+improve quality. This can be helpful when using Godot for offline rendering.
+
+3D tools
+^^^^^^^^
+
+- Built-in meshes: cube, cylinder/cone, (hemi)sphere, prism, plane, quad.
+- Tools for :ref:`procedural geometry generation <doc_procedural_geometry>`.
+- :ref:`Constructive solid geometry <doc_csg_tools>` (intended for prototyping).
+- Path3D node to represent a path in 3D space.
+
+   - Can be drawn in the editor or generated procedurally.
+   - PathFollow3D node to make nodes follow a Path3D.
+
+- 3D geometry helper class.
+
+3D physics
+^^^^^^^^^^
+
+**Physics bodies:**
+
+- Static bodies.
+- Rigid bodies.
+- Kinematic bodies.
+- Vehicle bodies (intended for arcade physics, not simulation).
+- Joints.
+- Soft bodies.
+- Ragdolls.
+- Areas to detect bodies entering or leaving it.
+
+**Collision detection:**
+
+- Built-in shapes: cuboid, sphere, capsule, cylinder (only with Bullet physics).
+- Generate triangle collision shapes for any mesh from the editor.
+- Generate one or several convex collision shapes for any mesh from the editor.
+
+Shaders
+^^^^^^^
+
+- *2D:* Custom vertex, fragment, and light shaders.
+- *3D:* Custom vertex, fragment, light, and sky shaders.
+- Text-based shaders using a `shader language inspired by GLSL <doc_shading_language>`.
+- Visual shader editor.
+
+   - Support for visual shader plugins.
+
+Scripting
+^^^^^^^^^
+
+**General:**
+
+- Object-oriented design pattern with scripts extending nodes.
+- Signals and groups for communicating between scripts.
+- Support for :ref:`cross-language scripting <doc_cross_language_scripting>`.
+- Many 2D and 3D linear algebra data types such as vectors and transforms.
+
+:ref:`GDScript: <toc-learn-scripting-gdscript>`
+
+- :ref:`High-level interpreted language <doc_gdscript>` with
+  :ref:`optional static typing <doc_gdscript_static_typing>`.
+- Syntax inspired by Python.
+- Syntax highlighting is provided on GitHub.
+- :ref:`Use threads <doc_using_multiple_threads>` to perform asynchronous actions
+  or make use of multiple processor cores.
+
+:ref:`C#: <toc-learn-scripting-C#>`
+
+- Packaged in a separate binary to keep file sizes and dependencies down.
+- Uses Mono 6.x.
+
+   - Full support for the C# 8.0 syntax and features.
+
+- Supports all platforms.
+- Using an external editor is recommended to benefit from IDE functionality.
+
+:ref:`VisualScript: <toc-learn-scripting-visual_script>`
+
+- :ref:`Graph-based visual scripting language <doc_what_is_visual_script>`.
+- Works best when used for specific purposes (such as level-specific logic)
+  rather than as a language to create entire projects.
+
+**GDNative (C, C++, Rust, D, ...):**
+
+- When you need it, link to native libraries for higher performance and third-party integrations.
+
+   - For scripting game logic, GDScript or C# are recommended if their
+     performance is suitable.
+
+- Official bindings for C and C++.
+
+   - Use any build system and language features you wish.
+
+- Maintained D, Kotlin, Python, Nim, and Rust bindings provided by the community.
+
+Audio
+^^^^^
+
+**Features:**
+
+- Mono, stereo, 5.1 and 7.1 output.
+- Non-positional and positional playback in 2D and 3D.
+
+   - Optional Doppler effect in 2D and 3D.
+
+- Support for re-routable :ref:`audio buses <doc_audio_buses>` and effects
+  with dozens of effects included.
+- Listener3D node to listen from a position different than the camera in 3D.
+- Audio input to record microphones.
+- MIDI input.
+
+   - No support for MIDI output yet.
+
+**APIs used:**
+
+- *Windows:* WASAPI.
+- *macOS:* CoreAudio.
+- *Linux:* PulseAudio or ALSA.
+
+Import
+^^^^^^
+
+- Support for :ref:`custom import plugins <doc_import_plugins>`.
+
+**Formats:**
+
+- *Images:* See :ref:`doc_import_images`.
+- *Audio:*
+
+   - WAV with optional IMA-ADPCM compression.
+   - Ogg Vorbis.
+
+- *3D scenes:*
+
+   - glTF 2.0 *(recommended)*.
+   - `ESCN <https://github.com/godotengine/godot-blender-exporter>`__
+     (direct export from Blender).
+   - FBX.
+   - Collada (.dae).
+   - Wavefront OBJ (static scenes only, can be loaded directly as a mesh).
+
+Input
+^^^^^
+
+- Input mapping system using hardcoded input events or remappable input actions.
+
+   - Axis values can be mapped to two different actions with a configurable deadzone.
+   - Use the same code to support both keyboards and gamepads.
+
+- Keyboard input.
+
+   - Keys can be mapped in "physical" mode to be independent of the keyboard layout.
+
+- Mouse input.
+
+   - The mouse cursor can be visible, hidden, captured or confined within the window.
+   - When captured, raw input will be used on Windows and Linux to
+     sidestep the OS' mouse acceleration settings.
+
+- Gamepad input (up to 8 simultaneous controllers).
+- Pen/tablet input with pressure support.
+
+Navigation
+^^^^^^^^^^
+
+- A* algorithm in 2D and 3D.
+- Navigation meshes with dynamic obstacle avoidance.
+- Generate navigation meshes from the editor.
+
+Networking
+^^^^^^^^^^
+
+- Low-level TCP networking using StreamPeer and TCP_Server.
+- Low-level UDP networking using PacketPeer and UDPServer.
+- Low-level HTTP requests using HTTPClient.
+- High-level HTTP requests using HTTPRequest.
+
+   - Supports HTTPS out of the box using bundled certificates.
+
+- High-level multiplayer API using UDP and ENet.
+
+   - Automatic replication using remote procedure calls (RPCs).
+   - Supports unreliable, reliable and ordered transfers.
+
+- WebSocket client and server, available on all platforms.
+- WebRTC client and server, available on all platforms.
+- Support for UPnP to sidestep the requirement to forward ports when hosting
+  a server behind a NAT.
+
+Internationalization
+^^^^^^^^^^^^^^^^^^^^
+
+- Full support for Unicode including emoji.
+- Store localization strings using :ref:`CSV <doc_internationalizing_games>`
+  or :ref:`gettext <doc_localization_using_gettext>`.
+- Use localized strings in your project automatically in GUI elements or by
+  using the ``tr()`` function.
+- Support for right-to-left typesetting and text shaping planned in Godot 4.0.
+
+Windowing and OS integration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Move, resize, minimize, and maximize windows spawned by the project.
+- Change the window title and icon.
+- Request attention (will cause the title bar to blink on most platforms).
+- Fullscreen mode.
+
+   - Doesn't use exclusive fullscreen, so the screen resolution can't be changed this way.
+     Use a Viewport with a different resolution instead.
+
+- Borderless windows (fullscreen or non-fullscreen).
+- Ability to keep a window always on top.
+- Transparent windows with per-pixel transparency.
+- Global menu integration on macOS.
+- Execute commands in a blocking or non-blocking manner.
+- Open file paths and URLs using default or custom protocol handlers (if registered on the system).
+- Parse custom command line arguments.
+
+Mobile
+^^^^^^
+
+- In-app purchases on Android and iOS.
+- Support for advertisements using third-party modules.
+
+XR support (AR and VR)
+^^^^^^^^^^^^^^^^^^^^^^
+
+- Support for ARKit on iOS out of the box.
+- Support for the OpenXR and OpenVR APIs.
+- Popular VR headsets like the Oculus Quest and HTC Vive are supported thanks to plugins.
+
+GUI system
+^^^^^^^^^^
+
+Godot's GUI is built using the same Control nodes used to make games in Godot.
+The editor UI can easily be extended in many ways using add-ons.
+
+**Nodes:**
+
+- Buttons.
+- Checkboxes, check buttons, radio buttons.
+- Text entry using LineEdit (single line) and TextEdit (multiple lines).
+- Dropdown menus using PopupMenu and OptionButton.
+- Scrollbars.
+- Labels.
+- RichTextLabel for :ref:`text formatted using BBCode <doc_bbcode_in_richtextlabel>`.
+- Trees (can also be used to represent tables).
+- Containers (horizontal, vertical, grid, center, margin, draggable splitter, ...).
+- Controls can be rotated and scaled.
+
+**Sizing:**
+
+- Anchors to keep GUI elements in a specific corner, edge or centered.
+- Containers to place GUI elements automatically following certain rules.
+
+   - :ref:`Stack <class_BoxContainer>` layouts.
+   - :ref:`Grid <class_GridContainer>` layouts.
+   - :ref:`Margin <class_MarginContainer>` and :ref:`centered <class_CenterContainer>`
+     layouts.
+   - :ref:`Draggable splitter <class_SplitContainer>` layouts.
+
+- Scale to multiple resolutions using the ``2d`` or ``viewport`` stretch modes.
+- Support any aspect ratio using anchors and the ``expand`` stretch aspect.
+
+**Theming:**
+
+- Built-in theme editor.
+
+   - Generate a theme based on the current editor theme settings.
+
+- Procedural vector-based theming using :ref:`class_StyleBoxFlat`.
+
+   - Supports rounded/beveled corners, drop shadows and per-border widths.
+
+- Texture-based theming using :ref:`class_StyleBoxTexture`.
+
+Godot's small distribution size can make it a suitable alternative to frameworks
+like Electron or Qt.
+
+Animation
+^^^^^^^^^
+
+- Direct kinematics and inverse kinematics.
+- Support for animating any property with customizable interpolation.
+- Support for calling methods in animation tracks.
+- Support for playing sounds in animation tracks.
+- Support for Bézier curves in animation.
+
+Formats
+^^^^^^^
+
+- Scenes and resources can be saved in :ref:`text-based <doc_tscn_file_format>` or binary formats.
+
+   - Text-based formats are human-readable and more friendly to version control.
+   - Binary formats are faster to save/load for large scenes/resources.
+
+- Read and write text or binary files using :ref:`class_File`.
+
+   - Can optionally be compressed or encrypted.
+
+- Read and write :ref:`class_JSON` files.
+- Read and write INI-style configuration files using :ref:`class_ConfigFile`.
+
+   - Can (de)serialize any Godot datatype, including Vector, Color, ...
+
+- Read XML files using :ref:`class_XMLParser`.
+- Pack game data into a PCK file (custom format optimized for fast seeking),
+  into a ZIP archive, or directly into the executable for single-file distribution.
+- :ref:`Export additional PCK files<doc_exporting_pcks>` that can be read
+  by the engine to support mods and DLCs.
+
+Miscellaneous
+^^^^^^^^^^^^^
+
+- :ref:`Low-level access to servers <doc_using_servers>` which allows bypassing
+  the scene tree's overhead when needed.
+- Command line interface for automation.
+
+   - Export and deploy projects using continuous integration platforms.
+   - `Completion scripts <https://github.com/godotengine/godot/tree/master/misc/dist/shell>`__
+     are available for Bash, zsh and fish.
+
+- Support for :ref:`C++ modules <doc_custom_modules_in_c++>` statically linked
+  into the engine binary.
+- Engine and editor written in C++17.
+
+   - Can be :ref:`compiled <doc_introduction_to_the_buildsystem>` using GCC,
+     Clang and MSVC. MinGW is also supported.
+   - Friendly towards packagers. In most cases, system libraries can be used
+     instead of the ones provided by Godot. The build system doesn't download anything.
+     Builds can be fully reproducible.
+
+- Licensed under the permissive MIT license.
+
+   - Open developement process with :ref:`contributions welcome <doc_ways_to_contribute>`.
+
+.. seealso::
+
+    The `roadmap <https://github.com/godotengine/godot-roadmap>`__ repository
+    documents features that have been agreed upon and may be implemented in
+    future Godot releases.

about/release_policy.rst

@@ -0,0 +1,86 @@
+.. _doc_release_policy:
+
+Godot release policy
+====================
+
+Godot versioning
+----------------
+
+Godot uses ``major.minor.patch`` version numbering. However, it does not
+strictly follow `Semantic Versioning <https://semver.org/>`__. This means that
+releases considered "semver-minor" by that standard (such as 3.1 -> 3.2) will
+most likely introduce breaking changes. Still, there won't be as many breaking
+changes as a "semver-major" version bump such as 3.2 -> 4.0.
+
+In the interest of stability and usability, patch releases may occasionally
+introduce small breaking changes as well. When repackaging Godot projects (e.g.
+in a Flatpak), make sure to always use the same patch version as the one used to
+initially export the project.
+
+.. note::
+
+    The first release in a major/minor release series doesn't end with a
+    trailing zero. For example, the first release in the 3.2 series is ``3.2``,
+    not ``3.2.0``.
+
+Release support timeline
+------------------------
+
+Godot versions are supported for a certain amount of time. While these durations
+are not set in stone, here's a table with the expected level of support
+for each Godot version:
+
++-------------+-------------------+--------------------------------------------------------------------------+
+| **Version** | **Release date**  | **Support level**                                                        |
++-------------+-------------------+--------------------------------------------------------------------------+
+| Godot 4.0   | ~2021 (see below) | |unstable| *Current focus of development (unstable).*                    |
++-------------+-------------------+--------------------------------------------------------------------------+
+| Godot 3.2   | January 2020      | |supported| Backwards-compatible new features (backported from the       |
+|             |                   | ``master`` branch) as well as bug, security, and platform support fixes. |
++-------------+-------------------+--------------------------------------------------------------------------+
+| Godot 3.1   | March 2019        | |partial| Only critical, security and platform support fixes.            |
++-------------+-------------------+--------------------------------------------------------------------------+
+| Godot 3.0   | January 2018      | |partial| Only critical, security and platform support fixes.            |
++-------------+-------------------+--------------------------------------------------------------------------+
+| Godot 2.1   | July 2016         | |partial| Only critical, security and platform support fixes.            |
++-------------+-------------------+--------------------------------------------------------------------------+
+| Godot 2.0   | February 2016     | |eol| No longer supported.                                               |
++-------------+-------------------+--------------------------------------------------------------------------+
+| Godot 1.1   | May 2015          | |eol| No longer supported.                                               |
++-------------+-------------------+--------------------------------------------------------------------------+
+| Godot 1.0   | December 2014     | |eol| No longer supported.                                               |
++-------------+-------------------+--------------------------------------------------------------------------+
+
+.. |supported| image:: img/supported.png
+.. |partial| image:: img/partial.png
+.. |eol| image:: img/eol.png
+.. |unstable| image:: img/unstable.png
+
+**Legend:**
+|supported| Full support -
+|partial| Partial support -
+|eol| No support (end of life) -
+|unstable| Development version
+
+Pre-release Godot versions aren't intended to be used in production and are
+provided on a best-effort basis.
+
+.. _doc_release_policy_when_is_next_release_out:
+
+When is the next release out?
+-----------------------------
+
+While Godot contributors aren't working under any deadlines, there's usually a
+major or minor Godot release made available every year. Following this trend,
+this means Godot 4.0 will most likely be released in **2021**.
+
+Patch releases are made available more frequently, typically every 2-6 months
+while a release is fully supported. Partially supported releases will only have
+new patch releases once an important security or platform support fix has been
+merged.
+
+.. seealso::
+
+    The `roadmap <https://github.com/godotengine/godot-roadmap>`__ repository
+    documents features that have been agreed upon and may be implemented in future
+    Godot releases.

about/troubleshooting.rst

@@ -0,0 +1,111 @@
+.. _doc_troubleshooting:
+
+Troubleshooting
+===============
+
+This page lists common issues encountered when using Godot and possible solutions.
+
+Everything I do in the editor or project manager appears delayed by one frame.
+------------------------------------------------------------------------------
+
+This is a `known bug <https://github.com/godotengine/godot/issues/23069>`__ on
+Intel graphics drivers on Windows. Updating to the latest graphics driver
+version *provided by Intel* should fix the issue.
+
+You should use the graphics driver provided by Intel rather than the one
+provided by your desktop or laptop's manufacturer because their version is often
+outdated.
+
+The editor runs slowly and uses all my CPU and GPU resources, making my computer noisy.
+---------------------------------------------------------------------------------------
+
+This is a known issue, especially on macOS since most Macs have Retina displays.
+Due to Retina displays' higher pixel density, everything has to be rendered at a
+higher resolution. This increases the load on the GPU and decreases perceived
+performance.
+
+There are several ways to improve performance and battery life:
+
+- In 3D, click the **Perspective** button in the top left corner and enable
+  **Half Resolution**. The 3D viewport will now be rendered at half resolution,
+  which can be up to 4 times faster.
+- Open the Editor Settings and increase the value of **Low Processor Mode Sleep Usec**
+  to ``33000`` (30 FPS). This value determines the amount of *microseconds*
+  between frames to render. Higher values will make the editor feel less reactive,
+  but will help decrease CPU and GPU usage significantly.
+- If you have a node that causes the editor to redraw continuously (such as
+  particles), hide it and show it using a script in the ``_ready()`` method.
+  This way, it will be hidden in the editor but will still be visible in the
+  running project.
+
+The grid disappears and meshes turn black when I rotate the 3D camera in the editor.
+------------------------------------------------------------------------------------
+
+This is a `known bug <https://github.com/godotengine/godot/issues/30330>`__ on
+Intel graphics drivers on Windows.
+
+The only workaround, for now, is to switch to the GLES2 renderer. You can switch
+the renderer in the top-right corner of the editor or the Project Settings.
+
+If you use a computer allowing you to switch your graphics card, like NVIDIA
+Optimus, you can use the dedicated graphics card to run Godot.
+
+The editor or project takes a very long time to start.
+------------------------------------------------------
+
+This is a `known bug <https://github.com/godotengine/godot/issues/20566>`__ on
+Windows when you have specific USB peripherals connected. In particular,
+Corsair's iCUE software seems to cause the bug. Try updating your USB
+peripherals' drivers to their latest version. If the bug persists, you need to
+disconnect the faulty peripherals before opening the editor. You can then
+connect the peripheral again.
+
+The Godot editor appears frozen after clicking the system console.
+------------------------------------------------------------------
+
+When running Godot on Windows with the system console enabled, you can
+accidentally enable *selection mode* by clicking inside the command window. This
+Windows-specific behavior pauses the application to let you select text inside
+the system console. Godot cannot override this system-specific behavior.
+
+To solve this, select the system console window and press Enter to leave
+selection mode.
+
+The project window appears blurry, unlike the editor.
+-----------------------------------------------------
+
+Unlike the editor, the project isn't marked as DPI-aware by default. This is
+done to improve performance, especially on integrated graphics, where rendering
+3D scenes in hiDPI is slow.
+
+To resolve this, open **Project > Project Settings** and enable **Display >
+Window > Dpi > Allow Hidpi**. On top of that, make sure your project is
+configured to support :ref:`multiple resolutions <doc_multiple_resolutions>`.
+
+The project window doesn't appear centered when I run the project.
+------------------------------------------------------------------
+
+This is a `known bug <https://github.com/godotengine/godot/issues/13017>`__. To
+resolve this, open **Project > Project Settings** and enable **Display > Window
+> Dpi > Allow Hidpi**. On top of that, make sure your project is configured to
+support :ref:`multiple resolutions <doc_multiple_resolutions>`.
+
+The project works when run from the editor, but fails to load some files when running from an exported copy.
+------------------------------------------------------------------------------------------------------------
+
+This is usually caused by forgetting to specify a filter for non-resource files
+in the Export dialog. By default, Godot will only include actual *resources*
+into the PCK file. Some files commonly used, such as JSON files, are not
+considered resources. For example, if you load ``test.json`` in the exported
+project, you need to specify ``*.json`` in the non-resource export filter. See
+:ref:`doc_exporting_projects_export_mode` for more information.
+
+Also, note that files and folders whose name begin with a period will never be
+included in the exported project. This is done to prevent version control
+folders like ``.git`` from being included in the exported PCK file.
+
+On Windows, this can also be due to :ref:`case sensitivity
+<doc_project_organization_case_sensitivity>` issues. If you reference a resource
+in your script with a different case than on the filesystem, loading will fail
+once you export the project. This is because the virtual PCK filesystem is
+case-sensitive, while Windows's filesystem is case-insensitive by default.

classes/class_animationplayer.rst

@@ -25,8 +25,6 @@ Updating the target properties of animations occurs at process time.
 Tutorials
 ---------
 
-- :doc:`../getting_started/step_by_step/animations`
-
 - :doc:`../tutorials/animation/index`
 
 Properties

classes/class_arraymesh.rst

@@ -41,7 +41,7 @@ The :ref:`MeshInstance<class_MeshInstance>` is ready to be added to the :ref:`Sc
 Tutorials
 ---------
 
-- :doc:`../tutorials/content/procedural_geometry/arraymesh`
+- :doc:`../tutorials/3d/procedural_geometry/arraymesh`
 
 Properties
 ----------

classes/class_basematerial3d.rst

@@ -23,7 +23,7 @@ This provides a default material with a wide variety of rendering features and p
 Tutorials
 ---------
 
-- :doc:`../tutorials/3d/spatial_material`
+- :doc:`../tutorials/3d/standard_material_3d`
 
 Properties
 ----------

classes/class_charfxtransform.rst

@@ -21,7 +21,7 @@ By setting various properties on this object, you can control how individual cha
 Tutorials
 ---------
 
-- :doc:`../tutorials/gui/bbcode_in_richtextlabel`
+- :doc:`../tutorials/ui/bbcode_in_richtextlabel`
 
 - `https://github.com/Eoin-ONeill-Yokai/Godot-Rich-Text-Effect-Test-Project <https://github.com/Eoin-ONeill-Yokai/Godot-Rich-Text-Effect-Test-Project>`_
 

classes/class_control.rst

@@ -35,7 +35,7 @@ Sets :ref:`mouse_filter<class_Control_property_mouse_filter>` to :ref:`MOUSE_FIL
 Tutorials
 ---------
 
-- :doc:`../tutorials/gui/index`
+- :doc:`../tutorials/ui/index`
 
 - :doc:`../tutorials/2d/custom_drawing_in_2d`
 

classes/class_dictionary.rst

@@ -90,7 +90,7 @@ You need to first calculate the dictionary's hash with :ref:`hash<class_Dictiona
 Tutorials
 ---------
 
-- `#dictionary <../getting_started/scripting/gdscript/gdscript_basics.html#dictionary>`_ in :doc:`../getting_started/scripting/gdscript/gdscript_basics`
+- `#dictionary <../tutorials/scripting/gdscript/gdscript_basics.html#dictionary>`_ in :doc:`../tutorials/scripting/gdscript/gdscript_basics`
 
 Methods
 -------

classes/class_editorscenepostimport.rst

@@ -42,7 +42,7 @@ The :ref:`post_import<class_EditorScenePostImport_method_post_import>` callback
 Tutorials
 ---------
 
-- `#custom-script <../getting_started/workflow/assets/importing_scenes.html#custom-script>`_ in :doc:`../getting_started/workflow/assets/importing_scenes`
+- `#custom-script <../tutorials/assets_pipeline/importing_scenes.html#custom-script>`_ in :doc:`../tutorials/assets_pipeline/importing_scenes`
 
 Methods
 -------

classes/class_gdnativelibrary.rst

@@ -21,9 +21,9 @@ A GDNative library can implement :ref:`NativeScript<class_NativeScript>`\ s, glo
 Tutorials
 ---------
 
-- :doc:`../tutorials/plugins/gdnative/gdnative-c-example`
+_ :doc:`../tutorials/scripting/gdnative/gdnative_c_example`
 
-- :doc:`../tutorials/plugins/gdnative/gdnative-cpp-example`
+_ :doc:`../tutorials/scripting/gdnative/gdnative_cpp_example`
 
 Properties
 ----------

classes/class_gdscript.rst

@@ -23,7 +23,7 @@ A script implemented in the GDScript programming language. The script extends th
 Tutorials
 ---------
 
-- :doc:`../getting_started/scripting/gdscript/index`
+- :doc:`../tutorials/scripting/gdscript/index`
 
 Methods
 -------

classes/class_javascript.rst

@@ -21,7 +21,7 @@ The JavaScript singleton is implemented only in the HTML5 export. It's used to a
 Tutorials
 ---------
 
-- `#calling-javascript-from-script <../getting_started/workflow/export/exporting_for_web.html#calling-javascript-from-script>`_ in :doc:`../getting_started/workflow/export/exporting_for_web`
+- `#calling-javascript-from-script <../tutorials/export/exporting_for_web.html#calling-javascript-from-script>`_ in :doc:`../tutorials/export/exporting_for_web`
 
 Methods
 -------

classes/class_multimesh.rst

@@ -27,9 +27,9 @@ Since instances may have any behavior, the AABB used for visibility must be prov
 Tutorials
 ---------
 
-- :doc:`../tutorials/3d/vertex_animation/animating_thousands_of_fish`
+- :doc:`../tutorials/performance/vertex_animation/animating_thousands_of_fish`
 
-- :doc:`../tutorials/optimization/using_multimesh`
+- :doc:`../tutorials/performance/using_multimesh`
 
 Properties
 ----------

classes/class_multimeshinstance.rst

@@ -23,11 +23,11 @@ This is useful to optimize the rendering of a high amount of instances of a give
 Tutorials
 ---------
 
-- :doc:`../tutorials/3d/vertex_animation/animating_thousands_of_fish`
+- :doc:`../tutorials/performance/vertex_animation/animating_thousands_of_fish`
 
 - :doc:`../tutorials/3d/using_multi_mesh_instance`
 
-- :doc:`../tutorials/optimization/using_multimesh`
+- :doc:`../tutorials/performance/using_multimesh`
 
 Properties
 ----------

classes/class_mutex.rst

@@ -21,7 +21,7 @@ A synchronization mutex (mutual exclusion). This is used to synchronize multiple
 Tutorials
 ---------
 
-- :doc:`../tutorials/threads/using_multiple_threads`
+- :doc:`../tutorials/performance/using_multiple_threads`
 
 Methods
 -------

classes/class_os.rst

@@ -1331,7 +1331,7 @@ Returns ``true`` if an environment variable exists.
 
 - :ref:`bool<class_bool>` **has_feature** **(** :ref:`String<class_String>` tag_name **)** const
 
-Returns ``true`` if the feature for the given feature tag is supported in the currently running instance, depending on platform, build etc. Can be used to check whether you're currently running a debug build, on a certain platform or arch, etc. Refer to the `Feature Tags <https://docs.godotengine.org/en/latest/getting_started/workflow/export/feature_tags.html>`_ documentation for more details.
+Returns ``true`` if the feature for the given feature tag is supported in the currently running instance, depending on platform, build etc. Can be used to check whether you're currently running a debug build, on a certain platform or arch, etc. Refer to the `Feature Tags <https://docs.godotengine.org/en/latest/tutorials/export/feature_tags.html>`_ documentation for more details.
 
 **Note:** Tag names are case-sensitive.
 

classes/class_particles.rst

@@ -23,7 +23,7 @@ Use the ``process_material`` property to add a :ref:`ParticlesMaterial<class_Par
 Tutorials
 ---------
 
-- :doc:`../tutorials/3d/vertex_animation/controlling_thousands_of_fish`
+- :doc:`../tutorials/performance/vertex_animation/controlling_thousands_of_fish`
 
 Properties
 ----------

classes/class_richtexteffect.rst

@@ -30,7 +30,7 @@ A custom effect for use with :ref:`RichTextLabel<class_RichTextLabel>`.
 Tutorials
 ---------
 
-- :doc:`../tutorials/gui/bbcode_in_richtextlabel`
+- :doc:`../tutorials/ui/bbcode_in_richtextlabel`
 
 - `https://github.com/Eoin-ONeill-Yokai/Godot-Rich-Text-Effect-Test-Project <https://github.com/Eoin-ONeill-Yokai/Godot-Rich-Text-Effect-Test-Project>`_
 

classes/class_richtextlabel.rst

@@ -23,7 +23,7 @@ Rich text can contain custom text, fonts, images and some basic formatting. The
 Tutorials
 ---------
 
-- :doc:`../tutorials/gui/bbcode_in_richtextlabel`
+- :doc:`../tutorials/ui/bbcode_in_richtextlabel`
 
 Properties
 ----------

classes/class_scenetree.rst

@@ -27,7 +27,7 @@ Tutorials
 
 - :doc:`../getting_started/step_by_step/scene_tree`
 
-- :doc:`../tutorials/viewports/multiple_resolutions`
+- :doc:`../tutorials/rendering/multiple_resolutions`
 
 Properties
 ----------

classes/class_semaphore.rst

@@ -21,7 +21,7 @@ A synchronization semaphore which can be used to synchronize multiple :ref:`Thre
 Tutorials
 ---------
 
-- :doc:`../tutorials/threads/using_multiple_threads`
+- :doc:`../tutorials/performance/using_multiple_threads`
 
 Methods
 -------

classes/class_shader.rst

@@ -23,9 +23,9 @@ This class allows you to define a custom shader program that can be used by a :r
 Tutorials
 ---------
 
-- :doc:`../tutorials/shading/index`
+- :doc:`../tutorials/shaders/index`
 
-- :doc:`../tutorials/shading/your_first_shader/what_are_shaders`
+- :ref:`doc_introduction_to_shaders`
 
 Properties
 ----------

classes/class_shadermaterial.rst

@@ -21,7 +21,7 @@ A material that uses a custom :ref:`Shader<class_Shader>` program to render eith
 Tutorials
 ---------
 
-- :doc:`../tutorials/shading/index`
+- :doc:`../tutorials/shaders/index`
 
 Properties
 ----------

classes/class_string.rst

@@ -19,7 +19,7 @@ This is the built-in string class (and the one used by GDScript). It supports Un
 Tutorials
 ---------
 
-- :doc:`../getting_started/scripting/gdscript/gdscript_format_string`
+- :doc:`../tutorials/scripting/gdscript/gdscript_format_string`
 
 Methods
 -------

classes/class_theme.rst

@@ -23,7 +23,7 @@ Theme resources can alternatively be loaded by writing them in a ``.theme`` file
 Tutorials
 ---------
 
-- :doc:`../tutorials/gui/gui_skinning`
+- :doc:`../tutorials/ui/gui_skinning`
 
 Properties
 ----------

classes/class_thread.rst

@@ -21,7 +21,7 @@ A unit of execution in a process. Can run methods on :ref:`Object<class_Object>`
 Tutorials
 ---------
 
-- :doc:`../tutorials/threads/using_multiple_threads`
+- :doc:`../tutorials/performance/using_multiple_threads`
 
 Methods
 -------

classes/class_viewport.rst

@@ -33,7 +33,7 @@ Tutorials
 
 - :doc:`../tutorials/2d/2d_transforms`
 
-- :doc:`../tutorials/viewports/index`
+- :doc:`../tutorials/rendering/viewports`
 
 Properties
 ----------

classes/class_visualscript.rst

@@ -25,7 +25,7 @@ You are most likely to use this class via the Visual Script editor or when writi
 Tutorials
 ---------
 
-- :doc:`../getting_started/scripting/visual_script/index`
+- :doc:`../tutorials/scripting/visual_script/index`
 
 Methods
 -------

classes/class_visualserver.rst

@@ -37,7 +37,7 @@ In 2D, all visible objects are some form of canvas item. In order to be visible,
 Tutorials
 ---------
 
-- :doc:`../tutorials/optimization/using_servers`
+- :doc:`../tutorials/performance/using_servers`
 
 Methods
 -------

classes/class_visualshadernode.rst

@@ -18,7 +18,7 @@ Base class for nodes in a visual shader graph.
 Tutorials
 ---------
 
-- :doc:`../tutorials/shading/visual_shaders`
+- :doc:`../tutorials/shaders/visual_shaders`
 
 Properties
 ----------

tutorials/assetlib/index.rst → community/asset_library/index.rst

@@ -7,4 +7,4 @@ Asset Library
 
    what_is_assetlib
    using_assetlib
-   uploading_to_assetlib
+   submitting_to_assetlib

tutorials/assetlib/uploading_to_assetlib.rst → community/asset_library/submitting_to_assetlib.rst

@@ -1,4 +1,4 @@
-.. _doc_uploading_to_assetlib:
+.. _doc_submitting_to_assetlib:
 
 Submitting to the Asset Library
 ===============================
@@ -38,7 +38,10 @@ are a few requirements your asset needs to meet to be approved.
   asset needs the contents of the submodule, your asset won't work.
 
 * The license needs to be correct. The license listed on the asset
-  library must match the license in the repository.
+  library must match the license in the repository. The repo MUST
+  have a license file, called either "LICENSE" or "LICENSE.md".
+  This file must contain the license text itself and a copyright
+  statement that includes the year(s) and copyright holder.
 
 * Use proper English for the name and description of your asset.
   This includes using correct capitalization, and using full
@@ -63,6 +66,12 @@ library a better place for all users.
   if other people wish to contribute to your asset. See: the
   :ref:`doc_gdscript_styleguide` or the :ref:`doc_c_sharp_styleguide`.
 
+* If you have screenshots in your repo, place them in their own subfolder
+  and add a **.gdignore** file in the same folder (note: **gd**, not **git**).
+  This prevents Godot from importing your screenshots.
+  On Windows, open a command prompt in the project folder and run
+  ``type nul > .gdignore`` to create a file whose name starts with a period.
+
 * If your asset is a library for working with other files,
   consider including example files in the asset.
 

tutorials/assetlib/using_assetlib.rst → community/asset_library/using_assetlib.rst

@@ -1,7 +1,7 @@
 .. _doc_using_assetlib:
 
-Using the AssetLib
-==================
+Using the Asset Library
+=======================
 
 On the website
 --------------
@@ -9,9 +9,9 @@ On the website
 Overview
 ~~~~~~~~
 
-As mentioned before, you can access the web frontend of the AssetLib
-on `Godot's official website <https://godotengine.org/asset-library/asset>`_, and this
-is what it looks like when you first visit it:
+As mentioned before, you can access the web frontend of the Asset Library on
+`Godot's official website <https://godotengine.org/asset-library/asset>`_.
+This is what it looks like when you first visit it:
 
 |image0|
 
@@ -99,7 +99,7 @@ new functions:
 |image6|
 
 You can learn how to submit assets to the Library, and what the asset submission
-guidelines are, in the next part of this tutorial, :ref:`doc_uploading_to_assetlib`.
+guidelines are, in the next part of this tutorial, :ref:`doc_submitting_to_assetlib`.
 
 In the editor
 -------------

community/channels.rst

@@ -17,18 +17,18 @@ Q&A
 IRC on Freenode
 ---------------
 
-- `General: #godotengine <http://webchat.freenode.net/?channels=#godotengine>`_
-- `Engine development: #godotengine-devel <http://webchat.freenode.net/?channels=#godotengine-devel>`_
-- `Documentation: #godotengine-doc <http://webchat.freenode.net/?channels=#godotengine-doc>`_
-- `Pull request meetings: #godotengine-meeting <http://webchat.freenode.net/?channels=#godotengine-meeting>`_
-- `GDNative: #godotengine-gdnative <http://webchat.freenode.net/?channels=#godotengine-gdnative>`_
-- `Website and public relations: #godotengine-atelier <http://webchat.freenode.net/?channels=#godotengine-atelier>`_
-- `IRC logs <https://godot.eska.me/irc-logs/>`_
+- `General: #godotengine <https://webchat.freenode.net/?channels=#godotengine>`_
+- `Engine development: #godotengine-devel <https://webchat.freenode.net/?channels=#godotengine-devel>`_
+- `Documentation: #godotengine-doc <https://webchat.freenode.net/?channels=#godotengine-doc>`_
+- `Pull request meetings: #godotengine-meeting <https://webchat.freenode.net/?channels=#godotengine-meeting>`_
+- `GDNative: #godotengine-gdnative <https://webchat.freenode.net/?channels=#godotengine-gdnative>`_
+- `Website and public relations: #godotengine-atelier <https://webchat.freenode.net/?channels=#godotengine-atelier>`_
+- `IRC logs <https://freenode.logbot.info/godotengine-devel>`_
 
 Other chats
 -----------
 
-- `Discord Server <https://discordapp.com/invite/zH7NUgz>`_
+- `Discord <https://discord.gg/4JBkykG>`_
 - `Matrix (IRC compatible) <https://matrix.to/#/#godotengine:matrix.org>`_
 
 Language-based communities
@@ -45,7 +45,8 @@ Social networks
 
 - `GitHub <https://github.com/godotengine/>`_
 - `Facebook group <https://www.facebook.com/groups/godotengine/>`_
-- `Twitter (also, #godotengine) <https://twitter.com/godotengine>`_
+- `Twitter <https://twitter.com/godotengine>`_
+  (see also the `#GodotEngine <https://twitter.com/hashtag/GodotEngine>`_ hashtag)
 - `Reddit <https://www.reddit.com/r/godot>`_
 - `YouTube <https://www.youtube.com/c/GodotEngineOfficial>`_
 - `Steam <https://steamcommunity.com/app/404790>`_
@@ -53,4 +54,4 @@ Social networks
 Forum
 -----
 
-- `Forum (godotforums.org) <https://godotforums.org/>`_
+- `Godot Forums <https://godotforums.org/>`_

community/contributing/best_practices_for_engine_contributors.rst

@@ -6,16 +6,26 @@ Best practices for engine contributors
 Introduction
 ------------
 
-Godot has a large amount of users who have the ability to contribute, given the project itself is aimed mainly at users with the ability to do programming. Despite this, not all of them have the same level of experience working in large projects or in software engineering, which can lead to common misunderstandings and bad practices during the process of contributing code to the project.
+Godot has a large amount of users who have the ability to contribute, given the
+project itself is aimed mainly at users with the ability to do programming.
+Despite this, not all of them have the same level of experience working in large
+projects or in software engineering, which can lead to common misunderstandings
+and bad practices during the process of contributing code to the project.
 
 Language
 --------
 
-The scope of this document is to be a list of best practices for contributors to follow, as well as to creating a language they can use to refer to common situations that arise in the process of submitting their contributions.
+The scope of this document is to be a list of best practices for contributors to
+follow, as well as to creating a language they can use to refer to common
+situations that arise in the process of submitting their contributions.
 
-While some may find it useful to extend this to general software development, our intention is to just restrict to situations that are most common in our project.
+While some may find it useful to extend this to general software development,
+our intention is to just restrict to situations that are most common in our
+project.
 
-Contributions are most of the time categorized as bug fixes, enhancements or new features. To abstract this idea, we will call them *Solutions*, because they always seek to solve something that can be described as a *Problem*.
+Contributions are most of the time categorized as bug fixes, enhancements or new
+features. To abstract this idea, we will call them *Solutions*, because they
+always seek to solve something that can be described as a *Problem*.
 
 Best Practices
 --------------
@@ -23,117 +33,212 @@ Best Practices
 #1: The problem always comes first
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Many contributors are extremely creative and just enjoy the process of designing abstract data structures, creating nice user interfaces, or simply love programming. Whatever the case may be, they come up with cool ideas, which may not be actually solving any actual problems.
+Many contributors are extremely creative and just enjoy the process of designing
+abstract data structures, creating nice user interfaces, or simply love
+programming. Whatever the case may be, they come up with cool ideas, which may
+or may not be solving any real problems.
 
 .. image:: img/best_practices1.png
 
-These are usually called *Solutions in search of a problem*. In an ideal world, they would not be harmful but, in reality, code takes time to write, takes space as source and binary and requires maintenance once it exists. Avoiding the addition of anything unnecessary is always considered a good practice in software development.
+These are usually called *Solutions in search of a problem*. In an ideal world,
+they would not be harmful but, in reality, code takes time to write, takes space
+as source and binary and requires maintenance once it exists. Avoiding the
+addition of anything unnecessary is always considered a good practice in
+software development.
 
-#2: The problem has to exist
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#2: To solve the problem, it has to exist in the first place
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This is a variation of the previous practice. I believe most developers agree that adding anything unnecessary is not a good idea, but what constitutes what is necessary and what isn't?
+This is a variation of the previous practice. Adding anything unnecessary is not
+a good idea, but what constitutes what is necessary and what isn't?
 
 .. image:: img/best_practices2.png
 
-The answer to this question is that the problem needs to *exist*. It must not be speculation or a belief. The user must be using the software as intended to create something they *need*. In this process, the user may stumble into a problem that requires a solution in order to continue, or in order to achieve greater productivity. In this case, *a solution is needed*.
+The answer to this question is that the problem needs to *exist* before it can
+be actually solved. It must not be speculation or a belief. The user must be
+using the software as intended to create something they *need*. In this process,
+the user may stumble into a problem that requires a solution to proceed, or in
+order to achieve greater productivity. In this case, *a solution is needed*.
 
-Believing that problems may arise in the future and that the software needs to be ready to solve them by the time they appear is called *"Future proofing"* and its characterized by lines of thought such as:
+Believing that problems may arise in the future and that the software needs to
+be ready to solve them by the time they appear is called *"Future proofing"* and
+its characterized by lines of thought such as:
 
 - I think it would be useful for users to...
 - I think users will eventually need to...
 
-This is generally considered a bad habit, because trying to solve problems that *don't actually exist* in the present will very often lead to code that will be written but never used, or to code that is considerably more complex to use and maintain than it needs to be.
+This is generally considered a bad habit because trying to solve problems that
+*don't actually exist* in the present will often lead to code that will be
+written but never used, or that is considerably more complex to use and maintain
+than it needs to be.
 
 #3: The problem has to be complex or frequent
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Software is designed to solve problems, but we can't expect it to solve *every problem that exists under the sun*. As a game engine, Godot will solve problems for you, so it helps you to make games better and faster, but it won't make the *entire game* for you. A line must be drawn somewhere.
+Software is designed to solve problems, but we can't expect it to solve *every
+problem that exists under the sun*. As a game engine, Godot will solve problems
+for you, so it helps you to make games better and faster, but it won't make the
+*entire game* for you. A line must be drawn somewhere.
 
 .. image:: img/best_practices3.png
 
-Whether a problem is worth solving is determined by the difficulty the user has to work around it. This difficulty can be expressed as:
+Whether a problem is worth solving is determined by the difficulty the user has
+to work around it. This difficulty can be expressed as:
 
 - The complexity of the problem
 - The frequency the problem
 
-If the problem is *too complex* for most users to solve, the software must offer a ready-made solution for it. Likewise, if the problem is easy for the user to workaround, offering such a solution is unnecessary and it's up to the user to do it.
+If the problem is *too complex* for most users to solve, the software must offer
+a ready-made solution for it. Likewise, if the problem is easy for the user to
+workaround, offering such a solution is unnecessary and it's up to the user to
+do it.
 
-The exception, however, is when the user stumbles into this problem *frequently enough* that having to do the simple solution every time becomes an annoyance. In this case, the software must offer a solution to simplify this use case.
+The exception, however, is when the user stumbles into this problem *frequently
+enough* that having to do the simple solution every time becomes an annoyance.
+In this case, the software must offer a solution to simplify this use case.
 
-In our experience, in most cases it's usually obvious to tell when a problem is complex or frequent, but cases may arise where drawing this line is difficult. This is why discussing with other developers (next point) is always advised.
+In our experience, in most cases it's usually obvious to tell when a problem is
+complex or frequent, but cases may arise where drawing this line is difficult.
+This is why discussing with other developers (next point) is always advised.
 
 #4: The solution must be discussed with others
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-It is often the case that, when users stumble upon problems, they are only immersed in their own project, so they will naturally try to solve the problem from their own perspective, thinking only about their use case.
+It is often the case that when users stumble upon problems, they are only
+immersed in their project, so they will naturally try to solve the problem
+from their perspective, thinking only about their use case.
 
-Because of this, user proposed solutions don't always contemplate other use cases that developers are often aware of, so they are often biased towards their own requirements.
+Because of this, user proposed solutions don't always contemplate other use
+cases that developers are often aware of, so they are often biased towards their
+own requirements.
 
 .. image:: img/best_practices4.png
 
-For developers, the perspective is different. They may find the user's problem too unique to justify a solution (instead of a user workaround), or maybe they will suggest a partial (usually simpler or lower level) solution that applies to a wider range of known problems, and leave the rest of the solution up to the user.
+For developers, the perspective is different. They may find the user's problem
+too unique to justify a solution (instead of a user workaround), or maybe they
+will suggest a partial (usually simpler or lower level) solution that applies to
+a wider range of known problems, and leave the rest of the solution up to the
+user.
 
-In any case, before attempting a contribution, it is important to discuss the actual problems with the other developers or contributors, so a better agreement on implementation can be reached.
+In any case, before attempting a contribution, it is important to discuss the
+actual problems with the other developers or contributors, so a better agreement
+on implementation can be reached.
 
-The only exception, in this case, is when an area of code has a clear owner (agreed by the other contributors), who talks to users directly and has the most knowledge to implement a solution directly.
+The only exception, in this case, is when an area of code has a clear owner
+(agreed by the other contributors), who talks to users directly and has the most
+knowledge to implement a solution directly.
+
+Also, Godot's philosophy is to favor ease of use and maintenance over absolute
+performance. Performance optimizations will be considered, but they may not
+be accepted if they make something too difficult to use or if they add too much
+complexity to the codebase.
 
 #5: To each problem, its own solution
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For programmers, it is always a most enjoyable challenge to find the most optimal solutions to problems. Things, however, may go overboard sometimes and programmers will try to come up with solutions that solve as many problems as possible.
+For programmers, it is always a most enjoyable challenge to find the most
+optimal solutions to problems. Things, however, may go overboard sometimes and
+programmers will try to come up with solutions that solve as many problems as
+possible.
 
-The situation will often take a turn for the worse when, in order to make this solution appear even more fantastic and flexible, the pure speculation-based problems (as described in #2) also make their appearance on stage.
+The situation will often take a turn for the worse when, in order to make this
+solution appear even more fantastic and flexible, the pure speculation-based
+problems (as described in #2) also make their appearance on stage.
 
 .. image:: img/best_practices5.png
 
-The main problem is that, in reality, it rarely works this way. Most of the time, just writing an individual solution to each problem results in code that is simpler and more maintainable.
+The main problem is that, in reality, it rarely works this way. Most of the
+time, just writing an individual solution to each problem results in code that
+is simpler and more maintainable.
 
-Additionally, solutions that target individual problems are better for the users, as they find something that does exactly what they need, without having to learn and remember a more complex system they will only need for simple tasks.
+Additionally, solutions that target individual problems are better for the
+users, as they find something that does exactly what they need, without having
+to learn and remember a more complex system they will only need for simple
+tasks.
 
-Big and flexible solutions also have an additional drawback which is that, over time, they are rarely flexible enough for all users, which keep requesting more functions added (and making the API and codebase more and more complex).
+Big and flexible solutions also have an additional drawback which is that, over
+time, they are rarely flexible enough for all users, which keep requesting more
+functions added (and making the API and codebase more and more complex).
 
 #6: Cater to common use cases, leave the door open for the rare ones
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This is a continuation of the previous point, which further explains why this way of thinking and designing software is preferred.
+This is a continuation of the previous point, which further explains why this
+way of thinking and designing software is preferred.
 
-As mentioned before (in point #2), it is very difficult for us (as human beings who design software) to actually understand all future user needs. Trying to write very flexible structures that cater to many use cases at once is often a mistake.
+As mentioned before (in point #2), it is very difficult for us (as human beings
+who design software) to actually understand all future user needs. Trying to
+write very flexible structures that cater to many use cases at once is often a
+mistake.
 
-We may come up with something we believe is brilliant, but when it's actually used, we will find that users will never even use half of it, or that they will require features that don't quite accommodate our original design, forcing us to either throw it away or make it even more complex.
+We may come up with something we believe is brilliant, but when it's actually
+used, we will find that users will never even use half of it, or that they will
+require features that don't quite accommodate our original design, forcing us to
+either throw it away or make it even more complex.
 
-The question is then, how to design software that gives users what *we know they need*, but that is flexible enough to allow them to do *what we don't know they might need* in the future?
+The question is then, how to design software that gives users what *we know they
+need*, but that is flexible enough to allow them to do *what we don't know they
+might need* in the future?
 
 .. image:: img/best_practices6.png
 
-The answer to this question is that, to ensure users still can do what they want to do, we need to give them access to a *low level API* that they can use to achieve what they want, even if it's more work for them because it means reimplementing some logic that already exists.
+The answer to this question is that, to ensure users still can do what they want
+to do, we need to give them access to a *low level API* that they can use to
+achieve what they want, even if it's more work for them because it means
+reimplementing some logic that already exists.
 
-In real-life scenarios, these use cases will be at most rare and uncommon anyway, so it makes sense a custom solution needs to be written. This is why it's important to still provide users the basic building blocks to do it.
+In real-life scenarios, these use cases will be at most rare and uncommon
+anyway, so it makes sense a custom solution needs to be written. This is why
+it's important to still provide users the basic building blocks to do it.
 
 #7: Solutions must be local
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When looking for a solution to a problem, be it implementing a new feature or fixing a bug, sometimes the easiest path is to add data or a new function in the core layers of code.
+When looking for a solution to a problem, be it implementing a new feature or
+fixing a bug, sometimes the easiest path is to add data or a new function in the
+core layers of code.
 
-The main problem here is, adding something to the core layers that will only be used from a single location far away will not only make the code more difficult to follow (split in two), but also make the core API larger, more complex, more difficult to understand in general.
+The main problem here is, adding something to the core layers that will only be
+used from a single location far away will not only make the code more difficult
+to follow (split in two), but also make the core API larger, more complex, more
+difficult to understand in general.
 
-This is bad, because readability and cleanness of core APIs is always of extreme importance given how much code relies on it, and because it's key for new contributors as a starting point to learning the codebase.
+This is bad, because readability and cleanness of core APIs is always of extreme
+importance given how much code relies on it, and because it's key for new
+contributors as a starting point to learning the codebase.
 
 
 .. image:: img/best_practices7.png
 
 
-The common reasoning for wanting to do this is that it's usually less code to simply add a hack in the core layers.
+The common reasoning for wanting to do this is that it's usually less code to
+simply add a hack in the core layers.
 
-Despite this, this practice is not advised. Generally, the code for a solution should be closer to where the problem originates, even if it involves more code, duplicated, more complex or is less efficient. More creativity might be needed, but this path is always the advised one.
+Despite this, this practice is not advised. Generally, the code for a solution
+should be closer to where the problem originates, even if it involves more code,
+duplicated, more complex or is less efficient. More creativity might be needed,
+but this path is always the advised one.
 
 #8: Don't use complex canned solutions for simple problems
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Not every problem has a simple solution and, many times, the right choice is to use a third party library to solve the problem.
+Not every problem has a simple solution and, many times, the right choice is to
+use a third party library to solve the problem.
 
-As Godot requires to be shipped in a large amount of platforms, we just can't link libraries dynamically. Instead, we bundle them in our source tree.
+As Godot requires to be shipped in a large amount of platforms, we just can't
+link libraries dynamically. Instead, we bundle them in our source tree.
 
 .. image:: img/best_practices8.png
 
-As a result, we are very picky with what goes in, and we tend to prefer smaller libraries (in fact, single header ones are our favorite). Only in cases where there is no other choice we end up bundling something larger.
+As a result, we are very picky with what goes in, and we tend to prefer smaller
+libraries (in fact, single header ones are our favorite). Only in cases where
+there is no other choice we end up bundling something larger.
+
+Also, libraries must use a permissive enough license to be included into Godot.
+Some examples of acceptable licenses are Apache 2.0, BSD, MIT, ISC, and MPL 2.0.
+In particular, we cannot accept libraries licensed under the GPL or LGPL since
+these licenses effectively disallow static linking in proprietary software
+(which Godot is distributed as in most exported projects). This requirement also
+applies to the editor, since we may want to run it on iOS in the long term.
+Since iOS doesn't support dynamic linking, static linking the only option on
+that platform.

community/contributing/bisecting_regressions.rst

@@ -95,9 +95,11 @@ folder and enter the following command:
 
 .. code-block:: shell
 
-    # <good> is the commit hash of the build that works as expected.
-    # <bad> is the commit hash of the build exhibiting the bug.
-    $ git bisect start <good> <bad>
+    # <good commit hash> is hash of the build that works as expected.
+    # <bad commit hash> is hash of the build exhibiting the bug.
+    $ git bisect start
+    $ git bisect good <good commit hash>
+    $ git bisect bad <bad commit hash>
 
 Compile Godot. This assumes you've set up a build environment:
 

community/contributing/bug_triage_guidelines.rst

@@ -4,8 +4,9 @@ Bug triage guidelines
 =====================
 
 This page describes the typical workflow of the bug triage team aka
-bugsquad when handling issues and pull requests on Godot's `GitHub <https://github.com/godotengine/godot>`_
-repository. It is bound to evolve together with the bugsquad, so do not
+bugsquad when handling issues and pull requests on Godot's
+`GitHub repository <https://github.com/godotengine/godot>`__.
+It is bound to evolve together with the bugsquad, so do not
 hesitate to propose modifications to the following guidelines.
 
 Issues management
@@ -25,7 +26,7 @@ contributors are welcome to take on any issue, if relevant after mentioning
 it on the issue ticket and/or discussing the best way to resolve it with
 other developers.
 
-For the time being we do not use the project dashboard feature either.
+For the time being, we do not use the project dashboard feature either.
 
 As far as possible, we try to assign labels (and milestones, when relevant)
 to both issues and pull requests.
@@ -39,7 +40,13 @@ The following labels are currently defined in the Godot repository:
 
 -  *Archived*: either a duplicate of another issue, or invalid. Such an
    issue would also be closed.
+-  *Breaks compat*: describes something that can only be fixed by breaking
+   compatibility with existing projects.
 -  *Bug*: describes something that is not working properly.
+-  *Cherrypick*: describes something that can be backported to a stable branch
+   after being merged in the ``master`` branch.
+-  *Crash:* describes a bug that causes the engine to crash.
+   This label is only used for "hard" crashes, not freezes.
 -  *Confirmed*: has been confirmed by at least one other contributor
    than the bug reporter (typically for *Bug* reports).
    The purpose of this label is to let developers know which issues are
@@ -58,18 +65,31 @@ The following labels are currently defined in the Godot repository:
 -  *Enhancement*: describes a proposed enhancement to an existing
    functionality.
 -  *Feature proposal*: describes a wish for a new feature to be
-   implemented.
+   implemented. Note that the main Godot repository no longer accepts
+   feature requests. Please use
+   `godot-proposals <https://github.com/godotengine/godot-proposals>`__ instead.
+-  *For PR meeting*: the issue needs to be discussed in a pull request meeting.
+   These meetings are public and are held regularly on the ``#godotengine-meeting``
+   IRC channel.
 -  *Junior job*: the issue is *assumed* to be an easy one to fix, which makes
    it a great fit for junior contributors who need to become familiar with
    the code base.
--  *Needs rebase*: the issue need a Git rebase to be merged.
+-  *High priority:* the issue is particularly important as it can
+   prevent people from releasing their projects or cause data loss.
+-  *Needs work*: the pull request needs additional work before it can be merged.
 -  *Needs testing*: the issue/pull request could not be completely tested
    and thus need further testing. This can mean that it needs to be tested
    on different hardware/software configurations or even that the steps to
    reproduce are not certain.
--  *PR welcome / hero wanted!*: Contributions for issues with these labels are especially welcome.
-   Note that this **doesn't** mean you can't work on issues without
-   these labels.
+-  *PR welcome / Hero wanted!*: Contributions for issues with these labels
+   are especially welcome. Note that this **doesn't** mean you can't work
+   on issues without these labels.
+-  *Regression*: the bug appeared after a stable release not exhibiting
+   the bug was released.
+-  *Salvageable*: the pull request can't be merged due to design issues or
+   merge conflicts and its author is not active anymore. However, it can still
+   be picked up by an external contributor to bring it to a mergeable state.
+   To do so, you need to open a new pull request based on the original pull request.
 -  *Tracker*: issue used to track other issues (like all issues related to
    the plugin system).
 -  *Usability*: issues that directly impact user usability.
@@ -86,19 +106,27 @@ feature request, or one that is not precise enough to be worked on.
 -  *Audio*: relates to the audio features (low and high level).
 -  *Buildsystem*: relates to building issues, either linked to the SCons
    buildsystem or to compiler peculiarities.
+-  *Codestyle*: relates to the programming style used within the codebase.
 -  *Core*: anything related to the core engine. It might be further
    split later on as it's a pretty big topic.
--  *Drivers*: relates to issues with the drivers used by the engine.
 -  *Editor*: relates to issues in the editor (mainly UI).
 -  *GDNative*: relates to the GDNative module.
 -  *GDScript*: relates to GDScript.
+-  *GUI*: relates to GUI (Control) nodes.
+-  *Import*: relates to the resource import system.
+-  *Input*: relates to input system.
 -  *Mono*: relates to the C# / Mono bindings.
+-  *Navigation*: relates to the navigation system (including A* and navmeshes).
 -  *Network*: relates to networking.
 -  *Physics*: relates to the physics engine (2D/3D).
 -  *Plugin*: relates to problems encountered while writing plugins.
--  *Porting*: relates to some specific platforms.
+-  *Porting*: relates to some specific platforms or exporting projects.
 -  *Rendering*: relates to the 2D and 3D rendering engines.
--  *VisualScript*: relates to issues with the visual scripting language.
+-  *Shaders*: relates to the Godot shader language or visual shaders.
+-  *Tests*: relates to unit tests.
+-  *Thirdparty*: relates to third-party libraries used in Godot.
+-  *VisualScript*: relates to issues with the visual scripting language (*not* visual shaders).
+-  *XR*: relates to Augmented Reality or Virtual Reality.
 
 Issues would typically correspond to only one topic, though it's not
 unthinkable to see issues that fit two bills. The general idea is that
@@ -114,17 +142,45 @@ If one of the platform labels is used, it is then exclusive and the
 previous assumption doesn't stand anymore (so if it's a bug on e.g.
 Android and Linux exclusively, select those two platforms).
 
+Documentation labels
+~~~~~~~~~~~~~~~~~~~~
+
+In the `documentation repository <https://github.com/godotengine/godot-docs>`__, we
+use the following labels:
+
+-  *Bug*: Incorrect information in an existing page. Not to be used for
+   *missing* information.
+-  *Class reference*: the issue is about the class reference, not a documentation page.
+-  *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.
+-  *New page*: a new page to be created.
+-  *Hero wanted!*: contributions for issues with these labels
+   are especially welcome. Note that this **doesn't** mean you can't work
+   on issues without these labels.
+-  *Organization*: The issue involves moving pages around or reorganizing content.
+-  *Redirect*: a redirection needs to be created in the Read the Docs backend.
+   Only administrators can do this.
+-  *Salvageable*: the pull request can't be merged due to design issues or
+   merge conflicts and its author is not active anymore. However, it can still
+   be picked up by an external contributor to bring it to a mergeable state.
+   To do so, you need to open a new pull request based on the original pull request.
+-  *Topic:Mono*: the issue is about C# support in Godot.
+-  *Topic:Website*: the issue relates to the Sphinx/Read the Docs frontend or backend,
+   not the documentation contents.
+
 Milestones
 ~~~~~~~~~~
 
-`Milestones <https://github.com/godotengine/godot/milestones>`_ correspond to planned future versions of Godot for which
-there is an existing roadmap. Issues that fit in the said roadmap should
-be filed under the corresponding milestone; if they don't correspond to
-any current roadmap, they should be left without milestone. As a rule of
-thumb, an issue corresponds to a given milestone if it concerns a feature
-that is new in the milestone, or a critical bug that can't be accepted in any
-future stable release, or anything that Juan wants to work on right now.
-:)
+`Milestones <https://github.com/godotengine/godot/milestones>`_ correspond to
+planned future versions of Godot for which there is an existing roadmap. Issues
+that fit in the said roadmap should be filed under the corresponding milestone;
+if they don't correspond to any current roadmap, they should be left without
+milestone. As a rule of thumb, an issue corresponds to a given milestone if it
+concerns a feature that is new in the milestone, or a critical bug that can't be
+accepted in any future stable release, or anything that Juan wants to work on
+right now. :)
 
 Contributors are free to pick issues regardless of their assigned milestone;
 if a fix is proposed for a bug that was not deemed urgent and thus without

community/contributing/code_style_guidelines.rst

@@ -186,7 +186,7 @@ Example:
 
     #include "core/hash_map.h"
     #include "core/list.h"
-    #include "scene/gui/control.h
+    #include "scene/gui/control.h"
 
     #include <png.h>
 
@@ -229,7 +229,7 @@ Example:
     #include "my_new_file.h"
 
     #include "core/math/math_funcs.h"
-    #include "scene/gui/line_edit.h
+    #include "scene/gui/line_edit.h"
 
     #include <zlib.h>
     #include <zstd.h>
@@ -248,7 +248,56 @@ Python
 Godot's SCons buildsystem is written in Python, and various scripts included
 in the source tree are also using Python.
 
-For those, we follow the `PEP-8 style guide <https://www.python.org/dev/peps/pep-0008/>`__,
-this is however not as strongly enforced as for the C++ code. If you are so
-inclined, you can check and format your Python changes using
-`autopep8 <https://pypi.org/project/autopep8/>`__.
+For those, we follow the `Black style guide <https://github.com/psf/black#the-black-code-style>`__.
+Blacken your Python changes using `Black <https://pypi.org/project/black/>`__.
+
+Using black locally
+~~~~~~~~~~~~~~~~~~~
+
+First of all, you will need to install black. Black requires Python 3.6.0+
+to run.
+
+Installation
+^^^^^^^^^^^^
+
+Here's how to install black:
+
+::
+
+    pip install black --user
+
+
+You then have different possibilities to apply black to your changes:
+
+Manual usage
+^^^^^^^^^^^^
+
+You can apply ``black`` manually to one or more files with the following
+command:
+
+::
+
+    black -l 120 <path/to/file(s)>
+
+- ``-l 120`` means that the allowed number of characters per line is 120.
+  This number was agreed upon by the developers.
+- The path can point to several files, either one after the other or using
+  wildcards like in a typical Unix shell.
+
+Pre-commit hook
+^^^^^^^^^^^^^^^
+
+For ease of use, we provide a pre-commit hook for Git that will run
+black automatically on all your commits to check them, and let you apply
+its changes in the final commit.
+
+This "hook" is a script which can be found in ``misc/hooks``. Refer to that
+folder's ``README.md`` for installation instructions.
+
+
+Editor integration
+^^^^^^^^^^^^^^^^^^
+
+Many IDEs or code editors have beautifier plugins that can be configured to run
+black automatically, for example each time you save a file. For details you can
+check `Black editor integration <https://github.com/psf/black#editor-integration>`__.

community/contributing/docs_writing_guidelines.rst

@@ -112,6 +112,10 @@ The progressive forms describe continuous actions. E.g. "is calling",
     Vector2 move ( Vector2 rel_vec )
     Moves the body in the vector's direction. The body **stops** if it collides with an obstacle. [...]
 
+Exception: If the subject is not clear, replacing "ing" verbs is not an
+improvement. For example, in the previous sentence, "it replaces"
+would not make much sense where "replacing" currently is.
+
 You may use the progressive tense to describe actions that are
 continuous in time. Anything like animation or coroutines.
 
@@ -294,7 +298,7 @@ The exception is topics that explain static typing concepts to users.
     var body_sprite := $Sprite as Sprite
 
 
-**Do** write constants variables with dynamic typing:
+**Do** write constants and variables with dynamic typing:
 
 ::
 
@@ -308,7 +312,7 @@ The exception is topics that explain static typing concepts to users.
 
 ::
 
-    func choose(arguments: Array):
+    func choose(arguments: PackedStringArray) -> String:
         # Chooses one of the arguments from array with equal chances
         randomize()
         var size := arguments.size()
@@ -388,7 +392,7 @@ functionality, in up to 200 characters.
 ::
 
     **Node2D**
-    2D game object, parent of all 2D related nodes. Has a position, rotation, scale and z-index.
+    A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.
 
 Use the node's full description to provide more information, and a code
 example, if possible.
@@ -514,10 +518,18 @@ Screenshot sizes should not exceed 1920×1080 to ensure fast loading on slower
 connections.
 
 When you need to highlight an area of the editor to show something, like a
-button or option, use a 2 pixel thick outline without a bevel.
+button or option, use a 2 pixel-thick yellow outline without a bevel. If the
+outline is on a dark background, the outline should be yellow so it can be
+easily seen by colorblind people. Please do not use red as it won't be visible
+for some users.
 
 Before you add or replace any images in the documentation, they should be run
-through a PNG compressor to save size. The built in lossless compressor in
-programs like Krita or Photoshop should be enough. For heavier images, also look
-into using a lossy compressor, such as `pngquant <https://pngquant.org/>`_ where
-almost no image quality is lost during compression.
+through a PNG compressor to save size. You can use the lossless OxiPNG
+compressor included in `Squoosh <https://squoosh.app/>`__ for this purpose. For
+heavier images, consider using a lossy compressor like `pngquant
+<https://pngquant.org/>`_. With it, almost no image quality is lost during
+compression.
+
+.. note::
+
+    The program pngquant must be installed locally as it's not available in Squoosh.

community/contributing/editor_and_docs_localization.rst

@@ -0,0 +1,412 @@
+.. _doc_editor_and_docs_localization:
+
+Editor and docs localization
+============================
+
+.. highlight:: none
+
+Godot aims to make game development available to everyone, including people who
+may not know or be comfortable with English. Therefore, we do our best to make
+the most important resources available in many languages, thanks to the
+translation effort of the community.
+
+These resources include:
+
+1. The `Godot editor's interface <https://hosted.weblate.org/projects/godot-engine/godot/>`__
+   (ca. 15,000 words).
+2. The `online documentation <https://hosted.weblate.org/projects/godot-engine/godot-docs/>`__
+   (editor manual and tutorials, ca. 300,000 words).
+3. The `class reference <https://hosted.weblate.org/projects/godot-engine/godot-class-reference/>`__,
+   available both online and in the editor (ca. 200,000 words).
+
+To manage translations, we use the GNU gettext file format (``PO`` files), and
+the open source `Weblate <https://weblate.org>`__ web-based localization
+platform, which allows easy collaboration of many contributors to complete the
+translation for the various components, and keep them up to date. Click the bold
+links above to access each resource on Weblate.
+
+This page gives an overview of the general translation workflow on Weblate, and
+some resource-specific instructions on e.g. how to handle some keywords or the
+localization of images.
+
+.. tip::
+
+    Translating all the official Godot content is a massive undertaking, so we
+    advise prioritizing the resources as they are listed above: first the editor
+    interface, then the online documentation, and eventually the class reference
+    if there are enough translators to keep up with updates.
+
+Using Weblate for translations
+------------------------------
+
+While our translations eventually reside in the Git repositories of the Godot
+engine and its documentation, all translation updates are handled through
+Weblate, and thus direct pull requests to the Git repositories are not accepted.
+Translations are synced manually between Weblate and the Godot repositories by
+maintainers.
+
+You should therefore `register on Weblate <https://hosted.weblate.org/accounts/register/>`__
+to contribute to Godot's translations.
+
+Once signed in, browse to the Godot resource which you want to contribute to (in
+this page we will use the `editor translation <https://hosted.weblate.org/projects/godot-engine/godot/>`__
+as an example) to find the list of all languages:
+
+.. image:: img/l10n_01_language_list.png
+
+.. seealso::
+
+    Feel free to consult Weblate's own documentation on the `translation
+    workflow <https://docs.weblate.org/en/latest/user/translating.html>`__ for
+    more details.
+
+Adding a new language
+^^^^^^^^^^^^^^^^^^^^^
+
+If your language is already listed, click on its name to access the overview,
+and skip the rest of this section.
+
+If your language is not listed, scroll to the bottom of the list of languages
+and click the "Start new translation" button, and select the language you want
+to translate to:
+
+.. image:: img/l10n_02_new_translation.png
+
+.. important::
+
+    If your language is spoken in several countries with only limited regional
+    variations, please consider adding it with its generic variant (e.g. ``fr``
+    for French) instead of a regional variant (e.g. ``fr_FR`` for French
+    (France), ``fr_CA`` for French (Canada), or ``fr_DZ`` for French (Algeria)).
+
+    Godot has a huge amount of content to translate, so duplicating the work for
+    regional variants should only be done if the language variations are
+    significant enough. Additionally, if a translation is done with for a
+    regional variant, it will only be available automatically for users located
+    in this region (or having their system language configured for this region).
+
+    When regional variations are significant enough to warrant separate
+    translations, we advise to focus on completing a generic variant first if
+    possible, then duplicate the fully completed translation for regional
+    variants and do the relevant edits. This is typically a good strategy for
+    e.g. Spanish (work on ``es`` first, then duplicate it to ``es_AR``,
+    ``es_ES``, ``es_MX``, etc. if necessary) or Portuguese (``pt_BR`` vs
+    ``pt_PT``).
+
+Translation interface
+^^^^^^^^^^^^^^^^^^^^^
+
+Once a language has been selected, you will see an overview of the translation
+status, including how many strings are left to translate or review. Each item
+can be clicked and used to browse through the corresponding list. You can also
+click the "Translate" button to get started on the list of strings needing
+action.
+
+.. image:: img/l10n_03_translation_overview.png
+
+After selecting a list of clicking "Translate", you will see the main
+translation interface where all the work happens:
+
+.. image:: img/l10n_04_translation_interface.png
+
+On that page, you have:
+
+ - A toolbar which lets you cycle through strings of the current list, change
+   to another pre-defined list or do a custom search, etc. There is also a "Zen"
+   editing mode with a simplified interface.
+ - The actual string you are working on in the "Translation" panel. By default,
+   there should be the English source string and an edit box for your language.
+   If you are familiar with other languages, you can add them in your user
+   settings to give you more context for translation.
+   Once you are done editing the current string, press "Save" to confirm changes
+   and move to the next entry. Alternatively, use the "Skip" button to skip it.
+   The "Needs editing" checkbox means that the original string was updated, and
+   the translation therefore needs review to take those changes into account (in
+   PO jargon, these are so-called "fuzzy" strings). Such strings won't be used
+   in the translation until fixed.
+ - The bottom panel has various tools which can help with the translation
+   effort, such as context from nearby strings (usually from the same editor
+   tool or documentation page, so they might use similar terms), comments from
+   other translators, machine translations, and a list of all other existing
+   translations for that string.
+ - On the top right, the glossary shows terms for which an entry has been added
+   previously, and which are included in the current string. For example, if
+   you decided with fellow translators to use a specific translation for the
+   "node" term in Godot, you can add it to the glossary to ensure that other
+   translators use the same convention.
+ - The bottom right panel includes information on the source string. The most
+   relevant item is the "source string location", which links you to the
+   original string on GitHub. You may need to search for the string in the page
+   to locate it and its surrounding context.
+
+Locating original content
+-------------------------
+
+PO files are an ordered list of source strings (``msgid``) and their translation
+(``msgstr``), and by default, Weblate will present the strings in that order. It
+can therefore be useful to understand how the content is organized in the PO
+files to help you locate the original content and use it as a reference when
+translating.
+
+.. important::
+
+    It is primordial to use the original context as reference when translating,
+    as many words have several possible translations depending on the context.
+    Using the wrong translation can actually be detrimental to the user and make
+    things harder to understand than if they stayed in English.
+    Using the context also makes the translation effort much easier and more
+    enjoyable, as you can see directly if the translation you wrote will make
+    sense in context.
+
+- The editor interface's translation template is generated by parsing all the
+  C++ source code in **alphabetical order**, so all the strings defined in a
+  given file will be grouped together. For example, if the "source string
+  location" indicates ``editor/code_editor.cpp``, the current string (and the
+  nearby ones) is defined in the ``editor/code_editor.cpp`` code file, and is
+  thereby related to the code editors in Godot (GDScript, shaders).
+- The online documentation's translation template is generated from the source
+  RST files in the same order as seen in the **table of contents**, so for
+  example the first strings are from the front page of the documentation.
+  The recommended workflow is therefore to find a unique string corresponding to
+  a page that you want to translate, and then translate all the strings with the
+  same source string location while comparing with the online version of that
+  page in English. An example of source string location could be
+  ``getting_started/step_by_step/scenes_and_nodes.rst`` for the
+  page :ref:`doc_scenes_and_nodes`.
+- The class reference's translation template is generated from the source XML
+  files in **alphabetical order**, which is also the same as the order of the
+  table of contents for the online version. You can therefore locate the source
+  string corresponding to the brief description of a given class to find the
+  first string to translate and all other descriptions from that class should be
+  in the subsequent strings on Weblate. For example, the descriptions for the
+  :ref:`class_Node2D` class would have the source string location
+  ``doc/classes/Node2D.xml``.
+
+A handy tool to locate specific pages/classes is to use Weblate's advanced
+search feature, and especially the "Location strings" query (which can also be
+used with the ``location:`` token, e.g. ``location:scenes_and_nodes.rst``):
+
+.. image:: img/l10n_05_search_location.png
+
+.. image:: img/l10n_06_browse_by_location.png
+
+.. note::
+
+    When a given source string is used in multiple source locations, they will
+    all be concatenated into one. For example, the above
+    ``location:scenes_and_nodes.rst`` query would land first on the
+    "Introduction" source string which is used in dozens of pages, including
+    some that come before ``scenes_and_nodes.rst`` in the template. Clicking the
+    "Next" button then brings us to the "Scene and nodes" title string displayed
+    above.
+    So it may happen that a given paragraph or section title is not at the
+    location you'd expect it when reading the online version of a page.
+
+Respecting the markup syntax
+----------------------------
+
+Each translation resource originates from a different source code format, and
+having some notions on the markup language used for each resource is important
+to avoid creating syntax errors in your translations.
+
+Editor interface (C++)
+^^^^^^^^^^^^^^^^^^^^^^
+
+The editor translations originate from C++ strings, and may use:
+
+- **C format specifiers** such as ``%s`` (a string) or ``%d`` (a number). These
+  specifiers are replaced by content at runtime, and should be preserved and
+  placed in your translation where necessary for it to be meaningful after
+  substitution. You may need to refer to the source string location to
+  understand what kind of content will be substituted if it's not clear from the
+  sentence. Example (``%s``  will be substituted with a file name or path)::
+
+    # PO file:
+    "There is no '%s' file."
+
+    # Weblate:
+    There is no '%s' file.
+
+- **C escape characters** such as ``\n`` (line break) or ``\t`` (tabulation). In
+  the Weblate editor, the ``\n`` characters are replaced by ``↵`` (return) and
+  ``\t`` by ``↹``. Tabs are not used much, but you should make sure to use line
+  breaks in the same way as the original English string (Weblate will issue a
+  warning if you don't). Line breaks might sometimes be used for vertical
+  spacing, or manual wrapping of long lines which would otherwise be too long
+  especially in the editor translation). Example::
+
+    # PO file:
+    "Scene '%s' is currently being edited.\n"
+    "Changes will only take effect when reloaded."
+
+    # Weblate:
+    Scene '%s' is currently being edited.↵
+    Changes will only take effect when reloaded.
+
+Online documentation (RST)
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The documentation translations originate from reStructuredText (RST) files,
+which also use their own markup syntax to style text, create internal and
+external links, etc. Here are some examples::
+
+    # "development" is styled bold.
+    # "Have a look here" is a link pointing to https://docs.godotengine.org/en/latest.
+    # You should translate "Have a look here", but not the URL, unless there is
+    # a matching URL for the same content in your language.
+    # Note: The `, <, >, and _ characters all have a meaning in the hyperlink
+    # syntax and should be preserved.
+
+    Looking for the documentation of the current **development** branch?
+    `Have a look here <https://docs.godotengine.org/en/latest>`_.
+
+    # "|supported|" is an inline reference to an image and should stay unchanged.
+    # "master" uses the markup for inline code, and will be styled as such.
+    # Note: Inline code in RST uses 2 backticks on each side, unlike Markdown.
+    # Single backticks are used for hyperlinks.
+
+    |supported| Backwards-compatible new features (backported from the ``master``
+    branch) as well as bug, security, and platform support fixes.
+
+    # The :ref: Sphinx "role" is used for internal references to other pages of
+    # the documentation.
+    # It can be used with only the reference name of a page (which should not be
+    # changed), in which case the title of that page will be displayed:
+
+    See :ref:`doc_ways_to_contribute`.
+
+    # Or it can be used with an optional custom title, which should thus be translated:
+
+    See :ref:`how to contribute <doc_ways_to_contribute>`.
+
+    # You may encounter other Sphinx roles, such as :kbd: used for shortcut keys.
+    # You can translate the content between backticks to match the usual key names,
+    # if it's different from the English one.
+
+    Save the scene. Click Scene -> Save, or press :kbd:`Ctrl + S` on Windows/Linux
+    or :kbd:`Cmd + S` on macOS.
+
+.. seealso::
+
+    See Sphinx's `reStructured Text primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
+    for a quick overview of the markup language you may find in source strings.
+    You may encounter especially the inline markup (bold, italics, inline code)
+    and the internal and external hyperlink markup.
+
+Class reference (BBCode)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The class reference is documented in the main Godot repository using XML files,
+and with BBCode-like markup for styling and internal references.
+
+Some of the tags used are from the original BBCode (e.g. ``[b]Bold[/b]`` and
+``[i]Italics[/i]``), while others are Godot-specific and used for advanced
+features such as inline code (e.g. ``[code]true[/code]``), linking to another
+class (e.g. ``[Node2D]``) or to a property in a given class (e.g.
+``[member Node2D.position]``), or for multiline code blocks. Example::
+
+    Returns a color according to the standardized [code]name[/code] with [code]alpha[/code] ranging from 0 to 1.
+    [codeblock]
+    red = ColorN("red", 1)
+    [/codeblock]
+    Supported color names are the same as the constants defined in [Color].
+
+In the above example, ``[code]name[/code]``, ``[code]alpha[/code]``, and
+``[Color]`` should *not* be translated, as they refer respectively to argument
+names and a class of the Godot API. Similarly, the contents of the
+``[codeblock]`` should not be translated, as ``ColorN`` is a function of the
+Godot API and ``"red"`` is one of the named colors it supports. At most, you can
+translate the name of the variable which holds the result (``red = ...``).
+
+Note also that in the XML, each line is a paragraph, so you should not add line
+breaks if they are not part of the original translation.
+
+.. seealso::
+
+    See our documentation for class reference writers for the :ref:`list of
+    BBCode-like tags <doc_updating_the_class_reference_bbcode>` which are used
+    throughout the class reference.
+
+Offline translation and testing
+-------------------------------
+
+While we advise using the Weblate interface to write translations, you also have
+the possibility to download the PO file locally to translate it with your
+preferred PO editing application, such as `Poedit <https://poedit.net/>`__ or
+`Lokalize <https://userbase.kde.org/Lokalize>`__.
+
+To download the PO file locally, browse to the translation overview for your
+language, and select the first item in the "Files" menu:
+
+.. image:: img/l10n_07_download_po_file.png
+
+Once you are done with a series of edits, use the "Upload translation" item in
+that same menu and select your file. Choose "Add as translation" for the file
+upload mode.
+
+.. note::
+
+    If a significant amount of time has passed between your download of the PO
+    file and the upload of the edited version, there is a risk to overwrite the
+    translations authored by other contributors in the meantime. This is why we
+    advise to use the online interface so that you always work on the latest
+    version.
+
+If you want to test changes locally (especially for the editor translation), you
+can use the downloaded PO file and :ref:`compile Godot from source <toc-devel-compiling>`.
+
+Rename the editor translation PO file to ``<lang>.po`` (e.g. ``eo.po`` for
+Esperanto) and place it in the ``editor/translations/`` folder
+(`GitHub <https://github.com/godotengine/godot/tree/master/editor/translations>`__).
+
+You can also test class reference changes the same way by renaming the PO file
+similarly and placing it in the ``doc/translations/`` folder
+(`GitHub <https://github.com/godotengine/godot/tree/master/doc/translations>`__).
+
+Localizing documentation images
+-------------------------------
+
+The online documentation includes many images, which can be screenshots of the
+Godot editor, custom-made graphs, of any other kind of visual content. Some of
+it includes text and might thus be relevant to localize in your language.
+
+This part is not handled via Weblate, but directly on the `godot-docs-l10n
+<https://github.com/godotengine/godot-docs-l10n>`_ Git repository where the
+documentation translations are synced from Weblate.
+
+.. note::
+
+   The workflow is not the most straightforward and requires some knowledge of
+   Git. We plan to work on a simplified Web tool which could be used to manage
+   image localization in a convenient way, abstracting away these steps.
+
+To translate an image, you should first locate it in the original English
+documentation. To do so, browse the relevant page in the docs, e.g.
+:ref:`doc_intro_to_the_editor_interface`. Click the "Edit on GitHub" link in the
+top right corner:
+
+.. image:: img/l10n_08_edit_on_github.png
+
+On GitHub, click on the image you want to translate. If relevant, click on
+"Download" to download it locally and edit it with an image edition tool.
+Note the full path to the image as it will be needed further down (here
+``getting_started/step_by_step/img/project_manager_first_open.png``).
+
+.. image:: img/l10n_09_path_to_image.png
+
+Create your localized version of the image, either by editing the English one,
+or by taking a screenshot of the editor with your language, if it's an editor
+screenshot. Some images may also have source files available in SVG format, so
+you can browse the ``img/`` folder which contains them to check for that.
+
+Name your localized image like the original one, but with the language code
+added before the extension, e.g. ``project_manager_first_open.png`` would become
+``project_manager_first_open.fr.png`` for the French localization.
+
+Finally, on godot-docs-l10n_, recreate the same folder structure as for the
+original image in the ``images`` subfolder
+(`GitHub <https://github.com/godotengine/godot-docs-l10n/tree/master/images>`_),
+and place your translated image there. In our example, the end result should be
+``images/getting_started/step_by_step/img/project_manager_first_open.fr.png``.
+
+Repeat this for other images and :ref:`make a Pull Request <doc_pr_workflow>`.

community/contributing/index.rst

@@ -14,3 +14,4 @@ Contributing
    documentation_guidelines
    docs_writing_guidelines
    updating_the_class_reference
+   editor_and_docs_localization

community/contributing/updating_the_class_reference.rst

@@ -1,7 +1,7 @@
 .. _doc_updating_the_class_reference:
 
-Contribute to the Class Reference
-=================================
+Contributing to the class reference
+===================================
 
 .. highlight:: shell
 
@@ -64,7 +64,7 @@ Create a new branch to make your changes. It makes it a lot easier to sync your
 
     git checkout -b your-new-branch-name
 
-The new branch is the same as your master branch, until you start to write API docs. In the ``doc/`` folder, you'll find the class reference.
+The new branch is the same as your master branch until you start to write API docs. In the ``doc/`` folder, you'll find the class reference.
 
 How to keep your local clone up-to-date
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -159,21 +159,21 @@ When it's done, you can ask for a Pull Request via the GitHub UI of your Godot f
 
     Although you can edit files on GitHub, it's not recommended. As hundreds of contributors work on Godot, the Git history must stay clean. Each commit should bundle all related improvements you make to the class reference, a new feature, bug fixes... When you edit from GitHub, it will create a new branch and a Pull Request every time you want to save it. If a few days pass before your changes get a review, you won't be able to update to the latest version of the repository cleanly. Also, it's harder to keep clean indents from GitHub. And they're very important in the docs.
 
-    TL;DR: If you don't know what you're doing exactly, do not edit files from GitHub.
+    TL;DR: If you don't know exactly what you're doing, do not edit files from GitHub.
 
 How to edit class XML
 ---------------------
 
 Edit the file for your chosen class in ``doc/classes/`` to update the class reference. The folder contains an XML file for each class. The XML lists the constants and methods you'll find in the class reference. Godot generates and updates the XML automatically.
 
-Edit it using your favorite text editor. If you use a code editor, make sure that it doesn't change the indent style: tabs for the XML, and 4 spaces inside BBcode-style blocks. More on that below.
+Edit it using your favorite text editor. If you use a code editor, make sure that it doesn't change the indent style: tabs for the XML, and 4 spaces inside BBCode-style blocks. More on that below.
 
 If you need to check that the modifications you've made are correct in the generated documentation, build Godot as described :ref:`here <toc-devel-compiling>`, run the editor and open the help for the page you modified.
 
 How to write the class reference
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Each class has a brief and a long description. The brief description is always at the top of the page, while the full description lies below the list of methods, variables and constants. Methods, member variables, constants and signals are in separate categories or XML nodes. For each, learn how they work in Godot's source code, and fill their <description>.
+Each class has a brief and long description. The brief description is always at the top of the page, while the full description lies below the list of methods, variables, and constants. Methods, member variables, constants, and signals are in separate categories or XML nodes. For each, learn how they work in Godot's source code, and fill their <description>.
 
 Our job is to add the missing text between these marks:
 
@@ -184,7 +184,7 @@ Our job is to add the missing text between these marks:
 -  <member></member>
 -  <signal></signal>
 
-Write in a clear and simple language. Always follow the :ref:`writing guidelines <doc_docs_writing_guidelines>` to keep your descriptions short and easy to read. **Do not leave empty lines** in the descriptions: each line in the XML file will result in a new paragraph.
+Write using clear and simple language. Always follow the :ref:`writing guidelines <doc_docs_writing_guidelines>` to keep your descriptions short and easy to read. **Do not leave empty lines** in the descriptions: each line in the XML file will result in a new paragraph.
 
 Here's how a class looks like in XML:
 
@@ -195,7 +195,7 @@ Here's how a class looks like in XML:
             Base node for 2D system.
         </brief_description>
         <description>
-            Base node for 2D system. Node2D contains a position, rotation and scale, which is used to position and animate. It can alternatively be used with a custom 2D transform ([Matrix32]). A tree of Node2Ds allows complex hierarchies for animation and positioning.
+            Base node for the 2D system. Node2D contains a position, rotation, and scale, which is used to position and animate. It can alternatively be used with a custom 2D transform ([Matrix32]). A tree of Node2Ds allows complex hierarchies for animation and positioning.
         </description>
         <methods>
             <method name="set_pos">
@@ -227,39 +227,46 @@ Here's how a class looks like in XML:
 
 Use a code editor like Vim, Atom, Code, Notepad++ or anything similar to edit the file quickly. Use the search function to find classes fast.
 
+.. _doc_updating_the_class_reference_bbcode:
 
-Improve formatting with BBcode style tags
+Improve formatting with BBCode style tags
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Godot's class reference supports BBcode-like tags. They add nice formatting to the text. Here's the list of available tags:
-
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| Tag                       | Effect                         | Usage                             | Result                                            |
-+===========================+================================+===================================+===================================================+
-| [Class]                   | Link a class                   | Move the [Sprite].                | Move the :ref:`class_sprite`.                     |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [method methodname]       | Link to a method in this class | Call [method hide].               | See :ref:`hide <class_spatial_method_hide>`.      |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [method Class.methodname] | Link to another class's method | Call [method Spatial.hide].       | See :ref:`hide <class_spatial_method_hide>`.      |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [member membername]       | Link to a member in this class | Get [member scale].               | Get :ref:`scale <class_node2d_property_scale>`.   |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [member Class.membername] | Link to another class's member | Get [member Node2D.scale].        | Get :ref:`scale <class_node2d_property_scale>`.   |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [signal signalname]       | Link to a signal in this class | Emit [signal renamed].            | Emit :ref:`renamed <class_node_signal_renamed>`.  |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [signal Class.signalname] | Link to another class's signal | Emit [signal Node.renamed].       | Emit :ref:`renamed <class_node_signal_renamed>`.  |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [b] [/b]                  | Bold                           | Some [b]bold[/b] text.            | Some **bold** text.                               |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [i] [/i]                  | Italic                         | Some [i]italic[/i] text.          | Some *italic* text.                               |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [code] [/code]            | Monospace                      | Some [code]monospace[/code] text. | Some ``monospace`` text.                          |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [kbd] [/kbd]              | Keyboard/mouse shortcut        | Some [kbd]Ctrl + C[/kbd] key.     | Some :kbd:`Ctrl + C` key.                         |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
-| [codeblock] [/codeblock]  | Multiline preformatted block   | *See below.*                      | *See below.*                                      |
-+---------------------------+--------------------------------+-----------------------------------+---------------------------------------------------+
+Godot's class reference supports BBCode-like tags. They add nice formatting to the text. Here's the list of available tags:
+
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| Tag                        | Effect                               | Usage                             | Result                                            |
++============================+======================================+===================================+===================================================+
+| [Class]                    | Link a class                         | Move the [Sprite].                | Move the :ref:`class_sprite`.                     |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [method methodname]        | Link to a method in this class       | Call [method hide].               | See :ref:`hide <class_spatial_method_hide>`.      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [method Class.methodname]  | Link to another class's method       | Call [method Spatial.hide].       | See :ref:`hide <class_spatial_method_hide>`.      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [member membername]        | Link to a member in this class       | Get [member scale].               | Get :ref:`scale <class_node2d_property_scale>`.   |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [member Class.membername]  | Link to another class's member       | Get [member Node2D.scale].        | Get :ref:`scale <class_node2d_property_scale>`.   |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [signal signalname]        | Link to a signal in this class       | Emit [signal renamed].            | Emit :ref:`renamed <class_node_signal_renamed>`.  |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [signal Class.signalname]  | Link to another class's signal       | Emit [signal Node.renamed].       | Emit :ref:`renamed <class_node_signal_renamed>`.  |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [b] [/b]                   | Bold                                 | Some [b]bold[/b] text.            | Some **bold** text.                               |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [i] [/i]                   | Italic                               | Some [i]italic[/i] text.          | Some *italic* text.                               |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [code] [/code]             | Monospace                            | Some [code]monospace[/code] text. | Some ``monospace`` text.                          |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [kbd] [/kbd]               | Keyboard/mouse shortcut              | Some [kbd]Ctrl + C[/kbd] key.     | Some :kbd:`Ctrl + C` key.                         |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [codeblock] [/codeblock]   | Multiline preformatted block         | *See below.*                      | *See below.*                                      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [codeblocks] [/codeblocks] | [codeblock] for multiple languages   | *See below.*                      | *See below.*                                      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [gdscript] [/gdscript]     | GDScript codeblock tab in codeblocks | *See below.*                      | *See below.*                                      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
+| [csharp] [/csharp]         | C# codeblock tab in codeblocks       | *See below.*                      | *See below.*                                      |
++----------------------------+--------------------------------------+-----------------------------------+---------------------------------------------------+
 
 Use ``[codeblock]`` for pre-formatted code blocks. Inside ``[codeblock]``, always use **four spaces** for indentation (the parser will delete tabs). Example:
 
@@ -279,11 +286,72 @@ Will display as:
         var sprite = get_node("Sprite")
         print(sprite.get_pos())
 
+If you need to have different code version in GDScript and C#, use ``[codeblocks]`` instead. If you use ``[codeblocks]``, you also need to have at least one of the language specific tags (``[gdscript]`` and ``[csharp]``). Always write GDScript code examples first! You can use this `experimental code translation tool <https://github.com/HaSa1002/codetranslator>`_ to speed up your workflow.
+
+.. code-block:: none
+
+    [codeblocks]
+    [gdscript]
+    func _ready():
+        var sprite = get_node("Sprite")
+        print(sprite.get_pos())
+    [/gdscript]
+    [csharp]
+    public override void _Ready()
+    {
+        var sprite = GetNode("Sprite");
+        GD.Print(sprite.GetPos());
+    }
+    [/csharp]
+    [/codeblocks]
+
+Will display as:
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    func _ready():
+        var sprite = get_node("Sprite")
+        print(sprite.get_pos())
+
+ .. code-tab:: csharp
+
+    public override void _Ready()
+    {
+        var sprite = GetNode("Sprite");
+        GD.Print(sprite.GetPos());
+    }
+
+
+To denote important information, add a paragraph starting with "[b]Note:[/b]" at
+the end of the description:
+
+.. code-block:: none
+
+    [b]Note:[/b] Only available when using the Vulkan renderer.
+
+To denote crucial information that could cause security issues or loss of data
+if not followed carefully, add a paragraph starting with "[b]Warning:[/b]" at the
+end of the description:
+
+.. code-block:: none
+
+    [b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.
+
+For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]".
+Notice the use of italics instead of bold:
+
+.. code-block:: none
+
+    [i]Deprecated.[/i] This property has been replaced by [member other_property].
+
+In all the paragraphs described above, make sure the punctuation is part of the
+BBCode tags for consistency.
 
 I don't know what this method does!
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-No problem. Leave it behind, and list the methods you skipped when you request a pull of your changes. Another writer will take care of it.
+No problem. Leave it behind and list the methods you skipped when you request a pull of your changes. Another writer will take care of it.
 
 You can still have a look at the methods' implementation in Godot's source code on GitHub. Also, if you have doubts, feel free to ask on the `Q&A website <https://godotengine.org/qa/>`__ and on IRC (freenode, #godotengine).
 

community/contributing/ways_to_contribute.rst

@@ -190,3 +190,12 @@ There are two separate resources referred to as "documentation" in Godot:
    to which you can contribute via pull requests on the
    `godot-docs <https://github.com/godotengine/godot-docs>`_ GitHub repository.
    See :ref:`doc_documentation_guidelines` for more details.
+
+Contributing translations
+-------------------------
+
+To make Godot accessible to everyone, including users who may prefer resources
+in their native language instead of English, our community helps translate both
+the Godot editor and its documentation in many languages.
+
+See :ref:`doc_editor_and_docs_localization` for more details.

community/tutorials.rst

@@ -14,11 +14,14 @@ The Godot video tutorials by `GDQuest <https://www.youtube.com/channel/UCxboW7x0
 
 If you're interested in Visual Scripting, `Emilio's tutorials <https://www.youtube.com/channel/UC9DR22-qohBDtZ74R3FxOZg>`_ may be worth a look.
 
+If you're interested in a complete introduction to programming using Godot and GDScript, the unofficial `Godot Tutorials <https://www.youtube.com/channel/UCnr9ojBEQGgwbcKsZC-2rIg>`_ YouTube channel is a good place to start.
+
 Some tutorials mentioned below provide more advanced tutorials, e.g. on 3D or shaders.
 
 Video tutorials
 ---------------
 
+- `Godot Tutorials <https://www.youtube.com/channel/UCnr9ojBEQGgwbcKsZC-2rIg>`_ (2D, GDScript, Programming Basics).
 - `Emilio <https://www.youtube.com/channel/UC9DR22-qohBDtZ74R3FxOZg>`_ (2D, GDScript and VisualScript).
 - `GDQuest <https://www.youtube.com/channel/UCxboW7x0jZqFdvMdCFKTMsQ/playlists>`_ (2D and 3D, GDScript, VisualScript and C#).
 - `Game Development Channel <https://www.youtube.com/channel/UClseGZiVmeHamsjYmpbiAmQ/playlists>`_ (2D, GDScript).

conf.py

@@ -14,7 +14,6 @@ needs_sphinx = "1.3"
 sys.path.append(os.path.abspath("_extensions"))
 extensions = [
     "sphinx_tabs.tabs",
-    "sphinx.ext.imgmath",
 ]
 
 # Warning when the Sphinx Tabs extension is used with unknown
@@ -76,6 +75,7 @@ supported_languages = {
     "ru": "Документация Godot Engine (%s) на русском языке",
     "uk": "Документація до Godot Engine (%s) українською мовою",
     "zh_CN": "Godot Engine (%s) 简体中文文档",
+    "zh_TW": "Godot Engine (%s) 正體中文 (台灣) 文件",
 }
 
 language = os.getenv("READTHEDOCS_LANGUAGE", "en")
@@ -101,6 +101,8 @@ from sphinx.highlighting import lexers
 lexers["gdscript"] = GDScriptLexer()
 # fmt: on
 
+smartquotes = False
+
 # Pygments (syntax highlighting) style to use
 pygments_style = "sphinx"
 highlight_language = "gdscript"

development/compiling/compiling_for_android.rst

@@ -83,8 +83,8 @@ As Google will require all APKs to include ARMv8 (64-bit) libraries starting
 from August 2019, the commands below will build an APK containing both
 ARMv7 and ARMv8 libraries.
 
-Compiling the standard export templates is done by calling SCons with
-the following arguments:
+Compiling the standard export templates is done by calling SCons from the Godot
+root directory with the following arguments:
 
 -  Release template (used when exporting with **Debugging Enabled** unchecked)
 

development/compiling/compiling_for_ios.rst

@@ -10,7 +10,12 @@ Requirements
 
 -  SCons 3.0+ (you can install it via Homebrew or Macports, you should be able
    to run ``scons`` in a terminal when installed).
--  Xcode 10.0 (or later) with the iOS (10.0) SDK and the command line tools.
+-  Xcode 11.0 (or later) with the iOS (13.0) SDK and the command line tools.
+
+If you are building the ``master`` branch:
+
+-  Download and follow README instructions to build a static ``.a`` library
+   from the `MoltenVK SDK <https://github.com/KhronosGroup/MoltenVK#fetching-moltenvk-source-code>`__.
 
 .. seealso:: For a general overview of SCons usage for Godot, see
              :ref:`doc_introduction_to_the_buildsystem`.

development/compiling/compiling_for_linuxbsd.rst

@@ -79,6 +79,12 @@ Distro-specific one-liners
 |                  |     sudo zypper install scons pkgconfig libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel \ |
 |                  |             libXi-devel Mesa-libGL-devel alsa-devel libpulse-devel libudev-devel libGLU1 yasm             |
 +------------------+-----------------------------------------------------------------------------------------------------------+
+| **NetBSD**       | ::                                                                                                        |
+|                  |                                                                                                           |
+|                  |     pkg_add pkg-config py37-scons yasm                                                                    |
+|                  |                                                                                                           |
+|                  | For audio support, you can optionally install ``pulseaudio``.                                             |
++------------------+-----------------------------------------------------------------------------------------------------------+
 | **Solus**        | ::                                                                                                        |
 |                  |                                                                                                           |
 |                  |     sudo eopkg install -c system.devel scons libxcursor-devel libxinerama-devel libxi-devel \             |
@@ -98,6 +104,12 @@ A good rule of thumb for the ``-j`` (*jobs*) flag, is to have at least as many
 threads compiling Godot as you have cores in your CPU, if not one or two more.
 Feel free to add the ``-j`` option to any SCons command you see below.
 
+.. note::
+
+    Prior to Godot 4.0, the Linux/\*BSD target was called ``x11`` instead of
+    ``linuxbsd``. If you are looking to compile Godot 3.2, make sure to use the
+    `3.2 branch of this documentation <https://docs.godotengine.org/en/3.2/development/compiling/compiling_for_x11.html>`__.
+
 If all goes well, the resulting binary executable will be placed in the
 "bin" subdirectory. This executable file contains the whole engine and
 runs without any dependencies. Executing it will bring up the project

development/compiling/compiling_for_osx.rst

@@ -33,9 +33,19 @@ If you are building the ``master`` branch:
 Compiling
 ---------
 
-Start a terminal, go to the root directory of the engine source code and type::
+Start a terminal, go to the root directory of the engine source code.
 
-    scons platform=osx --jobs=$(sysctl -n hw.logicalcpu)
+To compile for Intel (x86-64) powered Macs, use::
+
+    scons platform=osx arch=x86_64 --jobs=$(sysctl -n hw.logicalcpu)
+
+To compile for Apple Silicon (ARM64) powered Macs, use::
+
+    scons platform=osx arch=arm64 --jobs=$(sysctl -n hw.logicalcpu)
+
+To support both architectures in a single "Universal 2" binary, run the above two commands and then use ``lipo`` to bundle them together::
+
+    lipo -create bin/godot.osx.tools.x86_64 bin/godot.osx.tools.arm64 -output bin/godot.osx.tools.universal
 
 If all goes well, the resulting binary executable will be placed in the
 ``bin/`` subdirectory. This executable file contains the whole engine and
@@ -49,13 +59,18 @@ manager.
 
 To create an ``.app`` bundle like in the official builds, you need to use the
 template located in ``misc/dist/osx_tools.app``. Typically, for an optimized
-editor binary built with ``scons p=osx target=release_debug``::
+editor binary built with ``target=release_debug``::
 
     cp -r misc/dist/osx_tools.app ./Godot.app
     mkdir -p Godot.app/Contents/MacOS
-    cp bin/godot.osx.tools.64 Godot.app/Contents/MacOS/Godot
+    cp bin/godot.osx.opt.tools.universal Godot.app/Contents/MacOS/Godot
     chmod +x Godot.app/Contents/MacOS/Godot
 
+If you are building the ``master`` branch, additionally copy the Vulkan library::
+
+    mkdir -p Godot.app/Contents/Frameworks
+    cp <Vulkan SDK path>/macOS/libs/libMoltenVK.dylib Godot.app/Contents/Frameworks/libMoltenVK.dylib
+
 Compiling a headless/server build
 ---------------------------------
 

development/compiling/compiling_for_web.rst

@@ -39,7 +39,8 @@ either ``release`` for a release build or ``release_debug`` for a debug build::
     scons platform=javascript tools=no target=release_debug
 
 By default, the :ref:`JavaScript singleton <doc_javascript_eval>` will be built
-into the engine. Since ``eval()`` calls can be a security concern, the
+into the engine. Official export templates also have the JavaScript singleton
+enabled. Since ``eval()`` calls can be a security concern, the
 ``javascript_eval`` option can be used to build without the singleton::
 
     scons platform=javascript tools=no target=release javascript_eval=no

development/compiling/compiling_for_windows.rst

@@ -179,7 +179,9 @@ and 64-bit variants. The package names may differ based on your distribution,
 here are some known ones:
 
 +----------------+--------------------------------------------------------------+
-| **Arch Linux** | Install `mingw-w64-gcc from the AUR`_.                       |
+| **Arch Linux** | ::                                                           |
+|                |                                                              |
+|                |     pacman -Sy mingw-w64                                     |
 +----------------+--------------------------------------------------------------+
 | **Debian** /   | ::                                                           |
 | **Ubuntu**     |                                                              |
@@ -200,8 +202,6 @@ here are some known ones:
 |                |           mingw32-gcc-c++ mingw32-winpthreads-static         |
 +----------------+--------------------------------------------------------------+
 
-.. _mingw-w64-gcc from the AUR: https://aur.archlinux.org/packages/mingw-w64-gcc/
-
 Before attempting the compilation, SCons will check for
 the following binaries in your ``PATH`` environment variable::