Merge branch 'master' into 3.1

about/docs_changelog.rst

@@ -7,145 +7,192 @@ The documentation is continually being improved. The release of version 3.1
 includes many new tutorials, many fixes and updates for old tutorials, and many updates
 to the class reference. Below is a list of new tutorials added since version 3.0.
 
-.. note:: This document only contains new tutorials so not all changes are reflected, 
+.. note:: This document only contains new tutorials so not all changes are reflected,
           many tutorials have been substantially updated but are not reflected in this document.
 
-New tutorials since version 3.0
+New tutorials since version 3.1
 -------------------------------
 
-Step-by-step
-^^^^^^^^^^^^
+.. note:: This section only includes tutorials which have been added in the ``latest`` branch
+          and backported to this ``3.1`` branch. Some more tutorials specific to later Godot
+          releases are available on the ``latest`` branch.
 
-- :ref:`Signals <doc_signals>`
-- :ref:`Exporting <doc_exporting>`
+2D
+^^
 
-Project workflow
+- :ref:`doc_2d_sprite_animation`
+
+Math
+^^^^
+
+- :ref:`doc_beziers_and_curves`
+- :ref:`doc_interpolation`
+
+Inputs
+^^^^^^
+
+- :ref:`doc_input_examples`
+
+Internationalization
+^^^^^^^^^^^^^^^^^^^^
+
+- :ref:`doc_localization_using_gettext`
+
+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`
+
+Plugins
+^^^^^^^
+
+- :ref:`doc_inspector_plugins`
+
+Multi-threading
+^^^^^^^^^^^^^^^
+
+- :ref:`doc_using_multiple_threads`
+
+Creating content
 ^^^^^^^^^^^^^^^^
-Best Practices:
-  - :ref:`Introduction <doc_introduction_best_practices>`
-  - :ref:`What are Godot classes <doc_what_are_godot_classes>`
-  - :ref:`Scene organization <doc_scene_organization>`
-  - :ref:`Scenes versus scripts <doc_scenes_versus_scripts>`
-  - :ref:`Autoloads versus internal nodes <doc_autoloads_versus_internal_nodes>`
-  - :ref:`Node alternatives <doc_node_alternatives>`
-  - :ref:`Godot interfaces <doc_godot_interfaces>`
-  - :ref:`Godot notifications <doc_godot_notifications>`
-  - :ref:`Data preferences <doc_data_preferences>`
-  - :ref:`Logic preferences <doc_logic_preferences>`
+
+- :ref:`doc_procedural_geometry`
+
+Optimization
+^^^^^^^^^^^^
+
+- :ref:`doc_using_multimesh`
+- :ref:`doc_using_servers`
+
+Legal
+^^^^^
+
+- :ref:`doc_complying_with_licenses`
+
+New tutorials since version 3.0
+-------------------------------
+
+Step by step
+^^^^^^^^^^^^
+
+- :ref:`doc_signals`
+- :ref:`doc_exporting`
 
 Scripting
 ^^^^^^^^^
 
-- :ref:`Typed GDscript <doc_gdscript_static_typing>`
+- :ref:`doc_gdscript_static_typing`
+
+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`
 
 2D
 ^^
 
-- :ref:`2D lights and shadows <doc_2d_lights_and_shadows>`
-- :ref:`2D meshes <doc_2d_meshes>`
+- :ref:`doc_2d_lights_and_shadows`
+- :ref:`doc_2d_meshes`
 
 3D
 ^^
- 
-- :ref:`CSG <doc_csg_tools>`
-- :ref:`Animating thousands of fish with MultiMesh <doc_animating_thousands_of_fish>`
-- :ref:`Controlling thousands of fish with Particles <doc_controlling_thousands_of_fish>`
+
+- :ref:`doc_csg_tools`
+- :ref:`doc_animating_thousands_of_fish`
+- :ref:`doc_controlling_thousands_of_fish`
 
 Physics
 ^^^^^^^
 
-- :ref:`Ragdoll system <doc_ragdoll_system>`
-- :ref:`Softbody <doc_soft_body>`
+- :ref:`doc_ragdoll_system`
+- :ref:`doc_soft_body`
 
 Animation
 ^^^^^^^^^
 
-- :ref:`2D skeletons <doc_2d_skeletons>`
-- :ref:`AnimationTree <doc_animation_tree>`
+- :ref:`doc_2d_skeletons`
+- :ref:`doc_animation_tree`
 
 GUI
 ^^^
 
-- :ref:`Containers <doc_gui_containers>`
+- :ref:`doc_gui_containers`
 
 Viewports
 ^^^^^^^^^
 
-- :ref:`Using a Viewport as a texture <doc_viewport_as_texture>`
-- :ref:`Custom post-processing <doc_custom_postprocessing>`
+- :ref:`doc_viewport_as_texture`
+- :ref:`doc_custom_postprocessing`
 
 Shading
 ^^^^^^^
 
-- :ref:`Intro to shaders: 2D and 3D water (7 video tutorials) <doc_intro_to_shaders_water_workshop>`
-- :ref:`Migrating to Godot’s shading language <doc_migrating_to_godot_shader_language>`
-- :ref:`Advanced post-processing <doc_advanced_postprocessing>`
-
-Your First Shader Series:
-  - :ref:`What are shaders? <doc_what_are_shaders>`
-  - :ref:`Your first CanvasItem shader <doc_your_first_canvasitem_shader>`
-  - :ref:`Your first Spatial shader <doc_your_first_spatial_shader>`
-  - :ref:`Your first Spatial shader: Part 2 <doc_your_second_spatial_shader>`
+- :ref:`doc_intro_to_shaders_water_workshop`
+- :ref:`doc_migrating_to_godot_shader_language`
+- :ref:`doc_advanced_postprocessing`
 
 Shading Reference:
-  - :ref:`Shaders <doc_shaders>`
-  - :ref:`Shading language <doc_shading_language>`
-  - :ref:`Spatial shaders <doc_spatial_shader>`
-  - :ref:`CanvasItem shaders <doc_canvas_item_shader>`
-  - :ref:`Particles shaders <doc_particle_shader>`
+  - :ref:`doc_shaders`
+  - :ref:`doc_shading_language`
+  - :ref:`doc_spatial_shader`
+  - :ref:`doc_canvas_item_shader`
+  - :ref:`doc_particle_shader`
 
 VR
 ^^
 
-- :ref:`VR starter tutorial <doc_vr_starter_tutorial>`
+- :ref:`doc_vr_starter_tutorial`
+
+Plugins
+^^^^^^^
+
+- :ref:`doc_making_main_screen_plugins`
+- :ref:`doc_spatial_gizmo_plugins`
 
 Platform-specific
 ^^^^^^^^^^^^^^^^^
 
-- :ref:`Customizing the Web export HTML page <doc_customizing_html5_shell>`
+- :ref:`doc_customizing_html5_shell`
 
 Multi-threading
 ^^^^^^^^^^^^^^^
 
-- :ref:`Thread safe APIs <doc_thread_safe_apis>`
+- :ref:`doc_thread_safe_apis`
 
-Optimization
-^^^^^^^^^^^^
+Creating content
+^^^^^^^^^^^^^^^^
 
-- :ref:`Using MultiMesh <doc_using_multimesh>`
-- :ref:`Using servers <doc_using_servers>`
+- :ref:`doc_making_trees`
 
 Miscellaneous
 ^^^^^^^^^^^^^
 
-- :ref:`Fixing jitter and stutter <doc_jitter_stutter>`
-- :ref:`Running code in the editor <doc_running_code_in_the_editor>`
-- :ref:`Change scenes manually <doc_change_scenes_manually>`
-- :ref:`Differences between GLES2 and GLES3 <doc_gles2_gles3_differences>`
-
-Legal
-^^^^^
-
-- :ref:`Complying with Licenses <doc_complying_with_licenses>`
+- :ref:`doc_jitter_stutter`
+- :ref:`doc_running_code_in_the_editor`
+- :ref:`doc_change_scenes_manually`
+- :ref:`doc_gles2_gles3_differences`
 
 Compiling
 ^^^^^^^^^
 
-- :ref:`Optimizing a build for size <doc_optimizing_for_size>`
-- :ref:`Compiling with script encryption key <doc_compiling_with_script_encryption_key>`
+- :ref:`doc_optimizing_for_size`
+- :ref:`doc_compiling_with_script_encryption_key`
 
 Engine development
 ^^^^^^^^^^^^^^^^^^
 
-- :ref:`Binding to external libraries <doc_binding_to_external_libraries>`
-
-Creating content
-^^^^^^^^^^^^^^^^
-
-- :ref:`Making trees <doc_making_trees>`
-
-Plugins
-^^^^^^^
-
-- :ref:`Making main screen plugins <doc_making_main_screen_plugins>`
-- :ref:`Spatial gizmo plugins <doc_spatial_gizmo_plugins>`
+- :ref:`doc_binding_to_external_libraries`

community/tutorials.rst

@@ -25,21 +25,22 @@ Video tutorials
 - `Game from Scratch <https://www.youtube.com/watch?v=iDEcP8Mc-7s&list=PLS9MbmO_ssyDk79j9ewONxV88fD5e_o5d>`_
 - `HeartBeast <https://www.youtube.com/watch?v=wETY5_9kFtA&list=PL9FzW-m48fn2jlBu_0DRh7PvAt-GULEmd>`_
 - `Jeremy Bullock <https://www.youtube.com/channel/UCwJw2-V5S1TkBjLQ3_Ws54g>`_
-- `KidsCanCode <https://www.youtube.com/channel/UCNaPQ5uLX5iIEHUCLmfAgKg/playlists>`_
+- `KidsCanCode <https://www.youtube.com/channel/UCNaPQ5uLX5iIEHUCLmfAgKg/playlists>`__
 - `Mister Taft Creates <https://www.youtube.com/playlist?list=PL4vbr3u7UKWqwQlvwvgNcgDL1p_3hcNn2>`_
 - `Miziziziz <https://www.youtube.com/playlist?list=PLmugv6_kd0qN6AyjG245_Pdak4MXKUx88>`_
 - `P1X / Krzysztof Jankowski <https://www.youtube.com/playlist?list=PLvDk7UKhld4xGPovdB4IFtAHYMYjx_-3K>`_
 - `Pigdev <https://www.youtube.com/playlist?list=PLPMN4vCRFdordS3E-3zi0Hdh7pAsbWQ6a>`_
-- `Steincodes <https://www.youtube.com/c/steincodes/playlists>`_
+- `Steincodes <https://www.youtube.com/c/steincodes/playlists>`__
 
 Text tutorials
 --------------
 
-- `KidsCanCode <http://kidscancode.org/blog/tags/godot/>`_
-- `Steincodes <https://steincodes.tumblr.com>`_
+- `KidsCanCode <http://kidscancode.org/blog/tags/godot/>`__
+- `Steincodes <https://steincodes.tumblr.com>`__
 
 Devlogs
 -------
+
 - `Andrea Catania (Physics & AI) <https://www.youtube.com/channel/UCm4RuvYtgpgFDTCgaEUT5uQ/videos>`_
 - `Bastiaan Olij (AR & VR) <https://www.youtube.com/channel/UCrbLJYzJjDf2p-vJC011lYw/videos>`_
 

conf.py

@@ -33,6 +33,7 @@ version = 'latest'
 release = 'latest'
 
 language = 'en'
+is_i18n = tags.has('i18n')
 
 exclude_patterns = ['_build']
 
