Merge branch 'master' into 3.2

.gitattributes

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

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: Continuous integration
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Lint and build documentation
+        run: |
+          # Install tools used by `_tools/format.sh`.
+          sudo apt-get update -qq
+          sudo apt-get install -qq dos2unix recode
+          # Append the `PATH` so we can run `codespell`.
+          export PATH="$HOME/.local/bin:$PATH"
+          pip3 install -r requirements.txt
+          pip3 install codespell
+          bash _tools/format.sh
+          codespell -I _tools/codespell-ignore.txt {about,community,development,getting_started,tutorials}/**/*.rst
+          # Use dummy builder to improve performance.
+          sphinx-build --color -b dummy -d _build/doctrees . _build/html

.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

_tools/format.sh

@@ -1,18 +1,21 @@
-#!/bin/bash
+#!/usr/bin/env bash
+
+set -uo pipefail
+IFS=$'\n\t'
 
 # Loops through all text files tracked by Git.
 git grep -zIl '' |
 while IFS= read -rd '' f; do
     # Exclude csproj and hdr files.
-    if [[ $f == *"csproj" ]]; then
+    if [[ "$f" == *"csproj" ]]; then
         continue
-    elif [[ $f == *"hdr" ]]; then
+    elif [[ "$f" == *"hdr" ]]; then
         continue
     fi
     # Ensures that files are UTF-8 formatted.
-    recode UTF-8 $f 2> /dev/null
+    recode UTF-8 "$f" 2> /dev/null
     # Ensures that files have LF line endings.
-    dos2unix $f 2> /dev/null
+    dos2unix "$f" 2> /dev/null
     # Ensures that files do not contain a BOM.
     sed -i '1s/^\xEF\xBB\xBF//' "$f"
     # Ensures that files end with newline characters.
@@ -20,7 +23,7 @@ while IFS= read -rd '' f; do
 done
 
 git diff > patch.patch
-FILESIZE=$(stat -c%s patch.patch)
+FILESIZE="$(stat -c%s patch.patch)"
 MAXSIZE=5
 
 # If no patch has been generated all is OK, clean up, and exit.

about/index.rst

@@ -8,6 +8,7 @@ About
    introduction
    faq
    docs_changelog
+   release_policy
 
 .. history
 .. authors

about/release_policy.rst

@@ -0,0 +1,84 @@
+.. _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.
+
+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.

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/introduction_to_the_buildsystem.rst

@@ -307,8 +307,8 @@ platform:
 
     android_debug.apk
     android_release.apk
-    javascript_debug.zip
-    javascript_release.zip
+    webassembly_debug.zip
+    webassembly_release.zip
     linux_server_32
     linux_server_64
     linux_x11_32_debug

development/cpp/binding_to_external_libraries.rst

@@ -75,7 +75,11 @@ need to be created:
     register_types.h
     register_types.cpp
 
-With the following contents:
+.. important::
+    These files must be in the top-level folder of your module (next to your
+    ``SCsub`` and ``config.py`` files) for the module to be registered properly.
+
+These files should contain the following:
 
 .. code-block:: cpp
 
@@ -124,8 +128,8 @@ installation commands for Linux below, for reference.
     apt-cache search festvox-* <-- Displays list of voice packages
     sudo apt-get install festvox-don festvox-rablpc16k festvox-kallpc16k festvox-kdlpc16k <-- Installs voices
 
