Merge branch 'master' into 3.1

_templates/breadcrumbs.html

@@ -0,0 +1,7 @@
+{%- extends "sphinx_rtd_theme/breadcrumbs.html" %}
+
+{% block breadcrumbs_aside %}
+{% if not meta or meta.get('github_url') != 'hide' %}
+{{ super() }}
+{% endif %}
+{% endblock %}

about/docs_changelog.rst

@@ -42,10 +42,11 @@ Shading
 ^^^^^^^
 
 Your First Shader Series:
-  - :ref:`doc_what_are_shaders`
-  - :ref:`doc_your_first_canvasitem_shader`
-  - :ref:`doc_your_first_spatial_shader`
-  - :ref:`doc_your_second_spatial_shader`
+
+- :ref:`doc_what_are_shaders`
+- :ref:`doc_your_first_canvasitem_shader`
+- :ref:`doc_your_first_spatial_shader`
+- :ref:`doc_your_second_spatial_shader`
 
 Plugins
 ^^^^^^^
@@ -91,16 +92,17 @@ Project workflow
 ^^^^^^^^^^^^^^^^
 
 Best Practices:
-  - :ref:`doc_introduction_best_practices`
-  - :ref:`doc_what_are_godot_classes`
-  - :ref:`doc_scene_organization`
-  - :ref:`doc_scenes_versus_scripts`
-  - :ref:`doc_autoloads_versus_internal_nodes`
-  - :ref:`doc_node_alternatives`
-  - :ref:`doc_godot_interfaces`
-  - :ref:`doc_godot_notifications`
-  - :ref:`doc_data_preferences`
-  - :ref:`doc_logic_preferences`
+
+- :ref:`doc_introduction_best_practices`
+- :ref:`doc_what_are_godot_classes`
+- :ref:`doc_scene_organization`
+- :ref:`doc_scenes_versus_scripts`
+- :ref:`doc_autoloads_versus_internal_nodes`
+- :ref:`doc_node_alternatives`
+- :ref:`doc_godot_interfaces`
+- :ref:`doc_godot_notifications`
+- :ref:`doc_data_preferences`
+- :ref:`doc_logic_preferences`
 
 2D
 ^^
@@ -146,11 +148,12 @@ Shading
 - :ref:`doc_advanced_postprocessing`
 
 Shading Reference:
-  - :ref:`doc_shaders`
-  - :ref:`doc_shading_language`
-  - :ref:`doc_spatial_shader`
-  - :ref:`doc_canvas_item_shader`
-  - :ref:`doc_particle_shader`
+
+- :ref:`doc_shaders`
+- :ref:`doc_shading_language`
+- :ref:`doc_spatial_shader`
+- :ref:`doc_canvas_item_shader`
+- :ref:`doc_particle_shader`
 
 VR
 ^^

community/contributing/pr_workflow.rst

@@ -379,7 +379,7 @@ do:
 
 This will open a text editor with:
 
-::
+.. code-block:: text
 
     pick 1b4aad7 Add a pretty banner to the project manager
     pick e07077e Fix a typo in the banner's title
@@ -392,7 +392,7 @@ that "fixup" will discard the commit log from the squashed commit. In our
 example, we are not interested in keeping the log of the "Fix a typo" commit,
 so we use:
 
-::
+.. code-block:: text
 
     pick 1b4aad7 Add a pretty banner to the project manager
     fixup e07077e Fix a typo in the banner's title

community/contributing/updating_the_class_reference.rst

@@ -12,7 +12,7 @@ The developers can't write the entire reference on their own. Godot needs you, a
 **Important:** If you are planning to make larger changes or a more substantial contribution, it is usually a good idea
 to create an issue (or a comment in an existing one) to let others know so they don't start working on the same thing too.
 
-.. note:: This guide is available as a `Youtube video <https://www.youtube.com/watch?v=mKKjOulm5XI>`_.
+.. note:: This guide is available as a `video tutorial on YouTube <https://www.youtube.com/watch?v=5jeHXxeX-JY>`_.
 
 
 How to contribute

community/tutorials.rst

@@ -35,7 +35,7 @@ Video tutorials
 Text tutorials
 --------------
 
-- `KidsCanCode <http://kidscancode.org/blog/tags/godot/>`__
+- `Godot Recipes by KidsCanCode <http://godotrecipes.com/>`__
 - `Steincodes <https://steincodes.tumblr.com>`__
 
 Devlogs

conf.py

@@ -32,11 +32,20 @@ version = 'latest'
 # The full version, including alpha/beta/rc tags
 release = 'latest'
 
-language = 'en'
+# Parse Sphinx tags passed from RTD via environment
+env_tags = os.getenv('SPHINX_TAGS')
+if env_tags != None:
+   for tag in env_tags.split(','):
+       print("Adding Sphinx tag: %s" % tag.strip())
+       tags.add(tag.strip())
+
+# Language / i18n
+language = os.getenv('READTHEDOCS_LANGUAGE', 'en')
 is_i18n = tags.has('i18n')
 
 exclude_patterns = ['_build']
 
+# GDScript syntax highlighting
 from gdscript import GDScriptLexer
 from sphinx.highlighting import lexers
 lexers['gdscript'] = GDScriptLexer()
@@ -107,14 +116,20 @@ linkcheck_timeout = 10
 
 locale_dirs = ['../sphinx/po/']
 gettext_compact = False
+
+# Couldn't find a way to retrieve variables nor do advanced string
+# concat from reST, so had to hardcode this in the "epilog" added to
+# all pages. This is used in index.rst to display the Weblate badge.
+# On English pages, the badge points to the language-neutral engage page.
+rst_epilog = """
+.. |weblate_widget| image:: https://hosted.weblate.org/widgets/godot-engine/{image_locale}/godot-docs/287x66-white.png
+    :alt: Translation status
+    :target: https://hosted.weblate.org/engage/godot-engine{target_locale}/?utm_source=widget
+""".format(
+    image_locale='-' if language == 'en' else language,
+    target_locale='' if language == 'en' else '/' + language
+)
+
 # Exclude class reference when marked with tag i18n.
 if is_i18n:
     exclude_patterns = ['classes']
-    # Couldn't find a way to retrieve variables nor do advanced string
-    # concat from reST, so had to hardcode this in the "epilog" added to
-    # all pages. This is used in index.rst to display the Weblate badge.
-    rst_epilog = """
-.. |weblate_widget| image:: https://hosted.weblate.org/widgets/godot-engine/{weblate_locale}/godot-docs/287x66-white.png
-    :alt: Translation status
-    :target: https://hosted.weblate.org/engage/godot-engine/{weblate_locale}/?utm_source=widget
-""".format(weblate_locale = language)

development/compiling/compiling_for_windows.rst

@@ -151,29 +151,29 @@ If you are a Linux or macOS user, you need to install
 and 64-bit variants. The package names may differ based on your distribution,
 here are some known ones:
 
-+---------------+--------------------------------------------------------------+
-| **Arch**      | ::                                                           |
-|               |                                                              |
-|               |     pacman -S mingw-w64-gcc                                  |
-+---------------+--------------------------------------------------------------+
-| **Debian** /  | ::                                                           |
-| **Ubuntu**    |                                                              |
-|               |     apt install mingw-w64                                    |
-+---------------+--------------------------------------------------------------+
-| **Fedora**    | ::                                                           |
-|               |                                                              |
-|               |     dnf install mingw64-gcc-c++ mingw64-winpthreads-static \ |
-|               |                 mingw32-gcc-c++ mingw32-winpthreads-static   |
-+---------------+--------------------------------------------------------------+
-| **macOS**     | ::                                                           |
-|               |                                                              |
-|               |     brew install mingw-w64                                   |
-+---------------+--------------------------------------------------------------+
-| **Mageia**    | ::                                                           |
-|               |                                                              |
-|               |     urpmi mingw64-gcc-c++ mingw64-winpthreads-static \       |
-|               |           mingw32-gcc-c++ mingw32-winpthreads-static         |
-+---------------+--------------------------------------------------------------+
++----------------+--------------------------------------------------------------+
+| **Arch Linux** | Install `mingw-w64-gcc from the AUR`_.                       |
++----------------+--------------------------------------------------------------+
+| **Debian** /   | ::                                                           |
+| **Ubuntu**     |                                                              |
+|                |     apt install mingw-w64                                    |
++----------------+--------------------------------------------------------------+
+| **Fedora**     | ::                                                           |
+|                |                                                              |
+|                |     dnf install mingw64-gcc-c++ mingw64-winpthreads-static \ |
+|                |                 mingw32-gcc-c++ mingw32-winpthreads-static   |
++----------------+--------------------------------------------------------------+
+| **macOS**      | ::                                                           |
+|                |                                                              |
+|                |     brew install mingw-w64                                   |
++----------------+--------------------------------------------------------------+
+| **Mageia**     | ::                                                           |
+|                |                                                              |
+|                |     urpmi mingw64-gcc-c++ mingw64-winpthreads-static \       |
+|                |           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::

development/compiling/compiling_for_x11.rst

@@ -45,8 +45,9 @@ Distro-specific oneliners
 +----------------+-----------------------------------------------------------------------------------------------------------+
 | **FreeBSD**    | ::                                                                                                        |
 |                |                                                                                                           |
-|                |     sudo pkg install scons pkgconf xorg-libraries libXcursor libXrandr libXi xineramaproto libglapi \     |
-|                |         libGLU yasm                                                                                       |
+|                |     sudo pkg install scons pkgconf xorg-libraries libXcursor libXrandr libXi xorgproto libGLU alsa-lib \  |
+|                |         pulseaudio yasm                                                                                   |
+|                |                                                                                                           |
 +----------------+-----------------------------------------------------------------------------------------------------------+
 | **Gentoo**     | ::                                                                                                        |
 |                |                                                                                                           |

development/compiling/compiling_with_mono.rst

@@ -13,18 +13,18 @@ Requirements
 - NuGet
 - pkg-config
 
-You may need to import necessary certificates for NuGet to perform HTTPS requests. You can do this
-with the following command (on Windows, you can run it from the Mono command line prompt):
-
-::
+You may need to import necessary certificates for NuGet to perform HTTPS
+requests. You can do this with the following command (on Windows, you can run it
+from the Mono command line prompt)::
 
     mozroots --import --sync
 
 Environment variables
 ---------------------
 
-By default, SCons will try to find Mono in the Windows Registry on Windows or via ``pkg-config`` on other platforms.
-You can specify a different installation directory by using the following environment variables for the respective
+By default, SCons will try to find Mono in the Windows Registry on Windows or
+via ``pkg-config`` on other platforms. You can specify a different installation
+directory by using the following environment variables for the respective
 ``bits`` option: ``MONO32_PREFIX`` and ``MONO64_PREFIX``.
 
 The specified directory must contain the subdirectories ``bin``, ``include``, and ``lib``.
@@ -32,71 +32,77 @@ The specified directory must contain the subdirectories ``bin``, ``include``, an
 Enable the Mono module
 ----------------------
 
-By default, the mono module is disabled for builds. To enable it you can pass the
-option ``module_mono_enabled=yes`` to your SCons command.
+By default, the Mono module is disabled when building. To enable it, add the
+option ``module_mono_enabled=yes`` to the SCons command line.
 
 Generate the glue
 -------------------
 
-The glue sources are the wrapper functions that will be called by managed methods. These source
-files must be generated before building your final binaries. In order to generate them, first,
-you must build a temporary Godot binary with the options ``tools=yes`` and ``mono_glue=no``:
-
-::
+Glue sources are the wrapper functions that will be called by managed methods.
+These source files must be generated before building your final binaries. In
+order to generate them, first, you must build a temporary Godot binary with the
+options ``tools=yes`` and ``mono_glue=no``::
 
     scons p=<platform> tools=yes module_mono_enabled=yes mono_glue=no
 
-After the build finishes, you need to run the compiled executable with the parameter
-``--generate-mono-glue`` followed by the path to an output directory. This path
-must be ``modules/mono/glue`` in the Godot directory.
-
-::
+After the build finishes, you need to run the compiled executable with the
+parameter ``--generate-mono-glue`` followed by the path to an output directory.
+This path must be ``modules/mono/glue`` in the Godot directory::
 
     <godot_binary> --generate-mono-glue modules/mono/glue
 
 This command will tell Godot to generate the file ``modules/mono/glue/mono_glue.gen.cpp``.
-Once this file is generated, you can build Godot for all the desired targets without the need to repeat this process.
-
-``<godot_binary>`` refers to the tools binary you compiled above with the Mono module enabled.
-Its exact name will differ based on your system and configuration, but should be of the form
-``bin/godot.<platform>.tools.<bits>.mono``, e.g. ``bin/godot.x11.tools.64.mono`` or ``bin/godot.windows.tools.64.exe``.
-Be especially aware of the **.mono** suffix! If you compiled Godot without Mono support previously,
-you might have similarly named binaries without this suffix which can't be used to generate the Mono glue.
+Once this file is generated, you can build Godot for all the desired targets
+without the need to repeat this process.
+
+``<godot_binary>`` refers to the tools binary you compiled above with the Mono
+module enabled. Its exact name will differ based on your system and
+configuration, but should be of the form
+``bin/godot.<platform>.tools.<bits>.mono``, e.g. ``bin/godot.x11.tools.64.mono``
+or ``bin/godot.windows.tools.64.exe``. Be especially aware of the **.mono**
+suffix! If you've previously compiled Godot without Mono support, you might have
+similarly named binaries without this suffix. These binaries can't be used to
+generate the Mono glue.
 
 Notes
 ^^^^^
--  **Do not** build your final binaries with ``mono_glue=no``. This disables C# scripting.
-   This option must be used only for the temporary binary that will generate the glue.
-   Godot will print a warning at startup if it was built without the glue sources.
--  The glue sources must be regenerated every time the ClassDB registered API changes. That is, for example,
-   when a new method is registered to the scripting API or one of the parameter of such a method changes.
-   Godot will print an error at startup if there is an API mismatch between ClassDB and the glue sources.
+- **Do not build your final binaries with** ``mono_glue=no``.
+  This disables C# scripting. This option must be used only for the temporary
+  binary that will generate the glue. Godot will print a warning at startup if
+  it was built without the glue sources.
+- The glue sources must be regenerated every time the ClassDB-registered API
+  changes. That is, for example, when a new method is registered to the
+  scripting API or one of the parameters of such a method changes.
+  Godot will print an error at startup if there is an API mismatch
+  between ClassDB and the glue sources.
 
 
 Rebuild with Mono glue
 ----------------------
 
-Once you have generated the Mono glue, you can build the final binary with ``mono_glue=yes``.
-This is the default value for ``mono_glue`` so you can also omit it. You can build the Mono-enabled editor:
-
-::
+Once you have generated the Mono glue, you can build the final binary with
+``mono_glue=yes``. This is the default value for ``mono_glue``, so you can also
+omit it. To build a Mono-enabled editor::
 
     scons p=<platform> tools=yes module_mono_enabled=yes mono_glue=yes
 
-And Mono-enabled export templates:
-
-::
+And Mono-enabled export templates::
 
     scons p=<platform> tools=no module_mono_enabled=yes mono_glue=yes
 
-If everything went well, apart from the normal output SCons should have created the following files in the ``bin`` directory:
-
--  If you're not static linking the Mono runtime, the build script will place the Mono runtime shared library (``monosgen-2.0``) next
-   next to the Godot binary in the output directory. Make sure to include this library when distributing Godot.
--  Unlike "classical" Godot builds, when building with the mono module enabled and depending of the target platform a data directory
-   may be created both for the editor and for export templates. This directory is important for proper functioning and must be
-   distributed together with Godot. More details about this directory in :ref:`Data directory<compiling_with_mono_data_directory>`.
+If everything went well, apart from the normal output SCons should have created
+the following files in the ``bin`` directory:
 
+- If you're not linking the Mono runtime statically, the build script will place
+  the Mono runtime shared library (``monosgen-2.0``) next to the Godot
+  binary in the output directory. Make sure to include this library when
+  distributing Godot.
+- Unlike "classical" Godot builds, when building with the mono module enabled
+  (and depending of the target platform), a data directory may be created both
+  for the editor and for export templates. This directory is important for
+  proper functioning and must be distributed together with Godot.
+  More details about this directory in
+  :ref:`Data directory<compiling_with_mono_data_directory>`.
 
 Examples
 --------
@@ -138,22 +144,27 @@ Example (X11)
 Data directory
 --------------
 
-The data directory is a dependency for Godot binaries built with the mono module enabled. It contains files
-that are important for the correct functioning of Godot. It must be distributed together with the Godot executable.
+The data directory is a dependency for Godot binaries built with the mono module
+enabled. It contains important files for the correct functioning of Godot. It
+must be distributed together with the Godot executable.
 
 Export templates
 ^^^^^^^^^^^^^^^^
 
-The name of the data directory for a export template differs based on the configuration it was built with.
-The format is ``data.mono.<platform>.<bits>.<target>``, e.g. ``data.mono.x11.32.debug`` or ``data.mono.windows.64.release``.
+The name of the data directory for an export template differs based on the
+configuration it was built with. The format is
+``data.mono.<platform>.<bits>.<target>``, e.g. ``data.mono.x11.32.debug`` or
+``data.mono.windows.64.release``.
 
-This directory must be placed with its original name next to the Godot export templates.
-When exporting a project, Godot will also copy this directory with the game executable but
-the name will be changed to ``data_<APPNAME>``, where ``<APPNAME>`` is the application name
-as specified in the project setting ``application/config/name``.
+This directory must be placed with its original name next to the Godot export
+templates. When exporting a project, Godot will also copy this directory with
+the game executable but the name will be changed to ``data_<APPNAME>``, where
+``<APPNAME>`` is the application name as specified in the project setting
+``application/config/name``.
 
-In the case of macOS, where the export template is compressed as a zip file, the
-contents of the data directory can be placed in the following locations inside the zip:
+In the case of macOS, where the export template is compressed as a ZIP archive,
+the contents of the data directory can be placed in the following locations
+inside the ZIP archive:
 
 +-------------------------------------------------------+---------------------------------------------------------------+
 | ``bin/data.mono.<platform>.<bits>.<target>/Mono/lib`` | ``/osx_template.app/Contents/Frameworks/GodotSharp/Mono/lib`` |
@@ -164,8 +175,8 @@ contents of the data directory can be placed in the following locations inside t
 Editor
 ^^^^^^
 
-The name of the data directory for the Godot editor will always be ``GodotSharp``.
-The contents of this directory are the following:
+The name of the data directory for the Godot editor will always be
+``GodotSharp``. The contents of this directory are the following:
 
 - ``Api`` (optional)
 - ``Mono`` (optional)
@@ -226,14 +237,20 @@ In the case of macOS, if the Godot editor is distributed as a bundle, the conten
 Command-line options
 --------------------
 
-The following is the list of command-line options available when building with the mono module:
+The following is the list of command-line options available when building with
+the Mono module:
 
-- **module_mono_enabled**: Build Godot with the mono module enabled ( yes | **no** )
+- **module_mono_enabled**: Build Godot with the Mono module enabled
+  (yes | **no**)
 
-- **mono_glue**: Whether to include the glue source files in the build and define `MONO_GLUE_DISABLED` as a preprocessor macro ( **yes** | no )
+- **mono_glue**: Whether to include the glue source files in the build
+  and define ``MONO_GLUE_DISABLED`` as a preprocessor macro (**yes** | no)
 
-- **xbuild_fallback**: Whether to fallback to xbuild if MSBuild is not available ( yes | **no** )
+- **xbuild_fallback**: Whether to fallback to xbuild if MSBuild is not available
+  ( yes | **no** )
 
-- **mono_static**: Whether to link the mono runtime statically ( yes | **no** )
+- **mono_static**: Whether to link the Mono runtime statically
+  (yes | **no**)
 
-- **copy_mono_root**: Whether to copy the Mono framework assemblies and configuration files required by the Godot editor ( yes | **no** )
+- **copy_mono_root**: Whether to copy the Mono framework assemblies
+  and configuration files required by the Godot editor (yes | **no**)

development/compiling/introduction_to_the_buildsystem.rst

@@ -15,9 +15,8 @@ to move the build system to CMake, or Visual Studio, but this is not
 going to happen. There are many reasons why we have chosen SCons over
 other alternatives, for example:
 
--  Godot can be compiled for a dozen different platforms. All PC
-   platforms, all mobile platforms, many consoles, and many web-based
-   platforms (such as HTML5 and Chrome PNACL).
+-  Godot can be compiled for a dozen different platforms: all PC
+   platforms, all mobile platforms, many consoles, and WebAssembly.
 -  Developers often need to compile for several of the platforms **at
    the same time**, or even different targets of the same platform. They
    can't afford reconfiguring and rebuilding the project each time.
@@ -30,19 +29,24 @@ other alternatives, for example:
    customization (plugins). This requires complex logic which is easier
    to write in an actual programming language (like Python) rather than
    using a mostly macro-based language only meant for building.
--  Godot build process makes heavy use of cross compiling tools. Each
+-  Godot build process makes heavy use of cross-compiling tools. Each
    platform has a specific detection process, and all these must be
    handled as specific cases with special code written for each.
 
-So, please try to keep an open mind and get at least a little familiar with it if you are planning to
-build Godot yourself.
+So, please try to keep an open mind and get at least a little familiar with it
+if you are planning to build Godot yourself.
 
 Setup
 -----
 
-Please refer to the documentation for :ref:`doc_compiling_for_android`, :ref:`doc_compiling_for_ios`, :ref:`doc_compiling_for_osx`, :ref:`doc_compiling_for_uwp`, :ref:`doc_compiling_for_web`, :ref:`doc_compiling_for_windows` and :ref:`doc_compiling_for_x11`.
+Please refer to the documentation for :ref:`doc_compiling_for_android`,
+:ref:`doc_compiling_for_ios`, :ref:`doc_compiling_for_osx`,
+:ref:`doc_compiling_for_uwp`, :ref:`doc_compiling_for_web`,
+:ref:`doc_compiling_for_windows` and :ref:`doc_compiling_for_x11`.
 
-Note that for **Windows/Visual Studio**, you need to use ``x86_x64 Cross Tools Command Prompt for VS 2017`` or similar, depending on your install, instead of the standard Windows command prompt to enter the commands below.
+Note that for **Windows/Visual Studio**, you need to use ``x86_x64 Cross Tools
+Command Prompt for VS 2017`` or similar, depending on your install, instead of
+the standard Windows command prompt to enter the commands below.
 
 Platform selection
 ------------------
@@ -52,30 +56,25 @@ for. If not detected, the platform will simply not appear on the list of
 available platforms. The build requirements for each platform are
 described in the rest of this tutorial section.
 