@@ -68,7 +69,7 @@ html_theme_options = {
 
 # VCS options: https://docs.readthedocs.io/en/latest/vcs.html#github
 html_context = {
-    "display_github": True, # Integrate GitHub
+    "display_github": not is_i18n, # Integrate GitHub
     "github_user": "godotengine", # Username
     "github_repo": "godot-docs", # Repo name
     "github_version": "master", # Version
@@ -107,5 +108,13 @@ linkcheck_timeout = 10
 locale_dirs = ['../sphinx/po/']
 gettext_compact = False
 # Exclude class reference when marked with tag i18n.
-if tags.has('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_web.rst

@@ -10,7 +10,7 @@ Requirements
 
 To compile export templates for the Web, the following is required:
 
--  `Emscripten 1.38.22+ <http://kripken.github.io/emscripten-site>`__: If the version available
+-  `Emscripten 1.38.27+ <http://kripken.github.io/emscripten-site>`__: If the version available
    per package manager is not recent enough, the best alternative is to install
    using the `Emscripten SDK <http://kripken.github.io/emscripten-site/docs/getting_started/downloads.html>`__
 -  `Python 2.7+ or Python 3.5+ <https://www.python.org/>`__

development/compiling/compiling_for_windows.rst

@@ -10,15 +10,19 @@ Requirements
 
 For compiling under Windows, the following is required:
 
--  Visual C++, `Visual
-   Studio Community <https://www.visualstudio.com/vs/community/>`__
-   (recommended), version 2013 (12.0) or later.
-   **Make sure you read Installing Visual Studio caveats below or you
-   will have to run/download the installer again.**
--  `Python 2.7+ or Python 3.5+ <https://www.python.org/downloads/>`__.
--  `Pywin32 Python Extension <https://github.com/mhammond/pywin32>`__
-   for parallel builds (which increase the build speed by a great factor).
--  `SCons <https://www.scons.org>`__ build system.
+- `Visual Studio Community <https://www.visualstudio.com/vs/community/>`_,
+  version 2015 (14.0) or later.
+  **Make sure to read "Installing Visual Studio caveats" below or you
+  will have to run/download the installer again.**
+- MinGW-w64 can be used as an alternative to Visual Studio.
+- `Python 3.5+ (recommended) or Python 2.7+. <https://www.python.org/downloads/windows/>`_
+- `SCons <https://www.scons.org>`_ build system.
+- *Optional* - `yasm <https://yasm.tortall.net/>`_ (for WebM SIMD optimizations)
+
+.. note:: If you have `Scoop <https://scoop.sh/>`_ installed, you can easily
+          install MinGW and other dependencies using the following command::
+
+              scoop install gcc python scons
 
 .. seealso:: For a general overview of SCons usage for Godot, see
              :ref:`doc_introduction_to_the_buildsystem`.
@@ -26,302 +30,97 @@ For compiling under Windows, the following is required:
 Setting up SCons
 ----------------
 
-Python adds the interpreter (python.exe) to the path. It usually
-installs in ``C:\Python`` (or ``C:\Python[Version]``). SCons installs
-inside the Python install (typically in the ``Scripts`` folder) and
-provides a batch file called ``scons.bat``.
-The location of this file can be added to the path or it can simply be
-copied to ``C:\Python`` together with the interpreter executable.
+First, make sure to enable the option to add Python to the ``PATH`` in
+the Python installer. The SCons installer should then detect and use
+the existing Python installation.
 
 To check whether you have installed Python and SCons correctly, you can
-type ``python --version`` and ``scons --version`` into the
-Windows Command Prompt (``cmd.exe``).
-
-If commands above do not work, make sure you add Python to your PATH
-environment variable after installing it, and check again.
-
-Setting up Pywin32
-------------------
-
-Pywin32 is required for parallel builds using multiple CPU cores.
-If SCons is issuing a warning about Pywin32 after parsing SConstruct
-build instructions, when beginning to build, you need to install it properly
-from the correct installer executable for your Python version
-`located at Github. <https://github.com/mhammond/pywin32/releases>`__
-
-For example, if you installed a 32-bit version of Python 2.7, you would want
-to install the latest version of Pywin32 that is built for the mentioned version
-of Python. That executable installer would be named ``pywin32-221.win32-py2.7.exe``.
+type ``python --version`` and ``scons --version`` into a command prompt
+(``cmd.exe``).
 
-The ``amd64`` version of Pywin32 is for a 64-bit version of Python
-``pywin32-221.win-amd64-py2.7.exe``. Change the ``py`` number to install for
-your version of Python (check via ``python --version`` mentioned above).
+If the commands above don't work, make sure to add Python to your ``PATH``
+environment variable after installing it, then check again.
+You can do so by running the Python installer again and enabling the option
+to add Python to the ``PATH``.
 
 .. _doc_compiling_for_windows_install_vs:
 
 Installing Visual Studio caveats
 --------------------------------
 
-If installing Visual Studio 2015 or later, make sure to run **Custom** installation, not
-**Typical** and select C++ as language there (and any other things you might
-need). The installer does not install C++ by default. C++ was the
-`only language made optional <https://blogs.msdn.microsoft.com/vcblog/2015/07/24/setup-changes-in-visual-studio-2015-affecting-c-developers/>`__
-in Visual Studio 2015.
+If installing Visual Studio 2017 or 2019, make sure to enable **C++** in
+the list of workflows to install.
 
-If you have already made the mistake of installing a **Typical**,
-installation, rerun the executable installer you downloaded from
-internet, it will give you a **Modify** Button option. Running the
-install from Add/Remove programs will only give you the "Repair" option,
-which will do nothing for your problem.
+If installing Visual Studio 2015, make sure to run a **Custom**
+installation instead of **Typical** and select **C++** as a language there.
 
-If you're using Express, make sure you get/have a version that can
-compile for ***C++, Desktop***.
+If you've already made the mistake of installing Visual Studio without
+C++ support, run the installer again; it should present you a **Modify** button.
+Running the installer from *Add/Remove Programs* will only give you
+a **Repair** option, which won't let you install C++ tools.
 
 Downloading Godot's source
 --------------------------
 
-`Godot's <https://github.com/godotengine/godot>`__ source is hosted on
-GitHub. Downloading it (cloning) via `Git <https://git-scm.com/>`__ is recommended.
+Godot's source code is `hosted on GitHub <https://github.com/godotengine/godot>`_.
+Downloading it (cloning) using `Git <https://git-scm.com/>`_ is recommended.
 
-The tutorial will presume from now on that you placed the source into
+The tutorial will assume from now on that you placed the source code in
 ``C:\godot``.
 
 Compiling
 ---------
 
-SCons will not be able out of the box to compile from the
-Windows Command Prompt (``cmd.exe``) because SCons and Visual C++ compiler
-will not be able to locate environment variables and executables they
-need for compilation.
-
-Therefore, you need to start a Visual Studio command prompt. It sets up
-environment variables needed by SCons to locate the compiler.
-It should be called similar to one of the below names (for your
-respective version of Visual Studio):
-
-* "Developer Command Prompt for VS2013"
-* "VS2013 x64 Native Tools Command Prompt"
-* "VS2013 x86 Native Tools Command Prompt"
-* "VS2013 x64 Cross Tools Command Prompt"
-* "VS2013 x86 Cross Tools Command Prompt"
-
-You should be able to find at least the Developer Command Prompt for
-your version of Visual Studio in your start menu.
-
-However Visual Studio sometimes seems to not install some of the above
-shortcuts, except the Developer Console at these locations that are
-automatically searched by the start menu search option:
-
-::
-
-   Win 7:
-   C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2015\Visual Studio Tools
-   C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2013\Visual Studio Tools
+Selecting a compiler
+~~~~~~~~~~~~~~~~~~~~
 
-If you found the Developer Console, it will do for now to create a 32-bit
-version of Godot, but if you want the 64-bit version, you might need
-to setup the prompts manually for easy access.
+SCons will automatically find and use an existing Visual Studio installation.
+If you do not have Visual Studio installed, it will attempt to use
+MinGW instead. If you already have Visual Studio installed and want to
+use MinGW, pass ``use_mingw=yes`` to the SCons command line.
 
-If you don't see some of the shortcuts, "How the prompts actually work"
-section below will explain how to setup these prompts if you need them.
-
-About the Developer/Tools Command Prompts and the Visual C++ compiler
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There is a few things you need to know about these consoles and the
-Visual C++ compiler.
-
-Your Visual Studio installation will ship with several Visual C++
-compilers, them being more or less identical, however each ``cl.exe``
-(Visual C++ compiler) will compile Godot for a different architecture
-(32-bit x86 or 64-bit x86; the ARM compiler is not supported).
-
-The **Developer Command Prompt** will build a 32-bit version of Godot by
-using the 32-bit Visual C++ compiler.
-
-**Native Tools** Prompts (mentioned above) are used when you want the
-32-bit cl.exe to compile a 32-bit executable (x86 Native Tools
-Command Prompt). For the 64-bit cl.exe, it will compile a 64-bit
-executable (x64 Native Tools Command Prompt).
-
-The **Cross Tools** are used when your Windows is using one architecture
-(32-bit, for example) and you need to compile to a different
-architecture (64-bit). As you might be familiar, 32-bit Windows can not
-run 64-bit executables, but you still might need to compile for them.
-
-For example:
-
-* "VS2013 x64 Cross Tools Command Prompt" will use a 32-bit cl.exe that
-  will compile a 64 bit application.
-
-* "VS2013 x86 Cross Tools Command Prompt" will use a 64-bit cl.exe that
-  will compile a 32-bit application. This one is useful if you are
-  running a 32-bit Windows.
-
-On a 64-bit Windows, you can run any of above prompts and compilers
-(``cl.exe`` executables) because 64-bit Windows can run any 32-bit
-application. 32-bit Windows cannot run 64-bit executables, so the
-Visual Studio installer won't even install shortcuts for some of
-these prompts.
-
-Note that you need to choose the **Developer Console** or the correct
-**Tools Prompt** to build Godot for the correct architecture. Use only
-Native Prompts if you are not sure yet what exactly Cross Compile
-Prompts do.
+During development, using the Visual Studio compiler is usually a better idea,
+as it links the Godot binary much faster than MinGW. However, MinGW can
+produce more optimized binaries using link-time optimization (see below),
+making it a better choice for production use.
 
 Running SCons
 ~~~~~~~~~~~~~
 
-Once inside the **Developer Console/Tools Console Prompt**, go to the
-root directory of the engine source code and type:
-
-::
+After opening a command prompt, change to the root directory of
+the engine source code (using ``cd``) and type::
 
     C:\godot> scons platform=windows
 
-Tip: if you installed "Pywin32 Python Extension" you can append the -j
-command to instruct SCons to run parallel builds like this:
-
-::
+You can specify a number of CPU threads to use to speed up the build::
 
     C:\godot> scons -j6 platform=windows
 
 In general, it is OK to have at least as many threads compiling Godot as
 you have cores in your CPU, if not one or two more. Feel free to add the
--j option to any SCons command you see below if you setup the
-"Pywin32 Python Extension".
+-j option to any SCons command you see below.
+
+.. note:: When compiling with multiple CPU threads, SCons may warn about
+          pywin32 being missing. You can safely ignore this warning.
 
 If all goes well, the resulting binary executable will be placed in
-``C:\godot\bin\`` with the name of ``godot.windows.tools.32.exe`` or
-``godot.windows.tools.64.exe``. SCons will automatically detect what
-compiler architecture the environment (the prompt) is setup for and will
-build a corresponding executable.
+``C:\godot\bin\`` with the name ``godot.windows.tools.32.exe`` or
+``godot.windows.tools.64.exe``.
+
+.. note:: By default, SCons will build a binary matching your CPU architecture,
+          but this can be overriden using ``bits=64`` or ``bits=32``.
 
 This executable file contains the whole engine and runs without any
-dependencies. Executing it will bring up the Project Manager.
+dependencies. Running it will bring up the Project Manager.
 
 .. note:: If you are compiling Godot for production use, then you can
           make the final executable smaller and faster by adding the
           SCons option ``target=release_debug``.
 
-How the prompts actually work
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The Visual Studio command prompts are just shortcuts that call the
-standard Command Prompt and have it run a batch file before giving  you
-control. The batch file itself is called **vcvarsall.bat** and it sets up
-environment variables, including the PATH variable, so that the correct
-version of the compiler can be run. The Developer Command Prompt calls a
-different file called **VsDevCmd.bat** but none of the other tools that
-this batch file enables are needed by Godot/SCons.
-
-Since you are probably using Visual Studio 2013 or 2015, if you need to
-recreate them manually, use the below folders, or place them on the
-desktop/taskbar:
-
-::
-
-   C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2015\Visual Studio Tools
-   C:\ProgramData\Microsoft\Windows\Start Menu\Programs\Visual Studio 2013\Visual Studio Tools
-
-Start the creation of the shortcut by pressing the ``right mouse
-button/New/Shortcut`` in an empty place in your desired location.
-
-Then copy one of these commands below for the corresponding tool you
-need into the "Path" and "Name" sections of the shortcut creation
-wizard, and fix the path to the batch file if needed.
-
-* Visual Studio 2013 is in the "Microsoft Visual Studio 12.0" folder.
-* Visual Studio 2015 is in the "Microsoft Visual Studio 14.0" folder.
-* etc.
-
-::
-
-   Name: Developer Command Prompt for VS2013
-   Path: %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\Tools\VsDevCmd.bat""
-
-   Name: VS2013 x64 Cross Tools Command Prompt
-   Path: %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat"" x86_amd64
-
-   Name: VS2013 x64 Native Tools Command Prompt
-   Path: %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat"" amd64
-
-   Name: VS2013 x86 Native Tools Command Prompt
-   Path: %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat"" x86
-
-   Name: VS2013 x86 Cross Tools Command Prompt
-   Path: %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat"" amd64_x86
-
-After you create the shortcut, in the shortcut's properties, that you
-can access by right clicking with your mouse on the shortcut itself, you
-can choose the starting directory of the command prompt ("Start in"
-field).
-
-Some of these shortcuts (namely the 64-bit compilers) seem to not be
-available in the Express edition of Visual Studio or Visual C++. Before
-recreating the commands, make sure that ``cl.exe`` executables are present
-in one of these locations, they are the actual compilers for the
-architecture you want to build from the command prompt.
-
-::
-
-    x86 (32-bit) cl.exe
-    C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\cl.exe
-
-    x86 (32-bit) cl.exe for cross-compiling for 64-bit Windows.
-    C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\x86_amd64\cl.exe
-
-    x64 (64-bit) cl.exe
-    C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\amd64\cl.exe
-
-    x64 (64-bit) cl.exe for cross-compiling for 32-bit Windows.
-    C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\bin\amd64_x86\cl.exe
-
-
-In case you are wondering what these prompt shortcuts do, they call ``cmd.exe``
-with the ``\k`` option and have it run a Batch file.
-
-::
-
-   %comspec% - path to cmd.exe
-   \k - keep alive option of the command prompt
-   remainder - command to run via cmd.exe
-
-   cmd.exe \k(eep cmd.exe alive after commands behind this option run) ""runme.bat"" with_this_option
-
-How to run an automated build of Godot
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you just need to run the compilation process via a Batch file or
-directly in the Windows Command Prompt you need to use the
-following command:
-
-::
-
-   "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" x86
-
-with one of the following parameters:
-
-* x86 (32-bit cl.exe to compile for the 32-bit architecture)
-* amd64 (64-bit cl.exe to compile for the 64-bit architecture)
-* x86_amd64 (32-bit cl.exe to compile for the 64-bit architecture)
-* amd64_x86 (64-bit cl.exe to compile for the 32-bit architecture)
-
-and after that one, you can run SCons:
-
-::
-
-   scons platform=windows
-
-or you can run them together:
-
-::
-
-   32-bit Godot
-   "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" x86 && scons platform=windows
-
-   64-bit Godot
-   "C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" amd64 && scons platform=windows
+          If you are compiling Godot with MinGW, you can make the binary
+          even smaller and faster by adding the SCons option ``use_lto=yes``.
+          As link-time optimization is a memory-intensive process,
+          this will require about 3 GB of available RAM while compiling.
 
 Development in Visual Studio or other IDEs
 ------------------------------------------
@@ -331,74 +130,67 @@ in C++ is needed, for creating modules or extending the engine, working
 with an IDE is usually desirable.
 
 You can create a Visual Studio solution via SCons by running SCons with
-the ``vsproj=yes`` parameter, like this:
-
-::
+the ``vsproj=yes`` parameter, like this::
 
    scons p=windows vsproj=yes
 
 You will be able to open Godot's source in a Visual Studio solution now,
-and able to build Godot via the Visual Studio **Build** button. However,
-make sure that you have installed Pywin32 so that parallel (-j) builds
-work properly.
+and able to build Godot using Visual Studio's **Build** button.
 
-If you need to edit the compilation commands, they are located in
+If you need to edit the build commands, they are located in
 "Godot" project settings, NMAKE sheet. SCons is called at the end of
 the commands. If you make a mistake, copy the command from one of the
 other build configurations (debug, release_debug, release) or
-architectures (Win32/x64). They are equivalent.
+architectures (Win32/x64); they are equivalent.
 
 Cross-compiling for Windows from other operating systems
 --------------------------------------------------------
 
-If you are a Linux or macOS user, you need to install `MinGW-w64 <https://mingw-w64.org/doku.php>`_,
-which typically comes in 32-bit and 64-bit variants. The package names
-may differ based on your distro, here are some known ones:
-
-+---------------+--------------------------------------------------------+
-| **Arch**      | ::                                                     |
-|               |                                                        |
-|               |     pacman -S scons mingw-w64-gcc                      |
-+---------------+--------------------------------------------------------+
-| **Debian** /  | ::                                                     |
-| **Ubuntu**    |                                                        |
-|               |     apt-get install scons mingw-w64                    |
-+---------------+--------------------------------------------------------+
-| **Fedora**    | ::                                                     |
-|               |                                                        |
-|               |     dnf install scons mingw32-gcc-c++ mingw64-gcc-c++  |
-+---------------+--------------------------------------------------------+
-| **macOS**     | ::                                                     |
-|               |                                                        |
-|               |     brew install scons mingw-w64                       |
-+---------------+--------------------------------------------------------+
-| **Mageia**    | ::                                                     |
-|               |                                                        |
-|               |     urpmi scons mingw32-gcc-c++ mingw64-gcc-c++        |
-+---------------+--------------------------------------------------------+
-
-Before allowing you to attempt the compilation, SCons will check for
-the following binaries in your ``$PATH``:
-
-::
+If you are a Linux or macOS user, you need to install
+`MinGW-w64 <https://mingw-w64.org/doku.php>`_, which typically comes in 32-bit
+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         |
++---------------+--------------------------------------------------------------+
+
+Before attempting the compilation, SCons will check for
+the following binaries in your ``PATH`` environment variable::
 
     i686-w64-mingw32-gcc
     x86_64-w64-mingw32-gcc
 
-If the binaries are not located in the ``$PATH`` (e.g. ``/usr/bin``),
+If the binaries are not located in the ``PATH`` (e.g. ``/usr/bin``),
 you can define the following environment variables to give a hint to
-the build system:
-
-::
+the build system::
 
     export MINGW32_PREFIX="/path/to/i686-w64-mingw32-"
     export MINGW64_PREFIX="/path/to/x86_64-w64-mingw32-"
 
 To make sure you are doing things correctly, executing the following in
 the shell should result in a working compiler (the version output may
-differ based on your system):
-
-::
+differ based on your system)::
 
     user@host:~$ ${MINGW32_PREFIX}gcc --version
     i686-w64-mingw32-gcc (GCC) 6.1.0 20160427 (Mageia MinGW 6.1.0-1.mga6)
@@ -406,77 +198,55 @@ differ based on your system):
 Troubleshooting
 ~~~~~~~~~~~~~~~
 
-Cross-compiling from some versions of Ubuntu may lead to `this bug <https://github.com/godotengine/godot/issues/9258>`_,
+Cross-compiling from some Ubuntu versions may lead to
+`this bug <https://github.com/godotengine/godot/issues/9258>`_,
 due to a default configuration lacking support for POSIX threading.
 
 You can change that configuration following those instructions,
-for 32-bit:
+for 64-bit::
 
-::
+    sudo update-alternatives --config x86_64-w64-mingw32-gcc
+    <choose x86_64-w64-mingw32-gcc-posix from the list>
+    sudo update-alternatives --config x86_64-w64-mingw32-g++
+    <choose x86_64-w64-mingw32-g++-posix from the list>
+
+And for 32-bit::
 
     sudo update-alternatives --config i686-w64-mingw32-gcc
     <choose i686-w64-mingw32-gcc-posix from the list>
     sudo update-alternatives --config i686-w64-mingw32-g++
     <choose i686-w64-mingw32-g++-posix from the list>
 
-And for 64-bit:
-
-::
-
-    sudo update-alternatives --config x86_64-w64-mingw32-gcc
-    <choose x86_64-w64-mingw32-gcc-posix from the list>
-    sudo update-alternatives --config x86_64-w64-mingw32-g++
-    <choose x86_64-w64-mingw32-g++-posix from the list>
-
 Creating Windows export templates
 ---------------------------------
 
-Windows export templates are created by compiling Godot as release, with
-the following flags:
+Windows export templates are created by compiling Godot without the editor,
+with the following flags::
 
--  (using Mingw32 command prompt, using the bits parameter)
-
-::
-
-    C:\godot> scons platform=windows tools=no target=release bits=32
     C:\godot> scons platform=windows tools=no target=release_debug bits=32
-
--  (using Mingw-w64 command prompt, using the bits parameter)
-
-::
-
-    C:\godot> scons platform=windows tools=no target=release bits=64
+    C:\godot> scons platform=windows tools=no target=release bits=32
     C:\godot> scons platform=windows tools=no target=release_debug bits=64
+    C:\godot> scons platform=windows tools=no target=release bits=64
 
--  (using the Visual Studio command prompts for the correct
-   architecture, notice the lack of bits parameter)
-
-::
-
-    C:\godot> scons platform=windows tools=no target=release
-    C:\godot> scons platform=windows tools=no target=release_debug
-
-If you plan on replacing the standard templates, copy these to:
-
-::
-
-    C:\USERS\YOURUSER\AppData\Roaming\Godot\Templates
+If you plan on replacing the standard export templates, copy these to the
+following location, replacing ``<version>`` with the version identifier
+(such as ``3.1.1.stable`` or ``3.2.dev``)::
 
-With the following names:
+    %USERPROFILE%\AppData\Roaming\Godot\templates\<version>\
 
-::
+With the following names::
 
     windows_32_debug.exe
     windows_32_release.exe
     windows_64_debug.exe
     windows_64_release.exe
 
-However, if you are writing your custom modules or custom C++ code, you
-might instead want to configure your binaries as custom export templates
+However, if you are using custom modules or custom engine code, you
+may instead want to configure your binaries as custom export templates
 here:
 
 .. image:: img/wintemplates.png
 
-You don't even need to copy them, you can just reference the resulting
+You don't need to copy them in this case, just reference the resulting
 files in the ``bin\`` directory of your Godot source folder, so the next
-time you build you automatically have the custom templates referenced.
+time you build, you will automatically have the custom templates referenced.

development/compiling/compiling_for_x11.rst

@@ -12,15 +12,13 @@ For compiling under Linux or other Unix variants, the following is
 required:
 
 -  GCC or Clang
--  Python 2.7+ (Python 3 only supported as of SCons 3.0)
--  SCons build system
+-  Python 3 or 2.7+
+-  SCons build system (3.0 or later for Python 3)
 -  pkg-config (used to detect the dependencies below)
 -  X11, Xcursor, Xinerama, Xi and XRandR development libraries
 -  MesaGL development libraries
 -  ALSA development libraries
--  PulseAudio development libraries (for sound support)
--  Freetype (for the editor)
--  OpenSSL (for HTTPS and TLS)
+-  PulseAudio development libraries
 -  *Optional* - libudev (build with ``udev=yes``)
 -  *Optional* - yasm (for WebM SIMD optimizations)
 
@@ -29,55 +27,52 @@ required:
 
 Distro-specific oneliners
 ^^^^^^^^^^^^^^^^^^^^^^^^^
-+---------------+------------------------------------------------------------------------------------------------------------+
-| **Arch**      | ::                                                                                                         |
-|               |                                                                                                            |
-|               |     pacman -S scons libxcursor libxinerama libxi libxrandr mesa glu alsa-lib pulseaudio freetype2 yasm     |
-+---------------+------------------------------------------------------------------------------------------------------------+
-| **Debian** /  | ::                                                                                                         |
-| **Ubuntu**    |                                                                                                            |
-|               |     sudo apt-get install build-essential scons pkg-config libx11-dev libxcursor-dev libxinerama-dev \      |
-|               |         libgl1-mesa-dev libglu-dev libasound2-dev libpulse-dev libfreetype6-dev libssl-dev libudev-dev \   |
-|               |         libxi-dev libxrandr-dev yasm                                                                       |
-+---------------+------------------------------------------------------------------------------------------------------------+
-| **Fedora**    | ::                                                                                                         |
-|               |                                                                                                            |
-|               |     sudo dnf install scons pkgconfig libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel \     |
-|               |         libXi-devel mesa-libGL-devel alsa-lib-devel pulseaudio-libs-devel freetype-devel openssl-devel \   |
-|               |         libudev-devel mesa-libGLU-devel yasm                                                               |
-+---------------+------------------------------------------------------------------------------------------------------------+
-| **FreeBSD**   | ::                                                                                                         |
-|               |                                                                                                            |
-|               |     sudo pkg install scons pkg-config xorg-libraries libXcursor libXrandr libXi xineramaproto libglapi \   |
-|               |         libGLU freetype2 openssl yasm                                                                      |
-+---------------+------------------------------------------------------------------------------------------------------------+
-| **Gentoo**    | ::                                                                                                         |
-|               |                                                                                                            |
-|               |     emerge -an dev-util/scons x11-libs/libX11 x11-libs/libXcursor x11-libs/libXinerama x11-libs/libXi \    |
-|               |         media-libs/mesa media-libs/glu media-libs/alsa-lib media-sound/pulseaudio media-libs/freetype \    |
-|               |         dev-lang/yasm                                                                                      |
-+---------------+------------------------------------------------------------------------------------------------------------+
-| **Mageia**    | ::                                                                                                         |
-|               |                                                                                                            |
-|               |     urpmi scons task-c++-devel pkgconfig "pkgconfig(alsa)" "pkgconfig(freetype2)" "pkgconfig(glu)" \       |
-|               |         "pkgconfig(libpulse)" "pkgconfig(openssl)" "pkgconfig(udev)" "pkgconfig(x11)" "pkgconfig(xcursor)"\|
-|               |         "pkgconfig(xinerama)" "pkgconfig(xi)" "pkgconfig(xrandr)" "pkgconfig(zlib)" yasm                   |
-+---------------+------------------------------------------------------------------------------------------------------------+
-| **OpenBSD**   | ::                                                                                                         |
-|               |                                                                                                            |
-|               |     pkg_add python scons png llvm yasm                                                                     |
-+---------------+------------------------------------------------------------------------------------------------------------+
-| **openSUSE**  | ::                                                                                                         |
-|               |                                                                                                            |
-|               |     sudo zypper install scons pkgconfig libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel \  |
-|               |             libXi-devel Mesa-libGL-devel alsa-devel libpulse-devel freetype2-devel openssl-devel \         |
-|               |             libudev-devel libGLU1 libpng-devel yasm                                                        |
-+---------------+------------------------------------------------------------------------------------------------------------+
-| **Solus**     | ::                                                                                                         |
-|               |                                                                                                            |
-|               |     sudo eopkg install -c system.devel scons libxcursor-devel libxinerama-devel libxi-devel \              |
-|               |         libxrandr-devel mesalib-devel libglu alsa-lib pulseaudio freetype2-devel pulseaudio-devel yasm     |
-+---------------+------------------------------------------------------------------------------------------------------------+
++----------------+-----------------------------------------------------------------------------------------------------------+
+| **Arch Linux** | ::                                                                                                        |
+|                |                                                                                                           |
+|                |     pacman -S scons pkgconf gcc libxcursor libxinerama libxi libxrandr mesa glu alsa-lib pulseaudio yasm  |
++----------------+-----------------------------------------------------------------------------------------------------------+
+| **Debian** /   | ::                                                                                                        |
+| **Ubuntu**     |                                                                                                           |
+|                |     sudo apt-get install build-essential scons pkg-config libx11-dev libxcursor-dev libxinerama-dev \     |
+|                |         libgl1-mesa-dev libglu-dev libasound2-dev libpulse-dev libudev-dev libxi-dev libxrandr-dev yasm   |
++----------------+-----------------------------------------------------------------------------------------------------------+
+| **Fedora**     | ::                                                                                                        |
+|                |                                                                                                           |
+|                |     sudo dnf install scons pkgconfig libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel \    |
+|                |         libXi-devel mesa-libGL-devel mesa-libGLU-devel alsa-lib-devel pulseaudio-libs-devel \             |
+|                |         libudev-devel yasm                                                                                |
++----------------+-----------------------------------------------------------------------------------------------------------+
+| **FreeBSD**    | ::                                                                                                        |
+|                |                                                                                                           |
+|                |     sudo pkg install scons pkgconf xorg-libraries libXcursor libXrandr libXi xineramaproto libglapi \     |
+|                |         libGLU yasm                                                                                       |
++----------------+-----------------------------------------------------------------------------------------------------------+
+| **Gentoo**     | ::                                                                                                        |
+|                |                                                                                                           |
+|                |     emerge -an dev-util/scons x11-libs/libX11 x11-libs/libXcursor x11-libs/libXinerama x11-libs/libXi \   |
+|                |         media-libs/mesa media-libs/glu media-libs/alsa-lib media-sound/pulseaudio dev-lang/yasm           |
++----------------+-----------------------------------------------------------------------------------------------------------+
+| **Mageia**     | ::                                                                                                        |
+|                |                                                                                                           |
+|                |     urpmi scons task-c++-devel pkgconfig "pkgconfig(alsa)" "pkgconfig(glu)" "pkgconfig(libpulse)" \       |
+|                |         "pkgconfig(udev)" "pkgconfig(x11)" "pkgconfig(xcursor)" "pkgconfig(xinerama)" "pkgconfig(xi)" \   |
+|                |         "pkgconfig(xrandr)" yasm                                                                          |
++----------------+-----------------------------------------------------------------------------------------------------------+
+| **OpenBSD**    | ::                                                                                                        |
+|                |                                                                                                           |
+|                |     pkg_add python scons llvm yasm                                                                        |
++----------------+-----------------------------------------------------------------------------------------------------------+
+| **openSUSE**   | ::                                                                                                        |
+|                |                                                                                                           |
+|                |     sudo zypper install scons pkgconfig libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel \ |
+|                |             libXi-devel Mesa-libGL-devel alsa-devel libpulse-devel libudev-devel libGLU1 yasm             |
++----------------+-----------------------------------------------------------------------------------------------------------+
+| **Solus**      | ::                                                                                                        |
+|                |                                                                                                           |
+|                |     sudo eopkg install -c system.devel scons libxcursor-devel libxinerama-devel libxi-devel \             |
+|                |         libxrandr-devel mesalib-devel libglu alsa-lib pulseaudio pulseaudio-devel yasm                    |
++----------------+-----------------------------------------------------------------------------------------------------------+
 
 Compiling
 ---------
@@ -115,6 +110,14 @@ manager.
 Building export templates
 -------------------------
 
+.. warning:: Linux binaries usually won't run on distributions that are
+             older than the distribution they were built on. If you wish to
+             distribute binaries that work on most distributions,
+             you should build them on an old distribution such as Ubuntu 16.04.
+             You can use a virtual machine or a container to set up a suitable
+             build environment.
+
+
 To build X11 (Linux, \*BSD) export templates, run the build system with the
 following parameters:
 
@@ -132,14 +135,14 @@ following parameters:
     user@host:~/godot$ scons platform=x11 tools=no target=release bits=64
     user@host:~/godot$ scons platform=x11 tools=no target=release_debug bits=64
 
-Note that cross compiling for the opposite bits (64/32) as your host
+Note that cross-compiling for the opposite bits (64/32) as your host
 platform is not always straight-forward and might need a chroot environment.
 
 To create standard export templates, the resulting files must be copied to:
 
 ::
 
-    /home/[username]/.local/share/godot/templates/[gd-version]/
+    $HOME/.local/share/godot/templates/[gd-version]/
 
 and named like this (even for \*BSD which is seen as "Linux X11" by Godot):
 
@@ -157,5 +160,5 @@ here:
 .. image:: img/lintemplates.png
 
 You don't even need to copy them, you can just reference the resulting
-files in the bin/ directory of your Godot source folder, so the next
-time you build you automatically have the custom templates referenced.
+files in the ``bin/`` directory of your Godot source folder, so the next
+time you build, you automatically have the custom templates referenced.

development/compiling/compiling_with_mono.rst

@@ -12,9 +12,9 @@ Requirements
 - MSBuild
 - NuGet
 - pkg-config
-- NuGet
 
-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):
 
 ::
 