-.. note::
-    **Important:** The voices that Festival uses (and any other potential external/3rd-party
+.. important::
+    The voices that Festival uses (and any other potential external/3rd-party
     resource) all have varying licenses and terms of use; some (if not most) of them may be
     be problematic with Godot, even if the Festival Library itself is MIT License compatible.
     Please be sure to check the licenses and terms of use.
@@ -148,8 +152,8 @@ can link to them instead by adding them as submodules (from within the modules/t
     git submodule add https://github.com/festvox/festival
     git submodule add https://github.com/festvox/speech_tools
 
-.. note::
-    **Important:** Please note that Git submodules are not used in the Godot repository.  If
+.. important::
+    Please note that Git submodules are not used in the Godot repository.  If
     you are developing a module to be merged into the main Godot repository, you should not
     use submodules.  If your module doesn't get merged in, you can always try to implement
     the external library as a GDNative C++ plugin.

development/cpp/common_engine_methods_and_macros.rst

@@ -0,0 +1,246 @@
+.. _doc_common_engine_methods_and_macros:
+
+Common engine methods and macros
+================================
+
+Godot's C++ codebase makes use of dozens of custom methods and macros which are
+used in almost every file. This page is geared towards beginner contributors,
+but it can also be useful for those writing custom C++ modules.
+
+Print text
+----------
+
+.. code-block:: cpp
+
+    // Prints a message to standard output.
+    print_line("Message");
+
+    // Prints a message to standard output, but only when the engine
+    // is started with the `--verbose` command line argument.
+    print_verbose("Message");
+
+    // Prints a formatted error or warning message with a trace.
+    ERR_PRINT("Message");
+    WARN_PRINT("Message");
+
+    // Prints an error or warning message only once per session.
+    // This can be used to avoid spamming the console output.
+    ERR_PRINT_ONCE("Message");
+    WARN_PRINT_ONCE("Message");
+
+If you need to add placeholders in your messages, use format strings as
+described below.
+
+Format a string
+---------------
+
+The ``vformat()`` function returns a formatted :ref:`class_String`. It behaves
+in a way similar to C's ``sprintf()``:
+
+.. code-block:: cpp
+
+    vformat("My name is %s.", "Godette");
+    vformat("%d bugs on the wall!", 1234);
+    vformat("Pi is approximately %f.", 3.1416);
+
+    // Converts the resulting String into a `const char *`.
+    // You may need to do this if passing the result as an argument
+    // to a method that expects a `const char *` instead of a String.
+    vformat("My name is %s.", "Godette").c_str();
+
+In most cases, try to use ``vformat()`` instead of string concatenation as it
+makes for more readable code.
+
+Convert an integer or float to a string
+---------------------------------------
+
+This is mainly useful when printing numbers directly.
+
+.. code-block:: cpp
+
+    // Prints "42" using integer-to-string conversion.
+    print_line(itos(42));
+
+    // Prints "123.45" using real-to-string conversion.
+    print_line(rtos(123.45));
+
+Internationalize a string
+-------------------------
+
+There are two types of internationalization in Godot's codebase:
+
+- ``TTR()``: **Editor ("tools") translations** will only be processed in the
+  editor. If an user uses the same text in one of their projects, it won't be
+  translated if they provide a translation for it. When contributing to the
+  engine, this is generally the macro you should use for localizable strings.
+- ``RTR()``: **Run-time translations** will be automatically localized in
+  projects if they provide a translation for the given string. This kind of
+  translation shouldn't be used in editor-only code.
+
+.. code-block:: cpp
+
+    // Returns the translated string that matches the user's locale settings.
+    // Translations are located in `editor/translations`.
+    // The localization template is generated automatically; don't modify it.
+    TTR("Exit the editor?");
+
+To insert placeholders in localizable strings, wrap the localization macro in a
+``vformat()`` call as follows:
+
+.. code-block:: cpp
+
+    String file_path = "example.txt";
+    vformat(TTR("Couldn't open \"%s\" for reading."), file_path);
+
+.. note::
+
+    When using ``vformat()`` and a translation macro together, always wrap the
+    translation macro in ``vformat()``, not the other way around. Otherwise, the
+    string will never match the translation as it will have the placeholder
+    already replaced when it's passed to TranslationServer.
+
+Clamp a value
+-------------
+
+Godot has provides macros for clamping a value with a lower bound (``MAX``), an
+upper bound (``MIN``) or both (``CLAMP``):
+
+.. code-block:: cpp
+
+    int a = 3;
+    int b = 5;
+
+    MAX(b, 6); // 6
+    MIN(2, a); // 2
+    CLAMP(a, 10, 30); // 10
+
+This works with any type that can be compared to other values (like ``int`` and
+``float``).
+
+Microbenchmarking
+-----------------
+
+If you want to benchmark a piece of code but don't know how to use a profiler,
+use this snippet:
+
+.. code-block:: cpp
+
+    uint64_t begin = OS::get_singleton()->get_ticks_usec();
+
+    // Your code here...
+
+    uint64_t end = OS::get_singleton()->get_ticks_usec();
+    print_line(vformat("Snippet took %d microseconds", end - begin));
+
+This will print the time spent between the ``begin`` declaration and the ``end``
+declaration.
+
+.. note::
+
+    You may have to ``#include "core/os/os.h"`` if it's not present already.
+
+    When opening a pull request, make sure to remove this snippet as well as the
+    include if it wasn't there previously.
+
+Get project/editor settings
+---------------------------
+
+There are four macros available for this:
+
+.. code-block:: cpp
+
+    // Returns the specified project setting's value,
+    // defaulting to `false` if it doesn't exist.
+    GLOBAL_DEF("section/subsection/value", false);
+
+    // Returns the specified editor setting's value,
+    // defaulting to "Untitled" if it doesn't exist.
+    EDITOR_DEF("section/subsection/value", "Untitled");
+
+If a default value has been specified elsewhere, don't specify it again to avoid
+repetition:
+
+.. code-block:: cpp
+
+    // Returns the value of the project setting.
+    GLOBAL_GET("section/subsection/value");
+    // Returns the value of the editor setting.
+    EDITOR_GET("section/subsection/value");
+
+It's recommended to use ``GLOBAL_DEF``/``EDITOR_DEF`` only once per setting and
+use ``GLOBAL_GET``/``EDITOR_GET`` in all other places where it's referenced.
+
+Error macros
+------------
+
+Godot features many error macros to make error reporting more convenient.
+
+.. warning::
+
+    Conditions in error macros work in the **opposite** way of GDScript's
+    built-in ``assert()`` function. An error is reached if the condition inside
+    evaluates to ``true``, not ``false``.
+
+.. note::
+
+    Only variants with custom messages are documented here, as these should
+    always be used in new contributions. Make sure the custom message provided
+    includes enough information for people to diagnose the issue, even if they
+    don't know C++. In case a method was passed invalid arguments, you can print
+    the invalid value in question to ease debugging.
+
+    For internal error checking where displaying a human-readable message isn't
+    necessary, remove ``_MSG`` at the end of the macro name and don't supply a
+    message argument.
+
+    Also, always try to return processable data so the engine can keep running
+    well.
+
+.. code-block:: cpp
+
+    // Conditionally prints an error message and returns from the function.
+    // Use this in methods which don't return a value.
+    ERR_FAIL_COND_MSG(!mesh.is_valid(), vformat("Couldn't load mesh at: %s", path));
+
+    // Conditionally prints an error message and returns `0` from the function.
+    // Use this in methods which must return a value.
+    ERR_FAIL_COND_V_MSG(rect.x < 0 || rect.y < 0, 0,
+            "Couldn't calculate the rectangle's area.");
+
+    // Prints an error message if `index` is < 0 or >= `SomeEnum::QUALITY_MAX`,
+    // then returns from the function.
+    ERR_FAIL_INDEX_MSG(index, SomeEnum::QUALITY_MAX,
+            vformat("Invalid quality: %d. See SomeEnum for allowed values.", index));
+
+    // Prints an error message if `index` is < 0 >= `some_array.size()`,
+    // then returns `-1` from the function.
+    ERR_FAIL_INDEX_V_MSG(index, some_array.size(), -1,
+            vformat("Item %d is out of bounds.", index));
+
+    // Unconditionally prints an error message and returns from the function.
+    // Only use this if you need to perform complex error checking.
+    if (!complex_error_checking_routine()) {
+        ERR_FAIL_MSG("Couldn't reload the filesystem cache.");
+    }
+
+    // Unconditionally prints an error message and returns `false` from the function.
+    // Only use this if you need to perform complex error checking.
+    if (!complex_error_checking_routine()) {
+        ERR_FAIL_V_MSG(false, "Couldn't parse the input arguments.");
+    }
+
+    // Crashes the engine. This should generally never be used
+    // except for testing crash handling code. Godot's philosophy
+    // is to never crash, both in the editor and in exported projects.
+    CRASH_NOW_MSG("Can't predict the future! Aborting.");
+
+
+.. seealso::
+
+    See `core/error_macros.h <https://github.com/godotengine/godot/blob/master/core/error_macros.h>`__
+    in Godot's codebase for more information about each error macro.
+
+    Some functions return an error code (materialized by a return type of
+    ``Error``). This value can be returned directly from an error macro.
+    See the list of available error codes in
+    `core/error_list.h <https://github.com/godotengine/godot/blob/master/core/error_list.h>`__.

development/cpp/custom_modules_in_cpp.rst

@@ -119,7 +119,11 @@ need to be created:
     register_types.h
     register_types.cpp
 
-With the following contents:
+.. important::
+    These files must be in the top-level folder of your module (next to your
+    ``SCsub`` and ``config.py`` files) for the module to be registered properly.
+
+These files should contain the following:
 
 .. code-block:: cpp
 
@@ -347,7 +351,7 @@ library that will be dynamically loaded when starting our game's binary.
     # next to the Godot binary.
     shared_lib = module_env.SharedLibrary(target='#bin/summator', source=sources)
 
-    # Finally, notify the main env it has our shared lirary as a new dependency.
+    # Finally, notify the main env it has our shared library as a new dependency.
     # To do so, SCons wants the name of the lib with it custom suffixes
     # (e.g. ".x11.tools.64") but without the final ".so".
     # We pass this along with the directory of our library to the main env.
@@ -365,8 +369,9 @@ during runtime with the ``LD_LIBRARY_PATH`` environment variable:
     export LD_LIBRARY_PATH="$PWD/bin/"
     ./bin/godot*
 
-**note**: Pay attention you have to ``export`` the environ variable otherwise
-you won't be able to play your project from within the editor.
+.. note::
+  You have to ``export`` the environment variable otherwise
+  you won't be able to play your project from within the editor.
 
 On top of that, it would be nice to be able to select whether to compile our
 module as shared library (for development) or as a part of the Godot binary

development/cpp/index.rst

@@ -7,6 +7,7 @@ Engine development
 
    introduction_to_godot_development
    configuring_an_ide/index
+   common_engine_methods_and_macros
    core_types
    variant_class
    object_class

development/cpp/object_class.rst

@@ -66,13 +66,13 @@ Registering functions is one:
 
 .. code-block:: cpp
 
-    ClassDB::register_method(D_METHOD("methodname", "arg1name", "arg2name"), &MyCustomMethod);
+    ClassDB::bind_method(D_METHOD("methodname", "arg1name", "arg2name"), &MyCustomMethod);
 
 Default values for arguments can be passed in reverse order:
 
 .. code-block:: cpp
 
-    ClassDB::register_method(D_METHOD("methodname", "arg1name", "arg2name"), &MyCustomType::method, DEFVAL(-1)); // default value for arg2name
+    ClassDB::bind_method(D_METHOD("methodname", "arg1name", "arg2name"), &MyCustomType::method, DEFVAL(-1)); // default value for arg2name
 
 ``D_METHOD`` is a macro that converts "methodname" to a StringName for more
 efficiency. Argument names are used for introspection, but when
@@ -223,7 +223,7 @@ languages). Connecting to them is rather easy:
     obj->connect("enter_tree", this, "_node_entered_tree")
 
 The method ``_node_entered_tree`` must be registered to the class using
-``ClassDB::register_method`` (explained before).
+``ClassDB::bind_method`` (explained before).
 
 Adding signals to a class is done in ``_bind_methods``, using the
 ``ADD_SIGNAL`` macro, for example:

development/editor/editor_style_guide.rst

@@ -0,0 +1,98 @@
+.. _doc_editor_style_guide:
+
+Editor style guide
+==================
+
+Introduction
+------------
+
+Thanks for your interest in contributing to the Godot editor!
+
+This page describes the grammar and writing style used throughout the Godot
+editor. Following this style guide will help your contribution get merged faster
+since there will be fewer review steps required.
+
+Writing style
+-------------
+
+- **Write messages (errors, warnings, ...) as full sentences.** They should start
+  with an uppercase letter and end with a period.
+- **Try to keep sentences short.** This makes it more likely that their translations
+  will be short as well, which is a good thing to avoid UI bugs.
+- **Use contractions.** For example, use "isn't" instead of "is not". An exception
+  to this rule can be made when you specifically want to emphasize one of the
+  contraction's words.
+- **Use double quotes in messages** (``""``) instead of simple quotes (``''``).
+  Double quotes should be used to quote user input, file paths and possibly
+  other things depending on the context.
+
+.. seealso::
+
+    Try to follow the :ref:`doc_docs_writing_guidelines` in addition to the
+    guidelines outlined above.
+
+Button and menu texts
+---------------------
+
+Capitalize text in buttons and menu actions:
+
+- **Good:** *Open Editor Data Folder*
+- **Bad:** *Open editor data folder*
+
+If a menu action opens a modal dialog, suffix it with an ellipsis (``...``).
+
+- **Good:** *Editor Settings...*
+- **Bad:** *Editor Settings*
+
+Inspector sections
+------------------
+
+In general, don't create sections that contain less than 3 items. Sections that
+contain few items make it difficult to navigate the inspector, while missing the
+benefits of using sections such as folding.
+
+There are some valid exceptions for this, such as material features in
+:ref:`class_StandardMaterial3D`.
+
+This advice also applies to the Project Settings and Editor Settings.
+
+Inspector performance hints
+---------------------------
+
+Enum properties that noticeably impact performance should have a performance
+hint associated. The hint should refer to the *absolute* performance impact,
+rather than being relative to the other options provided in the enum. Here are
+some examples taken from the Godot editor:
+
+- **Screen-space antialiasing:** *Disabled (Fastest), FXAA (Fast)*
+- **MSAA quality:** *Disabled (Fastest), 2x (Fast), 4x (Average), 8x (Slow), 16x
+  (Slower)*
+- **DirectionalLight mode:** *Orthogonal (Fast), PSSM 2 Splits
+  (Average), PSSM 4 Splits (Slow)*
+
+For consistency, try to stick to the terms below (from fastest to slowest):
+
+- *Fastest, Faster, Fast, Average, Slow, Slower, Slowest*
+
+Their usage doesn't have to be contiguous. For example, you can use only "Fast"
+and "Slow" from the list above.
+
+If you're adding a new enum, its values should be ordered from the fastest
+option to the slowest option.
+
+Tooltips
+--------
+
+Consider adding tooltips whenever the action performed by a button or menu
+action isn't obvious. You can also provide additional context or highlight
+caveats in the tooltip.
+
+You can do this by calling ``set_tooltip(TTR("Text here."))`` on the
+Control-based node in question. If the tooltip is particularly long (more than
+~80 characters), wrap it over several lines by adding line breaks using ``\n``.
+
+Tooltips should follow the writing style described above. In addition to this,
+use indicative mood instead of imperative mood:
+
+- **Good:** *Computes global illumination for the selected GIProbe.*
+- **Bad:** *Compute global illumination for the selected GIProbe.*

development/editor/index.rst

@@ -6,3 +6,4 @@ Editor development
    :name: toc-devel-editor
 
    creating_icons
+   editor_style_guide

getting_started/scripting/c_sharp/c_sharp_basics.rst

@@ -1,7 +1,10 @@
 .. _doc_c_sharp:
 
+C# basics
+=========
+
 Introduction
-============
+------------
 
 .. warning:: C# support is a new feature available since Godot 3.0.
              As such, you may still run into some issues, or find spots
@@ -141,29 +144,6 @@ version control system. ``.mono`` can be safely added to the ignore list of your
 When troubleshooting, it can sometimes help to delete the ``.mono`` folder
 and let it regenerate.
 
-Note that currently, there are some issues where Godot and the C# project
-don't stay in sync; if you delete, rename or move a C# script, the change
-may not be reflected in the C# project file.
-In cases like this, you will have to edit the C# project file manually.
-
-For example, if you created a script (e.g. ``Test.cs``) and delete it in Godot,
-compilation will fail because the missing file is still expected to be there
-by the C# project file. For now, you can simply open up the ``.csproj`` file
-and look for the ``ItemGroup``, there should be a line included
-like the following:
-
-.. code-block:: xml
-    :emphasize-lines: 2
-
-    <ItemGroup>
-        <Compile Include="Test.cs" />
-        <Compile Include="AnotherTest.cs" />
-    </ItemGroup>
-
-Simply remove that line and your project should build correctly again.
-Same for renaming and moving things, simply rename and move them
-in the project file if needed.
-
 Example
 -------
 
@@ -224,15 +204,9 @@ you should be aware of when diving into C# in Godot, but if in doubt, also
 take a look over the official
 `issue tracker for Mono issues <https://github.com/godotengine/godot/labels/topic%3Amono>`_.
 
-- As explained above, the C# project isn't always kept in sync automatically
-  when things are deleted, renamed or moved in Godot
-  (`#12917 <https://github.com/godotengine/godot/issues/12917>`_).
 - Writing editor plugins is possible, but it is currently quite convoluted.
 - State is currently not saved and restored when hot-reloading,
   with the exception of exported variables.
-- Exporting Mono projects is supported for desktop platforms
-  (Linux, Windows and macOS), Android, HTML5, and iOS. UWP is not currently supported.
-  (`#20271 <https://github.com/godotengine/godot/issues/20271>`_).
 - Attached C# scripts should refer to a class that has a class name
   that matches the file name.
 - There are some methods such as ``Get()``/``Set()``, ``Call()``/``CallDeferred()``
@@ -242,6 +216,11 @@ take a look over the official
   the API is expecting the original ``snake_case`` version ``add_child``. However, you
   can use any custom properties or methods without this limitation.
 
+
+As of Godot 3.2.2, exporting Mono projects is supported for desktop platforms
+(Linux, Windows and macOS), Android, HTML5, and iOS. The only platform not
+supported yet is UWP.
+
 Performance of C# in Godot
 --------------------------
 

getting_started/scripting/c_sharp/c_sharp_differences.rst

@@ -1,7 +1,7 @@
 .. _doc_c_sharp_differences:
 
-API differences to GDScript
-===========================
+C# API differences to GDScript
+==============================
 
 This is a (incomplete) list of API differences between C# and GDScript.
 

getting_started/scripting/c_sharp/c_sharp_features.rst

@@ -1,7 +1,7 @@
 .. _doc_c_sharp_features:
 
-Features
-========
+C# features
+===========
 
 This page provides an overview of the commonly used features of both C# and Godot
 and how they are used together.

getting_started/scripting/gdscript/gdscript_basics.rst

@@ -861,7 +861,7 @@ Basic syntax::
 
 The patterns are matched from top to bottom.
 If a pattern matches, the first corresponding block will be executed. After that, the execution continues below the ``match`` statement.
-If you want to have a fallthrough, you can use ``continue`` to stop execution in the current block and check for an additional match in the patterns below it.
+You can use ``continue`` to stop execution in the current block and check for an additional match in the patterns below it.
 
 There are 6 pattern types:
 

getting_started/step_by_step/instancing.rst

@@ -90,14 +90,8 @@ Run the scene again and all of the balls will fall.
 Editing instances
 -----------------
 
-Open the ``Ball`` scene and add a ``PhysicsMaterial`` by opening the "Physics
-Material Override" dropdown in the Inspector dock and selecting "New
-PhysicsMaterial".
-
-.. image:: img/instancing_physicsmat1.png
-
-Then, expand the material by clicking on it, and set the ``Bounce`` property
-to ``1``.
+Open the ``Ball`` scene, expand the ``PhysicsMaterial`` by clicking on it,
+and set the ``Bounce`` property to ``1``.
 
 .. image:: img/instancing_physicsmat2.png
 

getting_started/step_by_step/intro_to_the_editor_interface.rst

@@ -135,7 +135,7 @@ related to the 3D viewport.
 
 The **Script** workspace is a complete code editor with a debugger, rich
 auto-completion, and built-in code reference. Press :kbd:`F3` (or :kbd:`Alt + 3` on macOS)
-to access it, and :kbd:`F4` to search the reference.
+to access it, and :kbd:`Shift + F1` to search the reference.
 
 .. image:: img/editor_ui_intro_editor_06_script_workspace_expanded.png
 

getting_started/step_by_step/resources.rst

@@ -152,7 +152,7 @@ Creating your own resources
 
 Like any Object in Godot, users can also script Resources. Resource scripts
 inherit the ability to freely translate between object properties and serialized
-text or binary data (/*.tres, /*.res). They also inherit the reference-counting
+text or binary data (\*.tres, \*.res). They also inherit the reference-counting
 memory management from the Reference type.
 
 This comes with many distinct advantages over alternative data

getting_started/step_by_step/your_first_game.rst

@@ -449,7 +449,7 @@ We want ``Player`` to detect when it's hit by an enemy, but we haven't
 made any enemies yet! That's OK, because we're going to use Godot's
 *signal* functionality to make it work.
 
-Add the following at the top of the script, after ``extends Area2d``:
+Add the following at the top of the script, after ``extends Area2D``:
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -629,8 +629,9 @@ choose one of the three animation types:
 
     public override void _Ready()
     {
-        var _mobTypes = GetNode<AnimatedSprite>("AnimatedSprite").Frames.GetAnimationNames();
-        GetNode<AnimatedSprite>("AnimatedSprite").Animation = _mobTypes[_random.Next(0, _mobTypes.Length)];
+        var animSprite = GetNode<AnimatedSprite>("AnimatedSprite");
+        var mobTypes = animSprite.Frames.GetAnimationNames();
+        animSprite.Animation = mobTypes[_random.Next(0, mobTypes.Length)];
     }
 
 First, we get the list of animation names from the AnimatedSprite's ``frames``
@@ -877,7 +878,7 @@ Note that a new instance must be added to the scene using ``add_child()``.
     {
         // Choose a random location on Path2D.
         var mobSpawnLocation = GetNode<PathFollow2D>("MobPath/MobSpawnLocation");
-        mobSpawnLocation.SetOffset(_random.Next());
+        mobSpawnLocation.Offset = _random.Next();
 
         // Create a Mob instance and add it to the scene.
         var mobInstance = (RigidBody2D)Mob.Instance();
@@ -894,7 +895,7 @@ Note that a new instance must be added to the scene using ``add_child()``.
         mobInstance.Rotation = direction;
 
         // Choose the velocity.
-        mobInstance.SetLinearVelocity(new Vector2(RandRange(150f, 250f), 0).Rotated(direction));
+        mobInstance.LinearVelocity = new Vector2(RandRange(150f, 250f), 0).Rotated(direction);
     }
 
 .. important:: Why ``PI``? In functions requiring angles, GDScript uses *radians*,

getting_started/workflow/assets/importing_scenes.rst

@@ -61,7 +61,8 @@ Blender has built-in COLLADA support, but it does not work properly for the need
 and should not be used as is.
 
 Godot provides a `Blender plugin <https://github.com/godotengine/collada-exporter>`_
-that will correctly export COLLADA scenes for use in Godot.
+that will correctly export COLLADA scenes for use in Godot. It does not work in Blender 2.8 or
+newer, but there are plans to update it in the future.
 
 Exporting ESCN files from Blender
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -69,7 +70,8 @@ Exporting ESCN files from Blender
 The most powerful one, called `godot-blender-exporter
 <https://github.com/godotengine/godot-blender-exporter>`__.
 It uses a .escn file, which is kind of another name for a .tscn file (Godot scene file);
-it keeps as much information as possible from a Blender scene.
+it keeps as much information as possible from a Blender scene. However, it is considered
+experimental.
 
 The ESCN exporter has a detailed `document <escn_exporter/index.html>`__ describing
 its functionality and usage.

getting_started/workflow/best_practices/introduction_best_practices.rst

@@ -18,8 +18,8 @@ each problem in fundamental questions, suggest solutions, analyze the pros and
 cons of each option, and highlight the best course of action for the problem at hand.
 
 You should start by reading :ref:`doc_what_are_godot_classes`. It explains how
-Godot's nodes and scenes relate to classes and objects in another
-Object-Oriented programming language. It will help you make sense of the rest of the series.
+Godot's nodes and scenes relate to classes and objects in other
+Object-Oriented programming languages. It will help you make sense of the rest of the series.
 
 .. note::
 

getting_started/workflow/best_practices/scene_organization.rst

@@ -13,12 +13,12 @@ How to build relationships effectively
 When Godot users begin crafting their own scenes, they often run into the
 following problem:
 
-They create their first scene and fill it with content before the creeping
-sense that they need to split it up into re-usable pieces haunts them. They
-save branches of their scene into their own scene. However, they then notice
-that the hard references they were able to rely on before are no longer
+They create their first scene and fill it with content only to eventually end
+up saving branches of their scene into separate scenes as the nagging feeling
+that they should split things up starts to accumulate. However, they then
+notice that the hard references they were able to rely on before are no longer
 possible. Re-using the scene in multiple places creates issues because the
-node paths do not find their targets. Signal connections established in the
+node paths do not find their targets and signal connections established in the
 editor break.
 
 To fix these problems, one must instantiate the sub-scenes without them
@@ -30,10 +30,9 @@ One of the biggest things to consider in OOP is maintaining
 focused, singular-purpose classes with
 `loose coupling <https://en.wikipedia.org/wiki/Loose_coupling>`_
 to other parts of the codebase. This keeps the size of objects small (for
-maintainability) and improves their reusability so that re-writing completed
-logic is unnecessary.
+maintainability) and improves their reusability.
 
-These OOP best practices have *several* ramifications for the best practices
+These OOP best practices have *several* implications for best practices
 in scene structure and script usage.
 
 **If at all possible, one should design scenes to have no dependencies.**
@@ -50,7 +49,7 @@ environment can inadvertently trigger bugs and unexpected behavior.
 To do this, one must expose data and then rely on a parent context to
 initialize it:
 
-1. Connect to a signal. Extremely safe, but should use only to "respond" to
+1. Connect to a signal. Extremely safe, but should be used only to "respond" to
    behavior, not start it. Note that signal names are usually past-tense verbs
    like "entered", "skill_activated", or "item_collected".
 
@@ -148,7 +147,7 @@ initialize it:
        // Child
        GetNode(TargetPath); // Use parent-defined NodePath.
 
-These options hide the source of accesses from the child node. This in turn
+These options hide the points of access from the child node. This in turn
 keeps the child **loosely coupled** to its environment. One can re-use it
 in another context without any extra changes to its API.
 
@@ -234,12 +233,14 @@ in another context without any extra changes to its API.
 
 So, why do all this complex switcharoo work? Well, because scenes operate
 best when they operate alone. If unable to work alone, then working with
-others anonymously (with minimal hard dependencies, i.e. loose coupling).
-If the inevitable changes made to a class cause it to interact with other
-scenes in unforeseen ways, then things break down. A change to one class could
-result in damaging effects to other classes.
-
-Scripts and scenes, as extensions of engine classes should abide
+others anonymously (with minimal hard dependencies, i.e. loose coupling)
+is the next best thing. Inevitably, changes may need to be made to a class and
+if these changes cause it to interact with other scenes in unforeseen ways,
+then things will start to break down. The whole point of all this indirection
+is to avoid ending up in a situation where changing one class results in
+adversely effecting other classes.
+
+Scripts and scenes, as extensions of engine classes, should abide
 by *all* OOP principles. Examples include...
 
 - `SOLID <https://en.wikipedia.org/wiki/SOLID>`_
@@ -259,7 +260,7 @@ a decent structure to start with.
 
 A game should always have a sort of "entry point"; somewhere the developer can
 definitively track where things begin so that they can follow the logic as it
-continues elsewhere. This place also serves as a bird's eye view to all of the
+continues elsewhere. This place also serves as a bird's eye view of all of the
 other data and logic in the program. For traditional applications, this would
 be the "main" function. In this case, it would be a Main node.
 
@@ -298,7 +299,7 @@ If one has a system that...
   the "World" as the main game node.
 
   Any GUI would need to also be a
-  singleton, be transitory parts of the "World", or be manually added as a
+  singleton; be a transitory part of the "World"; or be manually added as a
   direct child of the root. Otherwise, the GUI nodes would also delete
   themselves during scene transitions.
 
@@ -328,9 +329,9 @@ own place in the hierarchy as a sibling or some other relation.
   2. A group, to easily pull a reference to the desired node (assuming there
      will only ever be one of the targets).
 
-  When should one do this? Well, it's up to them to decide. The dilemma
-  arises when one must micro-manage when a node must move around the SceneTree
-  to preserve itself. For example...
+  When should one do this? Well, this is subjective. The dilemma arises when
+  one must micro-manage when a node must move around the SceneTree to preserve
+  itself. For example...
 
   - Add a "player" node to a "room".
   - Need to change rooms, so one must delete the current room.
@@ -348,7 +349,7 @@ own place in the hierarchy as a sibling or some other relation.
     - Instantiate and add the new room.
     - Re-add the player.
 
-  The issue is that the player here is a "special case", one where the
+  The issue is that the player here is a "special case"; one where the
   developers must *know* that they need to handle the player this way for the
   project. As such, the only way to reliably share this information as a team
   is to *document* it. Keeping implementation details in documentation however
@@ -356,7 +357,7 @@ own place in the hierarchy as a sibling or some other relation.
   the intellectual content of a project unnecessarily.
 
   In a more complex game with larger assets, it can be a better idea to simply
-  keep the player somewhere else in the SceneTree entirely. This involves...
+  keep the player somewhere else in the SceneTree entirely. This results in:
 
   1. More consistency.
   2. No "special cases" that must be documented and maintained somewhere.
@@ -384,10 +385,10 @@ own place in the hierarchy as a sibling or some other relation.
   of game connections and the like.
 
 The key to scene organization is to consider the SceneTree in relational terms
-rather than spatial terms. Do the nodes need to be dependent on their parent's
-existence? If not, then they can thrive all by themselves somewhere else.
-If so, then it stands to reason they should be children of that parent (and
-likely part of that parent's scene if they aren't already).
+rather than spatial terms. Are the nodes dependent on their parent's existance?
+If not, then they can thrive all by themselves somewhere else.
+If they are dependent, then it stands to reason that they should be children of
+that parent (and likely part of that parent's scene if they aren't already).
 
 Does this mean nodes themselves are components? Not at all.
 Godot's node trees form an aggregation relationship, not one of composition.

getting_started/workflow/best_practices/what_are_godot_classes.rst

@@ -10,7 +10,7 @@ while scripts can contain `imperative code
 <https://en.wikipedia.org/wiki/Imperative_programming>`_.
 
 As a result, many best practices in Godot boil down to applying Object-Oriented
-design principles to the scenes, nodes, or script that make up your game.
+design principles to the scenes, nodes, or scripts that make up your game.
 
 This guide explains how scripts and scenes work in the engine's core, to help
 you get a sense of how Godot works under the hood, and to help you better
@@ -127,7 +127,7 @@ The content of a scene helps to define:
 
 - What nodes are available to the script
 - How they are organized
-- How are they initialized
+- How they are initialized
 - What signal connections they have with each other
 
 Many Object-Oriented principles which apply to written code *also* apply to

getting_started/workflow/export/exporting_for_android.rst

@@ -14,12 +14,11 @@ Download and install the Android SDK from
 
 If you install Android Studio, you need to run it once to complete the SDK setup.
 
-Install OpenJDK or Oracle JDK
------------------------------
+Install OpenJDK 8
+-----------------
 
-Download and install  `OpenJDK <https://github.com/ojdkbuild/ojdkbuild>`__ or `Oracle JDK <http://www.oracle.com/technetwork/java/javase/downloads/index.html>`__. Versions below JDK 8 may not work; some users have reported issues with the jarsigner (used to sign the APKs) in JDK 7.
-
-If you install OpenJDK, choose ``1.8``. Don't choose the ``openjdk-jre`` files as that only contains the JRE, not the JDK which is required here.
+Download and install  `OpenJDK 8 <https://adoptopenjdk.net/index.html?variant=openjdk8&jvmVariant=hotspot>`__,
+newer versions do not work.
 
 Create a debug.keystore
 -----------------------

getting_started/workflow/export/exporting_for_web.rst

@@ -108,6 +108,12 @@ The default HTML page does not display the boot splash while loading. However,
 the image is exported as a PNG file, so :ref:`custom HTML pages <doc_customizing_html5_shell>`
 can display it.
 
+Shader language limitations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When exporting a GLES2 project to HTML5, WebGL 1.0 will be used. WebGL 1.0
+doesn't support dynamic loops, so shaders using those won't work there.
+
 Unimplemented functionality
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

getting_started/workflow/export/exporting_projects.rst

@@ -107,28 +107,16 @@ Export mode
 When exporting, Godot makes a list of all the files to export and then
 creates the package. There are 3 different modes for exporting:
 
--  Export every single file in the project
--  Export only resources (+ custom filter), this is the default.
--  Export only selected resources (+ custom filter)
+-  Export all resources in the project
+-  Export selected scenes (and dependencies)
+-  Export selected resources (and dependencies)
 
 .. image:: img/expres.png
 
--  **Export every single file** - This mode exports every single file in
-   the project. This is good to test if something is being forgotten,
-   but developers often have a lot of unrelated stuff around in the project
-   directory, which makes it a bad idea.
-
--  **Export only resources** - Only resources are exported. For most
-   projects, this is enough. However many developers like to use custom
-   datafiles in their games. To compensate for this, filters can be
-   added for extra extensions (for instance, ``*.txt,*.csv``).
-
--  **Export only selected resources** - Only select resources from a
-   list are exported. This is probably overkill for most projects, but
-   in some cases it is justified (usually huge projects). This mode
-   offers total control of what is exported. Individual resources can be
-   selected and dependency detection is performed to ensure that
-   everything needed is added.
+**Export all resources in the project** will export every resource in the
+project. **Export selected scenes** and **Export selected resources** gives
+you a list of the scenes or resources in the project, and you have to
+select every scene or resource you want to export.
 
 .. image:: img/expselected.png
 

getting_started/workflow/project_setup/project_organization.rst

@@ -44,6 +44,23 @@ They can then use a separate folder to store built levels that use them.
     /characters/npcs/suzanne/suzanne.png
     /levels/riverdale/riverdale.scn
 
+Style guide
+-----------
+
+For consistency across projects, we recommend following these guidelines:
+
+- Use **snake_case** for folder and file names (with the exception of C#
+  scripts). This sidesteps case sensitivity issues that can crop up after
+  exporting a project on Windows. C# scripts are an exception to this rule,
+  as the convention is to name them after the class name which should be
+  in PascalCase.
+- Use **PascalCase** for node names, as this matches built-in node casing.
+- In general, keep third-party resources in a top-level ``addons/`` folder, even
+  if they aren't editor plugins. This makes it easier to track which files are
+  third-party. There are some exceptions to this rule; for instance, if you use
+  third-party game assets for a character, it makes more sense to include them
+  within the same folder as the character scenes and scripts.
+
 Importing
 ---------
 

tutorials/2d/using_tilemaps.rst

@@ -1,7 +1,7 @@
 .. _doc_using_tilemaps:
 
 Using tilemaps
-~~~~~~~~~~~~~~
+==============
 
 Introduction
 ------------
@@ -81,8 +81,8 @@ TileSet".
 
 .. image:: img/tilemap_add_tileset.png
 
-When you do this, the "TileSet" panel will open at the bottom of the editor
-window:
+Click on the TileSet property, and the "TileSet" panel will open at the bottom
+of the editor window:
 
 .. image:: img/tilemap_tool.png
 
@@ -127,8 +127,10 @@ Atlas tiles
 -----------
 
 Rather than adding individual tiles one at a time, you can define a group of
-tiles all at once using an atlas. Click "New Atlas" and drag to select the
-entire tile sheet.
+tiles all at once using an atlas. This also allows you to randomly generate
+tiles from the group.
+
+Click "New Atlas" and drag to select the entire tile sheet.
 
 .. image:: img/tileset_atlas.png
 
@@ -150,6 +152,121 @@ tiles it contains:
 In addition to saving time when defining the tiles, this can help by grouping
 similar tiles together when you're working with a large number of tiles.
 
+Random tile priorities
+~~~~~~~~~~~~~~~~~~~~~~
+
+When drawing with atlas tiles, enabling the "Use priority" option causes tiles
+to be selected at random. By default, each tile in the tileset has an equal
+likelihood of occurring. You can change the likelihood by setting different
+priorities for each tile. For example, a tile with priority 2 is twice as
+likely to be selected as a tile with priority 1, and a tile with priority 3 is
+50% more likely to be selected than a tile with priority 2.
+
+Autotiles
+---------
+
+Autotiles allow you to define a group of tiles, then add rules to control which
+tile gets used for drawing based on the content of adjacent cells.
+
+Click "New Autotile" and drag to select the tiles you wish to use. You can add
+collisions, occlusion, navigation shapes, tile priorties, and select an icon
+tile in the same manner as for atlas tiles.
+
+Tile selection is controlled by bitmasks. Bitmasks can be added by clicking
+"Bitmask", then clicking parts of the tiles to add or remove bits in the mask.
+Left-clicking an area of the tile adds a bit, right-click removes "off",
+and shift-left-click sets an "ignore" bit.
+
+Whenever Godot updates a cell using an autotile, it first creates a pattern
+based on which adjacent cells are already set. Then, it searches the autotile
+for a single tile with a bitmask matching the created pattern. If no matching
+bitmask is found, the "icon" tile will be used instead. If more than one
+matching bitmask is found, one of them will be selected randomly, using the
+tile priorities.
+
+The rules for matching a bitmask to a pattern depend on the tileset's autotile
+bitmask mode. This can be set in the "Inspector" tab, under the "Selected Tile"
+heading. Allowed values are "2x2", "3x3 (minimal)", and "3x3".
+
+All "on" and "off" bits must be satisfied for a bitmask to match, but "ignore"
+bits are ignored.
+
+2x2
+~~~
+
+In 2x2 mode, each bitmask contains four bits, one for each corner.
+
+Where a bit is "on", all cells connected to that corner must be filled using
+the same autotile, in order for the bitmask to match.
+For example, if the top-left bit is set, the cell directly above,
+directly left, and diagonally above-left must be filled.
+
+Where a bit is "off", at least one cell connected to that corner must not be
+set using the same autotile.
+
+At least one bit must be set for the tile to be used, so a total of 15 tiles
+would be needed to provide exactly one tile for each arrangement that this mode
+can test for.
+
+2x2 mode can only match cells that are part of a 2-by-2 block - cells with no
+neighbors and lines only one cell wide are not supported.
+
+3x3 (minimal)
+~~~~~~~~~~~~~
+
+In 3x3 (minimal) mode, each bitmask contains 9 bits (4 corners, 4 edges,
+1 center).
+
+The 4 corner bits work the same as in 2x2 mode.
+
+When an edge bit is "on", the cell which shares that edge must be filled.
+When an edge bit is "off", the cell which shares that edge must be empty.
+
+The center bit should be "on" for any tile you wish to use.
+
+Note that in this mode, it makes no sense for a corner bit to be "on" when
+either edge bit adjacent to it is not "on".
+
+A total of 47 tiles would be needed to provide exactly one bitmask for each
+arrangement that this mode can test for.
+
+
+3x3
+~~~
+
+In 3x3 mode, each bitmaks contains 9 bits (4 corners, 4 edges, 1 center)
+
+Each bit checks a single adjacent cell. Corner bits only check diagonally
+adjacent cells. The center bit should be "on" for any tile you wish to use.
+
+A total of 256 tiles would be needed to provide exactly one bitmask for each
+arrangement that this mode can test for.
+
+
+Disabling autotile
+~~~~~~~~~~~~~~~~~~
+
+When using an autotile, it is possible to turn of the autotile behaviour and
+select tiles manually, by clicking "Disable Autotile" at the top of the tile
+selection window.
+
+Autotile binding
+~~~~~~~~~~~~~~~~
+
+By default, autotile only checks for adjacent cells filled using the same
+autotile. This behaviour can be overridden in order to have autotiles bind to
+each other, or even bind to empty cells. At present, this can only be done
+through scripting. You will need to add a script to your tileset, and define
+a function named "_is_tile_bound(drawn_id, neighbor_id)". This function will
+be called for each adjacent cell that does not contain the same autotile, and
+should return true if you want the drawn cell to "bind" to the neighbor cell.
+You can find the id of an autotile using "find_tile_by_name(name)", empty cells
+are given an id of -1.
+
+Note that to use this in the editor, the script should start with a "tool"
+declaration, and you may need to close and reload the scene for these changes
+to take effect.
+
 Tips and tricks
 ---------------
 

tutorials/3d/fps_tutorial/part_one.rst

@@ -518,7 +518,7 @@ The space in which an object's position is the origin of the universe. Because t
 of the origin can be at ``N`` many locations, the values derived from local space change
 with the position of the origin.
 
-.. note:: This stack overflow question has a much better explanation of world space and local space.
+.. note:: This question from Game Development Stack Exchange has a much better explanation of world space and local space.
 
           https://gamedev.stackexchange.com/questions/65783/what-are-world-space-and-eye-space-in-game-development
           (Local space and eye space are essentially the same thing in this context)

tutorials/audio/audio_buses.rst

@@ -32,7 +32,7 @@ For those unfamiliar with it, it can be explained with a few facts:
   This limit is not the human limit, but a limit from the sound hardware.
   Audio with amplitudes that are too high to be represented properly below 0 dB
   create a kind of distortion called *clipping*.
-- To avoid clipping, your sound mix be arranged so that the output of the
+- To avoid clipping, your sound mix should be arranged so that the output of the
   *master bus* (more on that later) never exceeds 0 dB.
 - Every 6 dB below the 0 dB limit, sound energy is *halved*.
   It means the sound volume at -6 dB is half as loud as 0dB.

tutorials/debug/debugger_panel.rst

@@ -0,0 +1,105 @@
+.. _doc_debugger_panel:
+
+Debugger panel
+==============
+
+Many of Godot's debugging tools, including the debugger, can be found in the
+debugger panel at the bottom of the screen. Click on **Debugger** to open it.
+
+.. image:: img/overview_debugger.png
+
+The debugger panel is split into several tabs, each focusing on a specific task.
+
+Debugger
+++++++++
+
+The Debugger tab opens automatically when the GDScript compiler reaches
+a breakpoint in your code.
+
+It gives you a `stack trace <https://en.wikipedia.org/wiki/Stack_trace>`__,
+information about the state of the object, and buttons to control
+the program's execution.
+
+You can use the buttons in the top-right corner to:
+
+- Skip all breakpoints. That way, you can save breakpoints for future
+  debugging sessions.
+- Copy the current error message.
+- **Step Into** the code. This button takes you to the next line of code,
+  and if it's a function, it steps line-by-line through the function.
+- **Step Over** the code. This button goes to the next line of code,
+  but it doesn't step line-by-line through functions.
+- **Break**. This button pauses the game's execution.
+- **Continue**. This button resumes the game after a breakpoint or pause.
+
+Errors
+++++++
+
+This is where error and warning messages are printed while running the game.
+
+You can disable specific warnings in **Project Settings > Debug > GDScript**.
+
+Profiler
+++++++++
+
+The debugger comes with three profilers for your processor, network operations,
+and video memory.
+
+The profiler is used to show why individual frames take as long as they do
+to process and render.
+
+Unlike other debugging tools, the profiler does not start automatically. It can
+be started at any time during gameplay by pressing the start button. You can
+even start the profiler before opening the game to profile startup performance.
+It can also be started and stopped while the game is running without losing
+information from when it was last running. The information it records won't
+go away unless you click clear, or close the game, reopen it and start
+the profiler again.
+
+After starting and stopping the profiler, you should see things being kept track
+of on the left and a graph on the right. The items listed on the left are
+everything that contributes to frame time, and they should each have a value
+for time and calls for the current frame you are looking at.
+
+The frame number in the top right tells you which frame you are currently
+looking at. You can change this by using the up or down arrows, typing in the
+frame number, or clicking on the graph.
+
+If you want to add something to your graph or think it looks too cluttered,
+you can check and uncheck the box next to an item to add or remove it
+from the graph.
+
+Network Profiler
+++++++++++++++++
+
+The Network Profiler contains a list of all the nodes that communicate over the
+multiplayer API and, for each one, some counters on the amount of incoming and
+outgoing network interactions. It also features a bandwidth meter that displays
+the total bandwidth usage at any given moment.
+
+Monitors
+++++++++
+
+The monitors are graphs of several aspects of the game while its running such as
+FPS, memory usage, how many nodes are in a scene and more. All monitors keep
+track of stats automatically, so even if one monitor isn't open while the game
+is running, you can open it later and see how the values changed.
+
+Video RAM
++++++++++
+
+The **Video RAM** tab shows the video RAM usage of the game while it is running.
+It provides a list of every resource using video RAM by resource path, the type
+of resource it is, what format it is in, and how much Video RAM that resource is
+using. There is also a total video RAM usage number at the top right of the panel.
+
+.. image:: img/video_ram.png
+
+Misc
+++++
+
+The **Misc** tab contains tools to identify the control nodes you are clicking
+at runtime:
+
+- **Clicked Control** tells you where the clicked node is in the scene tree.
+- **Clicked Control Type** tells you the type of the node you clicked is.

tutorials/debug/index.rst

@@ -6,3 +6,4 @@ Debug
    :name: toc-learn-features-debug
 
    overview_of_debugging_tools
+   debugger_panel

tutorials/debug/overview_of_debugging_tools.rst

@@ -14,6 +14,12 @@ in the running game.
 Finally, you have options to debug the game running on a remote device
 and to reload changes to your scenes or your code while the game is running.
 
+Debugger Panel
+--------------
+
+Many of Godot's debugging tools are part of the Debugger panel, which you can
+find information about in :ref:`doc_debugger_panel`.
+
 Debug menu options
 ------------------
 
@@ -109,103 +115,6 @@ Shapes
 Shapes are where you can adjust the color of shapes that only appear for
 debugging purposes, such as collision and navigation shapes.
 
-Debugging tools
----------------
-
-You can find the debugger in the bottom panel. Click on **Debugger** to open it.
-
-.. image:: img/overview_debugger.png
-
-The debugger is split into several tabs, each focusing on a specific task.
-
-Debugger
-++++++++
-
-The debugger tab opens automatically when the GDScript compiler reaches
-a breakpoint in your code.
-
-It gives you a `stack trace <https://en.wikipedia.org/wiki/Stack_trace>`__,
-information about the state of the object, and buttons to control
-the program's execution.
-
-You can use the buttons in the top-right to:
-
-- Skip all breakpoints. That way, you can save breakpoints for future
-  debugging sessions.
-- Copy the current error message.
-- **Step Into** the code. This button takes you to the next line of code,
-  and if it's a function, it steps line-by-line through the function.
-- **Step Over** the code. This button goes to the next line of code,
-  but it doesn't step line-by-line through functions.
-- **Break**. This button pauses the game's execution.
-- **Continue**. This button resumes the game after a breakpoint or pause.
-
-Errors
-++++++
-
-This is where errors and warning messages are printed while running the game.
-
-Profiler
-++++++++
-
-The debugger comes with three profilers for your processor, network operations,
-and video memory.
-
-The profiler is used to show why individual frames take as long as they do
-to process and render.
-
-Unlike other debugging tools, the profiler does not start automatically. It can
-be started at any time during gameplay by pressing the start button. You can
-even start the profiler before opening the game to profile startup performance.
-It can also be started and stopped while the game is running without losing
-information from when it was last running. The information it records won't
-go away unless you click clear, or close the game, reopen it and start
-the profiler again.
-
-After starting and stopping the profiler you should see things being kept track
-of on the left and a graph on the right. The items listed on the left are
-everything that contributes to frame time, and they should each have a value
-for time and calls for the current frame you are looking at.
-
-The frame number in the top right tells you which frame you are currently
-looking at. You can change this by using the up or down arrows, typing in the
-frame number, or clicking on the graph.
-
-If you want to add something to your graph, or think it looks too cluttered,
-you can check and uncheck the box next to an item to add or remove it
-from the graph.
-
-Network Profiler
-++++++++++++++++
-
-The Network Profiler contains a list of all the nodes that communicate over the
-multiplayer API and, for each one, some counters on the amount of incoming and
-outgoing network interactions. It also features a bandwidth meter that displays
-the total bandwidth usage at any given moment.
-
-Monitors
-++++++++
-
-The monitors are graphs of several aspects of the game while its running such as
-FPS, memory usage, how many nodes are in a scene and more. All monitors keep
-track of stats automatically, so even if one monitor isn't open while the game
-is running, you can open it later and see how the values changed.
-
-Video Memory
-++++++++++++
-
-The **Video Mem** tab lists the video memory usage of the running game
-and the resources using it.
-
-Misc
-++++
-
-The **Misc** tab contains tools to identify the control nodes you are clicking
-at runtime:
-
-- **Clicked Control** tells you where the clicked node is in the scene tree.
-- **Clicked Control Type** tells you the type of the node you clicked is.
-
 Remote in scene dock
 --------------------
 

tutorials/gui/gui_containers.rst

@@ -46,8 +46,8 @@ Size flags are independent for vertical and horizontal sizing and not all contai
 
 * **Fill**: Ensures the control *fills* the designated area within the container. No matter if
   a control *expands* or not (see below), it will only *fill* the designated area when this is toggled on (it is by default).
-* **Expand**: Attempts to use as most space as possible in the parent container (in this each axis).
-  Controls that don't expand will be pushed away by those that do. Between those expanding, the
+* **Expand**: Attempts to use as much space as possible in the parent container (in each axis).
+  Controls that don't expand will be pushed away by those that do. Between expanding controls, the
   amount of space they take from each other is determined by the *Ratio* (see below).
 * **Shrink Center** When expanding (and if not filling), try to remain at the center of the expanded
   area (by default it remains at the left or top).
@@ -89,8 +89,8 @@ depending on the theme configuration.
 
    .. image:: img/containers_margin.png
 
-Again, keep in mind that the margins are a *Theme* value, so they need to be edited at the
-constants overrides section if desired for a single control:
+Again, keep in mind that the margins are a *Theme* value, so they need to be edited from the
+constants overrides section of each control:
 
    .. image:: img/containers_margin_constants.png
 

tutorials/io/encrypting_save_games.rst

@@ -6,6 +6,9 @@ Encrypting save games
 Why?
 ----
 
+.. This introduction is an Easter egg and is not intended to be taken seriously.
+.. Please don't remove it :)
+
 Because the world today is not the world of yesterday. A capitalist
 oligarchy runs the world and forces us to consume in order to keep the
 gears of this rotten society on track. As such, the biggest market for

tutorials/io/saving_games.rst

@@ -267,7 +267,7 @@ load function:
         while (saveGame.GetPosition() < save_game.GetLen())
         {
             // Get the saved dictionary from the next line in the save file
-            var nodeData = (Godot.Collections.Dictionary<string, object>)JSON.Parse(saveGame.GetLine()).Result;
+            var nodeData = new Godot.Collections.Dictionary<string, object>((Godot.Collections.Dictionary)JSON.Parse(saveGame.GetLine()).Result);
 
             // Firstly, we need to create the object and add it to the tree and set its position.
             var newObjectScene = (PackedScene)ResourceLoader.Load(nodeData["Filename"].ToString());

tutorials/platform/android_in_app_purchases.rst

@@ -3,125 +3,151 @@
 Android in-app purchases
 ========================
 
-Godot Engine has integrated GooglePaymentsV3 module with which we can implement in-app purchases in our game.
+Godot offers a first-party ``GodotGooglePlayBilling`` Android plugin since Godot 3.2.2.
+The new plugin uses the `Google Play Billing library <https://developer.android.com/google/play/billing>`__
+instead of the now deprecated AIDL IAP implementation.
 
-The `Godot demo projects repository <https://github.com/godotengine/godot-demo-projects>`__
-has an `android_iap <https://github.com/godotengine/godot-demo-projects/tree/master/misc/android_iap>`__
-example project. It includes a GDScript interface for Android IAPs.
+If you learn better by looking at an example, you can find the demo project
+`here <https://github.com/godotengine/godot-demo-projects/tree/master/misc/android_iap>`__.
 
-Find the ``iap.gd`` script in:
 
-.. code-block:: none
+Migrating from Godot 3.2.1 and lower (GodotPaymentsV3)
+------------------------------------------------------
 
-    godot-demo-projects/misc/android_iap
+The new ``GodotGooglePlayBilling`` API is not compatible with its predecessor ``GodotPaymentsV3``.
 
-Copy it to your project, then open the Project Settings, add it to the AutoLoad
-list and name it as IAP so that we can reference it anywhere in the game.
+Changes
+*******
 
-Getting the product details
----------------------------
+- You need to enable the Custom Build option in your Android export settings and install
+  the ``GodotGooglePlayBilling`` plugin manually (see below for details)
+- All purchases have to be acknowledged by your app. This is a
+  `requirement from Google <https://developer.android.com/google/play/billing/integrate#process>`__.
+  Purchases that are not acknowledged by your app will be refunded.
+- Support for subscriptions
+- Signals (no polling or callback objects)
 
-When starting our game, we will need to get the item details from Google such as the product price, description, localized price string, etc.
 
-::
-
-    # First, listen to the SKU details update callback.
-    IAP.connect("sku_details_complete", self, "sku_details_complete")
-
-    # Then ask Google the details for these items.
-    # pid1 and pid2 are our product IDs entered in the Google Play dashboard.
-    IAP.sku_details_query(["pid1", "pid2"])
+Usage
+-----
 
+Getting started
+***************
 
-    # This will be called when SKU details are retrieved successfully.
-    func sku_details_complete():
-        print(IAP.sku_details)  # This will print the details as JSON format. Refer to the format in `iap.gd`.
-        print(IAP.sku_details["pid1"].price)  # Print formatted localized price.
+If not already done, make sure you have enabled and successfully set up :ref:`Android Custom Builds <doc_android_custom_build>`.
+Grab the``GodotGooglePlayBilling`` plugin binary and config from the `releases page <https://github.com/godotengine/godot-google-play-billing/releases>`__
+and put both into `res://android/plugins`.
+The plugin should now show up in the Android export settings, where you can enable it.
 
-We can use the IAP details to display the title, price and/or description on our shop scene.
 
-Check if user purchased an item
--------------------------------
+Getting started
+***************
 
-When starting our game, we can check if the user has purchased any product. **You should do this only after 2/3 seconds after your game is loaded.** If we do this as the first thing when the game is launched, IAPs might not be initialized and our game will crash on start.
+To use the ``GodotGooglePlayBilling`` API you first have to get the ``GodotGooglePlayBilling``
+singleton and start the connection:
 
 ::
 
-    # Add a listener first.
-    IAP.connect("has_purchased", self, "iap_has_purchased")
-    IAP.request_purchased() #Ask Google for all purchased items
+    var payment
 
-    # This will call for each and every user's purchased products.
-    func iap_has_purchased(item_name):
-        print(item_name) #print the name of purchased items
+    func _ready():
+        if Engine.has_singleton("GodotGooglePlayBilling"):
+            payment = Engine.get_singleton("GodotGooglePlayBilling")
+            
+            # These are all signals supported by the API
+            # You can drop some of these based on your needs
+            payment.connect("connected", self, "_on_connected") # No params
+            payment.connect("disconnected", self, "_on_disconnected") # No params
+            payment.connect("connect_error", self, "_on_connect_error") # Response ID (int), Debug message (string)
+            payment.connect("purchases_updated", self, "_on_purchases_updated") # Purchases (Dictionary[])
+            payment.connect("purchase_error", self, "_on_purchase_error") # Response ID (int), Debug message (string)
+            payment.connect("sku_details_query_completed", self, "_on_sku_details_query_completed") # SKUs (Dictionary[])
+            payment.connect("sku_details_query_error", self, "_on_sku_details_query_error") # Response ID (int), Debug message (string), Queried SKUs (string[])
+            payment.connect("purchase_acknowledged", self, "_on_purchase_acknowledged") # Purchase token (string)
+            payment.connect("purchase_acknowledgement_error", self, "_on_purchase_acknowledgement_error") # Response ID (int), Debug message (string), Purchase token (string)
+            payment.connect("purchase_consumed", self, "_on_purchase_consumed") # Purchase token (string)
+            payment.connect("purchase_consumption_error", self, "_on_purchase_consumption_error") # Response ID (int), Debug message (string), Purchase token (string)
+            
+            payment.startConnection()
+        else:
+            print("Android IAP support is not enabled. Make sure you have enabled 'Custom Build' and the GodotGooglePlayBilling plugin in your Android export settings! IAP will not work.")
 
+All API methods only work if the API is connected. You can use ``payment.isReady()`` to check the connection status.
 
-The Google IAP policy says the game should restore the user's purchases if the user replaces their phone or reinstalls the same app. We can use the above code to check what products the user has purchased and we can make our game respond accordingly.
 
-Simple Purchase
----------------
+Querying available items
+************************
 
-We can put this purchase logic on a product's buy button.
+As soon as the API is connected, you can query SKUs using ``querySkuDetails``.
 
-::
+Full example:
 
-    # First, listen for purchase_success callback.
-    IAP.connect("purchase_success", self, "purchase_success_callback")
+::
 
-    # Then call `purchase()` like this:
-    IAP.purchase("pid1")  # Replace pid1 with one of your product IDs.
-    IAP.purchase("pid2")  # Replace pid2 with another of your product IDs.
+    func _on_connected():
+      payment.querySkuDetails(["my_iap_item"], "inapp") # "subs" for subscriptions
 
-    # This function will be called when the purchase is a success.
-    func purchase_success_callback(item):
-        print(item + " has purchased")
+    func _on_sku_details_query_completed(sku_details):
+      for available_sku in sku_details:
+        print(available_sku)
 
-We can also implement other signals for the purchase flow and improve the user experience as you needed.
 
-- ``purchase_fail``: When the purchase is failed due to any reason.
-- ``purchase_cancel``: When the user cancels the purchase.
-- ``purchase_owned``: When the user already bought the product earlier.
+Purchase an item
+****************
 
-Consumables and Non-Consumables
--------------------------------
+To initiate the purchase flow for an item, call ``purchase``.
+You **must** query the SKU details for an item before you can
+initiate the purchase flow for it.
 
-There are two types of products - consumables and non-consumables:
+::
 
-- **Consumables** are purchased and used, for example, healing potions which can be purchased again and again.
-- **Non-consumables** are one time purchases, for example, level packs.
+    payment.purchase("my_iap_item")
 
-Google doesn't have this separation in their dashboard. If our product is a consumable, and if a user has purchased it, it will not be available for purchase until it is consumed. So we should call the consume method for our consumables and don't call consume for your non-consumables.
 
-::
 
-    IAP.connect("consume_success", self, "on_consume_success")
-    IAP.consume("pid")
+Check if the user purchased an item
+***********************************
 
-    func on_consume_success(item):
-        print(item + " consumed")
+To get all purchases, call ``queryPurchases``. Unlike most of the other functions, ``queryPurchases`` is
+a synchronous operation and returns a :ref:`Dictionary <class_Dictionary>` with a status code
+and either an array of purchases or an error message.
 
-If our game has only consumables, we don't have to do this. We can set it to consume the item automatically after a purchase.
+Full example:
 
 ::
 
-    IAP.set_auto_consume(true)
+    var query = payment.queryPurchases()
+    if query.status == OK:
+        for purchase in query.purchases:
+            if purchase.sku == "my_iap_item":
+                premium = true # Entitle the user to the content they bought
+                if !purchase.is_acknowledged:
+                    payment.acknowledgePurchase(purchase.purchase_token)
 
-If our game has only non-consumables, we can
 
-::
+Consumables
+***********
 
-    IAP.set_auto_consume(false)
+If your in-app item is not a one-time purchase but a consumable item (e.g. coins) which can be purchased
+multiple times, you can consume an item by calling ``consumePurchase`` with a purchase token.
+Call ``queryPurchases`` to get the purchase token. Calling ``consumePurchase`` automatically
+acknowledges a purchase.
 
-We should set the auto consume value only once when the game starts.
+::
 
-Testing
--------
+    var query = payment.queryPurchases()
+    if query.status == OK:
+        for purchase in query.purchases:
+            if purchase.sku == "my_consumable_iap_item":
+                if !purchase.is_acknowledged:
+                    payment.consumePurchase(purchase.purchase_token)
+                    # Check the _on_purchase_consumed callback and give the user what they bought
 
-If we add a Gmail ID as a tester in the Google Play dashboard, that tester can purchase items and they will not be charged. Another way to test IAP is using redeem codes generated by us for our game because the purchase flow is the same.
 
-Third way of testing is in development side. If we put the product ids as shown below, we will get a static fixed response according to the product ID. This is a quick way of testing things before going to the dashboard.
+Subscriptions
+*************
 
-- android.test.purchased
-- android.test.canceled
-- android.test.refunded
-- android.test.item_unavailable
+Subscriptions don't work much different from regular in-app items. Just use ``"subs"`` as second
+argument to ``querySkuDetails`` to get subscription details.
+Check ``is_auto_renewing`` in the results of ``queryPurchases()`` to see if a
+user has cancelled an auto-renewing subscription

tutorials/plugins/gdnative/gdnative-c-example.rst

@@ -510,6 +510,12 @@ select our ``.gdnlib`` file by clicking on *Library* and selecting *Load*:
 
 .. image:: img/nativescript_library.png
 
+.. note::
+
+    The *Class Name* must have the same spelling as the one given in ``godot_nativescript_init``
+    when registering the class.
+
+   
 Finally, click on the save icon and save this as ``bin/simple.gdns``:
 
 .. image:: img/save_gdns.gif

tutorials/shading/screen-reading_shaders.rst

@@ -20,10 +20,10 @@ few tools that make this process easy!
 SCREEN_TEXTURE built-in texture
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Godot :ref:`doc_shading_language` has a special texture, "SCREEN_TEXTURE" (and "DEPTH_TEXTURE" for depth, in the case of 3D).
+Godot :ref:`doc_shading_language` has a special texture, ``SCREEN_TEXTURE`` (and ``DEPTH_TEXTURE`` for depth, in the case of 3D).
 It takes as argument the UV of the screen and returns a vec3 RGB with the color. A
 special built-in varying: SCREEN_UV can be used to obtain the UV for
-the current fragment. As a result, this simple 2D fragment shader:
+the current fragment. As a result, this simple canvas_item fragment shader:
 
 .. code-block:: glsl
 
@@ -39,10 +39,15 @@ a chunk of the screen, it also does an efficient separatable gaussian blur to it
 This allows for not only reading from the screen, but reading from it with different amounts
 of blur at no cost.
 
+.. note::
+
+   Mipmaps are not generated in GLES2 due to poor performance and compatibility with older
+   devices. 
+
 SCREEN_TEXTURE example
 ~~~~~~~~~~~~~~~~~~~~~~
 
-SCREEN_TEXTURE can be used for many things. There is a
+``SCREEN_TEXTURE`` can be used for many things. There is a
 special demo for *Screen Space Shaders*, that you can download to see
 and learn. One example is a simple shader to adjust brightness, contrast
 and saturation:
@@ -68,25 +73,24 @@ and saturation:
 Behind the scenes
 ~~~~~~~~~~~~~~~~~
 
-While this seems magical, it's not. The SCREEN_TEXTURE built-in, when
+While this seems magical, it's not. In 2D, the ``SCREEN_TEXTURE`` built-in, when
 first found in a node that is about to be drawn, does a full-screen
 copy to a back-buffer. Subsequent nodes that use it in
 shaders will not have the screen copied for them, because this ends up
-being inefficient.
+being inefficient. In 3D, the screen is copied after the opaque geometry pass,
+but before the transparent geometry pass, so transparent objects will not be
+captured in the ``SCREEN_TEXTURE``.
 
-As a result, if shaders that use SCREEN_TEXTURE overlap, the second one
+As a result, in 2D, if shaders that use ``SCREEN_TEXTURE`` overlap, the second one
 will not use the result of the first one, resulting in unexpected
 visuals:
 
 .. image:: img/texscreen_demo1.png
 
 In the above image, the second sphere (top right) is using the same
-source for SCREEN_TEXTURE as the first one below, so the first one
+source for ``SCREEN_TEXTURE`` as the first one below, so the first one
 "disappears", or is not visible.
 
-In 3D, this is unavoidable because copying happens when opaque rendering
-completes.
-
 In 2D, this can be corrected via the :ref:`BackBufferCopy <class_BackBufferCopy>`
 node, which can be instantiated between both spheres. BackBufferCopy can work by
 either specifying a screen region or the whole screen:
@@ -97,19 +101,28 @@ With correct back-buffer copying, the two spheres blend correctly:
 
 .. image:: img/texscreen_demo2.png
 
+In 3D, there is less flexibility to solve this particular issue because the 
+``SCREEN_TEXTURE`` is only captured once. Be careful when using 
+``SCREEN_TEXTURE`` in 3D as it won't capture transparent objects and may capture
+some opaque objects that are in front of the object.
+
+You can reproduce the back-buffer logic in 3D by creating a :ref:`Viewport <class_Viewport>`
+with a camera in the same position as your object, and then use the 
+:ref:`Viewport's <class_Viewport>` texture instead of ``SCREEN_TEXTURE``.
+
 Back-buffer logic
 ~~~~~~~~~~~~~~~~~
 
 So, to make it clearer, here's how the backbuffer copying logic works in
 Godot:
 
--  If a node uses the SCREEN_TEXTURE, the entire screen is copied to the
+-  If a node uses the ``SCREEN_TEXTURE``, the entire screen is copied to the
    back buffer before drawing that node. This only happens the first
    time; subsequent nodes do not trigger this.
 -  If a BackBufferCopy node was processed before the situation in the
-   point above (even if SCREEN_TEXTURE was not used), the behavior
+   point above (even if ``SCREEN_TEXTURE`` was not used), the behavior
    described in the point above does not happen. In other words,
-   automatic copying of the entire screen only happens if SCREEN_TEXTURE is
+   automatic copying of the entire screen only happens if ``SCREEN_TEXTURE`` is
    used in a node for the first time and no BackBufferCopy node (not
    disabled) was found before in tree-order.
 -  BackBufferCopy can copy either the entire screen or a region. If set
@@ -117,14 +130,14 @@ Godot:
    not in the region copied, the result of that read is undefined
    (most likely garbage from previous frames). In other words, it's
    possible to use BackBufferCopy to copy back a region of the screen
-   and then use SCREEN_TEXTURE on a different region. Avoid this behavior!
+   and then use ``SCREEN_TEXTURE`` on a different region. Avoid this behavior!
 
 
 DEPTH_TEXTURE
 ~~~~~~~~~~~~~
 
 For 3D Shaders, it's also possible to access the screen depth buffer. For this,
-the DEPTH_TEXTURE built-in is used. This texture is not linear; it must be
+the ``DEPTH_TEXTURE`` built-in is used. This texture is not linear; it must be
 converted via the inverse projection matrix.
 
 The following code retrieves the 3D position below the pixel being drawn:

tutorials/shading/shading_reference/shading_language.rst

@@ -201,7 +201,7 @@ Local arrays
 ~~~~~~~~~~~~
 
 Local arrays are declared in functions. They can use all of the allowed datatypes, except samplers.
-The array declaration follows a C-style syntax: ``typename + identifier + [array size]``.
+The array declaration follows a C-style syntax: ``[const] + [precision] + typename + identifier + [array size]``.
 
 .. code-block:: glsl
 
@@ -369,6 +369,11 @@ Godot Shading language supports the most common types of flow control:
 Keep in mind that, in modern GPUs, an infinite loop can exist and can freeze your application (including editor).
 Godot can't protect you from this, so be careful not to make this mistake!
 
+.. warning::
+
+    When exporting a GLES2 project to HTML5, WebGL 1.0 will be used. WebGL 1.0
+    doesn't support dynamic loops, so shaders using those won't work there.
+
 Discarding
 ----------
 

tutorials/shading/shading_reference/spatial_shader.rst

@@ -298,6 +298,13 @@ Below is an example of a custom light function using a Lambertian lighting model
 
 If you want the lights to add together, add the light contribution to ``DIFFUSE_LIGHT`` using ``+=``, rather than overwriting it.
 
+.. warning::
+
+    The ``light()`` function won't be run if the ``vertex_lighting`` render mode
+    is enabled, or if
+    **Rendering > Quality > Shading > Force Vertex Shading** is enabled in the
+    Project Settings. (It's enabled by default on mobile platforms.)
+
 +-----------------------------------+-----------------------------------------------------+
 | Built-in                          | Description                                         |
 +===================================+=====================================================+

tutorials/shading/your_first_shader/what_are_shaders.rst

@@ -90,7 +90,14 @@ between the vertices to provide the values for the ``fragment()`` function.
 The ``light()`` function runs for every pixel and for every light. It takes variables from the
 ``fragment()`` function and from previous runs of itself.
 
-For more information about how shaders operate specifically in Godot see the :ref:`Shaders <doc_shaders>` doc.
+For more information about how shaders operate specifically in Godot, see the :ref:`Shaders <doc_shaders>` doc.
+
+.. warning::
+
+    The ``light()`` function won't be run if the ``vertex_lighting`` render mode
+    is enabled, or if
+    **Rendering > Quality > Shading > Force Vertex Shading** is enabled in the
+    Project Settings. (It's enabled by default on mobile platforms.)
 
 Technical overview
 ------------------