-SCons is invoked by just calling ``scons``.
+SCons is invoked by just calling ``scons``. If no platform is specified,
+SCons will detect the target platform automatically based on the host platform.
+It will then start building for the target platform right away.
 
-However, this will do nothing except list the available platforms, for
-example:
+To list the available target platforms, use ``scons platform=list``::
 
-::
-
-    user@host:~/godot$ scons
+    user@host:~/godot$ scons platform=list
     scons: Reading SConscript files ...
-    No valid target platform selected.
-    The following were detected:
+    The following platforms are available:
+
         android
-        server
         javascript
+        server
         windows
         x11
 
-    Please run scons again with argument: platform=<string>
-    scons: done reading SConscript files.
-    scons: Building targets ...
-    scons: `.' is up to date.
-    scons: done building targets.
+    Please run SCons again and select a valid platform: platform=<string>
 
-To build for a platform (for example, x11), run with the ``platform=`` (or just
+To build for a platform (for example, x11), run with the ``platform=`` (or
 ``p=`` to make it short) argument:
 
 ::
@@ -83,8 +82,8 @@ To build for a platform (for example, x11), run with the ``platform=`` (or just
     user@host:~/godot$ scons platform=x11
 
 This will start the build process, which will take a while. If you want
-scons to build faster, use the ``-j <cores>`` parameter to specify how many
-cores will be used for the build. Or just leave it using one core, so you
+SCons to build faster, use the ``-j <cores>`` parameter to specify how many
+cores will be used for the build. Or leave it using one core, so you
 can use your computer for something else :)
 
 Example for using 4 cores:
@@ -96,16 +95,12 @@ Example for using 4 cores:
 Resulting binary
 ----------------
 
-The resulting binaries will be placed in the bin/ subdirectory,
-generally with this naming convention:
-
-::
+The resulting binaries will be placed in the ``bin/`` subdirectory,
+generally with this naming convention::
 
     godot.<platform>.[opt].[tools/debug].<architecture>[extension]
 
-For the previous build attempt the result would look like this:
-
-::
+For the previous build attempt, the result would look like this::
 
     user@host:~/godot$ ls bin
     bin/godot.x11.tools.64
@@ -113,18 +108,16 @@ For the previous build attempt the result would look like this:
 This means that the binary is for X11, is not optimized, has tools (the
 whole editor) compiled in, and is meant for 64 bits.
 
-A Windows binary with the same configuration will look like this.
-
-::
+A Windows binary with the same configuration will look like this::
 
-    C:\GODOT> DIR BIN/
+    C:\godot> dir bin/
     godot.windows.tools.64.exe
 
-Just copy that binary to wherever you like, as it contains the
-project manager, editor and all means to execute the game. However, it
-lacks the data to export it to the different platforms. For that the
-export templates are needed (which can be either downloaded from
-`godotengine.org <https://godotengine.org/>`__, or you can build them yourself).
+Copy that binary to any location you like, as it contains the project manager,
+editor and all means to execute the game. However, it lacks the data to export
+it to the different platforms. For that the export templates are needed (which
+can be either downloaded from `godotengine.org <https://godotengine.org/>`__, or
+you can build them yourself).
 
 Aside from that, there are a few standard options that can be set in all
 build targets, and which will be explained below.
@@ -150,19 +143,19 @@ Target controls optimization and debug flags. Each mode means:
    checks and reports error) and none to little optimization.
 -  **release_debug**: Build without C++ debugging symbols and
    optimization, but keep the runtime checks (performs checks and
-   reports errors). Official binaries use this configuration.
+   reports errors). Official editor binaries use this configuration.
 -  **release**: Build without symbols, with optimization and with little
    to no runtime checks. This target can't be used together with
-   tools=yes, as the tools require some debug functionality and run-time
+   ``tools=yes``, as the editor requires some debug functionality and run-time
    checks to run.
 
 ::
 
     scons platform=<platform> target=debug/release_debug/release
 
-This flag appends the ".debug" suffix (for debug), or ".tools" (for debug
-with tools enabled). When optimization is enabled (release) it appends
-the ".opt" suffix.
+This flag appends the ``.debug`` suffix (for debug), or ``.tools`` (for debug
+with tools enabled). When optimization is enabled (release), it appends
+the ``.opt`` suffix.
 
 Bits
 ----
@@ -171,18 +164,17 @@ Bits is meant to control the CPU or OS version intended to run the
 binaries. It is focused mostly on desktop platforms and ignored everywhere
 else.
 
--  **32**: Build binaries for 32 bits platform.
--  **64**: Build binaries for 64 bits platform.
--  **default**: Build whatever the build system feels is best. On Linux
-   this depends on the host platform (if not cross compiling),
-   on Mac it defaults to 64 bits and on Windows it defaults to 32 bits.
+-  **32**: Build binaries for 32-bit platforms.
+-  **64**: Build binaries for 64-bit platforms.
+-  **default**: Build for the architecture that matches the host platform.
 
 ::
 
     scons platform=<platform> bits=default/32/64
 
-This flag appends ".32" or ".64" suffixes to resulting binaries when
-relevant.
+This flag appends ``.32`` or ``.64`` suffixes to resulting binaries when
+relevant. If ``bits=default`` is used, the suffix will match the detected
+architecture.
 
 Other build options
 -------------------
@@ -203,7 +195,7 @@ to build them yourself (in case you want newer ones, you are using custom
 modules, or simply don't trust your own shadow).
 
 If you download the official export templates package and unzip it, you
-will notice that most are just optimized binaries or packages for each
+will notice that most files are optimized binaries or packages for each
 platform:
 
 ::
@@ -225,12 +217,19 @@ platform:
     windows_64_debug.exe
     windows_64_release.exe
 
-To create those yourself, just follow the instructions detailed for each
+To create those yourself, follow the instructions detailed for each
 platform in this same tutorial section. Each platform explains how to
 create its own template.
 
-If you are developing for multiple platforms, macOS is definitely the most convenient
-host platform for cross compilation, since you can cross-compile for
-almost every target (except for UWP). Linux and Windows come in second
-place, but Linux has the advantage of being the easier platform to set
-this up.
+The ``version.txt`` file should contain the corresponding Godot version
+identifier. This file is used to install export templates in a version-specific
+directory to avoid conflicts. For instance, if you are building export templates
+for Godot 3.1.1, ``version.txt`` should contain ``3.1.1.stable`` on the first
+line (and nothing else). This version identifier is based on the ``major``,
+``minor``, ``patch`` (if present) and ``status`` lines of the
+`version.py file in the Godot Git repository <https://github.com/godotengine/godot/blob/master/version.py>`__.
+
+If you are developing for multiple platforms, macOS is definitely the most
+convenient host platform for cross-compilation, since you can cross-compile for
+almost every target (except for UWP). Linux and Windows come in second place,
+but Linux has the advantage of being the easier platform to set this up.

development/cpp/configuring_an_ide.rst

@@ -295,4 +295,4 @@ To create them:
 
 - You can now start Debug process again to test that everything works.
 
-- If the build phase fails, check console for hints. On Linux it's most likely that some dependencies are missing. Check :ref:`Compiling for X11 (Linux, \*BSD) <doc_compiling_for_x11>`
+- If the build phase fails, check the console for hints. On Linux it's most likely that some dependencies are missing. Check :ref:`Compiling for X11 (Linux, \*BSD) <doc_compiling_for_x11>`

development/cpp/custom_modules_in_cpp.rst

@@ -21,7 +21,7 @@ transparently.
 What for?
 ---------
 
-While it's recommended that most of a game is written in scripting (as
+While it's recommended that most of a game be written in scripting (as
 it is an enormous time saver), it's perfectly possible to use C++
 instead. Adding C++ modules can be useful in the following scenarios:
 

getting_started/editor/command_line_tutorial.rst

@@ -135,7 +135,7 @@ that is headless (server build, no video) is ideal for this.
 
 ::
 
-    user@host:~/newgame$ godot --export "Linux X11" /var/builds/project
+    user@host:~/newgame$ godot --export "Linux/X11" /var/builds/project
     user@host:~/newgame$ godot --export Android /var/builds/project.apk
 
 The platform names recognized by the ``--export`` switch are the same as

getting_started/scripting/c_sharp/c_sharp_basics.rst

@@ -174,8 +174,8 @@ class reference pages for
 :ref:`@GDScript <class_@gdscript>` and :ref:`@GlobalScope <class_@globalscope>`.
 
 .. note::
-    Keep in mind that the class you wish to attach to your node should be
-    named as the ``.cs`` file. Otherwise, you will get the following error
+    Keep in mind that the class you wish to attach to your node should have the same
+    name as the ``.cs`` file. Otherwise, you will get the following error
     and won't be able to run the scene:
     *"Cannot find class XXX for script res://XXX.cs"*
 

getting_started/scripting/gdscript/gdscript_basics.rst

@@ -1351,7 +1351,7 @@ initializers, but they must be constant expressions.
 
     export(Array, int) var ints = [1,2,3]
     export(Array, int, "Red", "Green", "Blue") var enums = [2, 1, 0]
-    export(Array, Array, float) var two_dimensional = [[1, 2], [3, 4]]
+    export(Array, Array, float) var two_dimensional = [[1.0, 2.0], [3.0, 4.0]]
 
     # You can omit the default value, but then it would be null if not assigned.
 
@@ -1481,10 +1481,10 @@ to. To create custom signals for a class, use the ``signal`` keyword.
 .. note:: 
 
    Signals are a `Callback
-   <https://en.wikipedia.org/wiki/Callback_(computer_programming)>`
+   <https://en.wikipedia.org/wiki/Callback_(computer_programming)>`_
    mechanism. They also fill the role of Observers, a common programming
-   pattern. For more information, read the `Observer
-   tutorial<http://gameprogrammingpatterns.com/observer.html>`_ in the
+   pattern. For more information, read the `Observer tutorial
+   <https://gameprogrammingpatterns.com/observer.html>`_ in the
    Game Programming Patterns ebook.
 
 You can connect these signals to methods the same way you connect built-in
@@ -1529,7 +1529,7 @@ the :ref:`Object.connect() <class_Object_method_connect>` method:
 
         # We emit the health_changed signal every time the
         # character takes damage
-        emit_signal(health_changed", old_health, health)
+        emit_signal("health_changed", old_health, health)
     ...
 
 ::
@@ -1620,7 +1620,7 @@ Our ``BattleLog`` node receives each element in the binds array as an extra argu
    func _on_Character_health_changed(old_value, new_value, character_name):
       if not new_value <= old_value:
          return
-      var damage = new_value - old_value
+      var damage = old_value - new_value
       label.text += character_name + " took " + str(damage) + " damage."
 
 

getting_started/step_by_step/resources.rst

@@ -184,7 +184,7 @@ and :ref:`Resource <class_Resource>` features:
 
     Resources and Dictionaries are both passed by reference, but only Resources are
     reference-counted. This means that if a Dictionary is passed between objects and
-    the first object is deleted, all other objects' references to the Dictinoary will
+    the first object is deleted, all other objects' references to the Dictionary will
     be invalidated. Conversely, Resources will not be freed from memory until *all* the 
     objects are deleted.
 

getting_started/step_by_step/scripting.rst

@@ -211,7 +211,7 @@ a node, the NodePath at the bottom will automatically update to point to a
 relative path from the emitting node to the selected node.
 
 By default, the method name will contain the emitting node's name ("Button" in
-this case), resulting in "_on_[EmitterNode]_[signal_name]". If you do have the
+this case), resulting in ``_on_[EmitterNode]_[signal_name]``. If you do have the
 "Make Function" check button checked, then the editor will generate the function
 for you before setting up the connection.
 

getting_started/step_by_step/scripting_continued.rst

@@ -33,7 +33,7 @@ This method will be called every time a frame is drawn:
         // Do something...
     }
 
-It's important to bear in mind that the frequecy with which ``_process()``
+It's important to bear in mind that the frequency with which ``_process()``
 will be called depends on how many frames per second (FPS) your application
 is running at. This rate can vary over time and devices.
 
@@ -204,7 +204,7 @@ follows, can be applied to nodes:
  .. code-tab:: gdscript GDScript
 
     func _enter_tree():
-        # When the node enters the _Scene Tree_, it becomes active
+        # When the node enters the Scene Tree, it becomes active
         # and  this function is called. Children nodes have not entered
         # the active scene yet. In general, it's better to use _ready()
         # for most cases.
@@ -212,13 +212,13 @@ follows, can be applied to nodes:
 
     func _ready():
         # This function is called after _enter_tree, but it ensures
-        # that all children nodes have also entered the _Scene Tree_,
+        # that all children nodes have also entered the Scene Tree,
         # and became active.
         pass
 
     func _exit_tree():
-        # When the node exits the _Scene Tree_, this function is called.
-        # Children nodes have all exited the _Scene Tree_ at this point
+        # When the node exits the Scene Tree, this function is called.
+        # Children nodes have all exited the Scene Tree at this point
         # and all became inactive.
         pass
 
@@ -234,7 +234,7 @@ follows, can be applied to nodes:
 
     public override void _EnterTree()
     {
-        // When the node enters the _Scene Tree_, it becomes active
+        // When the node enters the Scene Tree, it becomes active
         // and  this function is called. Children nodes have not entered
         // the active scene yet. In general, it's better to use _ready()
         // for most cases.
@@ -244,15 +244,15 @@ follows, can be applied to nodes:
     public override void _Ready()
     {
         // This function is called after _enter_tree, but it ensures
-        // that all children nodes have also entered the _Scene Tree_,
+        // that all children nodes have also entered the Scene Tree,
         // and became active.
         base._Ready();
     }
 
     public override void _ExitTree()
     {
-        // When the node exits the _Scene Tree_, this function is called.
-        // Children nodes have all exited the _Scene Tree_ at this point
+        // When the node exits the Scene Tree, this function is called.
+        // Children nodes have all exited the Scene Tree at this point
         // and all became inactive.
         base._ExitTree();
     }

getting_started/step_by_step/ui_introduction_to_the_ui_system.rst

@@ -3,7 +3,7 @@
 Design interfaces with the Control nodes
 ========================================
 
-Computer displays, mobile phones, and TV screen come in all shapes and
+Computer displays, mobile phones, and TV screens come in all shapes and
 sizes. To ship a game, you'll need to support different screen ratios
 and resolutions. It can be hard to build responsive interfaces that
 adapt to all platforms. Thankfully, Godot comes with robust tools to
@@ -132,7 +132,7 @@ To animate the bar, you'll want to look at the Range section. Set the
 ``Min`` and ``Max`` properties to define the range of the gauge. For instance,
 to represent a character's life, you'll want to set ``Min`` to ``0,`` and ``Max`` to
 the character's maximum life. Change the ``Value`` property to update the
-bar. If you leave the ``Min`` and ``Max`` values to the default of ``1`` and ``100,``
+bar. If you leave the ``Min`` and ``Max`` values to the default of ``0`` and ``100,``
 and set the ``Value`` property to ``40``, 40% of the ``Progress`` texture will show
 up, and 60% of it will stay hidden.
 

getting_started/step_by_step/ui_main_menu.rst

@@ -167,7 +167,8 @@ you pick a sprite to load into the texture slot.
 Repeat the operation for all ``TextureRect`` nodes. You should have the
 logo, the illustration, the three menu options and the version note,
 each as a separate node. Then, double click on each of the nodes in the
-Scene tab to rename them.
+Scene tab to rename them. Nothing has been placed in containers yet so this
+should look messy.
 
 .. figure:: img/ui_main_menu_6_texturerect_nodes.png
 

getting_started/step_by_step/your_first_game.rst

@@ -102,8 +102,7 @@ for our player. Notice that there is a warning symbol next to the node.
 An ``AnimatedSprite`` requires a :ref:`SpriteFrames <class_SpriteFrames>` resource, which is a
 list of the animations it can display. To create one, find the
 ``Frames`` property in the Inspector and click "[empty]" ->
-"New SpriteFrames". Next, in the same location, click
-``<SpriteFrames>``, then click "Open Editor" to open the "SpriteFrames" panel:
+"New SpriteFrames". This should automatically open the SpriteFrames panel.
 
 .. image:: img/spriteframes_panel.png
 
@@ -891,7 +890,7 @@ Create the following as children of the ``HUD`` node:
 -  :ref:`Button <class_Button>` named ``StartButton``.
 -  :ref:`Timer <class_Timer>` named ``MessageTimer``.
 
-Click on the ``ScoreLabel`` and type a number into the ``Text`` field in the
+Click on the ``ScoreLabel`` and type a number into the *Text* field in the
 Inspector. The default font for ``Control`` nodes is small and doesn't scale
 well. There is a font file included in the game assets called
 "Xolonium-Regular.ttf". To use this font, do the following for each of
@@ -1214,10 +1213,10 @@ Since the game is played with keyboard controls, it would be convenient if we
 could also start the game by pressing a key on the keyboard. One way to do this
 is using the "Shortcut" property of the ``Button`` node.
 
-In the ``HUD`` scene, select the ``StartButton`` and find its ``Shortcut`` property
+In the ``HUD`` scene, select the ``StartButton`` and find its *Shortcut* property
 in the Inspector. Select "New Shortcut" and click on the "Shortcut" item. A
-second ``Shortcut`` property will appear. Select "New InputEventAction" and click
-the new "InputEvent". Finally, in the ``Action`` property, type the name "ui_select".
+second *Shortcut* property will appear. Select "New InputEventAction" and click
+the new "InputEvent". Finally, in the *Action* property, type the name ``ui_select``.
 This is the default input event associated with the spacebar.
 
 .. image:: img/start_button_shortcut.png

getting_started/workflow/assets/importing_audio_samples.rst

@@ -10,6 +10,7 @@ Raw audio data in general is large and undesired. Godot provides two main
 options to import your audio data: WAV and OGG Vorbis.
 
 Each has different advantages.
+
 * Wav files use raw data or light compression, make few demands on the CPU to play back (hundreds of simultaneous voices in this format are fine), but take up significant space.
 * Ogg Vorbis files use a stronger compression that results in much smaller file size, but require significantly more processing power to play back.
 

getting_started/workflow/best_practices/data_preferences.rst

@@ -173,7 +173,7 @@ The important detail here is the complexity of the Object's task. Every time
 it performs one of these multi-source queries, it runs through *several*
 iteration loops and HashMap lookups. What's more, the queries are linear-time
 operations dependent on the Object's inheritance hierarchy size. If the class
-the Object queries (it's current class) doesn't find anything, the request
+the Object queries (its current class) doesn't find anything, the request
 defers to the next base class, all the way up until the original Object class.
 While these are each fast operations in isolation, the fact that it must make
 so many checks is what makes them slower than both of the alternatives for

getting_started/workflow/best_practices/godot_notifications.rst

@@ -67,7 +67,7 @@ One can access all these custom notifications from the universal
 
   A classic example is the
   :ref:`_init <class_Object_method__init>` method in Object. While it has no
-  NOTIFICATION_* equivalent, the engine still calls the method. Most languages
+  ``NOTIFICATION_*`` equivalent, the engine still calls the method. Most languages
   (except C#) rely on it as a constructor.
 
 So, in which situation should one use each of these notifications or
@@ -296,4 +296,4 @@ nodes that one might create at runtime.
         {
             GD.Print("I'm reacting to my parent's interaction!");
         }
-    }
+    }

getting_started/workflow/best_practices/introduction_best_practices.rst

@@ -3,22 +3,27 @@
 Introduction
 ============
 
-This tutorial series aims to illustrate intended Godot workflows, i.e. the
-"best practices" of defining one's game API. Godot allows for a great 
-amount of flexibility in how one designs a project's code and scene
-structure. Each method will have its own advantages and disadvantages,
-so outlining the best practices should help users feel less confused
-as they further explore Godot's depth.
-
-This series is also designed to help get users thinking about the best way
-to reason about best practices. It would be impossible to give a comprehensive
-overview of what one should do for any arbitrary design decision. As such,
-each article breaks problems down into the fundamental questions they pose,
-suggests the available solutions, analyzes the advantages and disadvantages
-of each option, and then highlights the best course of action depending on the
-circumstances.
-
-While the articles in this series are largely topic-directed, it is
-recommended that users begin with the :ref:`doc_what_are_godot_classes` article.
-It is from there that the "best practices" for the rest of the engine
-become more clear, based on established OOP practices.
+This series is a collection of best practices to help you work efficiently with
+Godot.
+
+Godot allows for a great amount of flexibility in how you structure a project's
+codebase and break it down into scenes. Each approach has its own pros and
+cons, and they can be hard to weigh until you've worked with the engine for long enough.
+
+There are always many ways to structure your code and solve specific programming
+problems. It would be impossible to cover them all here.
+
+That is why each article starts from a real-world problem. We will break down
+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.
+
+.. note::
+
+   The best practices in Godot rely on Object-Oriented design principles. We
+   use tools like the `single responsibility
+   <https://en.wikipedia.org/wiki/Single_responsibility_principle>`_ principle and
+   `encapsulation <https://en.wikipedia.org/wiki/Encapsulation_(computer_programming)>`_.

getting_started/workflow/best_practices/what_are_godot_classes.rst

@@ -1,80 +1,91 @@
 .. _doc_what_are_godot_classes:
 
-What are Godot classes really?
-==============================
+Godot scenes and scripts are classes
+====================================
 
-Godot offers two main means of creating types: scripts and scenes.
-Both of these represent a "class" since Godot revolves around
-Object-Oriented design. *How* they do this may not be clear to beginner
-or intermediate users though.
+In Godot, scripts and scenes can both be the equivalent of classes in an
+Object-Oriented programming language. The main difference is that scenes are
+`declarative code <https://en.wikipedia.org/wiki/Declarative_programming>`_,
+while scripts can contain `imperative code
+<https://en.wikipedia.org/wiki/Imperative_programming>`_.
 
-Godot Engine provides classes out-of-the-box (like
-:ref:`Node <class_Node>`), but user-created types are not actually classes.
-Instead they are resources that tell the engine a sequence of initializations
-to perform on an engine class.
+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.
 
-Godot's internal classes have methods that register a class's data with
-a :ref:`ClassDB <class_ClassDB>`. This database provides runtime access to
-class information (also called "reflection"). Things stored in the ClassDB
-include, among other things...
+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
+understand where some of this series' best practices come from.
 
-- properties
+Making sense of classes in Godot
+--------------------------------
 
-- methods
+Godot Engine provides built-in classes like :ref:`Node <class_Node>`.
+User-created types are not technically classes. Instead, they are resources that
+tell the engine a sequence of initializations to perform on one of the engine's
+built-in classes.
 
-- constants
+Godot's internal classes have methods that register a class's data with a
+:ref:`ClassDB <class_ClassDB>`. This database provides runtime access to class
+information. ``ClassDB`` contains information about classes like:
 
+- properties
+- methods
+- constants
 - signals
 
-Furthermore, this ClassDB is what Objects actually check against when
-performing any operation. Access a property? Call a method? Emit a signal?
-It will check the database's records (and the records of the Object's base
-types) to see if the Object supports the operation. Every C++ Object defines
-a static `_bind_methods()` function that describes what C++ content it
-registers to the database and how.
-
-So, if the engine provides all of this data at startup, then how does
-a user define their own data? It'd be nice if users could define a custom
-set of data to be appended to an object's data. That way, users could inject
-their own properties and methods into the engine's Object query requests.
-
-*This* is what a :ref:`Script <class_Script>` is. Objects check their attached
-script before the database, so scripts can even override methods.
-If a script defines a `_get_property_list()` method, that data is appended to
-the list of properties the Object fetches from the ClassDB. The same holds
-true for other declarative code.
-
-This can lead to some users' confusion when they see a script as being
-a class unto itself. In reality, the engine just auto-instantiates the
-base engine class and then adds the script to that object. This then allows
-the Object to defer to the Script's content where the engine logic deems
-appropriate.
-
-A problem does present itself though. As the size of Objects increases,
-the scripts' necessary size to create them grows much, much larger.
-Creating node hierarchies demonstrates this. Each individual Node's logic
-could be several hundred lines of code in length.
-
-let's see a simple example of creating a single Node as a child.
+This ``ClassDB`` is what Objects check against when performing an operation like
+accessing a property or calling a method. ``ClassDB`` checks the database's
+records and the records of the Object's base types to see if the Object supports
+the operation.
+
+On the engine's side, every class defines a static ``_bind_methods()`` function
+that describes what C++ content it registers to the database and how. When you
+use the engine, you can extend the methods, properties, and signals available from
+the ``ClassDB`` by attaching a :ref:`Script <class_Script>` to your node.
+
+Objects check their attached script before the database. This is why scripts can
+override built-in methods. If a script defines a ``_get_property_list()`` method,
+Godot appends that data to the list of properties the Object fetches from the
+ClassDB. The same is true for other declarative code.
+
+Even scripts that don't inherit from a built-in type, i.e. scripts that don't
+start with the ``extends`` keyword, implicitly inherit from the engine's base
+:ref:`Reference <class_Reference>` class. This allows the Object to defer
+to the script's content where the engine logic deems appropriate.
+
+.. note::
+
+   As a result, you can instance scripts without the ``extends`` keyword
+   from code, but you cannot attach them to a :ref:`Node <class_Node>`
+
+
+Scripting performances and PackedScene
+--------------------------------------
+
+As the size of Objects increases, the scripts' necessary size to create them
+grows much, much larger. Creating node hierarchies demonstrates this. Each
+individual Node's logic could be several hundred lines of code in length.
+
+Let's see a simple example of creating a single ``Node`` as a child. The code
+below creates a new ``Node``, changes its name, assigns a script to it, sets its
+future parent as its owner so it gets saved to disk along with it, and finally
+adds it as a child of the ``Main`` node:
 
 .. tabs::
   .. code-tab:: gdscript GDScript
 