@@ -23,25 +23,32 @@ You may need to import necessary certificates for NuGet to perform HTTPS request
 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 ``bits`` option: ``MONO32_PREFIX`` and ``MONO64_PREFIX``.
+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``.
 
 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 for builds. To enable it you can pass the
+option ``module_mono_enabled=yes`` to your SCons command.
 
 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``:
+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``:
 
 ::
 
     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.
 
 ::
 
@@ -51,19 +58,26 @@ This command will tell Godot to generate the file ``modules/mono/glue/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 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.
+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.
 
 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 bindings changes. That is, for example, when a new method is added to ClassDB 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 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.
+
 
 Rebuild with Mono glue
 ----------------------
 
 Once you have generated the Mono glue, you can build the final binary with ``mono_glue=yes``.
-It's the default value for ``mono_glue`` so you can also omit it. You can build the Mono-enabled editor:
+This is the default value for ``mono_glue`` so you can also omit it. You can build the Mono-enabled editor:
 
 ::
 
@@ -77,8 +91,12 @@ And Mono-enabled export templates:
 
 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 next to the Godot binary.
-- Unlike "classical" Godot builds, when building with the mono module enabled a data directory will 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 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>`.
+
 
 Examples
 --------
@@ -120,18 +138,22 @@ 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 next to the Godot executable.
+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.
 
 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 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``.
 
-In the case of export templates the data directory only contains Mono framework assemblies and configuration files, as well as some shared library dependencies like ``MonoPosixHelper``.
+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 file, the
+contents of the data directory can be placed in the following locations inside the zip:
 
 +-------------------------------------------------------+---------------------------------------------------------------+
 | ``bin/data.mono.<platform>.<bits>.<target>/Mono/lib`` | ``/osx_template.app/Contents/Frameworks/GodotSharp/Mono/lib`` |
@@ -140,9 +162,10 @@ In the case of macOS, where the export template is compressed as a zip file, the
 +-------------------------------------------------------+---------------------------------------------------------------+
 
 Editor
-^^^^^^^^
+^^^^^^
 
-The name of the data directory for the Godot editor will always be ``GodotSharp``. The main structure of this directory has the following subdirectories:
+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)
@@ -188,6 +211,7 @@ The following is an example script for building and copying the Godot API assemb
 The script assumes it's being executed from the directory where SConstruct is located.
 ``<godot_binary>`` refers to the tools binary compiled with the Mono module enabled.
 
+The ``Api`` subdirectory contains the Godot API assemblies.
 In the case of macOS, if the Godot editor is distributed as a bundle, the contents of the data directory may be placed in the following locations:
 
 +-------------------------------------------------------+---------------------------------------------------------------+
@@ -200,6 +224,12 @@ In the case of macOS, if the Godot editor is distributed as a bundle, the conten
 | ``bin/data.mono.<platform>.<bits>.<target>/Tools``    | ``<bundle_name>.app/Contents/Frameworks/GodotSharp/Tools``    |
 +-------------------------------------------------------+---------------------------------------------------------------+
 
+The ``Mono`` subdirectory is optional but will be needed when distributing the editor, as some issues might arise
+when the installed Mono version in the user's system is not be the same as the one the Godot editor was built with.
+Pass ``copy_mono_root=yes`` to SCons when building the editor in order to create this folder and its contents.
+
+The ``Tools`` subdirectory contains tools required by the editor, like the ``GodotTools`` assemblies and its dependencies.
+
 Command-line options
 --------------------
 

development/compiling/compiling_with_script_encryption_key.rst

@@ -1,10 +1,10 @@
 .. _doc_compiling_with_script_encryption_key:
 
-.. highlight:: shell
-
 Compiling with script encryption key
 ====================================
 
+.. highlight:: shell
+
 The export dialog gives you the option to encrypt your scripts with an 256bit
 AES key, when releasing your game. This will make sure your scripts are not
 stored in plain text and can not easily be ripped by some script kiddie.

development/cpp/binding_to_external_libraries.rst

@@ -22,10 +22,11 @@ Next, you will create a header file with a simple TTS class:
 .. code:: cpp
 
     /* tts.h */
+
     #ifndef GODOT_TTS_H
     #define GODOT_TTS_H
 
-    #include <reference.h>
+    #include "core/reference.h"
 
     class TTS : public Reference {
         GDCLASS(TTS, Reference);
@@ -34,7 +35,7 @@ Next, you will create a header file with a simple TTS class:
         static void _bind_methods();
 
     public:
-        bool say_text(String txt);
+        bool say_text(String p_txt);
 
         TTS();
     };
@@ -48,12 +49,13 @@ And then you'll add the cpp file.
     /* tts.cpp */
 
     #include "tts.h"
-    #include "festival/src/include/festival.h"
 
-    bool TTS::say_text(String txt) {
+    #include <festival.h>
+
+    bool TTS::say_text(String p_txt) {
 
         //convert Godot String to Godot CharString to C string
-        return festival_say_text(txt.ascii().get_data());
+        return festival_say_text(p_txt.ascii().get_data());
     }
 
     void TTS::_bind_methods() {
@@ -89,8 +91,7 @@ With the following contents:
 
     #include "register_types.h"
 
-    #include "class_db.h"
-
+    #include "core/class_db.h"
     #include "tts.h"
 
     void register_tts_types() {
@@ -98,7 +99,7 @@ With the following contents:
     }
 
     void unregister_tts_types() {
-       //nothing to do here
+        // Nothing to do here in this example.
     }
 
 Next, you need to create a ``SCsub`` file so the build system compiles
@@ -107,10 +108,11 @@ this module:
 .. code:: python
 
     # SCsub
+
     Import('env')
 
-    env_tts = env
-    env_tts.add_source_files(env.modules_sources,"*.cpp") # Add all cpp files to the build
+    env_tts = env.Clone()
+    env_tts.add_source_files(env.modules_sources, "*.cpp") # Add all cpp files to the build
 
 You'll need to install the external library on your machine to get the .a library files.  See the library's official
 documentation for specific instructions on how to do this for your operation system.  We've included the
@@ -157,7 +159,7 @@ environment's paths:
 
 .. code:: python
 
-    env_tts.Append(CPPPATH="speech_tools/include", "festival/src/include") # this is a path relative to /modules/tts/
+    env_tts.Append(CPPPATH=["speech_tools/include", "festival/src/include"]) # this is a path relative to /modules/tts/
     # http://www.cstr.ed.ac.uk/projects/festival/manual/festival_28.html#SEC132 <-- Festival library documentation
     env_tts.Append(LIBPATH=['libpath']) # this is a path relative to /modules/tts/ where your .a library files reside
     # You should check with the documentation of the external library to see which library files should be included/linked
@@ -170,11 +172,13 @@ Example `SCsub` with custom flags:
 .. code:: python
 
     # SCsub
+
     Import('env')
 
-    env_tts = env
-    env_tts.add_source_files(env.modules_sources,"*.cpp")
-    env_tts.Append(CXXFLAGS=['-O2', '-std=c++11'])
+    env_tts = env.Clone()
+    env_tts.add_source_files(env.modules_sources, "*.cpp")
+    env_tts.Append(CCFLAGS=['-O2']) # Flags for C and C++ code
+    env_tts.Append(CXXFLAGS=['-std=c++11']) # Flags for C++ code only
 
 The final module should look like this:
 
@@ -201,7 +205,7 @@ You can now use your newly created module from any script:
 ::
 
     var t = TTS.new()
-    var script = "Hello world.  This is a test!"
+    var script = "Hello world. This is a test!"
     var is_spoken = t.say_text(script)
     print('is_spoken: ', is_spoken)
 

development/cpp/custom_modules_in_cpp.rst

@@ -57,6 +57,7 @@ Inside we will create a simple summator class:
 .. code:: cpp
 
     /* summator.h */
+
     #ifndef SUMMATOR_H
     #define SUMMATOR_H
 
@@ -71,14 +72,14 @@ Inside we will create a simple summator class:
         static void _bind_methods();
 
     public:
-        void add(int value);
+        void add(int p_value);
         void reset();
         int get_total() const;
 
         Summator();
     };
 
-    #endif
+    #endif // SUMMATOR_H
 
 And then the cpp file.
 
@@ -88,23 +89,19 @@ And then the cpp file.
 
     #include "summator.h"
 
-    void Summator::add(int value) {
-
-        count += value;
+    void Summator::add(int p_value) {
+        count += p_value;
     }
 
     void Summator::reset() {
-
         count = 0;
     }
 
     int Summator::get_total() const {
-
         return count;
     }
 
     void Summator::_bind_methods() {
-
         ClassDB::bind_method(D_METHOD("add", "value"), &Summator::add);
         ClassDB::bind_method(D_METHOD("reset"), &Summator::reset);
         ClassDB::bind_method(D_METHOD("get_total"), &Summator::get_total);
@@ -142,12 +139,11 @@ With the following contents:
     #include "summator.h"
 
     void register_summator_types() {
-
-            ClassDB::register_class<Summator>();
+        ClassDB::register_class<Summator>();
     }
 
     void unregister_summator_types() {
-       //nothing to do here
+       // Nothing to do here in this example.
     }
 
 Next, we need to create a ``SCsub`` file so the build system compiles
@@ -156,9 +152,10 @@ this module:
 .. code:: python
 
     # SCsub
+
     Import('env')
 
-    env.add_source_files(env.modules_sources,"*.cpp") # Add all cpp files to the build
+    env.add_source_files(env.modules_sources, "*.cpp") # Add all cpp files to the build
 
 With multiple sources, you can also add each file individually to a Python
 string list:
@@ -177,8 +174,8 @@ environment's paths:
 
 .. code:: python
 
-    env.Append(CPPPATH="mylib/include") # this is a relative path
-    env.Append(CPPPATH="#myotherlib/include") # this is an 'absolute' path
+    env.Append(CPPPATH=["mylib/include"]) # this is a relative path
+    env.Append(CPPPATH=["#myotherlib/include"]) # this is an 'absolute' path
 
 If you want to add custom compiler flags when building your module, you need to clone
 `env` first, so it won't add those flags to whole Godot build (which can cause errors).
@@ -187,11 +184,13 @@ Example `SCsub` with custom flags:
 .. code:: python
 
     # SCsub
+
     Import('env')
 
     module_env = env.Clone()
-    module_env.add_source_files(env.modules_sources,"*.cpp")
-    module_env.Append(CXXFLAGS=['-O2', '-std=c++11'])
+    module_env.add_source_files(env.modules_sources, "*.cpp")
+    module_env.Append(CCFLAGS=['-O2']) # Flags for C and C++ code
+    module_env.Append(CXXFLAGS=['-std=c++11']) # Flags for C++ code only
 
 And finally, the configuration file for the module, this is a simple
 python script that must be named ``config.py``:
@@ -206,8 +205,8 @@ python script that must be named ``config.py``:
     def configure(env):
         pass
 
-The module is asked if it's ok to build for the specific platform (in
-this case, True means it will build for every platform).
+The module is asked if it's OK to build for the specific platform (in
+this case, ``True`` means it will build for every platform).
 
 And that's it. Hope it was not too complex! Your module should look like
 this:
@@ -266,6 +265,7 @@ library that will be dynamically loaded when starting our game's binary.
 .. code:: python
 
     # SCsub
+
     Import('env')
 
     sources = [
@@ -275,7 +275,7 @@ library that will be dynamically loaded when starting our game's binary.
 
     # First, create a custom env for the shared library.
     module_env = env.Clone()
-    module_env.Append(CXXFLAGS='-fPIC')  # Needed to compile shared library
+    module_env.Append(CCFLAGS=['-fPIC'])  # Needed to compile shared library
     # We don't want godot's dependencies to be injected into our shared library.
     module_env['LIBS'] = []
 
@@ -313,6 +313,7 @@ using the `ARGUMENT` command:
 .. code:: python
 
     # SCsub
+
     Import('env')
 
     sources = [
@@ -321,11 +322,12 @@ using the `ARGUMENT` command:
     ]
 
     module_env = env.Clone()
-    module_env.Append(CXXFLAGS=['-O2', '-std=c++11'])
+    module_env.Append(CCFLAGS=['-O2'])
+    module_env.Append(CXXFLAGS=['-std=c++11'])
 
     if ARGUMENTS.get('summator_shared', 'no') == 'yes':
         # Shared lib compilation
-        module_env.Append(CXXFLAGS='-fPIC')
+        module_env.Append(CCFLAGS=['-fPIC'])
         module_env['LIBS'] = []
         shared_lib = module_env.SharedLibrary(target='#bin/summator', source=sources)
         shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0]
@@ -335,7 +337,7 @@ using the `ARGUMENT` command:
         # Static compilation
         module_env.add_source_files(env.modules_sources, sources)
 
-Now by default ``scons`` command will build our module as part of godot's binary
+Now by default ``scons`` command will build our module as part of Godot's binary
 and as a shared library when passing ``summator_shared=yes``.
 
 Finally you can even speedup build further by explicitly specifying your

development/file_formats/tscn.rst

@@ -1,24 +1,24 @@
 TSCN file format
 ================
 
-A :code:`.tscn` File format is the "Text SCeNe" file format and represents
-a single scene-tree inside Godot. TSCN files have the advantage of being
-nearly human-readable and easy for version control systems to manage. During
-import the TSCN files are compiled into binary :code:`.scn` files stored
-inside the .import folder. This reduces the data size and speed up loading.
+The TSCN (text scene) file format represents a single scene tree inside
+Godot. TSCN files have the advantage of being mostly human-readable and easy for
+version control systems to manage. During import, TSCN files are compiled into
+binary ``.scn`` files stored inside the .import folder. This reduces the data
+size and speeds up loading.
 
-The :code:`.escn` file format is identical to the TSCN file format, but is used to
-indicate to Godot that the file has been exported from another program and
-should not be edited by the user from within Godot.
+The ESCN (exported scene) file format is identical to the TSCN file format, but
+is used to indicate to Godot that the file has been exported from another
+program and should not be edited by the user from within Godot.
 
-For those looking for a complete description, the parsing is handled in the
-file `resource_format_text.cpp <https://github.com/godotengine/godot/blob/master/scene/resources/resource_format_text.cpp>`_
-in the class :code:`ResourceFormatLoaderText`
+For those looking for a complete description, the parsing is handled in the file
+`resource_format_text.cpp <https://github.com/godotengine/godot/blob/master/scene/resources/resource_format_text.cpp>`_
+in the ``ResourceFormatLoaderText`` class.
 
 File structure
 --------------
 
