Merge branch 'master' into 3.2

about/faq.rst

@@ -183,6 +183,24 @@ free and open-source integration, consider starting the integration work yoursel
 Godot is not owned by one person; it belongs to the community, and it grows along
 with ambitious community contributors like you.
 
+Why does Godot use Vulkan or OpenGL instead of Direct3D?
+--------------------------------------------------------
+
+Godot aims for cross-platform compatibility and open standards first and
+foremost. OpenGL and Vulkan are the technologies that are both open and
+available (nearly) on all platforms. Thanks to this design decision, a project
+developed with Godot on Windows will run out of the box on Linux, macOS, and
+more.
+
+Since Godot only has a few people working on its renderer, we would prefer
+having fewer rendering backends to maintain. On top of that, using a single API
+on all platforms allows for greater consistency with fewer platform-specific
+issues.
+
+In the long term, we may develop a Direct3D 12 renderer for Godot (mainly for
+the Xbox's purposes), but Vulkan and OpenGL will remain the default rendering
+backends on all platforms, including Windows.
+
 How should assets be created to handle multiple resolutions and aspect ratios?
 ------------------------------------------------------------------------------
 

development/compiling/compiling_for_x11.rst

@@ -79,6 +79,12 @@ Distro-specific one-liners
 |                  |     sudo zypper install scons pkgconfig libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel \ |
 |                  |             libXi-devel Mesa-libGL-devel alsa-devel libpulse-devel libudev-devel libGLU1 yasm             |
 +------------------+-----------------------------------------------------------------------------------------------------------+
+| **NetBSD**       | ::                                                                                                        |
+|                  |                                                                                                           |
+|                  |     pkg_add pkg-config py37-scons yasm                                                                    |
+|                  |                                                                                                           |
+|                  | For audio support, you can optionally install ``pulseaudio``.                                             |
++------------------+-----------------------------------------------------------------------------------------------------------+
 | **Solus**        | ::                                                                                                        |
 |                  |                                                                                                           |
 |                  |     sudo eopkg install -c system.devel scons libxcursor-devel libxinerama-devel libxi-devel \             |

development/cpp/configuring_an_ide/qt_creator.rst

@@ -22,8 +22,8 @@ Importing the project
 
 - Next, you can choose which folders and files will be visible to the project.
   While C/C++ files are added automatically, other extensions can be potentially useful:
-  ``*.py`` for buildsystem files, ``*.java`` for Android platform development,
-  ``*.mm`` for macOS platform development.
+  ``*.glsl`` for shader files, ``*.py`` for buildsystem files,
+  ``*.java`` for Android platform development, ``*.mm`` for macOS platform development.
 
 .. figure:: img/qtcreator-apply-import-filter.png
    :figclass: figure-w480

getting_started/editor/command_line_tutorial.rst

@@ -290,11 +290,11 @@ conversion of assets or custom import/export.
 
 The script must inherit from ``SceneTree`` or ``MainLoop``.
 
-Here is a simple example of how it works:
+Here is a simple ``sayhello.gd`` example of how it works:
 
 .. code-block:: python
 
-    # sayhello.gd
+    #!/usr/bin/env -S godot -s
     extends SceneTree
 
     func _init():
@@ -310,3 +310,20 @@ And how to run it:
 
 If no ``project.godot`` exists at the path, current path is assumed to be the
 current working directory (unless ``--path`` is specified).
+
+The first line of ``sayhello.gd`` above is commonly referred to as
+a *shebang*. If the Godot binary is in your ``PATH`` as ``godot``,
+it allows you to run the script as follows in modern Linux
+distributions, as well as macOS:
+
+::
+    # Mark script as executable.
+    chmod +x sayhello.gd
+    # Prints "Hello!" to standard output.
+    ./sayhello.gd
+
+If the above doesn't work in your current version of Linux or macOS, you can
+always have the shebang run Godot straight from where it is located as follows:
+
+::
+    #!/usr/bin/godot -s

getting_started/scripting/cross_language_scripting.rst

@@ -156,7 +156,7 @@ Calling C# methods from GDScript
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Again, calling C# methods from GDScript should be straightforward. The
-marshalling process will do its best to cast your the arguments to match
+marshalling process will do its best to cast the arguments to match
 function signatures.
 If that's impossible, you'll see the following error: ``Invalid call. Nonexistent function `FunctionName```.
 

getting_started/workflow/export/android_custom_build.rst

@@ -28,9 +28,8 @@ Go to the Project menu, and install the *Custom Build* template:
 Make sure export templates are downloaded. If not, this menu will help you
 download them.
 
-This will create an Gradle-based Android project in ``res://android/build`` and
-place a ``.gdignore`` file in ``res://android`` so the Godot filesystem ignores
-this folder. Editing these files is not needed unless you want to :ref:`create
+A Gradle-based Android project will be created under ``res://android/build``.
+Editing these files is not needed unless you want to :ref:`create
 your own add-ons<doc_android_plugin>`, or you really need to modify the project.
 
 Install the Android SDK (command-line version)
@@ -50,6 +49,10 @@ You need to install a Java SDK (**not** just the runtime or JRE).
 `OpenJDK 8 <https://adoptopenjdk.net/index.html>`__ is required, newer
 versions won't work.
 
+On Windows, make sure that you enable "Set ``JAVA_HOME`` variable" in the *Custom Setup* view
+of the installer. You have to restart Godot after this, otherwise Godot can't
+find the ``JAVA_HOME`` variable.
+
 Download the command-line tools
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -62,12 +65,8 @@ To save disk space, you don't want the full IDE, so don't download it.
     doing the same using Android Studio.
 
 Look on that page for the *Command line tools only* section. Currently, they are listed under
-*Download Options*. Scroll down a bit until you see them.
-
-Download the ZIP file for your platform, there will be a single ``tools``
-folder inside:
-
-.. image:: img/custom_build_zip.png
+*Download Options*. Scroll down a bit until you see them and download the ZIP file for
+your platform.
 
 This may appear a little confusing, but be sure to follow these instructions
 carefully:
@@ -77,16 +76,22 @@ an empty directory). On Windows, the following path is usually good enough:
 
 .. code-block:: none
 