-    # main.gd
+    # Main.gd
     extends Node
 
-    var child # define a variable to store a reference to the child
-
     func _init():
-        child = Node.new() # Construct the child.
-        child.name = "Child" # Change its name.
-        child.script = preload("child.gd") # Give it custom features.
-        child.owner = self # Serialize this node if self is saved.
-        add_child(child) # Add "Child" as a child of self.
+        var child = Node.new()
+        child.name = "Child"
+        child.script = preload("Child.gd")
+        child.owner = self
+        add_child(child)
 
   .. code-tab:: csharp
 
-    // Main.cs
     using System;
     using Godot;
 
@@ -86,53 +97,43 @@ let's see a simple example of creating a single Node as a child.
 
             public Main()
             {
-                Child = new Node(); // Construct the child.
-                Child.Name = "Child"; // Change its name.
-                Child.Script = (Script)ResourceLoader.Load("child.gd"); // Give it custom features.
-                Child.Owner = this; // Serialize this node if this is saved.
-                AddChild(Child); // Add "Child" as a child of this.
+                Child = new Node();
+                Child.Name = "Child";
+                Child.Script = (Script)ResourceLoader.Load("child.gd");
+                Child.Owner = this;
+                AddChild(Child);
             }
         }
     }
 
-Notice that only two pieces of declarative code are involved in
-the creation of this child node: the variable declaration and
-the constructor declaration. Everything else about the child
-must be setup using imperative code. However, script code is
-much slower than engine C++ code. Each change must make a separate
-call to the scripting API which means a lot of C++ "lookups" within
-data structures to find the corresponding logic to execute.
-
-To help offload the work, it would be convenient if one could batch up
-all operations involved in creating and setting up node hierarchies. The
-engine could then handle the construction using its fast C++ code, and the
-script code would be free from the perils of imperative code.
-
-*This* is what a scene (:ref:`PackedScene <class_PackedScene>`) is: a
-resource that provides an advanced "constructor" serialization which is
-offloaded to the engine for batch processing.
+Script code like this is much slower than engine-side C++ code. Each change
+makes a separate call to the scripting API which leads to many "look-ups" on the
+back-end to find the logic to execute.
 
-Now, why is any of this important to scene organization? Because one must
-understand that scenes *are* objects. One often pairs a scene with
-a scripted root node that makes use of the sub-nodes. This means that the
-scene is often an extension of the script's declarative code.
+Scenes help to avoid this performance issue. :ref:`PackedScene
+<class_PackedScene>`, the base type that scenes inherit from, are resources that
+use serialized data to create objects. The engine can process scenes in batches
+on the back-end and provide much better performance than scripts.
 
-It helps to define...
+Scenes and scripts are objects
+------------------------------
 
-- what objects are available to the script?
+Why is any of this important to scene organization? Because scenes *are*
+objects. One often pairs a scene with a scripted root node that makes use of the
+sub-nodes. This means that the scene is often an extension of the script's
+declarative code.
 
-- how are they organized?
+The content of a scene helps to define:
 
-- how are they initialized?
+- What nodes are available to the script
+- How they are organized
+- How are they initialized
+- What signal connections they have with each other
 
-- what connections to each other do they have, if any?
+Many Object-Oriented principles which apply to written code *also* apply to
+scenes.
 
-As such, many Object-Oriented principles which apply to "programming", i.e.
-scripts, *also* apply to scenes. Some scripts are designed to only work
-in one scene (which are often bundled into the scene itself). Other scripts
-are meant to be re-used between scenes.
+The scene is *always an extension of the script attached to its root node*. You
+can see all the nodes it contains as part of a single class.
 
-**Regardless, the scene is always an extension of the root script, and can
-therefore be interpreted as a part of the class.**
-Most of the points covered in this series will build on this point, so
-keep it in mind.
+Most of the tips and techniques explained in this series will build on this.

index.rst

@@ -54,17 +54,7 @@ in the top left corner.
           ``#godotengine-doc`` channel on `irc.freenode.net
           <http://webchat.freenode.net/?channels=#godotengine-doc>`_!
 
-.. only:: not i18n
-
-  .. image:: https://hosted.weblate.org/widgets/godot-engine/-/godot-docs/287x66-white.png
-      :alt: Translation status
-      :align: center
-      :target: https://hosted.weblate.org/engage/godot-engine/?utm_source=widget
-
-.. only:: i18n
-
-  .. centered:: |weblate_widget|
-
+.. centered:: |weblate_widget|
 
 The main documentation for the site is organized into the following sections:
 

tutorials/3d/environment_and_post_processing.rst

@@ -256,6 +256,7 @@ Tweaking SSAO is possible with several parameters:
 - **Radius2/Intensity2:** A Secondary radius/intensity can be used. Combining a large and a small radius AO generally works well.
 - **Bias:** This can be tweaked to solve self occlusion, though the default generally works well enough.
 - **Light Affect:** SSAO only affects ambient light, but increasing this slider can make it also affect direct light. Some artists prefer this effect.
+- **Ao Channel Affect:** If a value of zero is used, only the material's AO texture will be used for ambient occlusion; SSAO will not be applied. Values greater than 0 multiply the AO texture by the SSAO effect to varying degrees. This does not affect materials without an AO texture.
 - **Quality:** Depending on quality, SSAO will take more samples over a sphere for every pixel. High quality only works well on modern GPUs.
 - **Blur:** Type of blur kernel used. The 1x1 kernel is a simple blur that preserves local detail better, but is not as efficient (generally works better with the high quality setting above), while 3x3 will soften the image better (with a bit of dithering-like effect), but does not preserve local detail as well.
 - **Edge Sharpness**: This can be used to preserve the sharpness of edges (avoids areas without AO on creases).

tutorials/3d/fps_tutorial/part_one.rst

@@ -618,7 +618,7 @@ _________
 
 Now let's look at ``process_movement``:
 
-First we ensure that ``dir`` does not have any movement on the ``Y`` axis by setting it's ``Y`` value to zero.
+First we ensure that ``dir`` does not have any movement on the ``Y`` axis by setting its ``Y`` value to zero.
 
 Next we normalize ``dir`` to ensure we're within a ``1`` radius unit circle. This makes it where we're moving at a constant speed regardless
 of whether the player is moving straight or diagonally. If we did not normalize, the player would move faster on the diagonal than when going straight.

tutorials/3d/high_dynamic_range.rst

@@ -101,65 +101,8 @@ indie games.
 Parameters of HDR
 -----------------
 
-HDR is found in the :ref:`Environment <class_Environment>`
+HDR setting can be found in the :ref:`Environment <class_Environment>`
 resource. These are found most of the time inside a
 :ref:`WorldEnvironment <class_WorldEnvironment>`
-node or set in a camera. There are many parameters for HDR:
-
-.. image:: img/hdr_parameters.png
-
-ToneMapper
-~~~~~~~~~~
-
-The ToneMapper is the heart of the algorithm. Many options for
-tonemappers are provided:
-
--  **Linear:** Simplest tonemapper. It does its job for adjusting scene
-   brightness, but if the differences in light are too big, it will
-   cause colors to be too saturated.
--  **Log:** Similar to linear but not as extreme.
--  **Reinhardt:** Classical tonemapper (modified, so it will not desaturate
-   as much)
--  **ReinhardtAutoWhite:** Same as above, but uses the max scene luminance
-   to adjust the white value.
-
-Exposure
-~~~~~~~~
-
-The same exposure parameter as in real cameras. Controls how much light
-enters the camera. Higher values will result in a brighter scene, and
-lower values will result in a darker scene.
-
-White
-~~~~~
-
-Maximum value of white.
-
-Glow threshold
-~~~~~~~~~~~~~~
-
-Determines above which value (from 0 to 1 after the scene is tonemapped)
-light will start bleeding.
-
-Glow scale
-~~~~~~~~~~
-
-Determines how much light will bleed.
-
-Min luminance
-~~~~~~~~~~~~~
-
-Lower bound value of light for the scene at which the tonemapper stops
-working. This allows dark scenes to remain dark.
-
-Max luminance
-~~~~~~~~~~~~~
-
-Upper bound value of light for the scene at which the tonemapper stops
-working. This allows bright scenes to remain saturated.
-
-Exposure adjustment speed
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Auto-exposure will change slowly and will take a while to adjust (like
-in real cameras). Bigger values mean faster adjustment.
+node or set in a camera. For more information see
+:ref:`doc_environment_and_post_processing`.

tutorials/3d/lights_and_shadows.rst

@@ -35,6 +35,7 @@ Each one has a specific function:
 -  **Indirect Energy**: Secondary multiplier used with indirect light (light bounces). This works in baked light or GIProbe.
 -  **Negative**: Light becomes subtractive instead of additive. It's sometimes useful to manually compensate some dark corners.
 -  **Specular**: Affects the intensity of the specular blob in objects affected by this light. At zero, this light becomes a pure diffuse light.
+-  **Bake Mode**: Sets the bake mode for the light. For more information see :ref:`doc_baked_lightmaps`
 -  **Cull Mask**: Objects that are in the selected layers below will be affected by this light.
 
 Shadow mapping

tutorials/3d/spatial_material.rst

@@ -116,6 +116,11 @@ Disable Ambient Light
 Makes the object not receive any kind of ambient lighting that would
 otherwise light it.
 
+Ensure Correct Normals
+~~~~~~~~~~~~~~~~~~~~~~
+
+Fixes normals when non-uniform scaling is used.
+
 Vertex Color
 ------------
 
@@ -244,6 +249,11 @@ faces the camera:
 
 The above options are only enabled for Particle Billboard.
 
+Billboard Keep Scale
+~~~~~~~~~~~~~~~~~~~~
+
+Enables scaling a mesh in billboard mode.
+
 Grow
 ~~~~
 

tutorials/gui/gui_containers.rst

@@ -25,7 +25,7 @@ When a :ref:`Container <class_Container>`-derived node is used, all children :re
 own positioning ability. This means the *Container* will control their positioning and any attempt to manually alter these
 nodes will be either ignored or invalidated the next time their parent is resized.
 
-Likewise, when a *Container* derived node is resized, all it's children will be re-positioned according to it, 
+Likewise, when a *Container* derived node is resized, all its children will be re-positioned according to it, 
 with a behavior based on the type of container used:
 
    .. image:: img/container_example.gif

tutorials/legal/complying_with_licenses.rst

@@ -19,7 +19,7 @@ In the case of the MIT license, the only requirement is to include the license t
 This text reads as follows:
 
 
-	Godot Engine
+	This game uses Godot Engine, available under the following license:
 
 	Copyright (c) 2007-2019 Juan Linietsky, Ariel Manzur.
 	Copyright (c) 2014-2019 Godot Engine contributors.
@@ -31,6 +31,8 @@ This text reads as follows:
 	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 
+.. note:: Your games do not need to be under the same license. You are free to release your Godot projects under any license and to create commercial games with the engine.
+
 Inclusion
 ---------
 
@@ -69,7 +71,7 @@ Godot itself contains software written by `third parties <https://github.com/god
 FreeType
 ^^^^^^^^
 
-Godot uses `FreeType <https://www.freetype.org/>`_ to render fonts. It's license requires attribution, so the following text must be included together with the Godot license:
+Godot uses `FreeType <https://www.freetype.org/>`_ to render fonts. Its license requires attribution, so the following text must be included together with the Godot license:
 
 
 	Portions of this software are copyright © <year> The FreeType Project (www.freetype.org).  All rights reserved.

tutorials/networking/high_level_multiplayer.rst

@@ -198,14 +198,14 @@ Let's get back to the lobby. Imagine that each player that connects to the serve
     var my_info = { name = "Johnson Magenta", favorite_color = Color8(255, 0, 255) }
 
     func _player_connected(id):
-        pass # Will go unused; not useful here.
+        # Called on both clients and server when a peer connects. Send my info to it.
+        rpc_id(id, "register_player", player_name)
 
     func _player_disconnected(id):
         player_info.erase(id) # Erase player from info.
 
     func _connected_ok():
-        # Only called on clients, not server. Send my ID and info to all the other peers.
-        rpc("register_player", get_tree().get_network_unique_id(), my_info)
+        pass # Only called on clients, not server. Will go unused; not useful here.
 
     func _server_disconnected():
         pass # Server kicked us; show error and abort.
@@ -213,16 +213,11 @@ Let's get back to the lobby. Imagine that each player that connects to the serve
     func _connected_fail():
         pass # Could not even connect to server; abort.
 
-    remote func register_player(id, info):
+    remote func register_player(info):
+        # Get the id of the RPC sender.
+        var id = get_tree().get_rpc_sender_id()
         # Store the info
         player_info[id] = info
-        # If I'm the server, let the new guy know about existing players.
-        if get_tree().is_network_server():
-            # Send my info to new player
-            rpc_id(id, "register_player", 1, my_info)
-            # Send the info of existing players
-            for peer_id in player_info:
-                rpc_id(id, "register_player", peer_id, player_info[peer_id])
 
         # Call function to update lobby UI here
 
@@ -230,7 +225,7 @@ You might have already noticed something different, which is the usage of the `r
 
 ::
 
-    remote func register_player(id, info):
+    remote func register_player(info):
 
 This keyword has two main uses. The first is to let Godot know that this function can be called from RPC. If no keywords are added,
 Godot will block any attempts to call functions for security. This makes security work a lot easier (so a client can't call a function

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

@@ -5,14 +5,28 @@ GDNative C example
 
 Introduction
 ------------
-This tutorial will introduce you to the bare minimum required to create GDNative modules. This should be your starting point into the world of GDNative, understanding the contents of this tutorial will help you in understanding all that is to come after this.
 
-Before we begin, you can download the source code to the example object we'll be describing here by following this link:
-https://github.com/GodotNativeTools/GDNative-demos/tree/master/c/SimpleDemo
+This tutorial will introduce you to the bare minimum required to create GDNative
+modules. This should be your starting point into the world of GDNative.
+Understanding the contents of this tutorial will help you in understanding all
+that is to come after this.
 
-This example project also contains a SConstruct file that makes compiling a little easier but in this tutorial we'll be doing things by hand.
+Before we begin, you can download the source code to the example object we
+describe below in the `GDNative-demos repository
+<https://github.com/GodotNativeTools/GDNative-demos/tree/master/c/SimpleDemo>`_.
 
-:ref:`GDNative <class_GDNative>` can be used to create several types of additions to Godot, from PluginScript to ARVR interfaces. In this tutorial we are going to look at creating a :ref:`NativeScript <class_NativeScript>` module. NativeScript allows you to write logic in C or C++ in similar fashion as you would write a GDScript file. We'll be creating the C equivalent of this GDScript:
+This example project also contains a SConstruct file that makes compiling a
+little easier, but in this tutorial we'll be doing things by hand to
+understand the process.
+
+:ref:`GDNative <class_GDNative>` can be used to create several types of
+additions to Godot, using interfaces such as
+:ref:`PluginScript <class_PluginScript>` or
+:ref:`ARVRInterfaceGDNative <class_ARVRInterfaceGDNative>`. In this tutorial we
+are going to look at creating a :ref:`NativeScript <class_NativeScript>`
+module. NativeScript allows you to write logic in C or C++ in a similar fashion
+as you would write a GDScript file. We'll be creating the C equivalent of this
+GDScript:
 
 ::
 
@@ -26,19 +40,24 @@ This example project also contains a SConstruct file that makes compiling a litt
     func get_data():
         return data
 
-We'll be writing separate tutorials on the other types of GDNative modules and explain what each of them is for as we go through them.
+Future tutorials will focus on the other types of GDNative modules and explain
+when and how to use each of them.
 
 Prerequisites
 -------------
-Before we start you'll need a few things.
 
-1) A Godot 3.0 executable
-2) A C compiler
-3) A copy of this repository: https://github.com/GodotNativeTools/godot_headers
+Before we start you'll need a few things:
 
-The first two pretty much speak for themselves. On Linux, you'll likely have a C compiler, on macOS, it's easiest to install Xcode from the Mac App Store and, on Windows, we've tested this with both MSVC 2015 and 2017.
+1) A Godot executable for your target version.
+2) A C compiler. On Linux, install ``gcc`` or ``clang`` from your package
+   manager. On macOS, you can install Xcode from the Mac App Store. On Windows,
+   you can use Visual Studio 2015 or later, or MinGW-w64.
+3) A Git clone of the `godot_headers
+   repository <https://github.com/GodotNativeTools/godot_headers>`_: these are
+   the C headers for Godot's public API exposed to GDNative.
 
-For number 3, we suggest that you create a folder somewhere that you use to store your code, open up a terminal and CD into that folder. Then execute:
+For the latter, we suggest that you create a dedicated folder for this GDNative
+example project, open a terminal in that folder and execute:
 
 .. code-block:: none
 
@@ -46,82 +65,135 @@ For number 3, we suggest that you create a folder somewhere that you use to stor
 
 This will download the required files into that folder.
 
-.. note:: On this repository you will now find different branches. As Godot evolves, so does GDNative. With the exception of one breaking change in ARVR between 3.0 and 3.1, GDNative modules build for older versions of Godot will work with newer versions of Godot but not the other way around.
-
-The master branch of the ``godot_headers`` repository is kept in line with the master branch of Godot and thus contains the GDNative class and structure definitions that will work with the latest Godot master.
+.. tip::
 
-The 3.0 branch of the ``godot_headers`` repository contains the GDNative class and structure definitions that will work with Godot 3.0. You can clone this branch by executing:
+    If you plan to use Git for your GDNative project, you can also add
+    ``godot_headers`` as a Git submodule.
 
-.. code-block:: none
+.. note::
 
-    git clone https://github.com/GodotNativeTools/godot_headers -b 3.0
+    The ``godot_headers`` repository has different branches. As Godot evolves,
+    so does GDNative. While we try to preserve compatibility between version,
+    you should always build your GDNative module against headers matching the
+    Godot stable branch (e.g. ``3.1``) and ideally actual release (e.g.
+    ``3.1.1-stable``) that you use.
+    GDNative modules built against older versions of the Godot headers *may*
+    work with newer versions of the engine, but not the other way around.
 
-If you are building Godot from source with your own changes that impact GDNative, you can find the updated class and structure definition in ``<godotsource>/modules/gdnative/include``
+The ``master`` branch of the ``godot_headers`` repository is kept in line with
+the ``master`` branch of Godot and thus contains the GDNative class and
+structure definitions that will work with the latest development builds.
 
-Our C source
-------------
-Let's start by writing our main code. Ideally, we want to end up with a file structure that looks something like this:
+If you want to write a GDNative module for a stable version of Godot, look at
+the available Git tags (with ``git tags``) for the one matching your engine
+version. In the ``godot_headers`` repository, such tags are prefixed with
+``godot-``, so you can e.g. checkout the ``godot-3.1.1-stable`` tag for use with
+Godot 3.1.1. In your cloned repository, you can do:
 
 .. code-block:: none
 
-  + <your development folder>
-    + godot_headers
-      - <lots of files here>
-    + simple
-      + bin
-        - libsimple.dll/so/dylib
-        - libsimple.gdnlib
-        - simple.gdns
-      + src
-        - .gdignore
-        - simple.c
-      main.tscn
-      project.godot
+    git checkout godot-3.1.1-stable
 
-Open up Godot and create a new project called simple. This will create the ``simple`` folder and ``project.godot`` file. Then manually create a ``bin`` and ``src`` subfolder in this folder.
+If a tag matching your stable release is missing for any reason, you can fall
+back to the matching stable branch (e.g. ``3.1``), which you would also check
+out with ``git checkout 3.1``.
 
-We're going to start by having a look at what our ``simple.c`` file contains. Now, for our example here we're making a single C source file without a header to keep things simple. Once you start writing bigger projects it is advisable you break your project up into multiple files. That however falls outside of the scope of this tutorial.
+If you are building Godot from source with your own changes that impact
+GDNative, you can find the updated class and structure definition in
+``<godotsource>/modules/gdnative/include``
 