-There are five main sections inside the TSCN File:
+There are five main sections inside the TSCN file:
 
 0. File Descriptor
 1. External resources
@@ -26,31 +26,33 @@ There are five main sections inside the TSCN File:
 3. Nodes
 4. Connections
 
-The file descriptor looks like :code:`[gd_scene load_steps=1 format=2]` And
-should be the first entry in the file. The load_steps parameter should (in
-theory) be the number of resources within the file, though in practice its
-value seems not to matter.
+The file descriptor looks like ``[gd_scene load_steps=1 format=2]`` and should
+be the first entry in the file. The ``load_steps`` parameter should (in theory)
+be the number of resources within the file. However, in practice, its value seems
+not to matter.
 
-These sections should appear in order, but it can be hard to distinguish
-them. The only difference between them is the first element in the heading
-for all of the items in the section.
-For example, the heading of all external resources should start with
-:code:`[ext_resource .....]`
+These sections should appear in order, but it can be hard to distinguish them.
+The only difference between them is the first element in the heading for all of
+the items in the section. For example, the heading of all external resources
+should start with ``[ext_resource .....]``.
+
+A TSCN file may contain single-line comments starting with a semicolon (``;``).
+However, comments will be discarded when saving the file using the Godot editor.
 
 Entries inside the file
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-A heading looks like:
-:code:`[<resource_type> key=value key=value key=value ...]`
-Where resource_type is one of:
+A heading looks like
+``[<resource_type> key=value key=value key=value ...]``
+where resource_type is one of:
 
-- ext_resource
-- sub_resource
-- node
-- connection
+- ``ext_resource``
+- ``sub_resource``
+- ``node``
+- ``connection``
 
-Underneath every heading comes zero or more :code:`key = value` pairs. The
-values can be complex datatypes such as arrays, transformations, colors, and
+Below every heading comes zero or more ``key = value`` pairs. The
+values can be complex datatypes such as Arrays, Transforms, Colors, and
 so on. For example, a spatial node looks like:
 
 ::
@@ -58,27 +60,29 @@ so on. For example, a spatial node looks like:
     [node name="Cube" type="Spatial" parent="."]
     transform=Transform( 1.0, 0.0, 0.0 ,0.0, 1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0 )
 
+
 The scene tree
 --------------
 
-The scene tree is made up of... nodes! The heading of each node consists of
+The scene tree is made up of… nodes! The heading of each node consists of
 its name, parent and (most of the time) a type. For example
-:code:`[node type="Camera" name="PlayerCamera" parent="Player/Head"]`
+``[node type="Camera" name="PlayerCamera" parent="Player/Head"]``
 
 Other valid keywords include:
 
- - instance
- - instance_placeholder
- - owner
- - index (if two nodes have the same name)
- - groups
+ - ``instance``
+ - ``instance_placeholder``
+ - ``owner``
+ - ``index`` (if two nodes have the same name)
+ - ``groups``
 
-The first node in the file should not have the :code:`parent=Path/To/Node`
-entry in it's heading, and it is the scene root. All scene files should have
-exactly one scene root. It it does not, Godot will fail to import the file.
-The parent path of other nodes should be absolute, but without the scene
-root's name. If it is a direct child of the scene root, it should be
-:code:`"."`. Here is an example scene tree (but without any node content).
+The first node in the file, which is also the scene root, must not have a
+``parent=Path/To/Node`` entry in its heading. All scene files should have
+exactly *one* scene root. If it doesn't, Godot will fail to import the file.
+The parent path of other nodes should be absolute, but shouldn't contain
+the scene root's name. If the node is a direct child of the scene root,
+the path should be ``"."``. Here is an example scene tree
+(but without any node content):
 
 ::
 
@@ -87,25 +91,26 @@ root's name. If it is a direct child of the scene root, it should be
     [node name="Hand" parent="Arm" type="Spatial"]
     [node name="Finger" parent="Arm/Hand" type="Spatial"]
 
+
 Similar to the internal resource, the document for each node is currently
-incomplete. Fortunately it is easy to find out because you can simply
+incomplete. Fortunately, it is easy to find out because you can simply
 save a file with that node in it. Some example nodes are:
 
 ::
 
-    [node  type="CollisionShape" name="SphereCollision" parent="SpherePhysics"]
+    [node type="CollisionShape" name="SphereCollision" parent="SpherePhysics"]
 
     shape = SubResource(8)
     transform = Transform( 1.0 , 0.0 , -0.0 , 0.0 , -4.371138828673793e-08 , 1.0 , -0.0 , -1.0 , -4.371138828673793e-08 ,0.0 ,0.0 ,-0.0  )
 
 
-    [node  type="MeshInstance" name="Sphere" parent="SpherePhysics"]
+    [node type="MeshInstance" name="Sphere" parent="SpherePhysics"]
 
     mesh = SubResource(9)
     transform = Transform( 1.0 , 0.0 , -0.0 , 0.0 , 1.0 , -0.0 , -0.0 , -0.0 , 1.0 ,0.0 ,0.0 ,-0.0  )
 
 
-    [node  type="OmniLight" name="Lamp" parent="."]
+    [node type="OmniLight" name="Lamp" parent="."]
 
     light_energy = 1.0
     light_specular = 1.0
@@ -116,7 +121,7 @@ save a file with that node in it. Some example nodes are:
     light_color = Color( 1.0, 1.0, 1.0, 1.0 )
 
 
-    [node  type="Camera" name="Camera" parent="."]
+    [node type="Camera" name="Camera" parent="."]
 
     projection = 0
     near = 0.10000000149011612
@@ -124,14 +129,15 @@ save a file with that node in it. Some example nodes are:
     transform = Transform( 0.6859206557273865 , -0.32401350140571594 , 0.6515582203865051 , 0.0 , 0.8953956365585327 , 0.44527143239974976 , -0.7276763319969177 , -0.3054208755493164 , 0.6141703724861145 ,14.430776596069336 ,10.093015670776367 ,13.058500289916992  )
     far = 100.0
 
+
 NodePath
 ~~~~~~~~
 
-A tree structure is not enough to represent the whole scene, Godot use
-a :code:`NodePath(Path/To/Node)` structure to refer to another node or
-attribute of the node anywhere in the scene tree. Some typical usages of
-NodePath like mesh node use :code:`NodePath()` to point to its skeleton,
-animation track use :code:`NodePath()` points to animated attribute in node.
+A tree structure is not enough to represent the whole scene. Godot uses a
+``NodePath(Path/To/Node)`` structure to refer to another node or attribute of
+the node anywhere in the scene tree. For instance, MeshInstance uses
+``NodePath()`` to point to its skeleton. Likewise, Animation tracks use
+``NodePath()`` to point to node properties to animate.
 
 ::
 
@@ -140,6 +146,7 @@ animation track use :code:`NodePath()` points to animated attribute in node.
     mesh = SubResource(1)
     skeleton = NodePath("..:")
 
+
 ::
 
     [sub_resource id=3 type="Animation"]
@@ -149,33 +156,30 @@ animation track use :code:`NodePath()` points to animated attribute in node.
     tracks/0/path = NodePath("Cube:")
     ...
 
+
 Skeleton
 ~~~~~~~~
 
-Skeleton node inherits Spatial node, besides that it may have a list
-of bones described in key, value pair in the format :code:`bones/Id/Attribute=Value`,
-attributes of bone consists of
-
-- name
-- parent
-- rest
-- pose
-- enabled
-- bound_children
-
-1) :code:`name` must put as the first attribute of each bone
-
-2) :code:`parent` is the index of parent bone in the bone list, with parent index,
-   the bone list is built to a bone tree
-
-3) :code:`rest` is the transform matrix of bone in rest position
+The Skeleton node inherits the Spatial node, but also may have a list of bones
+described in key-value pairs in the format ``bones/Id/Attribute=Value``. The
+bone attributes consist of:
 
-4) :code:`pose` is the pose matrix use :code:`rest` as basis
+- ``name``
+- ``parent``
+- ``rest``
+- ``pose``
+- ``enabled``
+- ``bound_children``
 
-5) :code:`bound_children` is a list of NodePath() points to
-   BoneAttachments belong to this bone
+1. ``name`` must be the first attribute of each bone.
+2. ``parent`` is the index of parent bone in the bone list, with parent index,
+   the bone list is built to a bone tree.
+3. ``rest`` is the transform matrix of bone in its "resting" position.
+4. ``pose`` is the pose matrix; use ``rest`` as the basis.
+5. ``bound_children`` is a list of ``NodePath()`` which point to
+   BoneAttachments belonging to this bone.
 
-An example of a skeleton node with two bones:
+Here's an example of a skeleton node with two bones:
 
 ::
 
@@ -194,13 +198,14 @@ An example of a skeleton node with two bones:
     bones/1/enabled = true
     bones/1/bound_children = [  ]
 
+
 BoneAttachment
 ~~~~~~~~~~~~~~
 
 BoneAttachment node is an intermediate node to describe some node being parented
-to a single bone in Skeleton node. The BoneAttachment has a :code:`bone_name=NameOfBone`,
-and the corresponding bone being the parent has the BoneAttachment node
-in its :code:`bound_children` list.
+to a single bone in a Skeleton node. The BoneAttachment has a
+``bone_name=NameOfBone`` attribute, and the corresponding bone being the parent has the
+BoneAttachment node in its ``bound_children`` list.
 
 An example of one MeshInstance parented to a bone in Skeleton:
 
@@ -225,13 +230,15 @@ An example of one MeshInstance parented to a bone in Skeleton:
     mesh = SubResource(1)
     transform = Transform(1.0, 0.0, 0.0, 0.0, 1.86265e-09, 1.0, 0.0, -1.0, 0.0, 0.0219986, -0.0343127, 2.25595)
 
+
 AnimationPlayer
 ~~~~~~~~~~~~~~~
 
-AnimationPlayer works as an animation lib. it has animations listed in the format
-:code:`anim/Name=SubResource(ResourceId)`, each refers to a Animation
-internal resource. All the animation resources use the root node of AnimationPlayer.
-The root node is stored as :code:`root_node=NodePath(Path/To/Node)`.
+AnimationPlayer works as an animation library. It stores animations listed in
+the format ``anim/Name=SubResource(ResourceId)``; each line refers to an
+Animation resource. All the animation resources use the root node of
+AnimationPlayer. The root node is stored as
+``root_node=NodePath(Path/To/Node)``.
 
 ::
 
@@ -245,6 +252,7 @@ The root node is stored as :code:`root_node=NodePath(Path/To/Node)`.
     anims/default = SubResource( 2 )
     blend_times = [  ]
 
+
 Resources
 ---------
 
@@ -252,29 +260,24 @@ Resources are components that make up the nodes. For example, a MeshInstance
 node will have an accompanying ArrayMesh resource. The ArrayMesh resource
 may be either internal or external to the TSCN file.
 
-References to the resources are handled by id numbers in the resources heading.
-External resources and internal resource are referred to with
-:code:`ExtResource(id)` and :code:`SubResource(id)`. Because there have
-different methods to refer to internal and external resource, you can have
+References to the resources are handled by ``id`` numbers in the resource's
+heading. External resources and internal resources are referred to with
+``ExtResource(id)`` and ``SubResource(id)``, respectively. Because there
+have different methods to refer to internal and external resources, you can have
 the same ID for both an internal and external resource.
 
-For example, to refer to the resource
-:code:`[ext_resource id=3 type="PackedScene" path=....]` you would use
-:code:`ExtResource(3)`
+For example, to refer to the resource ``[ext_resource id=3 type="PackedScene"
+path=....]``, you would use ``ExtResource(3)``.
 
 External resources
 ~~~~~~~~~~~~~~~~~~
 
 External resources are links to resources not contained within the TSCN file
-itself. An external resource consists of:
-
- - A path
- - A type
- - An ID
+itself. An external resource consists of a path, a type and an ID.
 
 Godot always generates absolute paths relative to the resource directory and
-thus prefixed with :code:`res://`, but paths relative to the TSCN file's
-location are also valid.
+thus prefixed with ``res://``, but paths relative to the TSCN file's location
+are also valid.
 
 Some example external resources are:
 
@@ -283,14 +286,19 @@ Some example external resources are:
     [ext_resource path="res://characters/player.dae" type="PackedScene" id=1]
     [ext_resource path="metal.tres" type="Material" id=2]
 
+
+Like TSCN files, a TRES file may contain single-line comments starting with a
+semicolon (``;``). However, comments will be discarded when saving the resource
+using the Godot editor.
+
 Internal resources
 ~~~~~~~~~~~~~~~~~~
 
-A TSCN file can contain meshes, materials and other data, and these are
-contained in the internal resources section of the file. The heading
-for an internal resource looks similar to those of external resources, but
-does not have a path. Internal resources also have :code:`key=value` pairs
-under each heading. For example, a capsule collision shape looks like:
+A TSCN file can contain meshes, materials and other data. These are contained in
+the *internal resources* section of the file. The heading for an internal
+resource looks similar to those of external resources, except that it doesn't
+have a path. Internal resources also have ``key=value`` pairs under each
+heading. For example, a capsule collision shape looks like:
 
 ::
 
@@ -299,45 +307,46 @@ under each heading. For example, a capsule collision shape looks like:
     radius = 0.5
     height = 3.0
 
