Merge branch 'master' into 3.2

about/faq.rst

@@ -289,6 +289,18 @@ developer experiences as a whole.
 Bonus points for bringing screenshots, concrete numbers, test cases, or example
 projects (if applicable).
 
+Is it possible to use Godot as a library?
+-----------------------------------------
+
+Godot is meant to be used with its editor. We recommend you give it a try, as it
+will most likely save you time in the long term. There are no plans to make
+Godot usable as a library, as it would make the rest of the engine more
+convoluted and difficult to use for casual users.
+
+If you want to use a rendering library, look into using an established rendering
+engine instead. Keep in mind rendering engines usually have smaller communities
+compared to Godot. This will make it more difficult to find answers to your
+questions.
 
 Why does Godot not use STL (Standard Template Library)
 ------------------------------------------------------

conf.py

@@ -101,6 +101,8 @@ from sphinx.highlighting import lexers
 lexers["gdscript"] = GDScriptLexer()
 # fmt: on
 
+smartquotes = False
+
 # Pygments (syntax highlighting) style to use
 pygments_style = "sphinx"
 highlight_language = "gdscript"

development/compiling/compiling_for_osx.rst

@@ -30,9 +30,19 @@ For compiling under macOS, the following is required:
 Compiling
 ---------
 
-Start a terminal, go to the root directory of the engine source code and type::
+Start a terminal, go to the root directory of the engine source code.
 
-    scons platform=osx --jobs=$(sysctl -n hw.logicalcpu)
+To compile for Intel (x86-64) powered Macs, use::
+
+    scons platform=osx arch=x86_64 --jobs=$(sysctl -n hw.logicalcpu)
+
+To compile for Apple Silicon (ARM64) powered Macs, use (only for Godot 3.2.3+)::
+
+    scons platform=osx arch=arm64 --jobs=$(sysctl -n hw.logicalcpu)
+
+To support both architectures in a single "Universal 2" binary, run the above two commands and then use ``lipo`` to bundle them together::
+
+    lipo -create bin/godot.osx.tools.x86_64 bin/godot.osx.tools.arm64 -output bin/godot.osx.tools.universal
 
 If all goes well, the resulting binary executable will be placed in the
 ``bin/`` subdirectory. This executable file contains the whole engine and
@@ -46,11 +56,11 @@ manager.
 
 To create an ``.app`` bundle like in the official builds, you need to use the
 template located in ``misc/dist/osx_tools.app``. Typically, for an optimized
-editor binary built with ``scons p=osx target=release_debug``::
+editor binary built with ``target=release_debug``::
 
     cp -r misc/dist/osx_tools.app ./Godot.app
     mkdir -p Godot.app/Contents/MacOS
-    cp bin/godot.osx.tools.64 Godot.app/Contents/MacOS/Godot
+    cp bin/godot.osx.opt.tools.universal Godot.app/Contents/MacOS/Godot
     chmod +x Godot.app/Contents/MacOS/Godot
 
 Compiling a headless/server build

development/compiling/introduction_to_the_buildsystem.rst

@@ -212,6 +212,18 @@ directory paths containing such modules:
 
     :ref:`doc_custom_modules_in_c++`
 
+Cleaning generated files
+------------------------
+
+Sometimes, you may encounter an error due to generated files being present. You
+can remove them by using ``scons --clean <options>``, where ``<options>`` is the
+list of build options you've used to build Godot previously.
+
+Alternatively, you can use ``git clean -fixd`` which will clean build artifacts
+for all platforms and configurations. Beware, as this will remove all untracked
+and ignored files in the repository. Don't run this command if you have
+uncommitted work!
+
 Other build options
 -------------------
 

development/cpp/binding_to_external_libraries.rst

@@ -8,8 +8,8 @@ Modules
 
 The Summator example in :ref:`doc_custom_modules_in_c++` is great for small,
 custom modules, but what if you want to use a larger, external library?
-Let's look at an example using Festival, a speech synthesis (text-to-speech)
-library written in C++.
+Let's look at an example using `Festival <http://www.cstr.ed.ac.uk/projects/festival/>`_,
+a speech synthesis (text-to-speech) library written in C++.
 
 To bind to an external library, set up a module directory similar to the Summator example:
 
@@ -163,11 +163,20 @@ environment's paths:
 
 .. code-block:: python
 
-    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
-    env_tts.Append(LIBS=['Festival', 'estools', 'estbase', 'eststring'])
+    # These paths are relative to /modules/tts/
+    env_tts.Append(CPPPATH=["speech_tools/include", "festival/src/include"])
+
+    # LIBPATH and LIBS need to be set on the real "env" (not the clone)
+    # to link the specified libraries to the Godot executable.
+
+    # This is a path relative to /modules/tts/ where your .a libraries reside.
+    # If you are compiling the module externally (not in the godot source tree),
+    # these will need to be full paths.
+    env.Append(LIBPATH=['libpath'])
+
+    # Check with the documentation of the external library to see which library
+    # files should be included/linked.
+    env.Append(LIBS=['Festival', 'estools', 'estbase', 'eststring'])
 
 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).