-We'll be looking at the source code bit by bit so all the parts below should all be put together into one big file. I'll explain each section as we add it.
-
-The below code includes our header files that we need and then defines two pointers to two different structs.
-GDNative supports a large collection for functions for calling back into the main Godot executable. In order for your module to have access to these functions, GDNative provides your application with a struct containing pointers to all these functions.
+Our C source
+------------
 
-To keep this implementation modular and easily extendable, the core functions are available directly through the "core" API struct, but additional functions have their own "GDNative structs" that are accessible through extensions.
+Let's start by writing our main code. Eventually, we want to end up with a file
+structure that looks along those lines:
 
-In our example, we access one of these extension to gain access to the functions specifically needed for NativeScript.
+.. code-block:: none
 
-.. code:: C
+    + <your development folder>
+      + godot_headers
+        - <lots of files here>
+      + simple
+        + bin
+          - libsimple.dll/so/dylib
+          - libsimple.gdnlib
+          - simple.gdns
+        + src
+          - .gdignore
+          - simple.c
+        main.tscn
+        project.godot
+
+Open up Godot and create a new project called "simple" alongside your
+``godot_headers`` Git clone. This will create the ``simple`` folder and
+``project.godot`` file. Then manually create ``bin`` and ``src`` subfolders in
+this folder.
+
+We're going to start by having a look at what our ``simple.c`` file contains.
+Now, for our example here we're making a single C source file without a header
+to keep things simple. Once you start writing bigger projects it is advisable
+to break your project up into multiple files. That however falls outside of the
+scope of this tutorial.
+
+We'll be looking at the source code bit by bit so all the parts below should all
+be put together into one big file. Each section will be explained as we add it.
+
+.. code-block:: C
 
     #include <gdnative_api_struct.gen.h>
-    #include <stdio.h>
-    #include <stdlib.h>
+
     #include <string.h>
 
     const godot_gdnative_core_api_struct *api = NULL;
     const godot_gdnative_ext_nativescript_api_struct *nativescript_api = NULL;
 
-A NativeScript behaves like any other script in Godot. Because the NativeScript API is rather low level, it requires the library to specify many things more verbosely than other scripting systems, such as GDScript. When a NativeScript instance gets created, a library-given constructor gets called. When that instance gets destroyed, the given destructor will be executed.
+The above code includes the GDNative API struct header and a standard header
+that we will use further down for string operations.
+It then defines two pointers to two different structs. GDNative supports a large
+collection of functions for calling back into the main Godot executable. In
+order for your module to have access to these functions, GDNative provides your
+application with a struct containing pointers to all these functions.
+
+To keep this implementation modular and easily extendable, the core functions
+are available directly through the "core" API struct, but additional functions
+have their own "GDNative structs" that are accessible through extensions.
+
+In our example, we access one of these extension to gain access to the functions
+specifically needed for NativeScript.
 
-These are forward declarations for the functions we'll be implementing for our object. A constructor and destructor is needed. Additionally, the object will have a single method called get_data.
+A NativeScript behaves like any other script in Godot. Because the NativeScript
+API is rather low level, it requires the library to specify many things more
+verbosely than other scripting systems, such as GDScript. When a NativeScript
+instance gets created, a library-given constructor gets called. When that
+instance gets destroyed, the given destructor will be executed.
 
-.. code:: C
+.. code-block:: C
 
     void *simple_constructor(godot_object *p_instance, void *p_method_data);
     void simple_destructor(godot_object *p_instance, void *p_method_data, void *p_user_data);
-    godot_variant simple_get_data(godot_object *p_instance, void *p_method_data
-        , void *p_user_data, int p_num_args, godot_variant **p_args);
+    godot_variant simple_get_data(godot_object *p_instance, void *p_method_data,
+            void *p_user_data, int p_num_args, godot_variant **p_args);
+
+These are forward declarations for the functions we'll be implementing for our
+object. A constructor and destructor is needed. Additionally, the object will
+have a single method called ``get_data``.
 
-Next up is the first of the entry points Godot will call when our dynamic library is loaded. These methods are all prefixed with Godot (you can change this later on) followed by their name. ``gdnative_init`` is a function that initialises our dynamic library. Godot will give it a pointer to a structure that contains various bits of information we may find useful amongst which the pointers to our API structures.
+Next up is the first of the entry points Godot will call when our dynamic
+library is loaded. These methods are all prefixed with ``godot_`` (you can
+change this later on) followed by their name. ``gdnative_init`` is a function
+that initializes our dynamic library. Godot will give it a pointer to a
+structure that contains various bits of information we may find useful among
+which the pointers to our API structures.
 
-For any additional API structures we need to loop through our extensions array and check the type of extension.
+For any additional API structures we need to loop through our extensions array
+and check the type of extension.
 
-.. code:: C
+.. code-block:: C
 
     void GDN_EXPORT godot_gdnative_init(godot_gdnative_init_options *p_options) {
         api = p_options->api_struct;
 
-        // now find our extensions
+        // Now find our extensions.
         for (int i = 0; i < api->num_extensions; i++) {
             switch (api->extensions[i]->type) {
                 case GDNATIVE_EXT_NATIVESCRIPT: {
@@ -132,24 +204,23 @@ For any additional API structures we need to loop through our extensions array a
         }
     }
 
-Next up is ``gdnative_terminate`` which is called before the library is unloaded. Godot will unload the library when no object uses it anymore. Here, you can do any cleanup you may need to do. For our example, we're simply going to clear our API pointers.
+Next up is ``gdnative_terminate`` which is called before the library is
+unloaded. Godot will unload the library when no object uses it anymore. Here,
+you can do any cleanup you may need to do. For our example, we're simply going
+to clear our API pointers.
 
-.. code:: C
+.. code-block:: C
 
     void GDN_EXPORT godot_gdnative_terminate(godot_gdnative_terminate_options *p_options) {
         api = NULL;
         nativescript_api = NULL;
     }
 
-Finally we have ``nativescript_init`` which is the most important function we'll need today. This function will be called by Godot as part of loading a GDNative library and communicates back to Godot what objects we make available to Godot.
+Finally we have ``nativescript_init`` which is the most important function we'll
+need today. This function will be called by Godot as part of loading a GDNative
+library and communicates back to the engine what objects we make available.
 
-We first tell Godot which classes are implemented by calling ``nativescript_register_class``. The first parameter here is the handle pointer given to us. The second is the name of our object class. The third is the type of object in Godot that we 'inherit' from, this is not true inheritance but it's close enough. Finally, our fourth and fifth parameters are descriptions for our constructor and destructor.
-
-We then tell Godot about our methods (well our one method in this case), by calling ``nativescript_register_method`` for each method of our class. In our case, that is just ``get_data``. Our first parameter is yet again our handle pointer. The second is again the name of the object class we're registering. The third is the name of our function as it will be known to GDScript. The fourth is our attributes setting. The fifth and final parameter is a description of which function to call when the method gets called.
-
-The descriptions contain the function pointers to the functions themselves. The other two fields in these structs are for specifying per-method userdata. The value in the ``method_data`` field will be passed on every function call as the ``p_method_data`` argument. This is useful to reuse one function for different methods on possibly multiple different script-classes. If the ``method_data`` value is a pointer to memory that needs to be freed, the ``free_func`` field can contain a pointer to a function that will free that memory. That free function gets called when the script itself (not instance!) gets unloaded (so usually at library-unload time).
-
-.. code:: C
+.. code-block:: C
 
     void GDN_EXPORT godot_nativescript_init(void *p_handle) {
         godot_instance_create_func create = { NULL, NULL, NULL };
@@ -158,31 +229,66 @@ The descriptions contain the function pointers to the functions themselves. The
         godot_instance_destroy_func destroy = { NULL, NULL, NULL };
         destroy.destroy_func = &simple_destructor;
 
-        nativescript_api->godot_nativescript_register_class(p_handle, "SIMPLE", "Reference",
-            create, destroy);
+        nativescript_api->godot_nativescript_register_class(p_handle, "Simple", "Reference",
+                create, destroy);
 
         godot_instance_method get_data = { NULL, NULL, NULL };
         get_data.method = &simple_get_data;
 
         godot_method_attributes attributes = { GODOT_METHOD_RPC_MODE_DISABLED };
 
-        nativescript_api->godot_nativescript_register_method(p_handle, "SIMPLE", "get_data",
-            attributes, get_data);
+        nativescript_api->godot_nativescript_register_method(p_handle, "Simple", "get_data",
+                attributes, get_data);
     }
 
-Now, it's time to start working on the functions of our object. First, we define a structure that we use to store the member data of an instance of our GDNative class.
-
-.. code:: C
+We first tell the engine which classes are implemented by calling
+``nativescript_register_class``. The first parameter here is the handle pointer
+given to us. The second is the name of our object class. The third is the type
+of object in Godot that we 'inherit' from; this is not true inheritance but it's
+close enough. Finally, our fourth and fifth parameters are descriptions for our
+constructor and destructor.
+
+We then tell Godot about our methods (well our one method in this case), by
+calling ``nativescript_register_method`` for each method of our class. In our
+case, that is just ``get_data``. Our first parameter is yet again our handle
+pointer. The second is again the name of the object class we're registering. The
+third is the name of our function as it will be known to GDScript. The fourth is
+our attributes setting (see ``godot_method_rpc_mode`` enum in
+``godot_headers/nativescript/godot_nativescript.h`` for possible values). The
+fifth and final parameter is a description of which function to call when the
+method gets called.
+
+The description struct ``instance_method`` contains the function pointer to the
+function itself as first field. The other two fields in these structs are for
+specifying per-method userdata. The second is the ``method_data`` field which is
+passed on every function call as the ``p_method_data`` argument. This is useful
+to reuse one function for different methods on possibly multiple different
+script-classes. If the ``method_data`` value is a pointer to memory that needs
+to be freed, the third ``free_func`` field can contain a pointer to a function
+that will free that memory. That free function gets called when the script
+itself (not instance!) gets unloaded (so usually at library-unload time).
+
+Now, it's time to start working on the functions of our object. First, we define
+a structure that we use to store the member data of an instance of our GDNative
+class.
+
+.. code-block:: C
 
     typedef struct user_data_struct {
         char data[256];
     } user_data_struct;
 
-And then, we define our constructor. All we do in our constructor is allocate memory for our structure and fill it with some data. Note that we use Godot's memory functions so the memory gets tracked and then return the pointer to our new structure. This pointer will act as our instance identifier in case multiple objects are instantiated.
+And then, we define our constructor. All we do in our constructor is allocate
+memory for our structure and fill it with some data. Note that we use Godot's
+memory functions so the memory gets tracked and then return the pointer to our
+new structure. This pointer will act as our instance identifier in case multiple
+objects are instantiated.
 
-This pointer will be passed to any of our functions related to our object as a parameter called ``p_user_data``, and can both be used to identify our instance and to access its member data.
+This pointer will be passed to any of our functions related to our object as a
+parameter called ``p_user_data``, and can both be used to identify our instance
+and to access its member data.
 
-.. code:: C
+.. code-block:: C
 
     void *simple_constructor(godot_object *p_instance, void *p_method_data) {
         user_data_struct *user_data = api->godot_alloc(sizeof(user_data_struct));
@@ -191,29 +297,27 @@ This pointer will be passed to any of our functions related to our object as a p
         return user_data;
     }
 
-Our destructor is called when Godot is done with our object and we free our instances' member data.
+Our destructor is called when Godot is done with our object and we free our
+instances' member data.
 
-.. code:: C
+.. code-block:: C
 
     void simple_destructor(godot_object *p_instance, void *p_method_data, void *p_user_data) {
         api->godot_free(p_user_data);
     }
 
-And finally, we implement our get_data function. Data is always sent and returned as variants so in order to return our data, which is a string, we first need to convert our C string to a Godot string object, and then copy that string object into the variant we are returning.
+And finally, we implement our ``get_data`` function. Data is always sent and
+returned as variants so in order to return our data, which is a string, we first
+need to convert our C string to a Godot string object, and then copy that string
+object into the variant we are returning.
 
-Strings are heap-allocated in Godot, so they have a destructor which frees the memory. Destructors are named ``godot_TYPENAME_destroy``. When a Variant gets created with a String, it references the String. That means that the original String can be "destroyed" to decrease the ref-count. If that does not happen the String memory will leak since the ref-count will never be zero and the memory never deallocated. The returned variant gets automatically destroyed by Godot.
-
-(In more complex operations it can be confusing the keep track of which value needs to be deallocated and which does not. As a general rule: call godot_XXX_destroy when a C++ destructor would be called instead. The String destructor would be called in C++ after the Variant was created, so the same is necessary in C)
-
-The variant we return is destroyed automatically by Godot.
-
-.. code:: C
+.. code-block:: C
 
     godot_variant simple_get_data(godot_object *p_instance, void *p_method_data,
             void *p_user_data, int p_num_args, godot_variant **p_args) {
         godot_string data;
         godot_variant ret;
-        user_data_struct * user_data = (user_data_struct *) p_user_data;
+        user_data_struct *user_data = (user_data_struct *)p_user_data;
 
         api->godot_string_new(&data);
         api->godot_string_parse_utf8(&data, user_data->data);
@@ -223,127 +327,231 @@ The variant we return is destroyed automatically by Godot.
         return ret;
     }
 
-And that is the whole source code of our module.
+Strings are heap-allocated in Godot, so they have a destructor which frees the
+memory. Destructors are named ``godot_TYPENAME_destroy``. When a Variant gets
+created with a String, it references the String. That means that the original
+String can be "destroyed" to decrease the ref-count. If that does not happen the
+String memory will leak since the ref-count will never be zero and the memory
+never deallocated. The returned variant gets automatically destroyed by Godot.
+
+.. note::
+
+    In more complex operations it can be confusing the keep track of which value
+    needs to be deallocated and which does not. As a general rule: call
+    ``godot_TYPENAME_destroy`` when a C++ destructor would be called instead.
+    The String destructor would be called in C++ after the Variant was created,
+    so the same is necessary in C.
+
+The variant we return is destroyed automatically by Godot.
 
-If you add a blank ``.gdignore`` file to the src folder, Godot will not try to import the compiler-generated temporary files.
+And that is the whole source code of our module.
 
 Compiling
 ---------
-We now need to compile our source code. As mentioned our example project on GitHub contains a Scons configuration that does all the hard work for you but for our tutorial here we are going to call the compilers directly.
 
-Assuming you are sticking to the folder structure suggested above it is best to CD into the src subfolder in a terminal session and execute the commands from there. Make sure to create the bin folder before you proceed.
+We now need to compile our source code. As mentioned our example project on
+GitHub contains a SCons configuration that does all the hard work for you, but
+for our tutorial here we are going to call the compilers directly.
+
+Assuming you are sticking to the folder structure suggested above, it is best to
+open a terminal session in the ``src`` folder and execute the commands from
+there. Make sure to create the ``bin`` folder before you proceed.
 
 On Linux:
 
 .. code-block:: none
 
-    clang -std=c11 -fPIC -c -I/PATH/TO/GODOT/HEADERS simple.c -o simple.os
-    clang -shared simple.os -o ../bin/libsimple.so
+    gcc -std=c11 -fPIC -c -I../../godot_headers simple.c -o simple.os
+    gcc -shared simple.os -o ../bin/libsimple.so
 
 On macOS:
 
 .. code-block:: none
 
-    clang -std=c11 -fPIC -c -I/PATH/TO/GODOT/HEADERS simple.c -o simple.os -arch i386 -arch x86_64
-    clang -dynamiclib simple.os -o ../bin/libsimple.dylib -arch i386 -arch x86_64
+    clang -std=c11 -fPIC -c -I../../godot_headers simple.c -o simple.os
+    clang -dynamiclib simple.os -o ../bin/libsimple.dylib
 
 On Windows:
 
 .. code-block:: none
 
-    cl /Fosimple.obj /c simple.c /nologo -EHsc -DNDEBUG /MD /I. /IC:\PATH\TO\GODOT\HEADERS
+    cl /Fosimple.obj /c simple.c /nologo -EHsc -DNDEBUG /MD /I. /I..\..\godot_headers
     link /nologo /dll /out:..\bin\libsimple.dll /implib:..\bin\libsimple.lib simple.obj
 
-.. note:: on the Windows build you also end up with a libsimple.lib library. This is a library that you can compile into a project to provide access to the DLL. We get it as a bonus and we do not need it :) When exporting your game for release this file will be ignored.
+.. note::
 
-Creating our GDNLIB file
-------------------------
-With our module compiled we now need to create a gdnlib file for our module which we place alongside our dynamic libraries. This file tells Godot what dynamic libraries are part of our module and need to be loaded per platform. At the time of writing this tutorial work is still being done on making this configurable from within Godot so for now grab your favourite text editor, create a file called libsimple.gdnlib and add the following into this file:
+    On the Windows build you also end up with a ``libsimple.lib`` library. This
+    is a library that you can compile into a project to provide access to the
+    DLL. We get it as a byproduct and we do not need it :)
+    When exporting your game for release this file will be ignored.
 
-.. code-block:: none
+.. tip::
 
-    [general]
+    If you add a blank ``.gdignore`` file to the ``src`` folder, Godot will not
+    try to import the compiler-generated files. This is necessary on Windows
+    were compiled objects have the ``.obj`` extension, which is also a 3D model
+    format supported by the engine.
 
-    singleton=false
-    load_once=true
-    symbol_prefix="godot_"
+Creating the GDNativeLibrary (``.gdnlib``) file
+-----------------------------------------------
 
-    [entry]
+With our module compiled, we now need to create a corresponding
+:ref:`GDNativeLibrary <class_GDNativeLibrary>` resource with ``.gdnlib``
+extension which we place alongside our dynamic libraries. This file tells Godot
+what dynamic libraries are part of our module and need to be loaded per
+platform.
 
-    X11.64="res://bin/libsimple.so"
-    Windows.64="res://bin/libsimple.dll"
-    OSX.64="res://bin/libsimple.dylib"
+We can use Godot to generate this file, so open the "simple" project in the
+editor.
 
-    [dependencies]
+Start by clicking the create resource button in the Inspector:
 
-    X11.64=[]
-    Windows.64=[]
-    OSX.64=[]
+.. image:: img/new_resource.gif
 
-This file contains 3 sections.
+And select ``GDNativeLibrary``:
 
-The **general** section contains some info that tells Godot how to use our module.
+.. image:: img/gdnativelibrary_resource.png
 
-If singleton is true our library is automatically loaded and a function called godot_singleton_init is called. We'll leave that for another tutorial.
+You should see a contextual editor appear in the bottom panel. Use the "Expand
+Bottom Panel" button in the bottom right to expand it to full height:
 
-If load_once is true our library is loaded only once and each individual script that uses our library will use the same data. Any variable you define globally will be accessible from any instance of your object you create. If load_once is false a new copy of the library is loaded into memory each time a script access the library.
+.. image:: img/gdnativelibrary_editor.png
 
-The symbol_prefix is a prefix for our core functions. So the Godot in godot_nativescript_init for instance. If you use multiple GDnative libraries that you wish to statically link you'll have to use different prefixes. This again is a subject to dive into deeper in a separate tutorial, it is only needed at this time for deployment to iOS as this platform does not like dynamic libraries.
+General properties
+~~~~~~~~~~~~~~~~~~
 
-The **entry** section tells us for each platform and feature combination which dynamic library has to be loaded. This also informs the exporter which files need to be exported when exporting to a specific platform.
+In the Inspector, you have various properties to control loading the library.
 
-The **dependencies** section tells Godot what other files need to be exported for each platform in order for our library to work. Say that your GDNative module uses another DLL to implement functionality from a 3rd party library, this is where you list that DLL.
+If *Load Once* is enabled, our library is loaded only once and each individual
+script that uses our library will use the same data. Any variable you define
+globally will be accessible from any instance of your object you create. If
+*Load Once* is disabled, a new copy of the library is loaded into memory each
+time a script accesses the library.
 
-Putting it all together
------------------------
-Now that we should have a working GDNative library it is time to fire up Godot and use it. Open up the sample project if you haven't left it open after creating the project all the way at the beginning of this tutorial.
+If *Singleton* is enabled, our library is automatically loaded and a function
+called ``godot_singleton_init`` is called. We'll leave that for another
+tutorial.
 
-Creating our GDNS file
-----------------------
-With our GDNLIB file we've told Godot how to load our library, now we need to tell it about our "Simple" object class. This we do by creating a GDNS resource file.
+The *Symbol Prefix* is a prefix for our core functions, such as ``godot_`` in
+``godot_nativescript_init`` seen earlier. If you use multiple GDNative libraries
+that you wish to statically link, you will have to use different prefixes. This
+again is a subject to dive into deeper in a separate tutorial, it is only needed
+at this time for deployment to iOS as this platform does not like dynamic
+libraries.
 
-Start by clicking the create resource button in the Inspector:
+*Reloadable* defines whether the library should be reloaded when the editor
+loses and gains focus, typically to pick up new or modified symbols from any
+change made to the library externally.
 
-.. image:: img/new_resource.gif
+Platform libraries
+~~~~~~~~~~~~~~~~~~
+
+The GDNativeLibrary editor plugin lets you configure two things for each
+platform and architecture that you aim to support.
+
+The *Dynamic Library* column (``entry`` section in the saved file) tells us for
+each platform and feature combination which dynamic library has to be loaded.
+This also informs the exporter which files need to be exported when exporting to
+a specific platform.
+
+The *Dependencies* column (also ``dependencies`` section) tells Godot what other
+files need to be exported for each platform in order for our library to work.
+Say that your GDNative module uses another DLL to implement functionality from a
+3rd party library, this is where you list that DLL.
+
+For our example, we only built libraries for Linux, macOS and/or Windows, so you
+can link them in the relevant fields by clicking the folder button. If you built
+all three libraries, you should have something like this:
+
+.. image:: img/gdnativelibrary_complete.png
+
+Saving the resource
+~~~~~~~~~~~~~~~~~~~
+
+We can then save our GDNativeLibrary resource as ``bin/libsimple.gdnlib`` with
+the Save button in the Inspector:
+
+.. image:: img/gdnativelibrary_save.png
+
+The file is saved in a text-based format and should have contents similar to
+this:
+
+.. code-block:: none
+
+    [general]
+
+    singleton=false
+    load_once=true
+    symbol_prefix="godot_"
+    reloadable=true
+
+    [entry]
+
+    OSX.64="res://bin/libsimple.dylib"
+    OSX.32="res://bin/libsimple.dylib"
+    Windows.64="res://bin/libsimple.dll"
+    X11.64="res://bin/libsimple.so"
+
+    [dependencies]
+
+    OSX.64=[  ]
+    OSX.32=[  ]
+    Windows.64=[  ]
+    X11.64=[  ]
+
+Creating the NativeScript (``.gdns``) file
+------------------------------------------
+
+With our ``.gdnlib`` file we've told Godot how to load our library, now we need
+to tell it about our "Simple" object class. We do this by creating a
+:ref:`NativeScript <class_NativeScript>` resource file with ``.gdns`` extension.
 