-  C:\users\<yourusername>\Documents\android-sdk
-  
+  C:\users\<yourusername>\android-sdk
+
+Create an empty folder named ``cmdline-tools`` inside of the ``android-sdk`` folder.
+Then unzip the Android SDK ZIP file into the ``android-sdk/cmdline-tools`` folder.
+
 .. note::
 
-    If you already have an android-sdk folder, normally located in ``%LOCALAPPDATA%\Android\Sdk``, 
-    then use this folder instead of creating an empty ``android-sdk`` folder. 
+    If you're on Windows, you must not extract the ZIP archive with the default
+    Windows extractor (e.g. Windows Explorer). You have to use another tool
+    like 7zip, WinRAR or the Powershell ``Expand-Archive`` command. If you
+    extract the archive with the default Windows extractor, the files are not
+    extracted correctly and you will run into errors later on!
+
+The ``cmdline-tools`` folder should now contain the unzipped folder called ``tools``.
+Finally, rename the ``tools`` folder to ``latest``.
 
-Unzip the Android SDK ZIP file into the ``android-sdk`` folder. This folder should 
-now contain the unzipped folder called ``tools``. Rename ``tools`` to ``latest``. 
-Finally, create an empty folder named ``cmdline-tools`` and place ``latest`` into it. 
 Your final directory structure should look like this :
 
 .. code-block:: none
@@ -95,7 +100,7 @@ Your final directory structure should look like this :
   android-sdk/cmdline-tools/
   android-sdk/cmdline-tools/latest
   android-sdk/cmdline-tools/latest/allTheOtherFiles
-  
+
 We need to setup the directory structure this way for the sdkmanager (inside the bin folder) to work.
 
 Accepting the licenses
@@ -136,20 +141,21 @@ keystore (this is needed to build). Go up two folders by writing:
 
 .. code-block:: shell
 
-    cd ..\..
+    cd ..\..\..
 
 (or open a new shell in the ``android-sdk`` folder).
 