development/cpp/common_engine_methods_and_macros.rst

@@ -70,7 +70,7 @@ Internationalize a string
 There are two types of internationalization in Godot's codebase:
 
 - ``TTR()``: **Editor ("tools") translations** will only be processed in the
-  editor. If an user uses the same text in one of their projects, it won't be
+  editor. If a user uses the same text in one of their projects, it won't be
   translated if they provide a translation for it. When contributing to the
   engine, this is generally the macro you should use for localizable strings.
 - ``RTR()``: **Run-time translations** will be automatically localized in
@@ -102,7 +102,7 @@ To insert placeholders in localizable strings, wrap the localization macro in a
 Clamp a value
 -------------
 
-Godot has provides macros for clamping a value with a lower bound (``MAX``), an
+Godot provides macros for clamping a value with a lower bound (``MAX``), an
 upper bound (``MIN``) or both (``CLAMP``):
 
 .. code-block:: cpp

development/cpp/custom_modules_in_cpp.rst

@@ -342,22 +342,30 @@ 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(CCFLAGS=['-fPIC'])  # Needed to compile shared library
-    # We don't want godot's dependencies to be injected into our shared library.
+
+    # Position-independent code is required for a shared library.
+    module_env.Append(CCFLAGS=['-fPIC'])
+
+    # Don't inject Godot's dependencies into our shared library.
     module_env['LIBS'] = []
 
-    # Now define the shared library. Note that by default it would be built
-    # into the module's folder, however it's better to output it into `bin`
-    # next to the Godot binary.
+    # Define the shared library. By default, it would be built in the module's
+    # folder, however it's better to output it into `bin` next to the
+    # Godot binary.
     shared_lib = module_env.SharedLibrary(target='#bin/summator', source=sources)
 
-    # Finally, notify the main env it has our shared library as a new dependency.
-    # To do so, SCons wants the name of the lib with it custom suffixes
+    # Finally, notify the main build environment it now has our shared library
+    # as a new dependency.
+
+    # LIBPATH and LIBS need to be set on the real "env" (not the clone)
+    # to link the specified libraries to the Godot executable.
+
+    env.Append(LIBPATH=['#bin'])
+
+    # SCons wants the name of the library with it custom suffixes
     # (e.g. ".x11.tools.64") but without the final ".so".
-    # We pass this along with the directory of our library to the main env.
     shared_lib_shim = shared_lib[0].name.rsplit('.', 1)[0]
     env.Append(LIBS=[shared_lib_shim])
-    env.Append(LIBPATH=['#bin'])
 
 Once compiled, we should end up with a ``bin`` directory containing both the
 ``godot*`` binary and our ``libsummator*.so``. However given the .so is not in

getting_started/editor/external_editor.rst

@@ -3,6 +3,10 @@
 Using an external text editor
 ==============================
 
+.. warning::
+
+    `External editors are currently incompatible with Godot's "Sync Script Changes" feature. <https://github.com/godotengine/godot/issues/10946>`__
+
 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``

getting_started/scripting/gdscript/gdscript_basics.rst

@@ -629,7 +629,7 @@ expressions and must be assigned on initialization.
     const E = [1, 2, 3, 4][0] # Constant expression: 1.
     const F = sin(20) # 'sin()' can be used in constant expressions.
     const G = x + 20 # Invalid; this is not a constant expression!
-    const H = A + 20 # Constant expression: 25.
+    const H = A + 20 # Constant expression: 25 (`A` is a constant).
 
 Although the type of constants is inferred from the assigned value, it's also
 possible to add explicit type specification::
@@ -639,6 +639,12 @@ possible to add explicit type specification::
 
 Assigning a value of an incompatible type will raise an error.
 
+.. note::
+
+    Since arrays and dictionaries are passed by reference, constants are "flat".
+    This means that if you declare a constant array or dictionary, it can still
+    be modified afterwards. They can't be reassigned with another value though.
+
 Enums
 ^^^^^
 
@@ -1571,7 +1577,7 @@ multiple times, you can yield to the ``completed`` signal conditionally:
         return result
 
 This ensures that the function returns whatever it was supposed to return
-irregardless of whether coroutines were used internally. Note that using
+regardless of whether coroutines were used internally. Note that using
 ``while`` would be redundant here as the ``completed`` signal is only emitted
 when the function didn't yield anymore.
 

getting_started/workflow/best_practices/scenes_versus_scripts.rst

@@ -41,7 +41,7 @@ a change in API:
         public class Game : Node
         {
             public readonly Script MyNodeScr = (Script)ResourceLoader.Load("MyNode.cs");
-            public readonly PackedScene MySceneScn = (PackedScene)ResourceLoader.load("MyScene.tscn");
+            public readonly PackedScene MySceneScn = (PackedScene)ResourceLoader.Load("MyScene.tscn");
             public Node ANode;
             public Node MyNode;
             public Node MyScene;

getting_started/workflow/export/exporting_for_android.rst

@@ -31,7 +31,7 @@ macOS, you can find it in the ``~/.android`` directory).
 If you can't find it or need to generate one, the keytool command from
 the JDK can be used for this purpose::
 