-And select NativeScript:
+Like done for the GDNativeLibrary resource, click the button to create a new
+resource in the Inspector and select ``NativeScript``:
 
 .. image:: img/nativescript_resource.png
 
-Press Create, now the inspector will show a few fields we need to enter. In Class Name we enter "SIMPLE" which is the object class name we used in our C source when calling godot_nativescript_register_class. We also need to select our GDNLIB file by clicking on Library and selecting Load:
+The inspector will show a few properties that we need to fill. As *Class Name*
+we enter "Simple" which is the object class name that we declared in our C
+source when calling ``godot_nativescript_register_class``. We also need to
+select our ``.gdnlib`` file by clicking on *Library* and selecting *Load*:
 
 .. image:: img/nativescript_library.png
 
-Finally click on the save icon and save this as bin/simple.gdns:
+Finally click on the save icon and save this as ``bin/simple.gdns``:
 
 .. image:: img/save_gdns.gif
 
-Now it's time to build our scene. Add a control node to your scene as your root and call it main. Then add a button and a label as subnodes. Place them somewhere nice on screen and give your button a name.
+Now it's time to build our scene. Add a Control node to your scene as your root
+and call it ``main``. Then add a Button and a Label as child nodes. Place them
+somewhere nice on screen and give your button a name.
 
 .. image:: img/c_main_scene_layout.png
 
-Select the control node and create a script for the control node:
+Select the control node and attach a script to it:
 
 .. image:: img/add_main_script.gif
 
-Next link up the pressed signal on the button to your script:
+Next link up the ``pressed`` signal on the button to your script:
 
 .. image:: img/connect_button_signal.gif
 
-Don't forget to save your scene, call it main.tscn.
+Don't forget to save your scene, call it ``main.tscn``.
 
-Now we can implement our main.gd code:
+Now we can implement our ``main.gd`` code:
 
 ::
 
     extends Control
 
-    # load the SIMPLE library
+    # load the Simple library
     onready var data = preload("res://bin/simple.gdns").new()
 
     func _on_Button_pressed():
         $Label.text = "Data = " + data.get_data()
 
-After all that, our project should work. The first time you run it Godot will ask you what your main scene is and you select your main.tscn file and presto:
+After all that, our project should work. The first time you run it Godot will
+ask you what your main scene is and you select your ``main.tscn`` file and
+presto:
 
 .. image:: img/c_sample_result.png

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

@@ -7,24 +7,22 @@ Introduction
 ------------
 
 This tutorial builds on top of the information given in the
-:ref:`GDNative C example <doc_gdnative_c_example>`, so we highly
-recommend you read that first.
+:ref:`GDNative C example <doc_gdnative_c_example>`, so we highly recommend you
+read that first.
 
-The C++ bindings for GDNative are built on top of the
-NativeScript GDNative API and provide a nicer way to "extend" nodes
-in Godot using C++. This is equivalent to writing scripts in GDScript,
-but in C++ instead.
+The C++ bindings for GDNative are built on top of the NativeScript GDNative API
+and provide a nicer way to "extend" nodes in Godot using C++. This is equivalent
+to writing scripts in GDScript, but in C++ instead.
 
-Godot 3.1 saw the introduction of the NativeScript 1.1 additions that
-enabled the GDNative team to build a nicer C++ bindings library.
-These changes have now been merged into the master branch and will
-be the way we go forward. If you want to write a C++ GDNative plugin
-that also supports Godot 3.0 you will need to use the 3.0 branch and
-the NativeScript 1.0 syntax. We'll be showing them side by side in
-this writeup.
+Godot 3.1 saw the introduction of the NativeScript 1.1 additions that enabled
+the GDNative team to build a nicer C++ bindings library. These changes have now
+been merged into the master branch and will be the way we go forward. If you
+want to write a C++ GDNative plugin that also supports Godot 3.0 you will need
+to use the 3.0 branch and the NativeScript 1.0 syntax. We'll be showing them
+side by side in this writeup.
 
-You can download the full example we'll be creating in this tutorial
-`on GitHub <https://github.com/BastiaanOlij/gdnative_cpp_example>`_.
+You can download the full example we'll be creating in this tutorial `on
+GitHub <https://github.com/BastiaanOlij/gdnative_cpp_example>`__.
 
 Setting up the project
 ----------------------
@@ -34,23 +32,22 @@ There are a few prerequisites you'll need:
 - a Godot 3.x executable,
 - a C++ compiler,
 - SCons as a build tool,
-- a copy of the `godot-cpp repository <https://github.com/GodotNativeTools/godot-cpp>`_.
+- a copy of the `godot-cpp
+  repository <https://github.com/GodotNativeTools/godot-cpp>`__.
 
 See also :ref:`Compiling <toc-devel-compiling>` as the build tools are identical
 to the ones you need to compile Godot from source.
 
-You can download these repositories from GitHub or let Git
-do the work for you.
-Note that these repositories now have different branches for different
-versions of Godot. GDNative modules written for an earlier version of
-Godot will work in newer versions (with the exception of one breaking
-change in ARVR interfaces between 3.0 and 3.1) but not vice versa so
-make sure you download the correct branch.
-Also note that the version of Godot you use to generate the ``api.json``
+You can download these repositories from GitHub or let Git do the work for you.
+Note that these repositories now have different branches for different versions
+of Godot. GDNative modules written for an earlier version of Godot will work in
+newer versions (with the exception of one breaking change in ARVR interfaces
+between 3.0 and 3.1) but not vice versa so make sure you download the correct
+branch. Also note that the version of Godot you use to generate the ``api.json``
 with becomes your minimum version.
 
-If you are versioning your project using Git,
-it is a good idea to add them as Git submodules:
+If you are versioning your project using Git, it is a good idea to add them as
+Git submodules:
 
 .. tabs::
  .. code-tab:: none Godot
@@ -71,10 +68,10 @@ it is a good idea to add them as Git submodules:
     cd godot-cpp
     git submodule update --init
 
-If you decide to just download the repositories or clone them
-into your project folder, make sure to keep the folder layout identical
-to the one described here, as much of the code we'll be showcasing here
-assumes the project follows this layout.
+If you decide to just download the repositories or clone them into your project
+folder, make sure to keep the folder layout identical to the one described here,
+as much of the code we'll be showcasing here assumes the project follows this
+layout.
 
 Do make sure you clone recursive to pull in both repositories:
 
@@ -91,13 +88,20 @@ Do make sure you clone recursive to pull in both repositories:
     cd gdnative_cpp_example
     git clone --recursive -b 3.0 https://github.com/GodotNativeTools/godot-cpp
 
-.. note:: ``godot-cpp`` now includes ``godot_headers`` as a nested submodule, if you've manually downloaded them please make sure to place ``godot_headers`` inside of the ``godot-cpp`` folder.
+.. note::
+
+    ``godot-cpp`` now includes ``godot_headers`` as a nested submodule, if you've
+    manually downloaded them please make sure to place ``godot_headers`` inside
+    of the ``godot-cpp`` folder.
 
-          You don't have to do it this way but we've found it easiest to manage. If you decide to just download the repositories or just clone them into your folder, make sure to keep the folder layout the same as we've setup here as much of the code we'll be showcasing here assumes the project has this layout.
+    You don't have to do it this way but we've found it easiest to manage. If you
+    decide to just download the repositories or just clone them into your folder,
+    make sure to keep the folder layout the same as we've setup here as much of
+    the code we'll be showcasing here assumes the project has this layout.
 
-If you cloned the example from the link specified in
-the introduction, the submodules are not automatically initialized.
-You will need to execute the following commands:
+If you cloned the example from the link specified in the introduction, the
+submodules are not automatically initialized. You will need to execute the
+following commands:
 
 .. code-block:: none
 
@@ -109,21 +113,23 @@ This will clone these two repositories into your project folder.
 Building the C++ bindings
 -------------------------
 
-Now that we've downloaded our prerequisites, it is time to build
-the C++ bindings.
+Now that we've downloaded our prerequisites, it is time to build the C++
+bindings.
 
 The repository contains a copy of the metadata for the current Godot release,
-but if you need to build these bindings for a newer version of Godot,
-simply call the Godot executable:
+but if you need to build these bindings for a newer version of Godot, simply
+call the Godot executable:
 
 .. code-block:: none
 
     godot --gdnative-generate-json-api api.json
 
-Place the resulting ``api.json`` file in the project folder and add ``use_custom_api_file=yes custom_api_file=../api.json`` to the scons command below.
+Place the resulting ``api.json`` file in the project folder and add
+``use_custom_api_file=yes custom_api_file=../api.json`` to the scons command
+below.
 
-To generate and compile the bindings, use this command (replacing
-``<platform>`` with ``windows``, ``x11`` or ``osx`` depending on your OS):
+To generate and compile the bindings, use this command (replacing ``<platform>``
+with ``windows``, ``x11`` or ``osx`` depending on your OS):
 
 .. code-block:: none
 
@@ -134,31 +140,34 @@ To generate and compile the bindings, use this command (replacing
 This step will take a while. When it is completed, you should have static
 libraries that can be compiled into your project stored in ``godot-cpp/bin/``.
 
-At some point in the future, compiled binaries will be available,
-making this step optional.
+At some point in the future, compiled binaries will be available, making this
+step optional.
+
+.. note::
 
-.. note:: You may need to add ``bits=64`` to the command on Windows or Linux. We're still working on better auto detection.
+    You may need to add ``bits=64`` to the command on Windows or Linux. We're
+    still working on better auto detection.
 
 Creating a simple plugin
 ------------------------
 
-Now it's time to build an actual plugin. We'll start by creating an
-empty Godot project in which we'll place a few files.
+Now it's time to build an actual plugin. We'll start by creating an empty Godot
+project in which we'll place a few files.
 
-Open Godot and create a new project. For this example, we will place it
-in a folder called ``demo`` inside our GDNative module's folder structure.
+Open Godot and create a new project. For this example, we will place it in a
+folder called ``demo`` inside our GDNative module's folder structure.
 
-In our demo project, we'll create a scene containing a Node called "Main"
-and we'll save it as ``main.tscn``. We'll come back to that later.
+In our demo project, we'll create a scene containing a Node called "Main" and
+we'll save it as ``main.tscn``. We'll come back to that later.
 
-Back in the top-level GDNative module folder, we're also going to create
-a subfolder called ``src`` in which we'll place our source files.
+Back in the top-level GDNative module folder, we're also going to create a
+subfolder called ``src`` in which we'll place our source files.
 
-You should now have ``demo``, ``godot-cpp``, ``godot_headers``,
-and ``src`` directories in your GDNative module.
+You should now have ``demo``, ``godot-cpp``, ``godot_headers``, and ``src``
+directories in your GDNative module.
 
-In the ``src`` folder, we'll start with creating our header file
-for the GDNative node we'll be creating. We will name it ``gdexample.h``:
+In the ``src`` folder, we'll start with creating our header file for the
+GDNative node we'll be creating. We will name it ``gdexample.h``:
 
 .. tabs::
  .. code-tab:: C++ NativeScript 1.1
@@ -221,32 +230,30 @@ for the GDNative node we'll be creating. We will name it ``gdexample.h``:
 
     #endif
 
-There are a few things of note to the above.
-We're including ``Godot.hpp`` which contains all our basic definitions.
-After that, we include ``Sprite.hpp`` which contains bindings
-to the Sprite class. We'll be extending this class in our module.
+There are a few things of note to the above. We're including ``Godot.hpp`` which
+contains all our basic definitions. After that, we include ``Sprite.hpp`` which
+contains bindings to the Sprite class. We'll be extending this class in our
+module.
 
-We're using the namespace ``godot``, since everything in GDNative
-is defined within this namespace.
+We're using the namespace ``godot``, since everything in GDNative is defined
+within this namespace.
 
-Then we have our class definition, which inherits from our Sprite
-through a container class. We'll see a few side effects of this later on.
-The ``GODOT_CLASS`` macro sets up a few internal things for us.
+Then we have our class definition, which inherits from our Sprite through a
+container class. We'll see a few side effects of this later on. The
+``GODOT_CLASS`` macro sets up a few internal things for us.
 
 After that, we declare a single member variable called ``time_passed``.
 
-In the next block we're defining our methods, we obviously have
-our constructor and destructor defined, but there are two other
-functions that will likely look familiar to some, and one new method.
+In the next block we're defining our methods, we obviously have our constructor
+and destructor defined, but there are two other functions that will likely look
+familiar to some, and one new method.
 
-The first is ``_register_methods``, which is a static function that Godot
-will call to find out which methods can be called on our NativeScript
-and which properties it exposes.
-The second is our ``_process`` function,
-which will work exactly the same as the ``_process`` function
-you're used to in GDScript.
-The third is our ``_init`` function which is called after Godot has properly
-set up our object. It has to exist even if you don't place any code in it.
+The first is ``_register_methods``, which is a static function that Godot will
+call to find out which methods can be called on our NativeScript and which
+properties it exposes. The second is our ``_process`` function, which will work
+exactly the same as the ``_process`` function you're used to in GDScript. The
+third is our ``_init`` function which is called after Godot has properly set up
+our object. It has to exist even if you don't place any code in it.
 
 Let's implement our functions by creating our ``gdexample.cpp`` file:
 
@@ -308,28 +315,27 @@ Let's implement our functions by creating our ``gdexample.cpp`` file:
         owner->set_position(new_position);
     }
 
-This one should be straightforward. We're implementing each method of
-our class that we defined in our header file.
-Note that the ``register_method`` call **must** expose the ``_process`` method,
-otherwise Godot will not be able to use it. However, we do not have to tell Godot
-about our constructor, destructor and ``_init`` functions.
+This one should be straightforward. We're implementing each method of our class
+that we defined in our header file. Note that the ``register_method`` call
+**must** expose the ``_process`` method, otherwise Godot will not be able to use
+it. However, we do not have to tell Godot about our constructor, destructor and
+``_init`` functions.
 
 The other method of note is our ``_process`` function, which simply keeps track
-of how much time has passed and calculates a new position for our sprite
-using a simple sine and cosine function.
-What stands out is calling ``owner->set_position`` to call one of the build
-in methods of our Sprite. This is because our class is a container class;
-``owner`` points to the actual Sprite node our script relates to.
-In the upcoming NativeScript 1.1, ``set_position`` can be called
-directly on our class.
-
-There is one more C++ file we need; we'll name it ``gdlibrary.cpp``.
-Our GDNative plugin can contain multiple NativeScripts, each with their
-own header and source file like we've implemented ``GDExample`` up above.
-What we need now is a small bit of code that tells Godot about all the
-NativeScripts in our GDNative plugin.
-
-.. code:: C++
+of how much time has passed and calculates a new position for our sprite using a
+simple sine and cosine function. What stands out is calling
+``owner->set_position`` to call one of the build in methods of our Sprite. This
+is because our class is a container class; ``owner`` points to the actual Sprite
+node our script relates to. In the upcoming NativeScript 1.1, ``set_position``
+can be called directly on our class.
+
+There is one more C++ file we need; we'll name it ``gdlibrary.cpp``. Our
+GDNative plugin can contain multiple NativeScripts, each with their own header
+and source file like we've implemented ``GDExample`` up above. What we need now
+is a small bit of code that tells Godot about all the NativeScripts in our
+GDNative plugin.
+
+.. code-block:: C++
 
     #include "gdexample.h"
 
@@ -347,37 +353,37 @@ NativeScripts in our GDNative plugin.
         godot::register_class<godot::GDExample>();
     }
 
-Note that we are not using the ``godot`` namespace here, since the
-three functions implemented here need to be defined without a namespace.
+Note that we are not using the ``godot`` namespace here, since the three
+functions implemented here need to be defined without a namespace.
 
-The ``godot_gdnative_init`` and ``godot_gdnative_terminate`` functions
-get called respectively when Godot loads our plugin and when it unloads it.
-All we're doing here is parse through the functions in our bindings module
-to initialize them, but you might have to set up more things depending
-on your needs.
+The ``godot_gdnative_init`` and ``godot_gdnative_terminate`` functions get
+called respectively when Godot loads our plugin and when it unloads it. All
+we're doing here is parse through the functions in our bindings module to
+initialize them, but you might have to set up more things depending on your
+needs.
 
-The important function is the third function called
-``godot_nativescript_init``. We first call a function in our bindings
-library that does its usual stuff. After that, we call the function
-``register_class`` for each of our classes in our library.
+The important function is the third function called ``godot_nativescript_init``.
+We first call a function in our bindings library that does its usual stuff.
+After that, we call the function ``register_class`` for each of our classes in
+our library.
 
 Compiling the plugin
 --------------------
 
-We cannot easily write by hand a ``SConstruct`` file that SCons would
-use for building. For the purpose of this example, just use
-:download:`this hardcoded SConstruct file <files/cpp_example/SConstruct>`
-we've prepared. We'll cover a more customizable, detailed example on
-how to use these build files in a subsequent tutorial.
+We cannot easily write by hand a ``SConstruct`` file that SCons would use for
+building. For the purpose of this example, just use
+:download:`this hardcoded SConstruct file <files/cpp_example/SConstruct>` we've
+prepared. We'll cover a more customizable, detailed example on how to use these
+build files in a subsequent tutorial.
+
+.. note::
 
-.. note:: This ``SConstruct`` file was written to be used with the latest
-          ``godot-cpp`` master, you may need to make small changes using it with
-          older versions or refer to the ``SConstruct`` file in the Godot 3.0
-          documentation.
+    This ``SConstruct`` file was written to be used with the latest ``godot-cpp``
+    master, you may need to make small changes using it with older versions or
+    refer to the ``SConstruct`` file in the Godot 3.0 documentation.
 
-Once you've downloaded the ``SConstruct`` file, place it in your
-GDNative module folder besides ``godot-cpp``, ``godot_headers``
-and ``demo``, then run:
+Once you've downloaded the ``SConstruct`` file, place it in your GDNative module
+folder besides ``godot-cpp``, ``godot_headers`` and ``demo``, then run:
 
 .. code-block:: none
 
@@ -387,19 +393,19 @@ You should now be able to find the module in ``demo/bin/<platform>``.
 
 .. note::
 
-    Here, we've compiled both godot-cpp and our gdexample library
-    as debug builds. For optimized builds, you should compile them using
-    the ``target=release`` switch.
+    Here, we've compiled both godot-cpp and our gdexample library as debug
+    builds. For optimized builds, you should compile them using the
+    ``target=release`` switch.
 
 Using the GDNative module
 -------------------------
 
-Before we jump back into Godot, we need to create two more files
-in ``demo/bin/``. Both can be created using the Godot editor,
-but it may be faster to create them directly.
+Before we jump back into Godot, we need to create two more files in
+``demo/bin/``. Both can be created using the Godot editor, but it may be faster
+to create them directly.
 
-The first one is a file that lets Godot know what dynamic libraries
-should be loaded for each platform and is called ``gdexample.gdnlib``.
+The first one is a file that lets Godot know what dynamic libraries should be
+loaded for each platform and is called ``gdexample.gdnlib``.
 
 .. code-block:: none
 
@@ -423,31 +429,30 @@ should be loaded for each platform and is called ``gdexample.gdnlib``.
     OSX.64=[]
 
 This file contains a ``general`` section that controls how the module is loaded.
-It also contains a prefix section which should be left on ``godot_`` for now.
-If you change this, you'll need to rename various functions that are
-used as entry points. This was added for the iPhone platform because it doesn't
-allow dynamic libraries to be deployed, yet GDNative modules
-are linked statically.
-
-The ``entry`` section is the important bit: it tells Godot the location of
-the dynamic library in the project's filesystem for each supported platform.
-It will also result in *just* that file being exported when you export the
-project, which means the data pack won't contain libraries that are
-incompatible with the target platform.
-
-Finally, the ``dependencies`` section allows you to name additional
-dynamic libraries that should be included as well. This is important when
-your GDNative plugin implements someone else's library and requires you
-to supply a third-party dynamic library with your project.
-
-If you double click on the ``gdexample.gdnlib`` file within Godot,
-you'll see there are far more options to set:
+It also contains a prefix section which should be left on ``godot_`` for now. If
+you change this, you'll need to rename various functions that are used as entry
+points. This was added for the iPhone platform because it doesn't allow dynamic
+libraries to be deployed, yet GDNative modules are linked statically.
+
+The ``entry`` section is the important bit: it tells Godot the location of the
+dynamic library in the project's filesystem for each supported platform. It will
+also result in *just* that file being exported when you export the project,
+which means the data pack won't contain libraries that are incompatible with the
+target platform.
+
+Finally, the ``dependencies`` section allows you to name additional dynamic
+libraries that should be included as well. This is important when your GDNative
+plugin implements someone else's library and requires you to supply a
+third-party dynamic library with your project.
+
+If you double click on the ``gdexample.gdnlib`` file within Godot, you'll see
+there are far more options to set:
 
 .. image:: img/gdnative_library.png
 
-The second file we need to create is a file used by each NativeScript
-we've added to our plugin. We'll name it ``gdexample.gdns`` for our
-gdexample NativeScript.
+The second file we need to create is a file used by each NativeScript we've
+added to our plugin. We'll name it ``gdexample.gdns`` for our gdexample
+NativeScript.
 
 .. code-block:: none
 
@@ -462,21 +467,20 @@ gdexample NativeScript.
     library = ExtResource( 1 )
     _sections_unfolded = [ "Resource" ]
 
-This is a standard Godot resource; you could just create it directly
-in your scene, but saving it to a file makes it much easier to reuse it
-in other places. This resource points to our gdnlib file, so that Godot
-can know which dynamic library contains our NativeScript. It also defines
-the ``class_name`` which identifies the NativeScript in our plugin
-we want to use.
+This is a standard Godot resource; you could just create it directly in your
+scene, but saving it to a file makes it much easier to reuse it in other places.
+This resource points to our gdnlib file, so that Godot can know which dynamic
+library contains our NativeScript. It also defines the ``class_name`` which
+identifies the NativeScript in our plugin we want to use.
 
-Time to jump back into Godot. We load up the main scene we created way back
-in the beginning and now add a Sprite to our scene:
+Time to jump back into Godot. We load up the main scene we created way back in
+the beginning and now add a Sprite to our scene:
 
 .. image:: img/gdnative_cpp_nodes.png
 