-Some internal resource contain links to other internal resources (such as a
+
+Some internal resources contain links to other internal resources (such as a
 mesh having a material). In this case, the referring resource must appear
-before the reference to it. Thus, in the internal resources section of the
-file, order does matter.
+*before* the reference to it. This means that order matters in the file's
+internal resources section.
 
-Unfortunately, documentation on the formats for these subresources is not
-complete, and while some can be found through inspecting resources of
-saved files, others can only be found by looking through Godot's source.
+Unfortunately, documentation on the formats for these subresources isn't
+complete. Some examples can be found by inspecting saved resource files, but
+others can only be found by looking through Godot's source.
 
 ArrayMesh
 ~~~~~~~~~
 
-ArrayMesh consists of several surfaces, each in the format :code:`surface\Index={}`,
-each surface is a set of vertex and a material.
+ArrayMesh consists of several surfaces, each in the format ``surface\Index={}``.
+Each surface is a set of vertices and a material.
 
-TSCN support two format of surface,
+TSCN files support two surface formats:
 
-1) for the old format, each surface has three essential keys:
+1. For the old format, each surface has three essential keys:
 
-- primitive
-- arrays
-- morph_arrays
+- ``primitive``
+- ``arrays``
+- ``morph_arrays``
 
-    i) :code:`primitive` is an enumerate variable, :code:`primitive=4` which is
-       PRIMITIVE_TRIANGLES is frequently used.
+    i. ``primitive`` is an enumerate variable, ``primitive=4`` which is
+       ``PRIMITIVE_TRIANGLES`` is frequently used.
 
-    ii) :code:`arrays` as the name suggests is an array of array, it contains:
+    ii. ``arrays`` is a two-dimensional array, it contains:
 
-        1) An array of vertex position
-        2) Tangents array
-        3) Vertex color array
-        4) UV array 1
-        5) UV array 2
-        6) Bone index array
-        7) Bone weight array
-        8) Vertex index array
+        1. Vertex positions array
+        2. Tangents array
+        3. Vertex colors array
+        4. UV array 1
+        5. UV array 2
+        6. Bone indexes array
+        7. Bone weights array
+        8. Vertex indexes array
 
-    iii) :code:`morph_arrays` is an array of morph, each morph is exactly an
-         :code:`arrays` without vertex index array.
+    iii. ``morph_arrays`` is an array of morphs. Each morph is exactly an
+         ``arrays`` without the vertex indexes array.
 
 An example of ArrayMesh:
 
@@ -361,54 +370,52 @@ An example of ArrayMesh:
         "morph_arrays":[]
     }
 
+
 Animation
 ~~~~~~~~~
 
-An animation resource consists of tracks. Besides, it has 'length', 'loop' and
-'step' applied to all the tracks.
-
-- length
-- loop
-- step
+An animation resource consists of tracks. Besides, it has ``length``, ``loop``
+and ``step`` applied to all the tracks.
 
-1) :code:`length` and :code:`step` are both time in seconds
+1. ``length`` and ``step`` are both durations in seconds.
 
-Each track is described by a list of (key, value) pairs in the format :code:`tracks/Id/Attribute`,
-it includes:
+Each track is described by a list of key-value pairs in the format
+``tracks/Id/Attribute``. Each track includes:
 
-- type
-- path
-- interp
-- keys
-- loop_wrap
-- imported
-- enabled
+- ``type``
+- ``path``
+- ``interp``
+- ``keys``
+- ``loop_wrap``
+- ``imported``
+- ``enabled``
 
-1) The :code:`type` must be put as the first attribute of each track.
-   The value of :code:`type` can be:
+1. The ``type`` must be the first attribute of each track.
+   The value of ``type`` can be:
 
-    - 'transform'
-    - 'value'
-    - 'method'
+    - ``transform``
+    - ``value``
+    - ``method``
 
-2) The :code:`path` has the format :code:`NodePath(Path/To/Node:Attribute)`.
-   It is the path from animation root node (property of AnimationPlayer) to the
-   animated node or attribute.
+2. The ``path`` has the format ``NodePath(Path/To/Node:attribute)``.
+   It's the path to the animated node or attribute, relative to the root node
+   defined in the AnimationPlayer.
 
-3) The :code:`interp` is the method to interpolate frames from the keyframes.
+3. The ``interp`` is the method to interpolate frames from the keyframes.
    it is a enum variable and can has value:
 
     - 0 (constant)
     - 1 (linear)
     - 2 (cubic)
 
-4) The :code:`keys` is the keyframes, it appears as a PoolRealArray()
-   but have different structure for track with different type
+4. The ``keys`` correspond to the keyframes. It appears as a ``PoolRealArray()``,
+   but may have a different structure for tracks with different types.
 
-    - A transform track use every 12 real number in the :code:`keys` to describte a keyframe.
-      The first number is the timestamp, the second number is the transition (default 1.0
-      in transform track), followed by a three number translation vector, followed by
-      four number rotation quaternion (x,y,z,w) and finally a three number scale vector.
+    - A Transform track uses every 12 real numbers in the ``keys`` to describe
+      a keyframe. The first number is the timestamp. The second number is the
+      transition followed by a 3-number translation vector, followed by a
+      4-number rotation quaternion (X, Y, Z, W) and finally a 3-number
+      scale vector. The default transition in a Transform track is 1.0.
 
 ::
 

getting_started/editor/external_editor.rst

@@ -3,25 +3,27 @@
 Using an external text editor
 ==============================
 
-Godot can be used with an external text editor, such as Sublime Text or Visual Studio Code. To select an external text editor via the Godot editor menu:
+Godot can be used with an external text editor, such as Sublime Text or Visual Studio Code.
+To enable an external text editor, browse to the relevant editor settings via:
 ``Editor -> Editor Settings -> Text Editor -> External``
 
 .. image:: img/editor_settings.png
 
 There are two fields: the executable path and command line flags. The flags
-allow you to better integrate the editor with Godot. Godot will replace the
-following inside the flags parameter:
+allow you to integrate the editor with Godot, passing it the file path to open
+and other relevant arguments. Godot will replace the following placeholders in
+the flags string:
 
 +---------------------+-----------------------------------------------------+
 | Field in Exec Flags | Is replaced with                                    |
 +=====================+=====================================================+
-| {project}           | The absolute path to the project directory          |
+| ``{project}``       | The absolute path to the project directory          |
 +---------------------+-----------------------------------------------------+
-| {file}              | The absolute path to the file                       |
+| ``{file}``          | The absolute path to the file                       |
 +---------------------+-----------------------------------------------------+
-| {col}               | The column number of the error                      |
+| ``{col}``           | The column number of the error                      |
 +---------------------+-----------------------------------------------------+
-| {line}              | The line number of the error                        |
+| ``{line}``          | The line number of the error                        |
 +---------------------+-----------------------------------------------------+
 
 Some example Exec Flags for various editors include:
@@ -29,15 +31,15 @@ Some example Exec Flags for various editors include:
 +---------------------+-----------------------------------------------------+
 | Editor              | Exec Flags                                          |
 +=====================+=====================================================+
-| Geany/Kate          | {file} -\-line {line} -\-column {col}               |
+| Geany/Kate          | ``{file} --line {line} --column {col}``             |
 +---------------------+-----------------------------------------------------+
-| Atom/Sublime Text   | {file}:{line}                                       |
+| Atom/Sublime Text   | ``{file}:{line}``                                   |
 +---------------------+-----------------------------------------------------+
-| JetBrains Rider     | -\-line {line} {file}                               |
+| JetBrains Rider     | ``--line {line} {file}``                            |
 +---------------------+-----------------------------------------------------+
-| Visual Studio Code  | {project} -\-goto {file}:{line}:{col}               |
+| Visual Studio Code  | ``{project} --goto {file}:{line}:{col}``            |
 +---------------------+-----------------------------------------------------+
-| Vim (gVim)          | "+call cursor({line}, {col})" {file}                |
+| Vim (gVim)          | ``"+call cursor({line}, {col})" {file}``            |
 +---------------------+-----------------------------------------------------+
 
-.. note:: For Visual Studio Code you will have to point to the "code.cmd" file.
+.. note:: For Visual Studio Code you will have to point to the ``code.cmd`` file.

getting_started/editor/unity_to_godot.rst

@@ -10,6 +10,10 @@ From Unity to Godot Engine
 This guide provides an overview of Godot Engine from the viewpoint of a Unity user,
 and aims to help you migrate your existing Unity experience into the world of Godot.
 
+.. note::
+
+   This article talks about older versions of Unity. Nestable prefabs ('Nested prefabs') were added to Unity 2018.3. Nestable prefabs are analogous to Godot's scenes, and allow a more Godot-like approach to scene organisation.
+
 Differences
 -----------
 
@@ -33,7 +37,7 @@ Differences
 | Third-party tools | Visual Studio or VS Code                                                           | * :ref:`External editors are possible <doc_external_editor>`                                                   |
 |                   |                                                                                    | * :ref:`Android SDK for Android export <doc_exporting_for_android>`                                            |
 +-------------------+------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------+
-| Killer features   | * Huge community                                                                   | * Scene System                                                                                                 |
+| Notable advantages| * Huge community                                                                   | * Scene System                                                                                                 |
 |                   | * Large assets store                                                               | * :ref:`Animation Pipeline <doc_animations>`                                                                   |
 |                   |                                                                                    | * :ref:`Easy to write Shaders <doc_shading_language>`                                                          |
 |                   |                                                                                    | * Debug on Device                                                                                              |
@@ -46,33 +50,30 @@ The editor
 ----------
 
 Godot Engine provides a rich-featured editor that allows you to build your games.
-The pictures below display both editors with colored blocks to indicate common functionalities.
+The pictures below display the default layouts of both editors with colored blocks to indicate common functionalities.
 
 .. image:: img/unity-gui-overlay.png
 .. image:: img/godot-gui-overlay.png
 
-
-Note that Godot editor allows you to dock each panel at the side of the scene editor you wish.
-
 While both editors may seem similar, there are many differences below the surface.
 Both let you organize the project using the filesystem,
 but Godot's approach is simpler with a single configuration file, minimalist text format,
-and no metadata. All this contributes to Godot being much friendlier to VCS systems, such as Git, Subversion, or Mercurial.
+and no metadata. This makes Godot more friendly to VCS systems, such as Git, Subversion, or Mercurial.
 
 Godot's Scene panel is similar to Unity's Hierarchy panel but, as each node has a specific function,
-the approach used by Godot is more visually descriptive. In other words, it's easier to understand
-what a specific scene does at a glance.
+the approach used by Godot is more visually descriptive. It's easier to understand
+what a scene does at a glance.
 
-The Inspector in Godot is more minimalist and designed to only show properties.
-Thanks to this, objects can export a much larger amount of useful parameters to the user
-without having to hide functionality in language APIs. As a plus, Godot allows animating any of those properties visually,
-so changing colors, textures, enumerations, or even links to resources in real-time is possible without involving code.
+The Inspector in Godot is more minimal, it shows only properties.
+Thanks to this, objects can expose more useful parameters to the user
+without having to hide functionality in language APIs. As a plus, Godot allows animating any of those properties visually.
+Changing colors, textures, enumerations, or even links to resources in real-time is possible without needing to write code.
 
-Finally, the Toolbar at the top of the screen is similar in the sense that it allows controlling the project playback,
-but projects in Godot run in a separate window, as they don't execute inside the editor
+The Toolbar at the top of the screen is similar in both editors, offering control over project playback.
+Projects in Godot run in a separate window, rather than inside the editor
 (but the tree and objects can still be explored in the debugger window).
 
-This approach has the disadvantage that the running game can't be explored from different angles
+This approach has the disadvantage that in Godot the running game can't be explored from different angles
 (though this may be supported in the future and displaying collision gizmos in the running game is already possible),
 but in exchange has several advantages:
 
@@ -80,21 +81,19 @@ but in exchange has several advantages:
 - Live editing is a lot more useful because changes done to the editor take effect immediately in the game and are not lost (nor have to be synced) when the game is closed. This allows fantastic workflows, like creating levels while you play them.
 - The editor is more stable because the game runs in a separate process.
 
-Finally, the top toolbar includes a menu for remote debugging.
-These options make it simple to deploy to a device (connected phone, tablet, or browser via HTML5),
-and debug/live edit on it after the game was exported.
+Finally, Godot's top toolbar includes a menu for remote debugging.
+These options allow deployment to a device (connected phone, tablet, or browser via HTML5),
+and debugging/live editing on it after the game is exported.
 
 The scene system
 ----------------
 
-This is the most important difference between Unity and Godot and, actually, the favourite feature of most Godot users.
+This is the most important difference between Unity and Godot and the favourite feature of most Godot users.
 
-Unity's scene system consists of embedding all the required assets in a scene
-and linking them together by setting components and scripts to them.
+Working on a 'level' in Unity usually means embedding all the required assets in a scene
+and linking them together with components and scripts.
 
-Godot's scene system is different: it actually consists of a tree made of nodes.
-Each node serves a purpose: Sprite, Mesh, Light, etc. Basically, this is similar to the Unity scene system.
-However, each node can have multiple children, which makes each a subscene of the main scene.
+Godot's scene system is superficially similar to Unity. A 'level' consists of a collection of nodes, each with its own purpose: Sprite, Mesh, Light, etc. However, in Godot the nodes are arranged in a tree. Each node can have multiple children, which makes each a subscene of the main scene.
 This means you can compose a whole scene with different scenes stored in different files.
 
 For example, think of a platformer level. You would compose it with multiple elements:
@@ -104,90 +103,80 @@ For example, think of a platformer level. You would compose it with multiple ele
 - The player
 - The enemies
 
-
 In Unity, you would put all the GameObjects in the scene: the player, multiple instances of enemies,
 bricks everywhere to form the ground of the level and then multiple instances of coins all over the level.
 You would then add various components to each element to link them and add logic in the level: For example,
 you'd add a BoxCollider2D to all the elements of the scene so that they can collide. This principle is different in Godot.
 
-In Godot, you would split your whole scene into 3 separate, smaller scenes, which you would then instance in the main scene.
+In Godot, you would split your whole scene into three separate, smaller scenes, and instance them in the main scene.
 
-1. **First, a scene for the Player alone.**
+1. **A scene for the Player alone.**
 
-Consider the player as a reusable element in other levels. It is composed of one node in particular:
-an AnimatedSprite node, which contains the sprite textures to form various animations (for example, walking animation)
+Consider the player as an element we'd like to use in different parent scenes (for instance 'level' scenes). In our case, the player element needs at least an AnimatedSprite node. This node contains the sprite textures necessary for various animations (for example, a walking animation).
 
-2. **Second, a scene for the Enemy.**
+2. **A scene for the Enemy.**
 