-    keytool -keyalg RSA -genkeypair -alias androiddebugkey -keypass android -keystore debug.keystore -storepass android -dname "CN=Android Debug,O=Android,C=US" -validity 9999
+    keytool -keyalg RSA -genkeypair -alias androiddebugkey -keypass android -keystore debug.keystore -storepass android -dname "CN=Android Debug,O=Android,C=US" -validity 9999 -deststoretype pkcs12
 
 This will create a ``debug.keystore`` file in your current directory. You should move it to a memorable location such as ``%USERPROFILE%\.android\``, because you will need its location in a later step. For more information on ``keytool`` usage, see `this Q&A article <https://godotengine.org/qa/21349/jdk-android-file-missing>`__.
 

tutorials/inputs/input_examples.rst

@@ -194,7 +194,7 @@ the :kbd:`T`:
     {
         if (inputEvent is InputEventKey keyEvent && keyEvent.Pressed)
         {
-            if ((Keylist)keyEvent.Scancode == KeyList.T)
+            if ((KeyList)keyEvent.Scancode == KeyList.T)
             {
                 GD.Print("T was pressed");
             }

tutorials/platform/android_in_app_purchases.rst

@@ -116,7 +116,7 @@ Full example:
 
 ::
 
-    var query = payment.queryPurchases()
+    var query = payment.queryPurchases("inapp") # Or "subs" for subscriptions
     if query.status == OK:
         for purchase in query.purchases:
             if purchase.sku == "my_iap_item":
@@ -135,7 +135,7 @@ acknowledges a purchase.
 
 ::
 
-    var query = payment.queryPurchases()
+    var query = payment.queryPurchases("inapp") # Or "subs" for subscriptions
     if query.status == OK:
         for purchase in query.purchases:
             if purchase.sku == "my_consumable_iap_item":

tutorials/plugins/editor/import_plugins.rst

@@ -178,7 +178,7 @@ good practice to use an enum so you can refer to them using names.
     tool
     extends EditorImportPlugin
 
-    enum Presets { PRESET_DEFAULT }
+    enum Presets { DEFAULT }
 
     ...
 
@@ -199,7 +199,7 @@ now, but we can make this method future-proof by returning the size of our
 
     func get_preset_name(preset):
         match preset:
-            PRESET_DEFAULT:
+            Presets.DEFAULT:
                 return "Default"
             _:
                 return "Unknown"
@@ -222,7 +222,7 @@ you do this you have to be careful when you add more presets.
 
     func get_import_options(preset):
         match preset:
-            PRESET_DEFAULT:
+            Presets.DEFAULT:
                 return [{
                            "name": "use_red_anyway",
                            "default_value": false

tutorials/shading/migrating_to_godot_shader_language.rst

@@ -70,8 +70,8 @@ fragment shader, rename ``main`` to ``fragment``.
 Constants
 ^^^^^^^^^
 
-Godot currently does not support constants. You can fake the functionality by using a uniform initialized
-to the value, but you will not benefit from the increased speed from using a constant.
+Global array constants are not supported in Godot 3.2.x. You can fake the functionality by using a uniform
+initialized to the value, but you will not benefit from the increased speed from using a constant.
 
 Macros
 ^^^^^^
@@ -133,7 +133,7 @@ Types
 ^^^^^
 
 Shadertoy uses the webgl spec, so it runs a slightly different version of GLSL. However, it still
-has the regular types, including `Constants`_ and macros.
+has the regular types, including constants and macros.
 
 mainImage
 ^^^^^^^^^
@@ -200,7 +200,7 @@ Types
 ^^^^^
 
 The Book of Shaders uses the webgl spec, so it runs a slightly different version of GLSL. However, it still
-has the regular types, including `Constants`_ and macros.
+has the regular types, including constants and macros.
 
 Main
 ^^^^

tutorials/shading/shading_reference/spatial_shader.rst

@@ -293,7 +293,7 @@ Below is an example of a custom light function using a Lambertian lighting model
 .. code-block:: glsl
 
     void light() {
-        DIFFUSE_LIGHT += dot(NORMAL, LIGHT) * ATTENUATION * ALBEDO;
+        DIFFUSE_LIGHT += clamp(dot(NORMAL, LIGHT), 0.0, 1.0) * ATTENUATION * ALBEDO;
     }
 
 If you want the lights to add together, add the light contribution to ``DIFFUSE_LIGHT`` using ``+=``, rather than overwriting it.

tutorials/vr/vr_primer.rst

@@ -127,6 +127,9 @@ in the `GodotVR Repository <https://github.com/GodotVR>`_.
   (desktop headsets only).
 * `Godot OpenHMD <https://github.com/GodotVR/godot_openhmd>`_ supports OpenHMD, an open source
   API and drivers for headsets.
+* `Godot OpenXR <https://github.com/GodotVR/godot_openxr>`_ supports OpenXR, an open standard
+  for VR and AR software. This plugin is early in development, only supports Linux and requires
+  extra setup described in the repository.
 
 These plugins can be downloaded from GitHub or the Godot Asset Library.