-We're going to assign the Godot logo to this sprite as our texture,
-disable the ``centered`` property and drag our ``gdexample.gdns`` file
-onto the ``script`` property of the sprite:
+We're going to assign the Godot logo to this sprite as our texture, disable the
+``centered`` property and drag our ``gdexample.gdns`` file onto the ``script``
+property of the sprite:
 
 .. image:: img/gdnative_cpp_sprite.png
 
@@ -487,9 +491,10 @@ We're finally ready to run the project:
 Adding properties
 -----------------
 
-GDScript allows you to add properties to your script using the ``export`` keyword.
-In GDNative you have to register the properties and there are two ways of doing this.
-You can either bind directly to a member or use a setter and getter function.
+GDScript allows you to add properties to your script using the ``export``
+keyword. In GDNative you have to register the properties and there are two ways
+of doing this. You can either bind directly to a member or use a setter and
+getter function.
 
 .. note::
 
@@ -497,12 +502,12 @@ You can either bind directly to a member or use a setter and getter function.
     ``_get_property_list``, ``_get`` and ``_set`` methods of an object but that
     goes far beyond the scope of this tutorial.
 
-We'll examine both starting with the direct bind.
-Lets add a property that allows us to control the amplitude of our wave.
+We'll examine both starting with the direct bind. Lets add a property that
+allows us to control the amplitude of our wave.
 
 In our ``gdexample.h`` file we simply need to add a member variable like so:
 
-.. code:: C++
+.. code-block:: C++
 
     ...
     private:
@@ -510,8 +515,8 @@ In our ``gdexample.h`` file we simply need to add a member variable like so:
         float amplitude;
     ...
 
-In our ``gdexample.cpp`` file we need to make a number of changes, we will only show
-the methods we end up changing, don't remove the lines we're omitting:
+In our ``gdexample.cpp`` file we need to make a number of changes, we will only
+show the methods we end up changing, don't remove the lines we're omitting:
 
 .. tabs::
  .. code-tab:: C++ NativeScript 1.1
@@ -562,22 +567,26 @@ the methods we end up changing, don't remove the lines we're omitting:
         owner->set_position(new_position);
     }
 
-Once you compile the module with these changes in place you will see that
-a property has been added to our interface.
-You can now change this property and when you run your project, you will
-see that our Godot icon travels along a larger figure.
+Once you compile the module with these changes in place you will see that a
+property has been added to our interface. You can now change this property and
+when you run your project, you will see that our Godot icon travels along a
+larger figure.
 
 .. note::
-    The ``reloadable`` property in the ``gdexample.gdnlib`` file must be set to ``true`` for the Godot editor
-    to automatically pick up the newly added property.
-    
-    However, this setting should be used with care especially when tool classes are used, 
-    as the editor might hold objects then that have script instances attached to them that are managed by a GDNative library.
 
-Lets do the same but for the speed of our animation and use a setter and getter function.
-Our ``gdexample.h`` header file again only needs a few more lines of code:
+    The ``reloadable`` property in the ``gdexample.gdnlib`` file must be set to
+    ``true`` for the Godot editor to automatically pick up the newly added
+    property.
 
-.. code:: C++
+    However, this setting should be used with care especially when tool classes
+    are used, as the editor might hold objects then that have script instances
+    attached to them that are managed by a GDNative library.
+
+Lets do the same but for the speed of our animation and use a setter and getter
+function. Our ``gdexample.h`` header file again only needs a few more lines of
+code:
+
+.. code-block:: C++
 
     ...
         float amplitude;
@@ -588,8 +597,8 @@ Our ``gdexample.h`` header file again only needs a few more lines of code:
         float get_speed();
     ...
 
-This requires a few more changes to our ``gdexample.cpp`` file, again we're only showing the
-methods that have changed so don't remove anything we're omitting:
+This requires a few more changes to our ``gdexample.cpp`` file, again we're only
+showing the methods that have changed so don't remove anything we're omitting:
 
 .. tabs::
  .. code-tab:: C++ NativeScript 1.1
@@ -663,36 +672,32 @@ methods that have changed so don't remove anything we're omitting:
 Now when the project is compiled we'll see another property called speed.
 Changing its value will make the animation go faster or slower.
 
-For this example there is no obvious advantage of using a setter and getter.
-It is just more code to write. For a simple example as this there may be a
-good reason for a setter if you want to react on the variable being changed
-but in many cases just binding the variable will be enough.
+For this example there is no obvious advantage of using a setter and getter. It
+is just more code to write. For a simple example as this there may be a good
+reason for a setter if you want to react on the variable being changed but in
+many cases just binding the variable will be enough.
 
-Getters and setters become far more useful in more complex scenarios
-where you need to make additional choices based on the state of your
-object.
+Getters and setters become far more useful in more complex scenarios where you
+need to make additional choices based on the state of your object.
 
 .. note::
 
     For simplicity we've left out the optional parameters in the
     register_property<class, type> method call. These parameters are
-    ``rpc_mode``, ``usage``, ``hint`` and ``hint_string``. These can
-    be used to further configure how properties are displayed and set
-    on the Godot side.
+    ``rpc_mode``, ``usage``, ``hint`` and ``hint_string``. These can be used to
+    further configure how properties are displayed and set on the Godot side.
 
-    Modern C++ compilers are able to infer the class and variable type
-    and allow you to omit the ``<GDExample, float>`` part of our
-    ``register_property`` method. we've had mixed experiences with this
-    however.
+    Modern C++ compilers are able to infer the class and variable type and allow
+    you to omit the ``<GDExample, float>`` part of our ``register_property``
+    method. We've had mixed experiences with this however.
 
 Signals
 -------
 
-Last but not least, signals fully work in GDNative as well.
-Having your module react to a signal given out by another object requires
-you to call ``connect`` on that object. We can't think of a good example for
-our wobbling Godot icon, we would need to showcase a far more complete
-example.
+Last but not least, signals fully work in GDNative as well. Having your module
+react to a signal given out by another object requires you to call ``connect``
+on that object. We can't think of a good example for our wobbling Godot icon, we
+would need to showcase a far more complete example.
 
 This however is the required syntax:
 
@@ -705,17 +710,17 @@ This however is the required syntax:
 
     some_other_node->connect("the_signal", owner, "my_method");
 
-Note that you can only call ``my_method`` if you've previously registered
-it in your ``_register_methods`` method.
+Note that you can only call ``my_method`` if you've previously registered it in
+your ``_register_methods`` method.
 
 Having your object sending out signals is far more common. For our wobbling
-Godot icon we'll do something silly just to show how it works. We're going
-to emit a signal every time a second has passed and pass the new location
-along.
+Godot icon we'll do something silly just to show how it works. We're going to
+emit a signal every time a second has passed and pass the new location along.
 
-In our ``gdexample.h`` header file we just need to define a new member ``time_emit``:
+In our ``gdexample.h`` header file we just need to define a new member
+``time_emit``:
 
-.. code:: C++
+.. code-block:: C++
 
     ...
         float time_passed;
@@ -723,9 +728,9 @@ In our ``gdexample.h`` header file we just need to define a new member ``time_em
         float amplitude;
     ...
 
-The changes in ``gdexample.cpp`` are a bit more elaborate this time.
-First you'll need to set ``time_emit = 0.0;`` in either our ``_init`` method or
-in our constructor. But the other two needed changes we'll look at one by one.
+The changes in ``gdexample.cpp`` are a bit more elaborate this time. First
+you'll need to set ``time_emit = 0.0;`` in either our ``_init`` method or in our
+constructor. But the other two needed changes we'll look at one by one.
 
 In our ``_register_methods`` method we need to declare our signal and we do this
 as follows:
@@ -808,15 +813,14 @@ Next we'll need to change our ``_process`` method:
         }
     }
 
-After a second has passed we emit our signal and reset our counter.
-Again in the new version of godot-cpp we can add our parameter values
-directly to ``emit_signal``.
-In NativeScript 1.0 We first build an array of values and then
+After a second has passed we emit our signal and reset our counter. Again in the
+new version of godot-cpp we can add our parameter values directly to
+``emit_signal``. In NativeScript 1.0 We first build an array of values and then
 call ``emit_signal``.
 
-Once compiled we can go into Godot and select our sprite node.
-On our ``Node`` tab we find our new signal and link it up by pressing connect.
-We've added a script on our main node and implemented our signal like this:
+Once compiled we can go into Godot and select our sprite node. On our ``Node``
+tab we find our new signal and link it up by pressing connect. We've added a
+script on our main node and implemented our signal like this:
 
 .. code-block:: none
 
@@ -827,26 +831,25 @@ We've added a script on our main node and implemented our signal like this:
 
 Every second we simply output our position to the console.
 
-
 NativeScript 1.1 vs NativeScript 1.0
 ------------------------------------
 
-So far in our example above there doesn't seem to be a lot of difference
-between the old and new syntax. The class is defined slightly differently
-and we no longer use the ``owner`` member to call methods on the Godot
-side of our object. A lot of the improvements are hidden under the hood.
+So far in our example above there doesn't seem to be a lot of difference between
+the old and new syntax. The class is defined slightly differently and we no
+longer use the ``owner`` member to call methods on the Godot side of our object.
+A lot of the improvements are hidden under the hood.
 
-This example only deals with simple variables and simple methods.
-Especially once you start passing references to other objects or when you
-start calling methods that require more complex parameters, NativeScript 1.1
-does start to show its benefits.
+This example only deals with simple variables and simple methods. Especially
+once you start passing references to other objects or when you start calling
+methods that require more complex parameters, NativeScript 1.1 does start to
+show its benefits.
 
 Next steps
 ----------
 
-The above is only a simple example, but we hope it shows you the basics.
-You can build upon this example to create full-fledged scripts to control
-nodes in Godot using C++.
+The above is only a simple example, but we hope it shows you the basics. You can
+build upon this example to create full-fledged scripts to control nodes in Godot
+using C++.
 
 You should be able to edit and recompile the plugin while the Godot editor
 remains open; just rerun the project after the library has finished building.

tutorials/shading/migrating_to_godot_shader_language.rst

@@ -159,7 +159,7 @@ uniform themself. The description gives the reader a hint about what they can pa
 +=====================+=========+========================+=====================================================+
 |fragColor            |out vec4 |COLOR                   |Output color for each pixel.                         |
 +---------------------+---------+------------------------+-----------------------------------------------------+
-|fragCoord            |vec2     |FRAGCOORD               |For full screen quads. For smaller quads, use UV.    |
+|fragCoord            |vec2     |FRAGCOORD.xy            |For full screen quads. For smaller quads, use UV.    |
 +---------------------+---------+------------------------+-----------------------------------------------------+
 |iResolution          |vec3     |1.0 / SCREEN_PIXEL_SIZE |Can also pass in manually.                           |
 +---------------------+---------+------------------------+-----------------------------------------------------+

tutorials/shading/shading_reference/canvas_item_shader.rst

@@ -143,7 +143,9 @@ it to the ``NORMALMAP`` property. Godot will handle converting it for use in 2D
 +----------------------------------+----------------------------------------------------------------+
 | Built-in                         | Description                                                    |
 +==================================+================================================================+
-| in vec4 **FRAGCOORD**            | Fragment coordinate, pixel adjusted.                           |
+| in vec4 **FRAGCOORD**            | Coordinate of pixel center. In screen space. ``xy`` specifies  |
+|                                  | position in window, ``z`` specifies fragment depth if          |
+|                                  | ``DEPTH`` is not used. Origin is lower-left.                   |
 +----------------------------------+----------------------------------------------------------------+
 | inout vec3 **NORMAL**            | Normal read from **NORMAL_TEXTURE**. Writable.                 |
 +----------------------------------+----------------------------------------------------------------+
@@ -192,7 +194,9 @@ When the shader is on a light pass, the ``AT_LIGHT_PASS`` variable will be ``tru
 +-------------------------------------+-------------------------------------------------------------------------------+
 | Built-in                            | Description                                                                   |
 +=====================================+===============================================================================+
-| in vec4 **FRAGCOORD**               | Fragment coordinate of pixel center. Origin at lower left.                    |
+| in vec4 **FRAGCOORD**               | Coordinate of pixel center. In screen space. ``xy`` specifies                 |
+|                                     | position in window, ``z`` specifies fragment depth if                         |
+|                                     | ``DEPTH`` is not used. Origin is lower-left.                                  |
 +-------------------------------------+-------------------------------------------------------------------------------+
 | in vec3 **NORMAL**                  | Input Normal. Although this value is passed in,                               |
 |                                     | **normal calculation still happens outside of this function**.                |

tutorials/shading/shading_reference/shading_language.rst

@@ -17,57 +17,69 @@ Data types
 
 Most GLSL ES 3.0 datatypes are supported:
 
-+-----------------+---------------------------------------------------------------------------+
-| Type            | Description                                                               |
-+=================+===========================================================================+
-| **void**        | Void datatype, useful only for functions that return nothing.             |
-+-----------------+---------------------------------------------------------------------------+
-| **bool**        | Boolean datatype, can only contain "true" or "false"                      |
-+-----------------+---------------------------------------------------------------------------+
-| **bvec2**       | Two-component vector of booleans.                                         |
-+-----------------+---------------------------------------------------------------------------+
-| **bvec3**       | Three-component vector of booleans.                                       |
-+-----------------+---------------------------------------------------------------------------+
-| **bvec4**       | Four-component vector of booleans.                                        |
-+-----------------+---------------------------------------------------------------------------+
-| **int**         | Signed scalar integer.                                                    |
-+-----------------+---------------------------------------------------------------------------+
-| **ivec2**       | Two-component vector of signed integers.                                  |
-+-----------------+---------------------------------------------------------------------------+
-| **ivec3**       | Three-component vector of signed integers.                                |
-+-----------------+---------------------------------------------------------------------------+
-| **ivec4**       | Four-component vector of signed integers.                                 |
-+-----------------+---------------------------------------------------------------------------+
-| **uint**        | Unsigned scalar integer; can't contain negative numbers.                  |
-+-----------------+---------------------------------------------------------------------------+
-| **uvec2**       | Two-component vector of unsigned integers.                                |
-+-----------------+---------------------------------------------------------------------------+
-| **uvec3**       | Three-component vector of unsigned integers.                              |
-+-----------------+---------------------------------------------------------------------------+
-| **uvec4**       | Four-component vector of unsigned integers.                               |
-+-----------------+---------------------------------------------------------------------------+
-| **float**       | Floating point scalar.                                                    |
-+-----------------+---------------------------------------------------------------------------+
-| **vec2**        | Two-component vector of floating point values.                            |
-+-----------------+---------------------------------------------------------------------------+
-| **vec3**        | Three-component vector of floating point values.                          |
-+-----------------+---------------------------------------------------------------------------+
-| **vec4**        | Four-component vector of floating point values.                           |
-+-----------------+---------------------------------------------------------------------------+
-| **mat2**        | 2x2 matrix, in column major order.                                        |
-+-----------------+---------------------------------------------------------------------------+
-| **mat3**        | 3x3 matrix, in column major order.                                        |
-+-----------------+---------------------------------------------------------------------------+
-| **mat4**        | 4x4 matrix, in column major order.                                        |
-+-----------------+---------------------------------------------------------------------------+
-| **sampler2D**   | Sampler type for binding 2D textures, which are read as float.            |
-+-----------------+---------------------------------------------------------------------------+
-| **isampler2D**  | Sampler type for binding 2D textures, which are read as signed integer.   |
-+-----------------+---------------------------------------------------------------------------+
-| **usampler2D**  | Sampler type for binding 2D textures, which are read as unsigned integer. |
-+-----------------+---------------------------------------------------------------------------+
-| **samplerCube** | Sampler type for binding Cubemaps, which are read as floats.              |
-+-----------------+---------------------------------------------------------------------------+
++---------------------+---------------------------------------------------------------------------------+
+| Type                | Description                                                                     |
++=====================+=================================================================================+
+| **void**            | Void datatype, useful only for functions that return nothing.                   |
++---------------------+---------------------------------------------------------------------------------+
+| **bool**            | Boolean datatype, can only contain "true" or "false".                           |
++---------------------+---------------------------------------------------------------------------------+
+| **bvec2**           | Two-component vector of booleans.                                               |
++---------------------+---------------------------------------------------------------------------------+
+| **bvec3**           | Three-component vector of booleans.                                             |
++---------------------+---------------------------------------------------------------------------------+
+| **bvec4**           | Four-component vector of booleans.                                              |
++---------------------+---------------------------------------------------------------------------------+
+| **int**             | Signed scalar integer.                                                          |
++---------------------+---------------------------------------------------------------------------------+
+| **ivec2**           | Two-component vector of signed integers.                                        |
++---------------------+---------------------------------------------------------------------------------+
+| **ivec3**           | Three-component vector of signed integers.                                      |
++---------------------+---------------------------------------------------------------------------------+
+| **ivec4**           | Four-component vector of signed integers.                                       |
++---------------------+---------------------------------------------------------------------------------+
+| **uint**            | Unsigned scalar integer; can't contain negative numbers.                        |
++---------------------+---------------------------------------------------------------------------------+
+| **uvec2**           | Two-component vector of unsigned integers.                                      |
++---------------------+---------------------------------------------------------------------------------+
+| **uvec3**           | Three-component vector of unsigned integers.                                    |
++---------------------+---------------------------------------------------------------------------------+
+| **uvec4**           | Four-component vector of unsigned integers.                                     |
++---------------------+---------------------------------------------------------------------------------+
+| **float**           | Floating point scalar.                                                          |
++---------------------+---------------------------------------------------------------------------------+
+| **vec2**            | Two-component vector of floating point values.                                  |
++---------------------+---------------------------------------------------------------------------------+
+| **vec3**            | Three-component vector of floating point values.                                |
++---------------------+---------------------------------------------------------------------------------+
+| **vec4**            | Four-component vector of floating point values.                                 |
++---------------------+---------------------------------------------------------------------------------+
+| **mat2**            | 2x2 matrix, in column major order.                                              |
++---------------------+---------------------------------------------------------------------------------+
+| **mat3**            | 3x3 matrix, in column major order.                                              |
++---------------------+---------------------------------------------------------------------------------+
+| **mat4**            | 4x4 matrix, in column major order.                                              |
++---------------------+---------------------------------------------------------------------------------+
+| **sampler2D**       | Sampler type for binding 2D textures, which are read as float.                  |
++---------------------+---------------------------------------------------------------------------------+
+| **isampler2D**      | Sampler type for binding 2D textures, which are read as signed integer.         |
++---------------------+---------------------------------------------------------------------------------+
+| **usampler2D**      | Sampler type for binding 2D textures, which are read as unsigned integer.       |
++---------------------+---------------------------------------------------------------------------------+
+| **sampler2DArray**  | Sampler type for binding 2D texture arrays, which are read as float.            |
++---------------------+---------------------------------------------------------------------------------+
+| **isampler2DArray** | Sampler type for binding 2D texture arrays, which are read as signed integer.   |
++---------------------+---------------------------------------------------------------------------------+
+| **usampler2DArray** | Sampler type for binding 2D texture arrays, which are read as unsigned integer. |
++---------------------+---------------------------------------------------------------------------------+
+| **sampler3D**       | Sampler type for binding 3D textures, which are read as float.                  |
++---------------------+---------------------------------------------------------------------------------+
+| **isampler3D**      | Sampler type for binding 3D textures, which are read as signed integer.         |
++---------------------+---------------------------------------------------------------------------------+
+| **usampler3D**      | Sampler type for binding 3D textures, which are read as unsigned integer.       |
++---------------------+---------------------------------------------------------------------------------+
+| **samplerCube**     | Sampler type for binding Cubemaps, which are read as floats.                    |
++---------------------+---------------------------------------------------------------------------------+
 
 Casting
 ~~~~~~~