-And you need to input the following line (on Linux and macOS, this should work
-out of the box, for Windows there are further instructions below):
+And you need to input the following line (This should work out of the box.
+However, if you haven't set the ``JAVA_HOME`` variable on Windows,
+there are further instructions below):
 
 .. code-block:: shell
 
     keytool -keyalg RSA -genkeypair -alias androiddebugkey -keypass android -keystore debug.keystore -storepass android -dname "CN=Android Debug,O=Android,C=US" -validity 9999
 
-On Windows, the full path to Java should be provided. You need to add ``&`` at
-the beginning of the line if you use PowerShell; it's not needed for the regular
-``cmd.exe`` console.
+On Windows, if you did not install the ``JAVA_HOME`` variable, the full path to Java
+should be provided. You need to add ``&`` at the beginning of the line if you use
+PowerShell; it's not needed for the regular ``cmd.exe`` console.
 
 To make it clearer, here is an capture of a line that works on PowerShell (by
 adding ``&`` and the full Java path before ``keytool.exe``). Again, keep in mind that you

tutorials/audio/audio_buses.rst

@@ -158,9 +158,9 @@ are far apart.
 Distortion
 ~~~~~~~~~~
 
-Distortion effects make the sound "dirty". Godot offers several types of
-distortion: *overdrive*, *tan* and *bit crushing*. Distortion can be used
-to simulate sound coming through a low-quality speaker or device.
+Makes the sound distorted. Godot offers several types of distortion: *overdrive*,
+*tan* and *bit crushing*. Distortion can be used to simulate sound coming through
+a low-quality speaker or device.
 
 EQ
 ~~
@@ -181,13 +181,18 @@ Filter
 
 Filter is what all other filters inherit from and should not be used directly.
 
-HighPassFilter, HighShelfFilter
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+HighPassFilter
+~~~~~~~~~~~~~~
 
-These are filters that cut frequencies below a specific *Cutoff* frequency.
-HighPassFilter and HighShelfFilter are used to reduce the bass content of a
+Cuts frequencies below a specific *Cutoff* frequency.
+HighPassFilter is used to reduce the bass content of a
 signal.
 
+HighShelfFilter
+~~~~~~~~~~~~~~~
+
+Reduces all frequencies above a specific *Cutoff* frequency.
+
 .. _doc_audio_buses_limiter:
 
 Limiter
@@ -197,13 +202,18 @@ A limiter is similar to a compressor, but it's less flexible and designed to
 prevent a signal's amplitude exceeding a given dB threshold. Adding a limiter to
 the Master bus is a safeguard against clipping.
 
-LowPassFilter, LowShelfFilter
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+LowPassFilter
+~~~~~~~~~~~~~
+
+Cuts frequencies above a specific *Cutoff* frequency and can also resonate
+(boost frequencies close to the *Cutoff* frequency). Low pass filters can be
+used to simulate "muffled" sound. For instance, underwater sounds, sounds
+blocked by walls, or distant sounds.
+
+LowShelfFilter
+~~~~~~~~~~~~~~
 
-These are the most common filters, they cut frequencies above a specific
-*Cutoff* frequency and can also resonate (boost frequencies close to the
-*Cutoff* frequency). Low pass filters can be used to simulate "muffled" sound.
-For instance, underwater sounds, sounds blocked by walls, or distant sounds.
+Reduces all frequencies below a specific *Cutoff* frequency.
 
 NotchFilter
 ~~~~~~~~~~~

tutorials/shading/your_first_shader/your_first_spatial_shader.rst

@@ -305,12 +305,12 @@ assign ``VERTEX.xz`` to ``tex_position``.
     ...
   }
 
-And now we can access ``vertex_position`` from the ``fragment()`` function.
+And now we can access ``tex_position`` from the ``fragment()`` function.
 
 .. code-block:: glsl
 
   void fragment() {
-    NORMALMAP = texture(normalmap, vertex_position).xyz;
+    NORMALMAP = texture(normalmap, tex_position).xyz;
   }
 
 With the normals in place the light now reacts to the height of the mesh dynamically.