-There again, an enemy is a reusable element in other levels. It is almost the same
-as the Player node - the only differences are the script (that manages AI, mostly)
-and sprite textures used by the AnimatedSprite.
+An enemy is also an element we'd like to use in several scenes. It's almost the same
+as the Player node. The only differences are the script (it needs 'AI' routines to generate the enemy's behaviour)
+and the sprite textures used by the AnimatedSprite node.
 
-3. **Lastly, the Level scene.**
+3. **A Level scene.**
 
-It is composed of Bricks (for platforms), Coins (for the player to grab) and a
-certain number of instances of the previous Enemy scene. These will be different, separate enemies,
-whose behaviour and appearance will be the same as defined in the Enemy scene.
-Each instance is then considered as a node in the Level scene tree.
-Of course, you can set different properties for each Enemy node (to change its color, for example).
+A Level scene is composed of Bricks (for platforms), Coins (for the player to collect) and a
+number of instances of the Enemy scene. Each instance is a node in the Level scene tree. These instances are separate enemies,
+which initially have shared behaviour and appearance as defined in the Enemy scene. You can set different properties for each Enemy node (to change its color, for example).
 
-Finally, the main scene would then be composed of one root node with 2 children: a Player instance node, and a Level instance node.
+4. **A Main scene.**
+The Main scene would be composed of one root node with 2 children: a Player instance node, and a Level instance node.
 The root node can be anything, generally a "root" type such as "Node" which is the most global type,
 or "Node2D" (root type of all 2D-related nodes), "Spatial" (root type of all 3D-related nodes) or
 "Control" (root type of all GUI-related nodes).
 
-
 As you can see, every scene is organized as a tree. The same goes for nodes' properties: you don't *add* a
 collision component to a node to make it collidable like Unity does. Instead, you make this node a *child* of a
 new specific node that has collision properties. Godot features various collision types nodes, depending on the usage
 (see the :ref:`Physics introduction <doc_physics_introduction>`).
 
-- Question: What are the advantages of this system? Wouldn't this system potentially increase the depth of the scene tree? Besides, Unity allows organizing GameObjects by putting them in empty GameObjects.
-
-    - First, this system is closer to the well-known object-oriented paradigm: Godot provides a number of nodes which are not clearly "Game Objects", but they provide their children with their own capabilities: this is inheritance.
-    - Second, it allows the extraction of a subtree of the scene to make it a scene of its own, which answers the second and third questions: even if a scene tree gets too deep, it can be split into smaller subtrees. This also allows a better solution for reusability, as you can include any subtree as a child of any node. Putting multiple nodes in an empty GameObject in Unity does not provide the same possibility, apart from a visual organization.
-
-
-These are the most important concepts you need to remember: "node", "parent node", and "child node".
+- What are the advantages of this system? Wouldn't this system potentially increase the depth of the scene tree? And doesn't Unity already allow you to organize GameObjects by putting them inside empty GameObjects?
 
+    - Godot's system is closer to the well-known object-oriented paradigm: Godot provides a number of nodes which are not clearly "Game Objects", but they provide their children with their own capabilities: this is inheritance.
+    - Godot allows the extraction of a subtree of a scene to make it a scene of its own. So if a scene tree gets too deep, it can be split into smaller subtrees. This is better for reusability, as you can include any subtree as a child of any node. Putting multiple GameObjects in an empty GameObject in Unity does not provide the same functionality.
 
 Project organization
 --------------------
 
 .. image:: img/unity-project-organization-example.png
 
-We previously observed that there is no perfect solution to set a project architecture.
-Any solution will work for Unity and Godot, so this point has a lesser importance.
+There is no perfect project architecture.
+Any architecture can be made to work in either Unity and Godot.
 
-However, we often observe a common architecture for Unity projects, which consists of having one Assets folder in the root directory
-that contains various folders, one per type of asset: Audio, Graphics, Models, Materials, Scripts, Scenes, etc.
+However, a common architecture for Unity projects is to have one Assets folder in the root directory
+that contains various folders, one per type of asset: Audio, Graphics, Models, Materials, Scripts, Scenes, and so on.
 
-As described before, the Godot scene system allows splitting scenes into smaller scenes.
-Since each scene and subscene is actually one scene file in the project, we recommend organizing your project a bit differently.
+Since Godot allows splitting scenes into smaller scenes, each scene and subscene existing as a file in the project, we recommend organizing your project a bit differently.
 This wiki provides a page for this: :ref:`doc_project_organization`.
 
 
 Where are my prefabs?
 ---------------------
 
-The concept of prefabs as provided by Unity is a 'template' element of the scene.
+A prefab as provided by Unity is a 'template' element of the scene.
 It is reusable, and each instance of the prefab that exists in the scene has an existence of its own,
 but all of them have the same properties as defined by the prefab.
 
-Godot does not provide prefabs as such, but this functionality is here, again, filled thanks to its scene system:
-As we saw, the scene system is organized as a tree. Godot allows you to save a subtree of a scene as its own scene,
-thus saved into its own file. This new scene can then be instanced as many times as you want.
+Godot does not provide prefabs as such, but the same functionality is provided by its scene system:
+The scene system is organized as a tree. Godot allows you to save any subtree of a scene as a scene file. This new scene can then be instanced as many times as you want, as a child of any node.
 Any change you make to this new, separate scene will be applied to its instances.
 However, any change you make to the instance will not have any impact on the 'template' scene.
 
 .. image:: img/save-branch-as-scene.png
 
-To be precise, you can modify the parameters of the instance in the Inspector panel.
-However, the nodes that compose this instance are locked although you can unlock them if you need to by
+To be precise, you can modify the parameters of an instance in the Inspector panel.
+The nodes that compose this instance are initially locked. You can unlock them if you need to by
 right-clicking the instance in the Scene tree and selecting "Editable children" in the menu.
-You don't need to do this to add new children nodes to this node, but it is possible.
-Remember that these new children will belong to the instance, not the 'template' scene.
-If you want to add new children to all the instances of your 'template' scene, then you need to add them in the 'template' scene.
+You don't need to do this to add *new* child nodes to this node.
+Remember that any new children will belong to the instance, not to the 'template' scene on disk.
+If you want to add new children to every instance of your 'template' scene, then you should add them in the 'template' scene.
 
 .. image:: img/editable-children.png
 
@@ -196,7 +185,7 @@ Glossary correspondence
 
 - GameObject -> Node
 - Add a component -> Inheriting
-- Prefab -> Externalized branch
+- Prefab -> Reusable Scene file
 
 
 Scripting: GDScript, C# and Visual Script
@@ -205,13 +194,13 @@ Scripting: GDScript, C# and Visual Script
 Design
 ^^^^^^
 
-As you may know already, Unity supports C#. C# benefits from its integration with Visual Studio and other features, such as static typing.
+Unity supports C#. C# benefits from its integration with Visual Studio and has desirable features such as static typing.
 
 Godot provides its own scripting language, :ref:`GDScript <doc_scripting>` as well as support
 for :ref:`Visual Script <toc-learn-scripting-visual_script>` and :ref:`C# <doc_c_sharp>`.
 GDScript borrows its syntax from Python, but is not related to it. If you wonder about the reasoning for a custom scripting language,
 please read the :ref:`doc_gdscript` and :ref:`doc_faq` pages. GDScript is strongly attached to the Godot API
-and is really easy to learn: Between one evening for an experienced programmer and a week for a complete beginner.
+and doesn't take long to learn: Between one evening for an experienced programmer and a week for a complete beginner.
 
 Unity allows you to attach as many scripts as you want to a GameObject.
 Each script adds a behaviour to the GameObject: For example, you can attach a script so that it reacts to the player's controls,
@@ -224,8 +213,7 @@ depending on your scene and on what you want to achieve:
 - either add a new node between your target node and its current parent, then add a script to this new node.
 - or, you can split your target node into multiple children and attach one script to each of them.
 
-As you can see, it can be easy to turn a scene tree to a mess. This is why it is important to have a real reflection
-and consider splitting a complicated scene into multiple, smaller branches.
+As you can see, it can be easy to turn a scene tree to a mess. Consider splitting any complicated scene into multiple, smaller branches.
 
 Connections: groups and signals
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

getting_started/scripting/c_sharp/c_sharp_differences.rst

@@ -260,7 +260,7 @@ Array
 =====================  ==============================================================
 GDScript               C#
 =====================  ==============================================================
-``Array``              ``Godot.Array``
+``Array``              ``Godot.Collections.Array``
 ``PoolIntArray``       ``int[]``
 ``PoolByteArray``      ``byte[]``
 ``PoolFloatArray``     ``float[]``
@@ -270,16 +270,16 @@ GDScript               C#
 ``PoolVector3Array``   ``Vector3[]``
 =====================  ==============================================================
 
-``Godot.Array<T>`` is a type-safe wrapper around ``Godot.Array``.
-Use the ``Godot.Array<T>(Godot.Array)`` constructor to create one.
+``Godot.Collections.Array<T>`` is a type-safe wrapper around ``Godot.Collections.Array``.
+Use the ``Godot.Collections.Array<T>(Godot.Collections.Array)`` constructor to create one.
 
 Dictionary
 ----------
 
-Use ``Godot.Dictionary``.
+Use ``Godot.Collections.Dictionary``.
 
-``Godot.Dictionary<T>`` is a type-safe wrapper around ``Godot.Dictionary``.
-Use the ``Godot.Dictionary<T>(Godot.Dictionary)`` constructor to create one.
+``Godot.Collections.Dictionary<T>`` is a type-safe wrapper around ``Godot.Collections.Dictionary``.
+Use the ``Godot.Collections.Dictionary<T>(Godot.Collections.Dictionary)`` constructor to create one.
 
 Variant
 -------

getting_started/scripting/c_sharp/c_sharp_style_guide.rst

@@ -20,9 +20,9 @@ of the language, we encourage you to do the same, especially if you do not have
 Language specification
 ----------------------
 
-Currently, Godot uses C# version 6.0 in its engine and example source code. So, before we move to
-a newer version, care must be taken to avoid mixing language features only available in C# 7.0 or
-later, such as pattern matching or expression-bodied members inside get/set accessors.
+Godot currently uses **C# version 7.0** in its engine and example source code. So, before we move to
+a newer version, care must be taken to avoid mixing language features only available in C# 7.1 or
+later.
 
 For detailed information on C# features in different versions, please see
 `What's New in C# <https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/>`_.
@@ -30,14 +30,15 @@ For detailed information on C# features in different versions, please see
 Formatting conventions
 ----------------------
 
-* If you create a new file, make sure that it uses linefeed (*LF*) characters to break lines, not *CRLF* or *CR*.
-* Use UTF-8 encoding without a byte order mark (BOM <https://en.wikipedia.org/wiki/Byte_order_mark>).
-* Use 4 spaces instead of tabs for indentation (which is referred to as 'soft tabs').
+* Use line feed (**LF**) characters to break lines, not CRLF or CR.
+* Use **UTF-8** encoding without a `byte order mark <https://en.wikipedia.org/wiki/Byte_order_mark>`_.
+* Use **4 spaces** instead of tabs for indentation (which is referred to as "soft tabs").
+* Consider breaking a line into several if it's longer than 100 characters.
 
 Line breaks and blank lines
 ---------------------------
 
-For a general indentation rule, follow `The 'Allman Style' <https://en.wikipedia.org/wiki/Indentation_style#Allman_style>`_
+For a general indentation rule, follow `the "Allman Style" <https://en.wikipedia.org/wiki/Indentation_style#Allman_style>`_
 which recommends placing the brace associated with a control statement on the next line, indented to
 the same level:
 
@@ -82,8 +83,9 @@ However, you may choose to omit line breaks inside brackets:
 
 Insert a blank line:
 
-* After *using* statement list.
+* After a list of ``using`` statements.
 * Between method, properties, and inner type declarations.
+* At the end of each file.
 
 Field and constant declarations can be grouped together according to relevance. In that case, consider
 inserting a blank line between the groups for easier reading.
@@ -92,63 +94,59 @@ Avoid inserting a blank line:
 
 * After ``{``, the opening brace.
 * Before ``}``, the closing brace.
-* After a comment block, or a single line comment.
+* After a comment block or a single-line comment.
 * Adjacent to another blank line.
 
 .. code-block:: csharp
 
     using System;
     using Godot;
-                                                  // Blank line after using list.
+                                              // Blank line after `using` list.
     public class MyClass
-    {                                             // No blank line after '{'.
+    {                                         // No blank line after `{`.
         public enum MyEnum
         {
             Value,
-            AnotherValue                          // No blank line before '}'.
+            AnotherValue                      // No blank line before `}`.
         }
-                                                  // Blank line around inner types.
+                                              // Blank line around inner types.
         public const int SomeConstant = 1;
         public const int AnotherConstant = 2;
 
-        private Vector3 _x;
-        private Vector3 _y;                       // Related constants or fields can be
-                                                  // grouped together.
+        private Vector3 _x;                  // Related constants or fields can be
+        private Vector3 _y;                  // grouped together.
+
         private float _width;
         private float _height;
 
         public int MyProperty { get; set; }
-                                                  // Blank line around properties.
+                                              // Blank line around properties.
         public void MyMethod()
         {
             // Some comment.
-            AnotherMethod();                      // No blank line after a comment.
+            AnotherMethod();                  // No blank line after a comment.
         }
-                                                  // Blank line around methods.
+                                              // Blank line around methods.
         public void AnotherMethod()
         {
         }
     }
 
-Consider breaking a line when it's longer than 100 characters. And it's also a good practice to
-insert a line feed (LF) character at the end of a file because some utilities have trouble
-recognizing the last line without it (e.g. the *cat* command on Linux).
-
 Using spaces
 ------------
 
 Insert a space:
 
 * Around a binary and tertiary operator.
-* Between an opening parenthesis and *if*, *for*, *foreach*, *catch*, *while*, *lock* or *using* keywords.
+* Between an opening parenthesis and ``if``, ``for``, ``foreach``, ``catch``, ``while``, ``lock`` or ``using`` keywords.
 * Before and within a single line accessor block.
 * Between accessors in a single line accessor block.
-* After a comma.
-* After a semi-colon in a *for* statement.
-* After a colon in a single line *case* statement.
+* After a comma which is not at the end of a line.
+* After a semicolon in a ``for`` statement.
+* After a colon in a single line ``case`` statement.
 * Around a colon in a type declaration.
 * Around a lambda arrow.
-* After a single line comment symbol ('//'), and before it if used at the end of a line.
+* After a single-line comment symbol (``//``), and before it if used at the end of a line.
 
 Do not use a space:
 
@@ -192,7 +190,7 @@ The following example shows a proper use of spaces, according to some of the abo
 Naming conventions
 ------------------
 
-Use *PascalCase* for all namespaces, type names and member level identifiers (i.e. methods, properties,
+Use **PascalCase** for all namespaces, type names and member level identifiers (i.e. methods, properties,
 constants, events), except for private fields:
 
 .. code-block:: csharp
@@ -213,12 +211,12 @@ constants, events), except for private fields:
         }
     }
 
-Use *camelCase* for all other identifiers (i.e. local variables, method arguments), and use
-underscore('_') as a prefix for private fields (but not for methods or properties, as explained above):
+Use **camelCase** for all other identifiers (i.e. local variables, method arguments), and use
+an underscore (``_``) as a prefix for private fields (but not for methods or properties, as explained above):
 
 .. code-block:: csharp
 
-    private Vector3 _aimingAt; // Use '_' prefix for private fields.
+    private Vector3 _aimingAt; // Use a `_` prefix for private fields.
 
     private void Attack(float attackStrength)
     {
@@ -227,10 +225,10 @@ underscore('_') as a prefix for private fields (but not for methods or propertie
         targetFound?.Hit(attackStrength);
     }
 
-There's an exception with acronyms which consist of two letters, like *'UI'*, which should be written in
-uppercase letters when used where Pascal case would be expected, and in lowercase letters otherwise.
+There's an exception with acronyms which consist of two letters, like ``UI``, which should be written in
+uppercase letters where PascalCase would be expected, and in lowercase letters otherwise.
 
-Note that *'id'* is **not** an acronym, so it should be treated as a normal identifier:
+Note that ``id`` is **not** an acronym, so it should be treated as a normal identifier:
 
 .. code-block:: csharp
 
@@ -241,20 +239,20 @@ Note that *'id'* is **not** an acronym, so it should be treated as a normal iden
         get { return uiManager; }
     }
 
-It is generally discouraged to use a type name as a prefix of an identifier, like *'string strText'*
-or *'float fPower'*, for example. An exception is made, however, for interfaces, which
-**should**, in fact, have an uppercase letter *'I'* prefixed to their names, like *'IInventoryHolder'* or *'IDamageable'*.
+It is generally discouraged to use a type name as a prefix of an identifier, like ``string strText``
+or ``float fPower``, for example. An exception is made, however, for interfaces, which
+**should**, in fact, have an uppercase letter ``I`` prefixed to their names, like ``IInventoryHolder`` or ``IDamageable``.
 
 Lastly, consider choosing descriptive names and do not try to shorten them too much if it affects
 readability.
 
-For instance, if you want to write code to find a nearby enemy and hit it with a weapon, prefer
+For instance, if you want to write code to find a nearby enemy and hit it with a weapon, prefer:
 
 .. code-block:: csharp
 
     FindNearbyEnemy()?.Damage(weaponDamage);
 
-Rather than,
+Rather than:
 
 .. code-block:: csharp
 
@@ -263,7 +261,7 @@ Rather than,
 Implicitly typed local variables
 --------------------------------
 
-Consider using implicitly typing (*'var'*) for declaration of a local variable, but do so
+Consider using implicitly typing (``var``) for declaration of a local variable, but do so
 **only when the type is evident** from the right side of the assignment:
 
 .. code-block:: csharp
@@ -287,8 +285,8 @@ Consider using implicitly typing (*'var'*) for declaration of a local variable,
     var velocity = direction * 1.5;
 
     // It's generally a better idea to use explicit typing for numeric values, especially with
-    // the existence of 'real_t' alias in Godot, which can either be double or float depending
-    // on the build configuration.
+    // the existence of the `real_t` alias in Godot, which can either be double or float
+    // depending on the build configuration.
 
     var value = 1.5;
 
@@ -297,9 +295,10 @@ Other considerations
 
  * Use explicit access modifiers.
  * Use properties instead of non-private fields.
- * Use modifiers in this order: *'public/protected/private/internal virtual/override/abstract/new static readonly'*.
- * Avoid using fully qualified names or *'this.'* prefix for members when it's not necessary.
- * Remove unused *'using'* statements and unnecessary parentheses.
- * Consider omitting default initial value for a type.
+ * Use modifiers in this order:
+   ``public``/``protected``/``private``/``internal``/``virtual``/``override``/``abstract``/``new``/``static``/``readonly``.
+ * Avoid using fully-qualified names or ``this.`` prefix for members when it's not necessary.
+ * Remove unused ``using`` statements and unnecessary parentheses.
+ * Consider omitting the default initial value for a type.
  * Consider using null-conditional operators or type initializers to make the code more compact.
  * Use safe cast when there is a possibility of the value being a different type, and use direct cast otherwise.

getting_started/scripting/gdscript/gdscript_basics.rst

@@ -1231,6 +1231,9 @@ special export syntax is provided.
 
     export(Texture) var character_face
     export(PackedScene) var scene_file
+    # There are many resource types that can be used this way, try e.g.
+    # the following to list them:
+    export(Resource) var resource
 
     # Integers and strings hint enumerated values.
 
@@ -1440,6 +1443,11 @@ placed at the top of the file:
     func _ready():
         print("Hello")
 
+.. warning:: Be cautious when freeing nodes with `queue_free()` or `free()`
+             in a tool script (especially the script's owner itself). As tool
+             scripts run their code in the editor, misusing them may lead to
+             crashing the editor.
+
 Memory management
 ~~~~~~~~~~~~~~~~~
 
@@ -1460,104 +1468,161 @@ freed.
 Signals
 ~~~~~~~
 
-Signals are a way to send notification messages from an object that
-other objects can listen to in a generic way. Create custom signals for
-a class using the ``signal`` keyword.
+Signals are a tool to emit messages from an object that other objects can react
+to. To create custom signals for a class, use the ``signal`` keyword.
 
 ::
 
-   # Signal with no arguments
-   signal your_signal_name
+   extends Node
+
+   # A signal named health_depleted
+   signal health_depleted
 
-   # Signal with two arguments
-   signal your_signal_name_with_args(a, b)
+.. note:: 
 
-These signals may be connected to methods in the same manner as you connect
-built-in signals of nodes such as :ref:`class_Button` or :ref:`class_RigidBody`.
+   Signals are a `Callback
+   <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
+   Game Programming Patterns ebook.
 
-Here's an example that creates a custom signal in one script and connects
-the custom signal to a method in a separate script, using the
-:ref:`Object.connect() <class_Object_method_connect>` method:
+You can connect these signals to methods the same way you connect built-in
+signals of nodes like :ref:`class_Button` or :ref:`class_RigidBody`.
+
+In the example below, we connect the ``health_depleted`` signal from a
+``Character`` node to a ``Game`` node. When the ``Character`` node emits the
+signal, the game node's ``_on_Character_health_depleted`` is called:
 
 ::
 
-   # your_notifier.gd
+   # Game.gd
+
+   func _ready():
+      var character_node = get_node('Character')
+      character_node.connect("health_depleted", self, "_on_Character_health_depleted")
+
+   func _on_Character_health_depleted():
+      get_tree().reload_current_scene()
+
+You can emit as many arguments as you want along with a signal. 
 
-   signal data_found
+Here is an example where this is useful. Let's say we want a life bar on screen
+to react to health changes with an animation, but we want to keep the user
+interface separate from the player in our scene tree.
 
-   var your_data = 42
+In our ``Character.gd`` script, we define a ``health_changed`` signal and emit
+it with :ref:`Object.emit_signal() <class_Object_method_emit_signal>`, and from
+a ``Game`` node higher up our scene tree, we connect it to the ``Lifebar`` using
+the :ref:`Object.connect() <class_Object_method_connect>` method:
 
 ::
 
-   # your_handler.gd
+    # Character.gd
+
+    ...
+    signal health_changed
 
-   func your_handler():
-      print("Your handler was called!")
+    func take_damage(amount):
+        var old_health = health
+        health -= amount
+
+        # We emit the health_changed signal every time the
+        # character takes damage
+        emit_signal(health_changed", old_health, health)
+    ...
 
 ::
 
-   # your_game.gd
+    # Lifebar.gd 
 
-   func _ready():
-      var notifier = your_notifier.new()
-      var handler = your_handler.new()
+    # Here, we define a function to use as a callback when the
+    # character's health_changed signal is emitted
 
-      notifier.connect("data_found", handler, "your_handler")
+    ...
+    func _on_Character_health_changed(old_value, new_value):
+        if old_value > new_value:
+            progress_bar.modulate = Color.red
+        else:
+            progress_bar.modulate = Color.green
 
-GDScript can bind arguments to connections between a signal and a method.
-When the signal is emitted, calling the connected method, the bound argument is
-given to the method. These bound arguments are specific to the connection
-rather than the signal or the method, meaning that each connection has
-unique bindings.
+        # Imagine that `animate` is a user-defined function that animates the
+        # bar filling up or emptying itself
+        progress_bar.animate(old_value, new_value)
+    ...
 
-Here is an example that creates a connection between a button's ``pressed`` signal and
-a method, binding the button instance to the connection. The handler uses the
-bound argument to print which button instance was pressed.
+.. note::
+   
+    To use signals, your class has to extend the ``Object`` class or any
+    type extending it like ``Node``, ``KinematicBody``, ``Control``...
+
+In the ``Game`` node, we get both the ``Character`` and ``Lifebar`` nodes, then
+connect the character, that emits the signal, to the receiver, the ``Lifebar``
+node in this case.
 
 ::
-   
-   func pressed_handler(which):
-      print("A button was pressed! Button's name was:", which.get_name())
+
+   # Game.gd
 
    func _ready():
-      for button in get_node("buttons").get_children()
-         # Connect the button's 'pressed' signal to our 'pressed_handler' method
-         # Bind the button to the connection so we know which button was pressed
-         button.connect("pressed", self, "pressed_handler", [button])
+      var character_node = get_node('Character')
+      var lifebar_node = get_node('UserInterface/Lifebar')
+
+      character_node.connect("health_changed", lifebar_node, "_on_Character_health_changed")
 
-Signals are generated by the :ref:`Object.emit_signal() <class_Object_method_emit_signal>`
-method which broadcasts the signal and arguments.
+This allows the ``Lifebar`` to react to health changes without coupling it to
+the ``Character`` node.
 
-Extending a previous example to use all the features of GDScript signals:
+you can write optional argument names in parentheses after the signal's
+definition. 
 
 ::
 
-   # your_notifier.gd
+   # Defining a signal that forwards two arguments
+   signal health_changed(old_value, new_value)
+
+These arguments show up in the editor's node dock, and Godot can use them to
+generate callback functions for you. However, you can still emit any number of
+arguments when you emit signals. So it's up to you to emit the correct values.
 
-   signal data_found(data)
+.. image:: img/gdscript_basics_signals_node_tab_1.png
 
-   var your_data = 42
+GDScript can bind an array of values to connections between a signal and a method. When
+the signal is emitted, the callback method receives the bound values. These bound
+arguments are unique to each connection, and the values will stay the same.
 
-   func _process(delta):
-      if delta == your_data:
-         emit_signal("data_found", your_data)
+You can use this array of values to add extra constant information to the
+connection if the emitted signal itself doesn't give you access to all the data
+that you need.
+
+Building on the example above, let's say we want to display a log of the damage
+taken by each character on the screen, like ``Player1 took 22 damage.``. The
+``health_changed`` signal doesn't give us the name of the character that took
+damage. So when we connect the signal to the in-game console, we can add the
+character's name in the binds array argument:
 
 ::
+   
+   # Game.gd
 
-   # your_handler.gd
+   func _ready():
+      var character_node = get_node('Character')
+      var battle_log_node = get_node('UserInterface/BattleLog')
 
-   func your_handler(data, obj):
-      print("Your handler was called from: ", obj.get_name(), " with data: ", data)
+      character_node.connect("health_changed", battle_log_node, "_on_Character_health_changed", [character_node.name])
+
+Our ``BattleLog`` node receives each element in the binds array as an extra argument:
 
 ::
 
-   # your_game.gd
+   # BattleLog.gd
 
-   func _ready():
-      var notifier = your_notifier.new()
-      var handler = your_handler.new()
+   func _on_Character_health_changed(old_value, new_value, character_name):
+      if not new_value <= old_value:
+         return
+      var damage = new_value - old_value
+      label.text += character_name + " took " + str(damage) + " damage."
 
-      notifier.connect("data_found", handler, "your_handler", [notifier])
 
 Coroutines with yield
 ~~~~~~~~~~~~~~~~~~~~~

getting_started/scripting/gdscript/gdscript_styleguide.rst

@@ -69,7 +69,20 @@ regular code blocks.
 Blank lines
 ~~~~~~~~~~~
 
-Surround functions and class definitions with a blank line.
+Surround functions and class definitions with two blank lines:
+
+::
+
+    func heal(amount):
+        health += amount
+        health = min(health, max_health)
+        emit_signal("health_changed", health)
+
+
+    func take_damage(amount, effect=null):
+        health -= amount
+        health = max(0, health)
+        emit_signal("health_changed", health)
 
 Use one blank line inside functions to separate logical sections.
 
@@ -194,3 +207,42 @@ Constants
 
 Use CONSTANT\_CASE, all caps, with an underscore (\_) to separate words:
 ``const MAX_SPEED = 200``
+
+Static typing
+-------------
+
+Since Godot 3.1, GDScript supports :ref:`optional static typing<doc_gdscript_static_typing>`.
+
+Type hints
+~~~~~~~~~~
+
+Place the colon right after the variable's name, without a space, and let the GDScript compiler infer the variable's type when possible.
+
+
+**Good**:
+
+::
+
+   onready var health_bar: ProgressBar = get_node("UI/LifeBar")
+
+   var health := 0 # The compiler will use the int type
+
+**Bad**:
+
+::
+
+   # The compiler can't infer the exact type and will use Node 
+   # instead of ProgressBar
+   onready var health_bar := get_node("UI/LifeBar") 
+
+When you let the compiler infer the type hint, write the colon and equal signs together: ``:=``.
+
+::
+
+   var health := 0 # The compiler will use the int type
+
+Add a space on either sides of the return type arrow when defining functions.
+
+::
+
+   func heal(amount: int) -> void:

getting_started/scripting/visual_script/nodes_purposes.rst

@@ -397,11 +397,9 @@ input and return an output. They are almost never sequenced.
 Built-In
 ^^^^^^^^
 
-There is a list of built-in helpers. The list is almost identical to the one from GDScript (@TODO, link to gdscript methods?).
-Most of them are mathematical functions, but others can be useful helpers. Make sure to take a look at the list
+There is a list of built-in helpers. The list is almost identical to the one from :ref:`GDScript<class_@GDScript>`. Most of them are mathematical functions, but others can be useful helpers. Make sure to take a look at the list
 at some point.
 
-
 By Type
 ^^^^^^^
 

getting_started/step_by_step/godot_design_philosophy.rst

@@ -113,8 +113,8 @@ This means all the technologies that ship with it have to be Free
 For the most part, they’re developed from the ground up by contributors.
 
 Anyone can plug in proprietary tools for the needs of their projects —
-they just won’t ship with the engine. This may include NVIDIA PhysX,
-Google AdMob, or an FBX model importer. Any of these can come as
+they just won’t ship with the engine. This may include Google AdMob,
+or FMOD. Any of these can come as
 third-party plugins instead.
 
 On the other hand, an open codebase means you can **learn from and extend

getting_started/step_by_step/instancing.rst

@@ -105,7 +105,9 @@ much more bouncy. Because the instanced balls are based on the saved scene,
 changes to that scene will affect all instances.
 
 You can also adjust individual instances. Set the bounce value back to ``0``
-and then in the ``Main`` scene, select one of the instanced balls. Set its
+and then in the ``Main`` scene, select one of the instanced balls. Resources
+like ``PhysicsMaterial`` are shared between instances by default, so we need
+to make it unique. Click on the down arrow and select "Make Unique". Set its
 ``Bounce`` to ``1`` and press "Play".
 
 .. image:: img/instancing_property.png

getting_started/step_by_step/scripting_continued.rst

@@ -89,7 +89,7 @@ Groups
 
 Groups in Godot work like tags you might have come across in other software.
 A node can be added to as many groups as desired. This is a useful feature for
-organizing large scenes. There are two ways to do add nodes to groups. The
+organizing large scenes. There are two ways to add nodes to groups. The
 first is from the UI, using the Groups button under the Node panel:
 
 .. image:: img/groups_in_nodes.png

getting_started/step_by_step/your_first_game.rst

@@ -1145,6 +1145,13 @@ current node at the end of the current frame.
 
     func _on_start_game():
         queue_free()
+ 
+ .. code-tab:: csharp
+
+    public void OnStartGame()
+    {
+        QueueFree();
+    }
           
 Then in ``Main.gd`` add a new line inside the ``_on_MobTimer_timeout()`` function,
 at the end.
@@ -1154,6 +1161,10 @@ at the end.
 
     $HUD.connect("start_game", mob, "_on_start_game")
 
+ .. code-tab:: csharp
+ 
+    GetNode("HUD").Connect("StartGame", mobInstance, "OnStartGame");
+
 This line tells the new Mob node (referenced by the ``mob`` variable) to respond
 to any ``start_game`` signal emitted by the ``HUD`` node by running its
 ``_on_start_game()`` function.

getting_started/workflow/assets/importing_images.rst

@@ -24,6 +24,12 @@ Import options are vast:
 
 .. image:: img/image_import1.png
 
+Detect 3D
+~~~~~~~~~
+
+This option makes Godot be aware of when a texture (which is imported for 2D as default) is used in 3D. If this happens, setting are changed so the texture flags
+are friendlier to 3D (mipmaps, filter and repeat become enabled and compression is changed to VRAM). Texture is also reimported automatically.
+
 Compression
 -----------
 
@@ -153,9 +159,3 @@ Invert Color
 ~~~~~~~~~~~~
 
 Reverses the image's color. This is useful, for example, to convert a height map generated by external programs to depth map to use with :ref:`doc_spatial_material`.
-
-Detect 3D
----------
-
-This option makes Godot be aware of when a texture (which is imported for 2D as default) is used in 3D. If this happens, setting are changed so the texture flags
-are friendlier to 3D (mipmaps, filter and repeat become enabled and compression is changed to VRAM). Texture is also reimported automatically.

getting_started/workflow/assets/importing_translations.rst

@@ -30,7 +30,9 @@ each string. This allows you to revise the text while it is being
 translated to other languages. The unique ID can be a number, a string,
 or a string with a number (it's just a unique string anyway).
 
-Translators also usually prefer to work with spreadsheets.
+.. note:: If you need a more powerful file format, Godot also supports
+          loading translations written in the gettext ``.po`` format. See
+          :ref:`doc_localization_using_gettext` for details.
 
 Translation format
 ------------------
@@ -77,5 +79,3 @@ Importing will also add the translation to the list of
 translations to load when the game runs, specified in project.godot (or the
 project settings). Godot allows loading and removing translations at
 runtime as well.
-
-

getting_started/workflow/export/exporting_for_ios.rst

@@ -39,6 +39,9 @@ After you click **Export Project**, there are still two important options left:
           project's name. When you see **exported_xcode_project_name**
           in the following steps, replace it with the name you used instead.
 
+.. note:: Avoid using spaces when you choose your **exported_xcode_project_name** as
+          this can lead to corruption in your XCode project file.
+
 When the export completes, the output folder should look like this:
 
 .. image:: img/ios_export_output.png

index.rst

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

tutorials/3d/environment_and_post_processing.rst

@@ -136,6 +136,8 @@ In practice, it makes light stand out more across the fog.
 Tonemap
 ^^^^^^^
 
+*This feature is only available when using the GLES3 backend.*
+
 Selects the tone-mapping curve that will be applied to the scene, from a short
 list of standard curves used in the film and game industry. Tone mapping can make
 light and dark areas more homogeneous, even though the result is not that strong.
@@ -148,6 +150,8 @@ Tone mapping options are:
 Auto Exposure (HDR)
 ^^^^^^^^^^^^^^^^^^^
 
+*This feature is only available when using the GLES3 backend.*
+
 Even though, in most cases, lighting and texturing are heavily artist controlled,
 Godot supports a simple high dynamic range implementation with the auto exposure
 mechanism. This is generally used for the sake of realism when combining
@@ -188,6 +192,8 @@ in the Environment.
 Screen-Space Reflections (SSR)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+*This feature is only available when using the GLES3 backend.*
+
 While Godot supports three sources of reflection data (Sky, ReflectionProbe, and
 GIProbe), they may not provide enough detail for all situations. Scenarios
 where Screen Space Reflections make the most sense are when objects are in
@@ -212,6 +218,8 @@ Keep in mind that screen-space-reflections only work for reflecting opaque geome
 Screen-Space Ambient Occlusion (SSAO)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+*This feature is only available when using the GLES3 backend.*
+
 As mentioned in the **Ambient** section, areas where light from light nodes
 does not reach (either because it's outside the radius or shadowed) are lit
 with ambient light. Godot can simulate this using GIProbe, ReflectionProbe,
@@ -255,6 +263,8 @@ Tweaking SSAO is possible with several parameters:
 Depth of Field / Far Blur
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
+*This feature is only available when using the GLES3 backend.*
+
 This effect simulates focal distance on high end cameras. It blurs objects behind
 a given range. It has an initial **Distance** with a **Transition** region
 (in world units):
@@ -267,6 +277,8 @@ the **Quality** may be needed in order to avoid artifacts.
 Depth of Field / Near Blur
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+*This feature is only available when using the GLES3 backend.*
+
 This effect simulates focal distance on high end cameras. It blurs objects close
 to the camera (acts in the opposite direction as far blur).
 It has an initial **Distance** with a **Transition** region (in world units):
@@ -284,6 +296,8 @@ given object:
 Glow
 ^^^^
 
+*This feature is only available when using the GLES3 backend.*
+
 In photography and film, when light amount exceeds the maximum supported by the
 media (be it analog or digital), it generally bleeds outwards to darker regions
 of the image. This is simulated in Godot with the **Glow** effect.
@@ -335,6 +349,8 @@ gets rids of it, at a minimal performance cost.
 Adjustments
 ^^^^^^^^^^^
 
+*This feature is only available when using the GLES3 backend.*
+
 At the end of processing, Godot offers the possibility to do some standard
 image adjustments.
 

tutorials/3d/fps_tutorial/part_one.rst

@@ -189,8 +189,9 @@ Add the following code to ``Player.gd``:
 
         input_movement_vector = input_movement_vector.normalized()
 
-        dir += -cam_xform.basis.z.normalized() * input_movement_vector.y
-        dir += cam_xform.basis.x.normalized() * input_movement_vector.x
+        # Basis vectors are already normalized.
+        dir += -cam_xform.basis.z * input_movement_vector.y
+        dir += cam_xform.basis.x * input_movement_vector.x
         # ----------------------------------
 
         # ----------------------------------
@@ -304,8 +305,9 @@ Add the following code to ``Player.gd``:
 
             inputMovementVector = inputMovementVector.Normalized();
 
-            _dir += -camXform.basis.z.Normalized() * inputMovementVector.y;
-            _dir += camXform.basis.x.Normalized() * inputMovementVector.x;
+            // Basis vectors are already normalized.
+            _dir += -camXform.basis.z * inputMovementVector.y;
+            _dir += camXform.basis.x * inputMovementVector.x;
             //  -------------------------------------------------------------------
 
             //  -------------------------------------------------------------------

tutorials/3d/gi_probes.rst

@@ -6,6 +6,10 @@ GI Probes
 Introduction
 ------------
 
+.. note:: This feature is only available when using the GLES3 backend.
+          :ref:`doc_baked_lightmaps` can be used as an alternative
+          when using the GLES2 renderer.
+
 Just like with :ref:`doc_reflection_probes`, and as stated in
 the :ref:`doc_spatial_material`, objects can show reflected or diffuse light.
 GI Probes are similar to Reflection Probes, but they use a different and more

tutorials/3d/lights_and_shadows.rst

@@ -23,7 +23,7 @@ Light nodes
 -----------
 
 There are three types of light nodes: `Directional light`_,
-`Omni light`_ and `Spot light`_. Let's take a look at the common 
+`Omni light`_ and `Spot light`_. Let's take a look at the common
 parameters for lights:
 
 .. image:: img/light_params.png
@@ -47,7 +47,7 @@ There is a list of generic shadow parameters, each also has a specific function:
 -  **Enabled**: Check to enable shadow mapping in this light.
 -  **Color**: Areas occluded are multiplied by this color. It is black by default, but it can be changed to tint shadows.
 -  **Bias**: When this parameter is too small, self shadowing occurs. When too large, shadows separate from the casters. Tweak to what works best for you.
--  **Contact**: Performs a short screen-space raycast to reduce the gap generated by the bias.
+-  **Contact**: Performs a short screen-space raycast to reduce the gap generated by the bias. Contact shadows are only available when using the GLES3 backend.
 -  **Reverse Cull Faces**: Some scenes work better when shadow mapping is rendered with face-culling inverted.
 
 Below is an image of what tweaking bias looks like. Default values work for most

tutorials/3d/spatial_material.rst

@@ -354,6 +354,8 @@ intermediate values generally works best.
 Clearcoat
 ~~~~~~~~~
 
+*This feature is only available when using the GLES3 backend.*
+
 The *Clearcoat* parameter is used to add a secondary pass of transparent coat
 to the material. This is common in car paint and toys. In practice, it's a
 smaller specular blob added on top of the existing material.
@@ -361,6 +363,8 @@ smaller specular blob added on top of the existing material.
 Anisotropy
 ~~~~~~~~~~
 
+*This feature is only available when using the GLES3 backend.*
+
 This changes the shape of the specular blob and aligns it to tangent space.
 Anisotropy is commonly used with hair, or to make materials such as brushed
 aluminum more realistic. It works especially well when combined with flowmaps.
@@ -381,6 +385,8 @@ AO map. It is recommended to bake ambient occlusion whenever possible.
 Depth
 ~~~~~
 
+*This feature is only available when using the GLES3 backend.*
+
 Setting a depth map on a material produces a ray-marched search to emulate the
 proper displacement of cavities along the view direction. This is not real
 added geometry, but an illusion of depth. It may not work for complex objects,
@@ -392,6 +398,8 @@ but it produces a realistic depth effect for textures. For best results,
 Subsurface Scattering
 ~~~~~~~~~~~~~~~~~~~~~
 
+*This feature is only available when using the GLES3 backend.*
+
 This effect emulates light that penetrates an object's surface, is scattered,
 and then comes out. It is useful to create realistic skin, marble, colored
 liquids, etc.
@@ -410,6 +418,8 @@ such as plant leaves, grass, human ears, etc.
 Refraction
 ~~~~~~~~~~~
 
+*This feature is only available when using the GLES3 backend.*
+
 When refraction is enabled, it supersedes alpha blending, and Godot attempts to
 fetch information from behind the object being rendered instead. This allows
 distorting the transparency in a way similar to refraction in real life.

tutorials/content/procedural_geometry.rst

@@ -111,19 +111,19 @@ Similar code as before, but draw a square using indices:
 
     normal_array[0] = Vector3(0, 0, 1)
     uv_array[0] = Vector2(0, 0)
-    vertex_array[0] = Vector3(-1, -1)
+    vertex_array[0] = Vector3(-1, -1, 0)
 
     normal_array[1] = Vector3(0, 0, 1)
     uv_array[1] = Vector2(0,1)
-    vertex_array[1] = Vector3(-1, 1)
+    vertex_array[1] = Vector3(-1, 1, 0)
 
     normal_array[2] = Vector3(0, 0, 1)
     uv_array[2] = Vector2(1, 1)
-    vertex_array[2] = Vector3(1, 1)
+    vertex_array[2] = Vector3(1, 1, 0)
 
     normal_array[3] = Vector3(0, 0, 1)
     uv_array[3] = Vector2(1, 0)
-    vertex_array[3] = Vector3(1, -1)
+    vertex_array[3] = Vector3(1, -1, 0)
 
     # Indices are optional in Godot, but if they exist they are used.
     index_array[0] = 0

tutorials/i18n/index.rst

@@ -6,4 +6,5 @@ Internationalization
    :name: toc-learn-features-i18n
 
    internationalizing_games
+   localization_using_gettext
    locales

tutorials/i18n/localization_using_gettext.rst

@@ -0,0 +1,143 @@
+.. _doc_localization_using_gettext:
+
+Localization using gettext
+==========================
+
+In addition to :ref:`doc_importing_translations` in CSV format, Godot
+also supports loading translation files written in the GNU gettext
+(``.po``) format.
+
+.. note:: For an introduction to gettext, check out
+          `A Quick Gettext Tutorial <https://www.labri.fr/perso/fleury/posts/programming/a-quick-gettext-tutorial.html>`_.
+          It's written with C projects in mind, but much of the advice
+          also applies to Godot (with the exception of ``xgettext``).
+
+Advantages
+----------
+
+- gettext is a standard format, which can be edited using any text editor
+  or GUI editors such as `Poedit <https://poedit.net/>`_.
+- gettext is supported by translation platforms such as
+  `Transifex <https://www.transifex.com/>`_ and `Weblate <https://weblate.org/>`_,
+  which makes it easier for people to collaborate to localization.
+- Compared to CSV, gettext works better with version control systems like Git,
+  as each locale has its own messages file.
+- Multiline strings are more convenient to edit in gettext files compared
+  to CSV files.
+
+Disadvantages
+-------------
+
+- gettext is a more complex format than CSV and can be harder to grasp for
+  people new to software localization.
+- People who maintain localization files will have to install gettext tools
+  on their system. However, as Godot doesn't use compiled message object files
+  (``.mo``), translators can test their work without having to install
+  gettext tools.
+
+Caveats
+-------
+
+- As Godot uses its own PO file parser behind the scenes
+  (which is more limited than the reference GNU gettext implementation),
+  some features such as pluralization aren't supported.
+
+Installing gettext tools
+------------------------
+
+The command line gettext tools are required to perform maintenance operations,
+such as updating message files. Therefore, it's strongly recommended to
+install them.
+
+- **Windows:** Download an installer from
+  `this page <https://mlocati.github.io/articles/gettext-iconv-windows.html>`_.
+  Any architecture and binary type (shared or static) works;
+  if in doubt, choose the 64-bit static installer.
+- **macOS:** Use `Homebrew <https://brew.sh/>`_ to install gettext with the
+  ``brew install gettext`` command.
+- **Linux:** On most distributions, install the ``gettext`` package from
+  your distribution's package manager.
+
+Creating the PO template
+------------------------
+
+Godot currently doesn't support extracting source strings using ``xgettext``,
+so the ``.pot`` file must be created manually. This file can be placed anywhere
+in the project directory, but it's recommended to keep it in a subdirectory, as
+each locale will be defined in its own file.
+
+Create a directory named `locale` in the project directory. In this directory,
+save a file named ``messages.pot`` with the following contents:
+
+::
+
+    # Don't remove the two lines below, they're required for gettext to work correctly.
+    msgid ""
+    msgstr ""
+
+    msgid "Hello world!"
+    msgstr ""
+
+Messages in gettext are made of ``msgid`` and ``msgstr`` pairs.
+``msgid`` is the source string (usually in English), ``msgstr`` will be
+the translated string.
+
+The ``msgstr`` value in PO template files (``.pot``) should **always** be empty.
+Localization will be done in the generated ``.po`` files instead.
+
+Creating a messages file from a PO template
+-------------------------------------------
+
+The ``msginit`` command is used to turn a PO template into a messages file.
+For instance, to create a French localization file, use the following command
+while in the ``locale`` directory:
+
+::
+
+    msginit --no-translator --input=messages.pot --locale=fr
+
+
+The command above will create a file named ``fr.po`` in the same directory
+as the PO template.
+
+Loading a messages file in Godot
+--------------------------------
+
+To register a messages file as a translation in a project, open the
+**Project Settings**, then go to the **Localization** tab.
+In **Translations**, click **Add…** then choose the ``.po`` file
+in the file dialog. The locale will be inferred from the
+``"Language: <code>\n"`` property in the messages file.
+
+.. note:: See :ref:`doc_internationalizing_games` for more information on
+          importing and testing translations in Godot.
+
+Updating message files to follow the PO template
+------------------------------------------------
+
+After updating the PO template, you will have to update message files so
+that they contain new strings, while removing strings that are no longer
+present in the PO template removed in the PO template. This can be done
+automatically using the ``msgmerge`` tool:
+
+::
+
+    # The order matters: specify the message file *then* the PO template!
+    msgmerge --update --backup=none fr.po messages.pot
+
+
+If you want to keep a backup of the original message file (which would be
+saved as ``fr.po~`` in this example), remove the ``--backup=none`` argument.
+
+Checking the validity of a PO file or template
+----------------------------------------------
+
+It is possible to check whether a gettext file's syntax is valid by running
+the command below:
+
+::
+
+    msgfmt fr.po --check
+
+If there are syntax errors or warnings, they will be displayed in the console.
+Otherwise, ``msgfmt`` won't output anything.

tutorials/inputs/input_examples.rst

@@ -91,7 +91,7 @@ It inherits from the following classes:
         with events so you can check the event type's available properties and
         methods.
 
-You can encounter errors if you try and access a property on an input type that
+You can encounter errors if you try to access a property on an input type that
 doesn't contain it - calling ``position`` on ``InputEventKey`` for example. To
 avoid this, make sure to test the event type first:
 

tutorials/io/encrypting_save_games.rst

@@ -71,7 +71,7 @@ some unique user identifier, for example:
     f.StoreVar(gameState);
     f.Close();
 
-Note that ``OS.get_unique_id()`` only works on iOS and Android.
+Note that ``OS.get_unique_id()`` does not work on UWP or HTML5.
 
 That is all! Thank you for your cooperation, citizen.
 

tutorials/legal/complying_with_licenses.rst

@@ -49,7 +49,7 @@ Some games have a special menu (often in the settings) to display licenses.
 Output log
 ^^^^^^^^^^
 
-Just printing the licensing text using a print() function may be enough on platforms where a global output log is readable (as an example, mobile devices).
+Just printing the licensing text using a :ref:`print() <class_@GDScript_method_print>` function may be enough on platforms where a global output log is readable (as an example, mobile devices).
 
 Accompanying file
 ^^^^^^^^^^^^^^^^^
@@ -64,7 +64,7 @@ If the game includes printed manuals, license text can be included there.
 Third Party licenses
 --------------------
 
-Godot itself contains software written by `third parties <https://github.com/godotengine/godot/blob/master/COPYRIGHT.txt>`_. Most of it does not requiere license inclusion, but some do. Make sure to do it if you are using them. Here is a list of which ones require it:
+Godot itself contains software written by `third parties <https://github.com/godotengine/godot/blob/master/COPYRIGHT.txt>`_. Most of it does not require license inclusion, but some do. Make sure to do it if you are using them. Here is a list of which ones require it:
 
 FreeType
 ^^^^^^^^
@@ -78,7 +78,7 @@ Godot uses `FreeType <https://www.freetype.org/>`_ to render fonts. It's license
 ENet
 ^^^^
 
-If the project being creater is a multiplayer game using the `ENet <http://enet.bespin.org/>`_ driver, ENet has similar licensing terms as Godot
+If the project being created is a multiplayer game using the `ENet <http://enet.bespin.org/>`_ driver, ENet has similar licensing terms as Godot
 
 
 	Copyright (c) 2002-2016 Lee Salzman
@@ -92,7 +92,7 @@ If the project being creater is a multiplayer game using the `ENet <http://enet.
 MBedTLS
 ^^^^^^^
 
-If the is done with Godot 3.1 or above and it utilizes SSL (usually through HTTP requests), the `MBedTLS <https://tls.mbed.org>`_ Apache license needs to be complied by including the following text:
+If the project is done with Godot 3.1 or above and it utilizes SSL (usually through HTTP requests), the `MBedTLS <https://tls.mbed.org>`_ Apache license needs to be complied by including the following text:
 
 
 	MBedTLS is Copyright (C) 2013-2019 ARM

tutorials/misc/instancing_with_signals.rst

@@ -68,7 +68,7 @@ You could do this by adding the bullet to the main scene directly:
     Node bulletInstance = Bullet.Instance();
     GetParent().AddChild(bulletInstance);
 
-However, this will lead to a different problem. Now if you try and test your
+However, this will lead to a different problem. Now if you try to test your
 "Player" scene independently, it will crash on shooting, because there is no
 parent node to access. This makes it a lot harder to test your player code
 independently and also means that if you decide to change your main scene's

tutorials/misc/pausing_games.rst

@@ -50,6 +50,15 @@ property in a node:
 
 .. image:: img/pausemode.png
 
+You can achieve the same result in code:
+
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    func _ready():
+        pause_mode = Node.PAUSE_MODE_PROCESS
+
 By default all nodes have this property in the "Inherit" state. This
 means, that they will only process (or not) depending on what this same
 property is set on the parent node. If the parent is set to "Inherit" ,

tutorials/networking/index.rst

@@ -9,5 +9,3 @@ Networking
    http_request_class
    http_client_class
    ssl_certificates
-
-.. managing_tcp_udp_connections.rst

tutorials/plugins/gdnative/files/cpp_example/SConstruct

@@ -37,37 +37,51 @@ if env['platform'] == '':
     print("No valid target platform selected.")
     quit();
 
+# For the reference:
+# - CCFLAGS are compilation flags shared between C and C++
+# - CFLAGS are for C-specific compilation flags
+# - CXXFLAGS are for C++-specific compilation flags
+# - CPPFLAGS are for pre-processor flags
+# - CPPDEFINES are for pre-processor defines
+# - LINKFLAGS are for linking flags
+
 # Check our platform specifics
 if env['platform'] == "osx":
     env['target_path'] += 'osx/'
     cpp_library += '.osx'
     if env['target'] in ('debug', 'd'):
-        env.Append(CCFLAGS = ['-g','-O2', '-arch', 'x86_64'])
-        env.Append(LINKFLAGS = ['-arch', 'x86_64'])
+        env.Append(CCFLAGS=['-g', '-O2', '-arch', 'x86_64'])
+        env.Append(LINKFLAGS=['-arch', 'x86_64'])
     else:
-        env.Append(CCFLAGS = ['-g','-O3', '-arch', 'x86_64'])
-        env.Append(LINKFLAGS = ['-arch', 'x86_64'])
+        env.Append(CCFLAGS=['-g', '-O3', '-arch', 'x86_64'])
+        env.Append(LINKFLAGS=['-arch', 'x86_64'])
 
 elif env['platform'] in ('x11', 'linux'):
     env['target_path'] += 'x11/'
     cpp_library += '.linux'
     if env['target'] in ('debug', 'd'):
-        env.Append(CCFLAGS = ['-fPIC', '-g3','-Og', '-std=c++17'])
+        env.Append(CCFLAGS=['-fPIC', '-g3', '-Og'])
+        env.Append(CXXFLAGS=['-std=c++17'])
     else:
-        env.Append(CCFLAGS = ['-fPIC', '-g','-O3', '-std=c++17'])
+        env.Append(CCFLAGS=['-fPIC', '-g', '-O3'])
+        env.Append(CXXFLAGS=['-std=c++17'])
 
 elif env['platform'] == "windows":
     env['target_path'] += 'win64/'
     cpp_library += '.windows'
     # This makes sure to keep the session environment variables on windows,
     # that way you can run scons in a vs 2017 prompt and it will find all the required tools
-    env.Append(ENV = os.environ)
+    env.Append(ENV=os.environ)
 
-    env.Append(CCFLAGS = ['-DWIN32', '-D_WIN32', '-D_WINDOWS', '-W3', '-GR', '-D_CRT_SECURE_NO_WARNINGS'])
+    env.Append(CPPDEFINES=['WIN32', '_WIN32', '_WINDOWS', '_CRT_SECURE_NO_WARNINGS'])
+    env.Append(CCFLAGS=['-W3', '-GR'])
     if env['target'] in ('debug', 'd'):
-        env.Append(CCFLAGS = ['-EHsc', '-D_DEBUG', '-MDd'])
+        env.Append(CPPDEFINES=['_DEBUG'])
+        env.Append(CCFLAGS=['-EHsc', '-MDd', '-ZI'])
+        env.Append(LINKFLAGS=['-DEBUG'])
     else:
-        env.Append(CCFLAGS = ['-O2', '-EHsc', '-DNDEBUG', '-MD'])
+        env.Append(CPPDEFINES=['NDEBUG'])
+        env.Append(CCFLAGS=['-O2', '-EHsc', '-MD'])
 
 if env['target'] in ('debug', 'd'):
     cpp_library += '.debug'

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

@@ -102,7 +102,7 @@ You will need to execute the following commands:
 .. code-block:: none
 
     cd gdnative_cpp_example
-    git submodule --init update --recursive
+    git submodule update --init --recursive
 
 This will clone these two repositories into your project folder.
 

tutorials/shading/shading_reference/particle_shader.rst

@@ -20,7 +20,7 @@ to the fragment shader for pixel-processing. Because of this, transform feedback
 shaders can build on themselves each run, unlike other shaders that discard the
 data they have calculated once they draw to the frame buffer.
 
-.. note:: Particle shaders are only available in the GLES3 renderer. If you need 
+.. note:: Particle shaders are only available in the GLES3 backend. If you need
           particles in GLES2, use :ref:`CPUParticles <class_CPUParticles>`.
 
 Render modes

tutorials/shading/your_first_shader/your_first_canvasitem_shader.rst

@@ -57,7 +57,7 @@ the following format:
   
   shader_type canvas_item;
 
-Becuase we are writing a CanvasItem shader, we specify ``canvas_item`` in the first line. All our code will
+Because we are writing a CanvasItem shader, we specify ``canvas_item`` in the first line. All our code will
 go beneath this declaration.
 
 This line tells the engine which built-in variables and functionality to supply you with.

tutorials/shading/your_first_shader/your_first_spatial_shader.rst

@@ -167,15 +167,20 @@ Once you set it up and should look like this.
 
 .. image:: img/noise-set.png
 
-Now, access the noise texture using the ``texture()`` function. ``texture()`` takes the texture as a first
-argument and the position on the texture as the second. We use the ``x`` and ``z`` channels of ``VERTEX`` to 
-determine where on the texture to look up. 
+Now, access the noise texture using the ``texture()`` function. ``texture()`` takes a texture as the first
+argument and a ``vec2`` for the position on the texture as the second argument. We use the ``x`` and ``z``
+channels of ``VERTEX`` to determine where on the texture to look up. ``texture()`` returns a ``vec4`` of the
+``r, g, b, a`` channels at the position. Since the noise texture is grayscale, all of the values are the same,
+so we can use any one of the channels as the height. In this case we'll use the ``r``, or ``x`` channel.
 
 .. code-block:: glsl
 
-  float height = texture(noise, VERTEX.xz / 2.0 ); //divide by the size of the PlaneMesh
+  float height = texture(noise, VERTEX.xz / 2.0 ).x; //divide by the size of the PlaneMesh
   VERTEX.y += height;
 
+Note: ``xyzw`` is the same as ``rgba`` in GLSL, so instead of ``texture().x`` above, we could use ``texture().r``.
+See the `OpenGL documentation <https://www.khronos.org/opengl/wiki/Data_Type_(GLSL)#Vectors>`_ for more details.
+
 Using this code you can see the texture creates random looking hills.
 
 .. image:: img/noise.png
@@ -328,6 +333,7 @@ most of the difficult stuff for you.
   void vertex() {
     vertex_position = VERTEX.xz / 2.0;
     float height = texture(noise, vertex_position).x * height_scale;
+    VERTEX.y += height * height_scale;
   }
 
   void fragment() {