@@ -430,182 +442,202 @@ When vec_type (float), vec_int_type, vec_uint_type, vec_bool_type nomenclature i
 .. note:: For a list of the functions that are not available in the GLES2 backend, please see the 
           :ref:`Differences between GLES2 and GLES3 doc <doc_gles2_gles3_differences>`. 
 
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| Function                                                                                      | Description                                    |
-+===============================================================================================+================================================+
-| vec_type **radians** ( vec_type )                                                             | Convert degrees to radians                     |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **degrees** ( vec_type )                                                             | Convert radians to degrees                     |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **sin** ( vec_type )                                                                 | Sine                                           |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **cos** ( vec_type )                                                                 | Cosine                                         |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **tan** ( vec_type )                                                                 | Tangent                                        |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **asin** ( vec_type )                                                                | Arc-Sine                                       |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **acos** ( vec_type )                                                                | Arc-Cosine                                     |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **atan** ( vec_type )                                                                | Arc-Tangent                                    |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **atan** ( vec_type x, vec_type y )                                                  | Arc-Tangent to convert vector to angle         |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **sinh** ( vec_type )                                                                | Hyperbolic-Sine                                |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **cosh** ( vec_type )                                                                | Hyperbolic-Cosine                              |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **tanh** ( vec_type )                                                                | Hyperbolic-Tangent                             |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **asinh** ( vec_type )                                                               | Inverse-Hyperbolic-Sine                        |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **acosh** ( vec_type )                                                               | Inverse-Hyperbolic-Cosine                      |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **atanh** ( vec_type )                                                               | Inverse-Hyperbolic-Tangent                     |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **pow** ( vec_type, vec_type )                                                       | Power                                          |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **exp** ( vec_type )                                                                 | Base-e Exponential                             |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **exp2** ( vec_type )                                                                | Base-2 Exponential                             |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **log** ( vec_type )                                                                 | Natural Logarithm                              |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **log2** ( vec_type )                                                                | Base-2 Logarithm                               |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **sqrt** ( vec_type )                                                                | Square Root                                    |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **inversesqrt** ( vec_type )                                                         | Inverse Square Root                            |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **abs** ( vec_type )                                                                 | Absolute                                       |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_int_type **abs** ( vec_int_type )                                                         | Absolute                                       |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **sign** ( vec_type )                                                                | Sign                                           |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_int_type **sign** ( vec_int_type )                                                        | Sign                                           |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **floor** ( vec_type )                                                               | Floor                                          |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **round** ( vec_type )                                                               | Round                                          |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **roundEven** ( vec_type )                                                           | Round nearest even                             |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **trunc** ( vec_type )                                                               | Truncation                                     |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **ceil** ( vec_type )                                                                | Ceiling                                        |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **fract** ( vec_type )                                                               | Fractional                                     |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **mod** ( vec_type, vec_type )                                                       | Remainder                                      |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **mod** ( vec_type, float )                                                          | Remainder                                      |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **modf** ( vec_type x, out vec_type i )                                              | Fractional of x, with i has integer part       |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_scalar_type **min** ( vec_scalar_type a, vec_scalar_type b )                              | Minimum                                        |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_scalar_type **max** ( vec_scalar_type a, vec_scalar_type b )                              | Maximum                                        |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_scalar_type **clamp** ( vec_scalar_type value, vec_scalar_type min, vec_scalar_type max ) | Clamp to Min-Max                               |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **mix** ( vec_type a, vec_type b, float c )                                          | Linear Interpolate (Scalar Coef.)              |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **mix** ( vec_type a, vec_type b, vec_type c )                                       | Linear Interpolate (Vector Coef.)              |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **mix** ( vec_type a, vec_type b, bool c )                                           | Linear Interpolate (Bool Selection)            |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **mix** ( vec_type a, vec_type b, vec_bool_type c )                                  | Linear Interpolate (Bool-Vector Selection)     |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **step** ( vec_type a, vec_type b )                                                  | ``b[i] < a[i] ? 0.0 : 1.0``                    |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **step** ( float a, vec_type b )                                                     | ``b[i] < a ? 0.0 : 1.0``                       |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **smoothstep** ( vec_type a, vec_type b, vec_type c )                                | Hermite Interpolate                            |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **smoothstep** ( float a, float b, vec_type c )                                      | Hermite Interpolate                            |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_bool_type **isnan** ( vec_type )                                                          | Scalar, or vector component being nan          |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_bool_type **isinf** ( vec_type )                                                          | Scalar, or vector component being inf          |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_int_type **floatBitsToInt** ( vec_type )                                                  | Float->Int bit copying, no conversion          |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_uint_type **floatBitsToUint** ( vec_type )                                                | Float->UInt bit copying, no conversion         |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **intBitsToFloat** ( vec_int_type )                                                  | Int->Float bit copying, no conversion          |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **uintBitsToFloat** ( vec_uint_type )                                                | UInt->Float bit copying, no conversion         |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| float **length** ( vec_type )                                                                 | Vector Length                                  |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| float **distance** ( vec_type, vec_type )                                                     | Distance between vector                        |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| float **dot** ( vec_type, vec_type )                                                          | Dot Product                                    |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec3 **cross** ( vec3, vec3 )                                                                 | Cross Product                                  |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **normalize** ( vec_type )                                                           | Normalize to unit length                       |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec3 **reflect** ( vec3 I, vec3 N )                                                           | Reflect                                        |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec3 **refract** ( vec3 I, vec3 N, float eta )                                                | Refract                                        |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **faceforward** ( vec_type N, vec_type I, vec_type Nref )                            | If dot(Nref, I) < 0, return N, otherwise –N    |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| mat_type **matrixCompMult** ( mat_type, mat_type )                                            | Matrix Component Multiplication                |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| mat_type **outerProduct** ( vec_type, vec_type )                                              | Matrix Outer Product                           |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| mat_type **transpose** ( mat_type )                                                           | Transpose Matrix                               |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| float **determinant** ( mat_type )                                                            | Matrix Determinant                             |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| mat_type **inverse** ( mat_type )                                                             | Inverse Matrix                                 |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_bool_type **lessThan** ( vec_scalar_type, vec_scalar_type )                               | Bool vector cmp on < int/uint/float vectors    |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_bool_type **greaterThan** ( vec_scalar_type, vec_scalar_type )                            | Bool vector cmp on > int/uint/float vectors    |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_bool_type **lessThanEqual** ( vec_scalar_type, vec_scalar_type )                          | Bool vector cmp on <= int/uint/float vectors   |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_bool_type **greaterThanEqual** ( vec_scalar_type, vec_scalar_type )                       | Bool vector cmp on >= int/uint/float vectors   |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_bool_type **equal** ( vec_scalar_type, vec_scalar_type )                                  | Bool vector cmp on == int/uint/float vectors   |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_bool_type **notEqual** ( vec_scalar_type, vec_scalar_type )                               | Bool vector cmp on != int/uint/float vectors   |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| bool **any** ( vec_bool_type )                                                                | Any component is true                          |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| bool **all** ( vec_bool_type )                                                                | All components are true                        |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| bool **not** ( vec_bool_type )                                                                | No components are true                         |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| ivec2 **textureSize** ( sampler2D_type s, int lod )                                           | Get the size of a texture                      |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| ivec2 **textureSize** ( samplerCube s, int lod )                                              | Get the size of a cubemap                      |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec4_type **texture** ( sampler2D_type s, vec2 uv [, float bias] )                            | Perform a 2D texture read                      |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec4_type **texture** ( samplerCube s, vec3 uv [, float bias] )                               | Perform a Cube texture read                    |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec4_type **textureProj** ( sampler2D_type s, vec3 uv [, float bias] )                        | Perform a texture read with projection         |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec4_type **textureProj** ( sampler2D_type s, vec4 uv [, float bias] )                        | Perform a texture read with projection         |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec4_type **textureLod** ( sampler2D_type s, vec2 uv, float lod )                             | Perform a 2D texture read at custom mipmap     |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec4_type **textureLod** ( samplerCube s, vec3 uv, float lod )                                | Perform a Cube texture read at custom mipmap   |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec4_type **textureProjLod** ( sampler2D_type s, vec3 uv, float lod )                         | Perform a texture read with projection/lod     |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec4_type **textureProjLod** ( sampler2D_type s, vec4 uv, float lod )                         | Perform a texture read with projection/lod     |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec4_type **texelFetch** ( sampler2D_type s, ivec2 uv, int lod )                              | Fetch a single texel using integer coords      |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **dFdx** ( vec_type )                                                                | Derivative in x using local differencing       |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **dFdy** ( vec_type )                                                                | Derivative in y using local differencing       |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
-| vec_type **fwidth** ( vec_type )                                                              | Sum of absolute derivative in x and y          |
-+-----------------------------------------------------------------------------------------------+------------------------------------------------+
++----------------------------------------------------------------------------+--------------------------------------------------+
+| Function                                                                   | Description                                      |
++============================================================================+==================================================+
+| vec_type **radians** ( vec_type degrees )                                  | Convert degrees to radians                       |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **degrees** ( vec_type radians )                                  | Convert radians to degrees                       |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **sin** ( vec_type x )                                            | Sine                                             |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **cos** ( vec_type x )                                            | Cosine                                           |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **tan** ( vec_type x )                                            | Tangent                                          |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **asin** ( vec_type x )                                           | Arc-Sine                                         |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **acos** ( vec_type x )                                           | Arc-Cosine                                       |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **atan** ( vec_type y_over_x )                                    | Arc-Tangent                                      |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **atan** ( vec_type y, vec_type x )                               | Arc-Tangent to convert vector to angle           |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **sinh** ( vec_type x )                                           | Hyperbolic-Sine                                  |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **cosh** ( vec_type x )                                           | Hyperbolic-Cosine                                |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **tanh** ( vec_type x )                                           | Hyperbolic-Tangent                               |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **asinh** ( vec_type x )                                          | Inverse-Hyperbolic-Sine                          |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **acosh** ( vec_type x )                                          | Inverse-Hyperbolic-Cosine                        |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **atanh** ( vec_type x )                                          | Inverse-Hyperbolic-Tangent                       |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **pow** ( vec_type x, vec_type y )                                | Power                                            |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **exp** ( vec_type x )                                            | Base-e Exponential                               |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **exp2** ( vec_type x )                                           | Base-2 Exponential                               |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **log** ( vec_type x )                                            | Natural Logarithm                                |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **log2** ( vec_type x )                                           | Base-2 Logarithm                                 |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **sqrt** ( vec_type x )                                           | Square Root                                      |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **inversesqrt** ( vec_type x )                                    | Inverse Square Root                              |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **abs** ( vec_type x )                                            | Absolute                                         |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| ivec_type **abs** ( ivec_type x )                                          | Absolute                                         |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **sign** ( vec_type x )                                           | Sign                                             |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| ivec_type **sign** ( ivec_type x )                                         | Sign                                             |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **floor** ( vec_type x )                                          | Floor                                            |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **round** ( vec_type x )                                          | Round                                            |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **roundEven** ( vec_type x )                                      | Round nearest even                               |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **trunc** ( vec_type x )                                          | Truncation                                       |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **ceil** ( vec_type x )                                           | Ceil                                             |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **fract** ( vec_type x )                                          | Fractional                                       |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **mod** ( vec_type x, vec_type y )                                | Remainder                                        |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **mod** ( vec_type x , float y )                                  | Remainder                                        |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **modf** ( vec_type x, out vec_type i )                           | Fractional of x, with i has integer part         |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type  **min** ( vec_type a, vec_type b )                               | Minimum                                          |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type  **max** ( vec_type a, vec_type b )                               | Maximum                                          |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **clamp** ( vec_type x, vec_type min, vec_type max )              | Clamp to Min-Max                                 |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **mix** ( float a, float b, float c )                             | Linear Interpolate                               |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **mix** ( vec_type a, vec_type b, float c )                       | Linear Interpolate (Scalar Coef.)                |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **mix** ( vec_type a, vec_type b, vec_type c )                    | Linear Interpolate (Vector Coef.)                |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **mix** ( vec_type a, vec_type b, bvec_type c )                   | Linear Interpolate (Boolean-Vector Selection)    |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **step** ( vec_type a, vec_type b )                               | ``b[i] < a[i] ? 0.0 : 1.0``                      |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **step** ( float a, vec_type b)                                   | ``b[i] < a ? 0.0 : 1.0``                         |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **smoothstep** ( vec_type a, vec_type b, vec_type c )             | Hermite Interpolate                              |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **smoothstep** ( float a, float b, vec_type c )                   | Hermite Interpolate                              |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| bvec_type **isnan** ( vec_type x )                                         | Scalar, or vector component being NaN            |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| bvec_type **isinf** ( vec_type x )                                         |  Scalar, or vector component being INF           |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| ivec_type **floatBitsToInt** ( vec_type x )                                | Float->Int bit copying, no conversion            |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| uvec_type **floatBitsToUint** ( vec_type x )                               | Float->UInt bit copying, no conversion           |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **intBitsToFloat** ( ivec_type x )                                | Int->Float bit copying, no conversion            |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **uintBitsToFloat** ( uvec_type x  )                              | UInt->Float bit copying, no conversion           |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| float **length** ( vec_type x )                                            | Vector Length                                    |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| float **distance** ( vec_type a, vec_type b )                              | Distance between vectors i.e ``length(a - b)``   |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| float **dot** ( vec_type a, vec_type b )                                   | Dot Product                                      |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec3 **cross** ( vec3 a, vec3 b )                                          | Cross Product                                    |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **normalize** ( vec_type x )                                      | Normalize to unit length                         |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec3 **reflect** ( vec3 I, vec3 N )                                        | Reflect                                          |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec3 **refract** ( vec3 I, vec3 N, float eta )                             | Refract                                          |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **faceforward** ( vec_type N, vec_type I, vec_type Nref )         | If dot(Nref, I) < 0, return N, otherwise –N      |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| mat_type **matrixCompMult** ( mat_type x, mat_type y )                     | Matrix Component Multiplication                  |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| mat_type **outerProduct** ( vec_type column, vec_type row )                | Matrix Outer Product                             |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| mat_type **transpose** ( mat_type m )                                      | Transpose Matrix                                 |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| float **determinant** ( mat_type m )                                       | Matrix Determinant                               |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| mat_type **inverse** ( mat_type m )                                        | Inverse Matrix                                   |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| bvec_type **lessThan** ( vec_type x, vec_type y )                          | Bool vector cmp on < int/uint/float vectors      |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| bvec_type **greaterThan** ( vec_type x, vec_type y )                       | Bool vector cmp on > int/uint/float vectors      |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| bvec_type **lessThanEqual** ( vec_type x, vec_type y )                     | Bool vector cmp on <= int/uint/float vectors     |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| bvec_type **greaterThanEqual** ( vec_type x, vec_type y )                  | Bool vector cmp on >= int/uint/float vectors     |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| bvec_type **equal** ( vec_type x, vec_type y )                             | Bool vector cmp on == int/uint/float vectors     |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| bvec_type **notEqual** ( vec_type x, vec_type y )                          | Bool vector cmp on != int/uint/float vectors     |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| bool **any** ( bvec_type x )                                               | Any component is true                            |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| bool **all** ( bvec_type x )                                               | All components are true                          |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| bvec_type **not** ( bvec_type x )                                          | Invert boolean vector                            |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| ivec2 **textureSize** ( sampler2D_type s, int lod )                        |  Get the size of a 2D texture                    |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| ivec3 **textureSize** ( sampler2DArray_type s, int lod )                   | Get the size of a 2D texture array               |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| ivec3 **textureSize** ( sampler3D s, int lod )                             | Get the size of a 3D texture                     |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| ivec2 **textureSize** ( samplerCube s, int lod )                           | Get the size of a Cube texture                   |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type **texture** ( sampler2D_type s, vec2 uv [, float bias] )         | Perform a 2D texture read                        |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type  **texture** ( sampler2DArray_type s, vec3 uv [, float bias] )   | Perform a 2D texture array read                  |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type  **texture** ( sampler3D_type s, vec3 uv [, float bias] )        | Perform a 3D texture read                        |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4 **texture** ( samplerCube s, vec3 uv [, float bias] )                 | Perform an Cube texture read                     |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type **textureProj** ( sampler2D_type s, vec3 uv [, float bias] )     | Perform a 2D texture read with projection        |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type **textureProj** ( sampler2D_type s, vec4 uv [, float bias] )     | Perform a 2D texture read with projection        |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type  **textureProj** ( sampler3D_type s, vec4 uv [, float bias] )    | Perform a 3D texture read with projection        |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type **textureLod** ( sampler2D_type s, vec2 uv, float lod )          | Perform a 2D texture read at custom mipmap       |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type **textureLod** ( sampler2DArray_type s, vec3 uv, float lod )     | Perform a 2D texture array read at custom mipmap |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type **textureLod** ( sampler3D_type s, vec3 uv, float lod )          | Perform a 3D texture read at custom mipmap       |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4 **textureLod** ( samplerCube s, vec3 uv, float lod )                  | Perform a 3D texture read at custom mipmap       |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type **textureProjLod** ( sampler2D_type s, vec3 uv, float lod )      | Perform a 2D texture read with projection/lod    |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type **textureProjLod** ( sampler2D_type s, vec4 uv, float lod )      | Perform a 2D texture read with projection/lod    |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type **textureProjLod** ( sampler3D_type s, vec4 uv, float lod )      | Perform a 3D texture read with projection/lod    |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type **texelFetch** ( sampler2D_type s, ivec2 uv, int lod )           | Fetch a single texel using integer coords        |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type **texelFetch** ( sampler2DArray_type s, ivec3 uv, int lod )      | Fetch a single texel using integer coords        |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec4_type **texelFetch** ( sampler3D_type s, ivec3 uv, int lod )           | Fetch a single texel using integer coords        |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **dFdx** ( vec_type p )                                           | Derivative in x using local differencing         |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **dFdy** ( vec_type p )                                           | Derivative in y using local differencing         |
++----------------------------------------------------------------------------+--------------------------------------------------+
+| vec_type **fwidth** ( vec_type p )                                         | Sum of absolute derivative in x and y            |
++----------------------------------------------------------------------------+--------------------------------------------------+

tutorials/shading/shading_reference/spatial_shader.rst

@@ -68,10 +68,14 @@ Render modes
 +---------------------------------+-----------------------------------------------------------------------+
 | **vertex_lighting**             | Use vertex-based lighting.                                            |
 +---------------------------------+-----------------------------------------------------------------------+
-| **shadows_disabled**            | Disable computing shaders in shader.                                  |
+| **shadows_disabled**            | Disable computing shadows in shader.                                  |
 +---------------------------------+-----------------------------------------------------------------------+
 | **ambient_light_disabled**      | Disable contribution from ambient light and radiance map.             |
 +---------------------------------+-----------------------------------------------------------------------+
+| **shadow_to_opacity**           | Lighting modifies the alpha so shadowed areas are opaque and          | 
+|                                 | non-shadowed areas are transparent. Useful for overlaying shadows onto|
+|                                 | a camera feed in AR.                                                  |
++---------------------------------+-----------------------------------------------------------------------+
 
 Vertex built-ins
 ^^^^^^^^^^^^^^^^
@@ -120,6 +124,10 @@ shader, this value can be used as desired.
 +--------------------------------------+-------------------------------------------------------+
 | Built-in                             | Description                                           |
 +======================================+=======================================================+
+| in float **TIME**                    | Elapsed total time in seconds.                        |
++--------------------------------------+-------------------------------------------------------+
+| in vec2 **VIEWPORT_SIZE**            | Size of viewport (in pixels).                         |
++--------------------------------------+-------------------------------------------------------+
 | inout mat4 **WORLD_MATRIX**          | Model space to world space transform.                 |
 +--------------------------------------+-------------------------------------------------------+
 | in mat4 **INV_CAMERA_MATRIX**        | World space to view space transform.                  |
@@ -132,37 +140,33 @@ shader, this value can be used as desired.
 +--------------------------------------+-------------------------------------------------------+
 | inout mat4 **INV_PROJECTION_MATRIX** | Clip space to view space transform.                   |
 +--------------------------------------+-------------------------------------------------------+
-| in float **TIME**                    | Elapsed total time in seconds.                        |
-+--------------------------------------+-------------------------------------------------------+
-| in vec2 **VIEWPORT_SIZE**            | Size of viewport (in pixels).                         |
-+--------------------------------------+-------------------------------------------------------+
 | inout vec3 **VERTEX**                | Vertex in local coordinates.                          |
 +--------------------------------------+-------------------------------------------------------+
+| out vec4  **POSITION**               | If written to, overrides final vertex position.       |
++--------------------------------------+-------------------------------------------------------+
 | inout vec3 **NORMAL**                | Normal in local coordinates.                          |
 +--------------------------------------+-------------------------------------------------------+
 | inout vec3 **TANGENT**               | Tangent in local coordinates.                         |
 +--------------------------------------+-------------------------------------------------------+
 | inout vec3 **BINORMAL**              | Binormal in local coordinates.                        |
 +--------------------------------------+-------------------------------------------------------+
+| out float **ROUGHNESS**              | Roughness for vertex lighting.                        |
++--------------------------------------+-------------------------------------------------------+
 | inout vec2 **UV**                    | UV main channel.                                      |
 +--------------------------------------+-------------------------------------------------------+
 | inout vec2 **UV2**                   | UV secondary channel.                                 |
 +--------------------------------------+-------------------------------------------------------+
+| in bool **OUTPUT_IS_SRGB**           | True when calculations happen in sRGB color space     |
+|                                      | (true in GLES2, false in GLES3).                      |
++--------------------------------------+-------------------------------------------------------+
 | inout vec4 **COLOR**                 | Color from vertices.                                  |
 +--------------------------------------+-------------------------------------------------------+
 | inout float **POINT_SIZE**           | Point size for point rendering.                       |
 +--------------------------------------+-------------------------------------------------------+
-| out vec4  **POSITION**               | If written to, overrides final vertex position.       |
-+--------------------------------------+-------------------------------------------------------+
 | in int **INSTANCE_ID**               | Instance ID for instancing.                           |
 +--------------------------------------+-------------------------------------------------------+
 | in vec4 **INSTANCE_CUSTOM**          | Instance custom data (for particles, mostly).         |
 +--------------------------------------+-------------------------------------------------------+
-| out float **ROUGHNESS**              | Roughness for vertex lighting.                        |
-+--------------------------------------+-------------------------------------------------------+
-| in bool **OUTPUT_IS_SRGB**           | True when calculations happen in sRGB color space     |
-|                                      | (true in GLES2, false in GLES3).                      |
-+--------------------------------------+-------------------------------------------------------+
 
 Fragment built-ins
 ^^^^^^^^^^^^^^^^^^
@@ -174,7 +178,12 @@ these properties, and if you don't write to them, Godot will optimize away the c
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
 | Built-in                          | Description                                                                                      |
 +===================================+==================================================================================================+
-| in vec4 **FRAGCOORD**             | Fragment coordinate, pixel adjusted. In screen space.                                            |
+| in float **TIME**                 | Elapsed total time in seconds.                                                                   |
++-----------------------------------+--------------------------------------------------------------------------------------------------+
+| in vec2 **VIEWPORT_SIZE**         | Size of viewport (in pixels).                                                                    |
++-----------------------------------+--------------------------------------------------------------------------------------------------+
+| in vec4 **FRAGCOORD**             | Coordinate of pixel center in screen space. ``xy`` specifies  position in window, ``z``          |
+|                                   | specifies fragment depth if ``DEPTH`` is not used. Origin is lower-left.                         |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
 | in mat4 **WORLD_MATRIX**          | Model space to world space transform.                                                            |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
@@ -186,10 +195,6 @@ these properties, and if you don't write to them, Godot will optimize away the c
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
 | in mat4 **INV_PROJECTION_MATRIX** | Clip space to view space transform.                                                              |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
-| in float **TIME**                 | Elapsed total time in seconds.                                                                   |
-+-----------------------------------+--------------------------------------------------------------------------------------------------+
-| in vec2 **VIEWPORT_SIZE**         | Size of viewport (in pixels).                                                                    |
-+-----------------------------------+--------------------------------------------------------------------------------------------------+
 | in vec3 **VERTEX**                | Vertex that comes from vertex function (default, in view space).                                 |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
 | in vec3 **VIEW**                  | Vector from camera to fragment position (in view space).                                         |
@@ -210,12 +215,16 @@ these properties, and if you don't write to them, Godot will optimize away the c
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
 | in vec2 **UV2**                   | UV2 that comes from vertex function.                                                             |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
+| in bool **OUTPUT_IS_SRGB**        | True when calculations happen in sRGB color space (true in GLES2, false in GLES3).               |
++-----------------------------------+--------------------------------------------------------------------------------------------------+
 | in vec4 **COLOR**                 | COLOR that comes from vertex function.                                                           |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
 | out vec3 **ALBEDO**               | Albedo (default white).                                                                          |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
 | out float **ALPHA**               | Alpha (0..1); if written to, the material will go to the transparent pipeline.                   |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
+| out float **ALPHA_SCISSOR**       | If written to, values below a certain amount of alpha are discarded.                             |
++-----------------------------------+--------------------------------------------------------------------------------------------------+
 | out float **METALLIC**            | Metallic (0..1).                                                                                 |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
 | out float **SPECULAR**            | Specular. Defaults to 0.5, best not to modify unless you want to change IOR.                     |
@@ -238,12 +247,12 @@ these properties, and if you don't write to them, Godot will optimize away the c
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
 | out vec3 **TRANSMISSION**         | Transmission mask (default 0,0,0). Allows light to pass through object. Only applied if used.    |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
+| out vec3 **EMISSION**             | Emission color (can go over 1,1,1 for HDR).                                                      |
++-----------------------------------+--------------------------------------------------------------------------------------------------+
 | out float **AO**                  | Strength of Ambient Occlusion. For use with pre-baked AO.                                        |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
 | out float **AO_LIGHT_AFFECT**     | How much AO affects lights (0..1; default 0).                                                    |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
-| out vec3 **EMISSION**             | Emission color (can go over 1,1,1 for HDR).                                                      |
-+-----------------------------------+--------------------------------------------------------------------------------------------------+
 | sampler2D **SCREEN_TEXTURE**      | Built-in Texture for reading from the screen. Mipmaps contain increasingly blurred copies.       |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
 | sampler2D **DEPTH_TEXTURE**       | Built-in Texture for reading depth from the screen. Must convert to linear using INV_PROJECTION. |
@@ -254,11 +263,6 @@ these properties, and if you don't write to them, Godot will optimize away the c
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
 | in vec2 **POINT_COORD**           | Point Coordinate for drawing points with POINT_SIZE.                                             |
 +-----------------------------------+--------------------------------------------------------------------------------------------------+
-| out float **ALPHA_SCISSOR**       | If written to, values below a certain amount of alpha are discarded.                             |
-+-----------------------------------+--------------------------------------------------------------------------------------------------+
-| in bool **OUTPUT_IS_SRGB**        | True when calculations happen in sRGB color space (true in GLES2, false in GLES3).               |
-+-----------------------------------+--------------------------------------------------------------------------------------------------+
-
 
 Light built-ins
 ^^^^^^^^^^^^^^^
@@ -287,7 +291,14 @@ If you want the lights to add together, add the light contribution to ``DIFFUSE_
 +-----------------------------------+---------------------------------------------+
 | Built-in                          | Description                                 |
 +===================================+=============================================+
-| in vec4 **FRAGCOORD**             | Fragment coordinate, pixel adjusted.        |
+| in float **TIME**                 | Elapsed total time in seconds.              |
++-----------------------------------+---------------------------------------------+
+| in vec2 **VIEWPORT_SIZE**         | Size of viewport (in pixels).               |
++-----------------------------------+---------------------------------------------+
+| in vec4 **FRAGCOORD**             | Coordinate of pixel center in screen space. |
+|                                   | ``xy`` specifies position in window, ``z``  |
+|                                   | specifies fragment depth if ``DEPTH`` is    |
+|                                   | not used. Origin is lower-left.             |
 +-----------------------------------+---------------------------------------------+
 | in mat4 **WORLD_MATRIX**          | Model space to world space transform.       |
 +-----------------------------------+---------------------------------------------+
@@ -299,30 +310,33 @@ If you want the lights to add together, add the light contribution to ``DIFFUSE_
 +-----------------------------------+---------------------------------------------+
 | in mat4 **INV_PROJECTION_MATRIX** | Clip space to view space transform.         |
 +-----------------------------------+---------------------------------------------+
-| in float **TIME**                 | Elapsed total time in seconds.              |
+| in vec3 **NORMAL**                | Normal vector, in view space.               |
 +-----------------------------------+---------------------------------------------+
-| in vec2 **VIEWPORT_SIZE**         | Size of viewport (in pixels).               |
+| in vec2 **UV**                    | UV that comes from vertex function.         |
 +-----------------------------------+---------------------------------------------+
-| in vec3 **NORMAL**                | Normal vector, in view space.               |
+| in vec2 **UV2**                   | UV2 that comes from vertex function.        |
 +-----------------------------------+---------------------------------------------+
 | in vec3 **VIEW**                  | View vector, in view space.                 |
 +-----------------------------------+---------------------------------------------+
 | in vec3 **LIGHT**                 | Light Vector, in view space.                |
 +-----------------------------------+---------------------------------------------+
-| in vec3 **LIGHT_COLOR**           | Color of light multiplied by energy.        |
-+-----------------------------------+---------------------------------------------+
 | in vec3 **ATTENUATION**           | Attenuation based on distance or shadow.    |
 +-----------------------------------+---------------------------------------------+
+| in bool **OUTPUT_IS_SRGB**        | True when calculations happen in sRGB       |
+|                                   | color space (true in GLES2, false in GLES3).|
++-----------------------------------+---------------------------------------------+
 | in vec3 **ALBEDO**                | Base albedo.                                |
 +-----------------------------------+---------------------------------------------+
-| in vec3 **TRANSMISSION**          | Transmission mask.                          |
+| in vec3 **LIGHT_COLOR**           | Color of light multiplied by energy.        |
++-----------------------------------+---------------------------------------------+
+| out float **ALPHA**               | Alpha (0..1); if written to, the material   |
+|                                   | will go to the transparent pipeline.        |
 +-----------------------------------+---------------------------------------------+
 | in float **ROUGHNESS**            | Roughness.                                  |
 +-----------------------------------+---------------------------------------------+
+| in vec3 **TRANSMISSION**          | Transmission mask from fragment function.   |
++-----------------------------------+---------------------------------------------+
 | out vec3 **DIFFUSE_LIGHT**        | Diffuse light result.                       |
 +-----------------------------------+---------------------------------------------+
 | out vec3 **SPECULAR_LIGHT**       | Specular light result.                      |
 +-----------------------------------+---------------------------------------------+
-| in bool **OUTPUT_IS_SRGB**        | True when calculations happen in sRGB       |
-|                                   | color space (true in GLES2, false in GLES3).|
-+-----------------------------------+---------------------------------------------+

tutorials/shading/your_first_shader/your_second_spatial_shader.rst

@@ -83,8 +83,8 @@ a low ``METALLIC`` has a more equal representation of sky color and ``ALBEDO`` c
 .. note:: ``METALLIC`` should be close to ``0`` or ``1`` for proper PBR shading. Only set it between
           them for blending between materials.
 
-Water is not a metal, so we will set it's ``METALLIC`` property to ``0.0``. But, water is also highly
-reflective, so we will set it's ``ROUGHNESS`` property to by quite low as well.
+Water is not a metal, so we will set its ``METALLIC`` property to ``0.0``. Water is also highly
+reflective, so we will set its ``ROUGHNESS`` property to be quite low as well.
 
 .. code-block:: glsl
 

tutorials/threads/using_multiple_threads.rst

@@ -6,11 +6,13 @@ Using multiple threads
 Threads
 -------
 
-Threads allow simultaneous execution of code. It allows off-loading work from the main thread.
+Threads allow simultaneous execution of code. It allows off-loading work
+from the main thread.
 
 Godot supports threads and provides many handy functions to use them.
 
-.. note:: If using other languages (C#, C++), it may be easier to use the threading classes they support.
+.. note:: If using other languages (C#, C++), it may be easier to use the
+          threading classes they support.
 
 Creating a Thread
 -----------------
@@ -42,8 +44,8 @@ Creating a thread is very simple, just use the following code:
 
 Your function will, then, run in a separate thread until it returns.
 Even if the function has returned already, the thread must collect it, so call
-:ref:`Thread.wait_to_finish()<class_Thread_method_wait_to_finish>`, which will wait until the
-thread is done (if not done yet), then properly dispose of it.
+:ref:`Thread.wait_to_finish()<class_Thread_method_wait_to_finish>`, which will
+wait until the thread is done (if not done yet), then properly dispose of it.
 
 Mutexes
 -------
@@ -52,12 +54,17 @@ Accessing objects or data from multiple threads is not always supported (if you
 cause unexpected behaviors or crashes). Read the :ref:`Thread safe APIs<doc_thread_safe_apis>`
 to understand which engine APIs support multiple thread access.
 
-When processing your own data or calling your own functions, as a rule, try to avoid accessing
-the same data directly from different threads. You may run into synchronization problems, as the
-data is not always updated between CPU cores when modified.
-Always use a :ref:`Mutex<class_Mutex>` when accessing a piece of data from different threads.
+When processing your own data or calling your own functions, as a rule, try to
+avoid accessing the same data directly from different threads. You may run into
+synchronization problems, as the data is not always updated between CPU cores
+when modified. Always use a :ref:`Mutex<class_Mutex>` when accessing
+a piece of data from different threads.
 
-When calling :ref:`Mutex.lock()<class_Mutex_method_lock>`, a thread ensures that all other threads will be blocked (put on suspended state) if they try to *lock* the same mutex. When the mutex us unlocked by calling :ref:`Mutex.unlock()<class_Mutex_method_unlock>`, the other threads will be allowed to proceed with the lock (but only one at a time).  
+When calling :ref:`Mutex.lock()<class_Mutex_method_lock>`, a thread ensures that
+all other threads will be blocked (put on suspended state) if they try to *lock*
+the same mutex. When the mutex is unlocked by calling
+:ref:`Mutex.unlock()<class_Mutex_method_unlock>`, the other threads will be
+allowed to proceed with the lock (but only one at a time).
 
 Here is an example of using a Mutex:
 
@@ -73,7 +80,7 @@ Here is an example of using a Mutex:
         mutex = Mutex.new()
         thread = Thread.new()
         thread.start(self, "_thread_function")
-        
+
         # Increase value, protect it with Mutex.
         mutex.lock()
         counter += 1
@@ -93,12 +100,15 @@ Here is an example of using a Mutex:
 Semaphores
 ----------
 
-Sometimes you want your thread to work *"on demand"*. In other words, tell it when to work
-and let it suspend when it isn't doing anything.
-For this :ref:`Semaphores<class_Semaphore>` are used. The function :ref:`Semaphore.wait()<class_Semaphore_method_wait>`
-is used in the thread to suspend it until some data arrives.
+Sometimes you want your thread to work *"on demand"*. In other words, tell it
+when to work and let it suspend when it isn't doing anything.
+For this, :ref:`Semaphores<class_Semaphore>` are used. The function
+:ref:`Semaphore.wait()<class_Semaphore_method_wait>` is used in the thread to
+suspend it until some data arrives.
 
-The main thread, instead, uses :ref:`Semaphore.post()<class_Semaphore_method_post>` to signal that data is ready to be processed:
+The main thread, instead, uses
+:ref:`Semaphore.post()<class_Semaphore_method_post>` to signal that data is
+ready to be processed:
 
 .. tabs::
  .. code-tab:: gdscript GDScript

tutorials/viewports/multiple_resolutions.rst

@@ -3,50 +3,56 @@
 Multiple resolutions
 ====================
 
-
 The problem of multiple resolutions
 -----------------------------------
 
-Developers often have trouble understanding  how to best support multiple resolutions
-in their games. For Desktop and Console games this is more or less straightforward,
-as most screen aspect ratios are 16:9 and resolutions are standard (720,1080,2k,4k,etc).
+Developers often have trouble understanding how to best support multiple
+resolutions in their games. For desktop and console games, this is more or less
+straightforward, as most screen aspect ratios are 16:9 and resolutions
+are standard (720p, 1080p, 1440p, 4K, …).
 
-For mobile games at first it was easy. For many years, the iPhone (and iPad) used the same
-resolution. When *Retina* was implemented, they just doubled the amount of pixel density 
-(so most developers had assets in default and double resolutions).
+For mobile games, at first, it was easy. For many years, the iPhone and iPad
+used the same resolution. When *Retina* was implemented, they just doubled
+the pixel density; most developers had to supply assets in default and double
+resolutions.
 
-Nowadays this is no longer the case, as there are plenty of different screen sizes, densities
-and aspect ratios for mobile, and non conventional sizes are becoming trendy for Desktop,
-such as ultra-wide.
+Nowadays, this is no longer the case, as there are plenty of different screen
+sizes, densities, and aspect ratios. Non-conventional sizes are also becoming
+increasingly popular, such as ultrawide displays.
 
-For 3D games there is not much of a need to support multiple resolutions (from the aesthetic
-point of view). The 3D geometry will just fill the screen based on the field-of-view, disregarding
-the aspect ratio. The main reason one may want to support this, in this case, is for *performance* reasons (running
-in lower resolution to increase frames per second).
+For 3D games, there is not much of a need to support multiple resolutions (from
+the aesthetic point of view). The 3D geometry will just fill the screen based on
+the field of view, disregarding the aspect ratio. The main reason one may want
+to support this, in this case, is for *performance* reasons (running in lower
+resolution to increase frames per second).
 
-For 2D and game UIs, this is a different matter, as art needs to be created using specific pixel sizes
-in software such as Photoshop, Gimp, Krita, etc.
+For 2D and game UIs, this is a different matter, as art needs to be created
+using specific pixel sizes in software such as Photoshop, GIMP or Krita.
 
-Given layouts, aspect ratios, resolutions and pixel densities can change so much, it is no longer possible
-to design UIs for every specific screen. Another method must be used.
+Since layouts, aspect ratios, resolutions, and pixel densities can change so
+much, it is no longer possible to design UIs for every specific screen.
+Another method must be used.
 
 One size fits all
 -----------------
 
-The most common approach nowadays is to just use a single *base* resolution and then fit it to everything else.
-This resolution is how most players are expected to play the game (given their hardware). For mobile, Google 
-has useful `stats <https://developer.android.com/about/dashboards>`_ online, and for desktop, 
-Steam `also does <https://store.steampowered.com/hwsurvey/Steam-Hardware-Software-Survey-Welcome-to-Steam>`_.
+The most common approach is to use a single *base* resolution and
+then fit it to everything else. This resolution is how most players are expected
+to play the game (given their hardware). For mobile, Google has useful `stats
+<https://developer.android.com/about/dashboards>`_ online, and for desktop,
+Steam `also does <https://store.steampowered.com/hwsurvey/>`_.
 
-As an example, Steam shows that the most common *primary display resolution* is 1920x1080, so a sensible approach is to develop a game for this resolution, then handle scaling for different sizes and aspect ratios.
+As an example, Steam shows that the most common *primary display resolution* is
+1920×1080, so a sensible approach is to develop a game for this resolution, then
+handle scaling for different sizes and aspect ratios.
 
 Godot provides a several useful tools to do this easily.
 
 Base size
 ---------
 
-A base size for the window can be specified in the project settings under
-"Display", "Window".
+A base size for the window can be specified in the Project Settings under
+**Display → Window**.
 
 .. image:: img/screenres.png
 
@@ -89,7 +95,7 @@ of configuration variables that provide several options:
 Stretch Mode
 ^^^^^^^^^^^^
 
-The "Stretch Mode" setting defines how the base size is stretched to fit
+The **Stretch Mode** setting defines how the base size is stretched to fit
 the resolution of the window or screen.
 
 .. image:: img/stretch.png
@@ -104,21 +110,21 @@ demonstrate the effect of different stretch modes. A single sprite, also
 .. Animated GIFs are generated from:
 .. https://github.com/ttencate/godot_scaling_mode
 
--  Stretch Mode = **Disabled** (default): No stretching happens. One
+-  **Stretch Mode = Disabled** (default): No stretching happens. One
    unit in the scene corresponds to one pixel on the screen. In this
-   mode, the "Stretch Aspect" setting has no effect.
+   mode, the **Stretch Aspect** setting has no effect.
 
    This is a good option if you want full control over every screen
    pixel, and is probably the best option for 3D games.
 
    .. image:: img/stretch_disabled_expand.gif
 
--  Stretch Mode = **2D**: In this mode, the size specified in
-   display/width and display/height in the project settings will be
-   stretched to cover the whole screen (taking the "Stretch Aspect"
-   setting into account). This means that everything will be rendered
-   directly at the target resolution. 3D will be largely unaffected,
-   while in 2D there is no longer a 1:1 correspondence between sprite
+-  **Stretch Mode = 2D**: In this mode, the size specified in
+   display/width and display/height in the project settings is
+   stretched to cover the whole screen (taking the **Stretch Aspect**
+   setting into account). This means that everything is rendered
+   directly at the target resolution. 3D is largely unaffected,
+   while in 2D, there is no longer a 1:1 correspondence between sprite
    pixels and screen pixels, which may result in scaling artifacts.
 
    This is a good option if your 2D artwork has a sufficiently high
@@ -128,15 +134,15 @@ demonstrate the effect of different stretch modes. A single sprite, also
 
    .. image:: img/stretch_2d_expand.gif
 
--  Stretch Mode = **Viewport**: Viewport scaling means that the size of
+-  **Stretch Mode = Viewport**: Viewport scaling means that the size of
    the root :ref:`Viewport <class_Viewport>` is set precisely to the
-   base size specified in the "Display" section of the project settings.
+   base size specified in the Project Settings' **Display** section.
    The scene is rendered to this viewport first. Finally, this viewport
-   is scaled to fit the screen (taking the "Stretch Aspect" setting into
+   is scaled to fit the screen (taking the **Stretch Aspect** setting into
    account).
 
    This mode is useful when working with pixel-precise games, or for the
-   sake of rendering to a lower resolution for improving performance.
+   sake of rendering to a lower resolution to improve performance.
 
    .. image:: img/stretch_viewport_expand.gif
 
@@ -144,14 +150,14 @@ Stretch Aspect
 ^^^^^^^^^^^^^^
 
 The second setting is the stretch aspect. Note that this only takes effect if
-"Stretch Mode" is set to something other than "disabled".
+**Stretch Mode** is set to something other than **Disabled**.
 
 In the animations below, you will notice gray and black areas. The black
 areas are added by the engine and cannot be drawn into. The gray areas
 are part of your scene, and can be drawn to. The gray areas correspond
 to the region outside the blue frame you see in the 2D editor.
 
--  Stretch Aspect = **Ignore**: Ignore the aspect ratio when stretching
+-  **Stretch Aspect = Ignore**: Ignore the aspect ratio when stretching
    the screen. This means that the original resolution will be stretched
    to exactly fill the screen, even if it's wider or narrower. This may
    result in nonuniform stretching: things looking wider or taller than
@@ -159,7 +165,7 @@ to the region outside the blue frame you see in the 2D editor.
 
    .. image:: img/stretch_viewport_ignore.gif
 
--  Stretch Aspect = **Keep**: Keep aspect ratio when stretching the
+-  **Stretch Aspect = Keep**: Keep aspect ratio when stretching the
    screen. This means that the viewport retains its original size
    regardless of the screen resolution, and black bars will be added to
    the top/bottom of the screen ("letterboxing") or the sides
@@ -171,7 +177,7 @@ to the region outside the blue frame you see in the 2D editor.
 
    .. image:: img/stretch_viewport_keep.gif
 
--  Stretch Aspect = **Keep Width**: Keep aspect ratio when stretching the
+-  **Stretch Aspect = Keep Width**: Keep aspect ratio when stretching the
    screen. If the screen is wider than the base size, black bars are
    added at the left and right (pillarboxing). But if the screen is
    taller than the base resolution, the viewport will be grown in the
@@ -184,7 +190,7 @@ to the region outside the blue frame you see in the 2D editor.
 
    .. image:: img/stretch_viewport_keep_width.gif
 
--  Stretch Aspect = **Keep Height**: Keep aspect ratio when stretching
+-  **Stretch Aspect = Keep Height**: Keep aspect ratio when stretching
    the screen. If the screen is taller than the base size, black
    bars are added at the top and bottom (letterboxing). But if the
    screen is wider than the base resolution, the viewport will be grown
@@ -196,7 +202,7 @@ to the region outside the blue frame you see in the 2D editor.
 
    .. image:: img/stretch_viewport_keep_height.gif
 
--  Stretch Aspect = **Expand**: Keep aspect ratio when stretching the
+-  **Stretch Aspect = Expand**: Keep aspect ratio when stretching the
    screen, but keep neither the base width nor height. Depending on the
    screen aspect ratio, the viewport will either be larger in the
    horizontal direction (if the screen is wider than the base size) or
@@ -208,19 +214,19 @@ to the region outside the blue frame you see in the 2D editor.
 Stretch Shrink
 ^^^^^^^^^^^^^^
 
-The "Shrink" setting allows you to add an extra scaling factor on top of
-what the "Stretch" options above already provide. The default value of 1
+The **Shrink** setting allows you to add an extra scaling factor on top of
+what the **Stretch** options above already provide. The default value of 1
 means that no scaling occurs.
 
-If, for example, you set "Shrink" to 4 and leave "Stretch Mode" on
-"Disabled", each unit in your scene will correspond to 4×4 pixels on the
+If, for example, you set **Shrink** to 4 and leave **Stretch Mode** on
+**Disabled**, each unit in your scene will correspond to 4×4 pixels on the
 screen.
 
-If "Stretch Mode" is set to something other than "Disabled", the size of
-the root viewport is scaled down by the "Shrink" factor, and pixels in
-the output are scaled up by the same amount. This is rarely useful for
-2D games, but can be used to increase performance in 3D games by
-rendering them at a lower resolution.
+If **Stretch Mode** is set to something other than **Disabled**, the size of
+the root viewport is scaled down by the **Shrink** factor, and pixels
+in the output are scaled up by the same amount. This is rarely useful for
+2D games, but can be used to increase performance in 3D games
+by rendering them at a lower resolution.
 
 From scripts
 ^^^^^^^^^^^^
@@ -232,21 +238,34 @@ To configure stretching at runtime from a script, use the
 Reducing aliasing on downsampling
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If the game has a very high base resolution (say 4k), aliasing might appear
-when downsampling to something considerably lower like 720. This can be
-detected and reduced by forcing to shrink all images by 2 upon load (this is
-very fast). This can be achieved by calling
+If the game has a very high base resolution (e.g. 3840×2160), aliasing might
+appear when downsampling to something considerably lower like 1280×720.
+Aliasing can be made less visible by shrinking all images by a factor of 2
+upon loading. This can be done by calling the method below before
+the game data is loaded:
 
 ::
 
-    VisualServer.texture_set_shrink_all_x2_on_set_data(true) 
-
+    VisualServer.texture_set_shrink_all_x2_on_set_data(true)
 
-Before most game data is loaded.
 
 Handling aspect ratios
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Once scaling for different resolutions is accounted for, just make sure that your *user interface*
-also scales for different aspect ratios. This can be easily done using :ref:`anchors <doc_size_and_anchors>` 
-and/or :ref:`containers <doc_gui_containers>`.
+Once scaling for different resolutions is accounted for, make sure that
+your *user interface* also scales for different aspect ratios. This can be
+done using :ref:`anchors <doc_size_and_anchors>` and/or :ref:`containers
+<doc_gui_containers>`.
+
+Field of view scaling
+^^^^^^^^^^^^^^^^^^^^^
+
+The 3D Camera node's **Keep Aspect** property defaults to the **Keep Height**
+scaling mode (also called *Hor+*). This is usually the best value for desktop
+games and mobile games in landscape mode, as widescreen displays will
+automatically use a wider field of view.
+
+However, if your 3D game is intended to be played in portrait mode, it may make
+more sense to use **Keep Width** instead (also called *Vert-*). This way,
+smartphones with an aspect ratio taller than 16:9 (e.g. 19:9) will use a
+*taller* field of view, which is more logical here.