Merge branch 'master' into 3.2

getting_started/workflow/assets/import_process.rst

@@ -11,20 +11,27 @@ of a separate directory with source assets. Without doing this, it was
 impossible to specify how to convert and change import flags for
 textures, audio files, scenes, etc.
 
-In Godot 3.0, we use a more modern approach to importing: Simply drop
+In Godot 3.0+, we use a more modern approach to importing: Simply drop
 your assets (image files, scenes, audio files, fonts, etc) directly in the
 project folder (copy them manually with your OS file explorer).
 Godot will automatically import these files internally
 and keep the imported resources hidden in a res://.import folder.
 
-This allows changing all the import parameters transparently.
+This means that when trying to access imported assets through code you
+need to use the :ref:`Resource Loader<class_ResourceLoader>` as it will
+automatically take into account where the internal files are saved. If you
+try and access an imported asset using the :ref:`File <class_File>` class
+it will work in the editor, but break in the exported project.
+
+However, the :ref:`Resource Loader<class_ResourceLoader>` cannot access
+non imported files, only the :ref:`File <class_File>` class can.
 
 Changing import parameters
 --------------------------
 
-Changing the import parameters of an asset in Godot (again, keep in mind
-import parameters are only present in non-native Godot resource types) is
-easy. Select the relevant resource in the filesystem dock:
+To change the import parameters of an asset in Godot (again, keep in mind
+import parameters are only present in non-native Godot resource types)
+select the relevant resource in the filesystem dock:
 
 .. image:: img/asset_workflow1.png
 
@@ -35,6 +42,22 @@ Changing the import parameters of several assets at the same time is also
 possible. Simply select all of them together in the resources dock and the
 exposed parameters will apply to all of them when reimporting.
 
+Reimporting multiple assets
+---------------------------
+
+While working on a project you may find that several assets need to have
+the same parameters changed, such as enabling mipmaps, but you only want
+those specific parameters changed. To do this, select every asset you want
+to reimport in the file system. In the import tab there will now be a
+checkbox to the left of every import parameter.
+
+.. image:: img/reimport_multiple.png
+
+Select the checkbox of the parameters you want to change on your imported
+assets, then change the parameters normally. Finally, click the reimport
+button and every selected asset will be reimported with only those
+parameters changed.
+
 Automatic reimport
 ------------------
 

getting_started/workflow/assets/importing_images.rst

@@ -3,35 +3,6 @@
 Importing images
 ================
 
-Why import them?
-----------------
-
-In Godot 3+, image files are no longer native resources and they must be imported.
-The reason behind this is the large amount of configuration parameters that
-image files can be imported with.
-
-This small tutorial will explain what these parameters are and how to best
-make use of them.
-
-Importing textures
-------------------
-
-The default action in Godot is to import images as textures. Textures are stored
-in video memory and can't be accessed directly. This is what makes drawing them
-efficient.
-
-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.
-
-.. _doc_importing_images_supported_formats:
-
 Supported image formats
 -----------------------
 
@@ -63,6 +34,23 @@ Godot can import the following image formats:
     If you've compiled the Godot editor from source with specific modules disabled,
     some formats may not be available.
 
+Importing textures
+------------------
+
+The default action in Godot is to import images as textures. Textures are stored
+in video memory and can't be accessed directly. This is what makes drawing them
+efficient.
+
+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
 -----------
 
@@ -212,3 +200,11 @@ 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`.
+
+Svg
+---
+
+Scale
+~~~~~
+
+This option only applies to SVG files. It controls the scale of the SVG image. The default scale (1.0) will make the imported SVG match its original design scale.

getting_started/workflow/best_practices/introduction_best_practices.rst

@@ -7,7 +7,7 @@ This series is a collection of best practices to help you work efficiently with
 Godot.
 
 Godot allows for a great amount of flexibility in how you structure a project's
-codebase and break it down into scenes. Each approach has its own pros and
+codebase and break it down into scenes. Each approach has its pros and
 cons, and they can be hard to weigh until you've worked with the engine for long enough.
 
 There are always many ways to structure your code and solve specific programming

getting_started/workflow/best_practices/scenes_versus_scripts.rst

@@ -147,6 +147,60 @@ this way.
 
 On the downside, it also means having to use largely imperative programming.
 
+Performance of Script vs PackedScene
+------------------------------------
+
+One last aspect to consider when choosing scenes and scripts is execution speed.
+
+As the size of objects increases, the scripts' necessary size to create and
+initialize them grows much larger. Creating node hierarchies demonstrates this.
+Each Node's logic could be several hundred lines of code in length.
+
+The code example below creates a new ``Node``, changes its name, assigns a
+script to it, sets its future parent as its owner so it gets saved to disk along
+with it, and finally adds it as a child of the ``Main`` node:
+
+.. tabs::
+  .. code-tab:: gdscript GDScript
+
+    # Main.gd
+    extends Node
+
+    func _init():
+        var child = Node.new()
+        child.name = "Child"
+        child.script = preload("Child.gd")
+        child.owner = self
+        add_child(child)
+
+  .. code-tab:: csharp
+
+    using System;
+    using Godot;
+
+    public class Main : Resource
+    {
+        public Node Child { get; set; }
+
+        public Main()
+        {
+            Child = new Node();
+            Child.Name = "Child";
+            Child.Script = ResourceLoader.Load<Script>("child.gd");
+            Child.Owner = this;
+            AddChild(Child);
+        }
+    }
+
+Script code like this is much slower than engine-side C++ code. Each instruction
+makes a call to the scripting API which leads to many "lookups" on the back-end
+to find the logic to execute.
+
+Scenes help to avoid this performance issue. :ref:`PackedScene
+<class_PackedScene>`, the base type that scenes inherit from, defines resources
+that use serialized data to create objects. The engine can process scenes in
+batches on the back-end and provide much better performance than scripts.
+
 Conclusion
 ----------
 

getting_started/workflow/best_practices/what_are_godot_classes.rst

@@ -1,127 +1,59 @@
 .. _doc_what_are_godot_classes:
 
-Godot scenes and scripts are classes
-====================================
+Applying object-oriented principles in Godot
+============================================
 
-In Godot, scripts and scenes can both be the equivalent of classes in an
-Object-Oriented programming language. The main difference is that scenes are
-`declarative code <https://en.wikipedia.org/wiki/Declarative_programming>`_,
-while scripts can contain `imperative code
-<https://en.wikipedia.org/wiki/Imperative_programming>`_.
+The engine offers two main ways to create reusable objects: scripts and scenes. Neither of these
+technically define classes under the hood.
 
-As a result, many best practices in Godot boil down to applying Object-Oriented
-design principles to the scenes, nodes, or scripts that make up your game.
+Still, many best practices using Godot involve applying object-oriented programming principles to
+the scripts and scenes that compose your game. That is why it's useful to understand how we can
+think of them as classes.
 
-This guide explains how scripts and scenes work in the engine's core, to help
-you get a sense of how Godot works under the hood, and to help you better
-understand where some of this series' best practices come from.
+This guide briefly explains how scripts and scenes work in the engine's core to help you understand
+how they work under the hood.
 
-Making sense of classes in Godot
---------------------------------
+How scripts work in the engine
+------------------------------
 
-Godot Engine provides built-in classes like :ref:`Node <class_Node>`.
-User-created types are not technically classes. Instead, they are resources that
-tell the engine a sequence of initializations to perform on one of the engine's
-built-in classes.
+The engine provides built-in classes like :ref:`Node <class_Node>`. You can extend those to create
+derived types using a script.
 
-Godot's internal classes have methods that register a class's data with a
-:ref:`ClassDB <class_ClassDB>`. This database provides runtime access to class
-information. ``ClassDB`` contains information about classes like:
+These scripts are not technically classes. Instead, they are resources that tell the engine a
+sequence of initializations to perform on one of the engine's built-in classes.
 
-- properties
-- methods
-- constants
-- signals
+Godot's internal classes have methods that register a class's data with a :ref:`ClassDB
+<class_ClassDB>`. This database provides runtime access to class information. ``ClassDB`` contains
+information about classes like:
 
-This ``ClassDB`` is what Objects check against when performing an operation like
-accessing a property or calling a method. ``ClassDB`` checks the database's
-records and the records of the Object's base types to see if the Object supports
-the operation.
+- Properties.
+- Methods.
+- Constants.
+- Signals.
 
-On the engine's side, every class defines a static ``_bind_methods()`` function
-that describes what C++ content it registers to the database and how. When you
-use the engine, you can extend the methods, properties, and signals available from
-the ``ClassDB`` by attaching a :ref:`Script <class_Script>` to your node.
+This ``ClassDB`` is what objects check against when performing an operation like accessing a
+property or calling a method. It checks the database's records and the object's base types' records
+to see if the object supports the operation.
 
-Objects check their attached script before the database. This is why scripts can
-override built-in methods. If a script defines a ``_get_property_list()`` method,
-Godot appends that data to the list of properties the Object fetches from the
-ClassDB. The same is true for other declarative code.
-
-Even scripts that don't inherit from a built-in type, i.e. scripts that don't
-start with the ``extends`` keyword, implicitly inherit from the engine's base
-:ref:`Reference <class_Reference>` class. This allows the Object to defer
-to the script's content where the engine logic deems appropriate.
+Attaching a :ref:`Script <class_Script>` to your object extends the methods, properties, and signals
+available from the ``ClassDB``.
 
 .. note::
 
-   As a result, you can instance scripts without the ``extends`` keyword
-   from code, but you cannot attach them to a :ref:`Node <class_Node>`
+    Even scripts that don't use the ``extends`` keyword implicitly inherit from the engine's base
+    :ref:`Reference <class_Reference>` class. As a result, you can instantiate scripts without the
+    ``extends`` keyword from code. Since they extend ``Reference`` though, you cannot attach them to
+    a :ref:`Node <class_Node>`.
 
+Scenes
+------
 
-Scripting performances and PackedScene
---------------------------------------
+The behavior of scenes has many similarities to classes, so it can make sense to think of a scene as
+a class. Scenes are reusable, instantiable, and inheritable groups of nodes. Creating a scene is
+similar to having a script that creates nodes and adds them as children using ``add_child()``.
 
-As the size of Objects increases, the scripts' necessary size to create them
-grows much, much larger. Creating node hierarchies demonstrates this. Each
-individual Node's logic could be several hundred lines of code in length.
-
-Let's see a simple example of creating a single ``Node`` as a child. The code
-below creates a new ``Node``, changes its name, assigns a script to it, sets its
-future parent as its owner so it gets saved to disk along with it, and finally
-adds it as a child of the ``Main`` node:
-
-.. tabs::
-  .. code-tab:: gdscript GDScript
-
-    # Main.gd
-    extends Node
-
-    func _init():
-        var child = Node.new()
-        child.name = "Child"
-        child.script = preload("Child.gd")
-        child.owner = self
-        add_child(child)
-
-  .. code-tab:: csharp
-
-    using System;
-    using Godot;
-
-    namespace ExampleProject
-    {
-        public class Main : Resource
-        {
-            public Node Child { get; set; }
-
-            public Main()
-            {
-                Child = new Node();
-                Child.Name = "Child";
-                Child.Script = (Script)ResourceLoader.Load("child.gd");
-                Child.Owner = this;
-                AddChild(Child);
-            }
-        }
-    }
-
-Script code like this is much slower than engine-side C++ code. Each change
-makes a separate call to the scripting API which leads to many "look-ups" on the
-back-end to find the logic to execute.
-
-Scenes help to avoid this performance issue. :ref:`PackedScene
-<class_PackedScene>`, the base type that scenes inherit from, are resources that
-use serialized data to create objects. The engine can process scenes in batches
-on the back-end and provide much better performance than scripts.
-
-Scenes and scripts are objects
-------------------------------
-
-Why is any of this important to scene organization? Because scenes *are*
-objects. One often pairs a scene with a scripted root node that makes use of the
-sub-nodes. This means that the scene is often an extension of the script's
-declarative code.
+We often pair a scene with a scripted root node that makes use of the scene's nodes. As such, the
+scene is often an extension of the script's declarative code.
 
 The content of a scene helps to define:
 
@@ -130,10 +62,11 @@ The content of a scene helps to define:
 - How they are initialized
 - What signal connections they have with each other
 
-Many Object-Oriented principles which apply to written code *also* apply to
-scenes.
+Why is any of this important to scene organization? Because instances of scenes *are* objects. As a
+result, many object-oriented principles that apply to written code also apply to scenes: single
+responsibility, encapsulation, and others.
 
-The scene is *always an extension of the script attached to its root node*. You
-can see all the nodes it contains as part of a single class.
+The scene is *always an extension of the script attached to its root node*, so you can interpret it
+as part of a class.
 
-Most of the tips and techniques explained in this series will build on this.
+Most of the techniques explained in this best practices series build on this point.

getting_started/workflow/export/changing_application_icon_for_windows.rst

@@ -7,6 +7,25 @@ By default, the exported project's icon will be the Godot icon.
 You will most likely want to change that for your project. There are two types
 of icons that can be changed on Windows: the file icon and the taskbar icon.
 
+Creating an ICO file
+--------------------
+
+Windows does not use formats such as png or jpg for application icons. Instead,
+it uses a Windows-only format called ICO. You can create your application icon
+in any program but you will have to convert it to an ICO file using a program such 
+as GIMP.
+
+`This video tutorial <https://www.youtube.com/watch?v=uqV3UfM-n5Y>`_ goes over how to
+export an ICO file with GIMP.
+
+It is also possible to convert a PNG image to an hiDPI-friendly ICO file
+using this `ImageMagick <https://www.imagemagick.org/>`_ command:
+
+.. code-block:: none
+
+    magick convert icon.png -define icon:auto-resize=256,128,64,48,32,16 icon.ico
+
+
 Changing the taskbar icon
 -------------------------
 
@@ -16,16 +35,25 @@ is running.
 .. image:: img/icon_taskbar_icon.png
 
 To change the taskbar icon, go to
-**Project → Project Settings → Application → Config → Icon**.
-Click on the folder icon and select your desired icon.
-
-.. note:: This is also the icon that gets displayed in the Godot project list.
+**Project → Project Settings → Application → Config → Windows Native Icon**.
+Click on the folder icon and select your ICO file.
 
 .. image:: img/icon_project_settings.png
 
+This setting only changes the icon for your exported game on Windows. 
+To set the icon for macOS, use ``Macos Native Icon``. And for any other platform,
+use the ``Icon`` setting.
+
 Changing the file icon
 ----------------------
 
+.. warning::
+
+    There are `known issues <https://github.com/godotengine/godot/issues/33466>`__
+    when changing the application icon in executables that embed a PCK file.
+    It's recommended to avoid using rcedit for now if you choose to enable the
+    **Embed Pck** option for your Windows export preset in the Export dialog.
+
 The file icon is the icon of the executable that you click on to start
 the project.
 
@@ -52,10 +80,6 @@ Go to **Project → Export**. Assuming you have already created
 a Windows Desktop preset, select your icon in ICO format in
 the **Application → Icon** field.
 
-.. note:: You can use software such as GIMP to export an ICO image.
-          For more information, please refer to
-          `this tutorial <http://skyboygames.com/easily-create-a-windows-app-icon-with-gimp/>`_.
-
 .. image:: img/icon_export_settings.png
 
 Testing the result
@@ -65,28 +89,6 @@ You can now export the project. If it worked correctly, you should see this:
 
 .. image:: img/icon_result.png
 
-ICO file requirements
----------------------
-
-Regardless of which program you use to create your
-`ICO file <https://en.wikipedia.org/wiki/ICO_(file_format)>`_, there are
-some requirements to ensure the icon (and your executable) works on Windows.
-
-This is a bit tricky, as can be seen in the following Stack Overflow threads:
-`one <https://stackoverflow.com/q/3236115/>`_,
-`two <https://stackoverflow.com/q/40749785/>`_.
-
-Your ICO file should at least contain icons in the following resolutions:
-16×16, 48×48 and 256×256.
-
-If you want to fully support high-DPI screens, this is the full list of
-supported icon sizes on Windows 10:
-16, 20, 24, 28, 30, 31, 32, 40, 42, 47, 48, 56, 60, 63, 84
-and one larger than 255 pixels (such as 256, 512 or 1024).
-
-It is also possible to convert a PNG image to an hiDPI-friendly ICO file
-using this `ImageMagick <https://www.imagemagick.org/>`_ command:
-
-.. code-block:: none
-
-    magick convert icon.png -define icon:auto-resize=256,128,64,48,32,16 icon.ico
+.. note:: if your icon isn't showing up properly, on Windows 10, try clearing 
+             the icon cache. To do so, open `Run` and call the command 
+             ``ie4uinit.exe -ClearIconCache`` or ``ie4uinit.exe -show``.

getting_started/workflow/export/exporting_for_dedicated_servers.rst

@@ -82,6 +82,34 @@ different name, you can specify the path to the PCK file using the
 
     ./godot-server --main-pack my_project.pck
 
+Starting the dedicated server
+-----------------------------
+
+If both your client and server are part of the same Godot project, you will have
+to add a way to start the server directly using a command-line argument. This
+can be done by adding the following code snippet in your main scene (or a
+singleton)'s ``_ready()`` method::
+
+    if "--server" in OS.get_cmdline_args():
+        # Run your server startup code here...
+        # Using this check, you can start a dedicated server by running
+        # a Godot binary (headless or not) with the `--server` command-line argument.
+        pass
+
+Alternatively, you can make the dedicated server always start up if a headless
+or server binary is detected::
+
+    # Note: Feature tags are case-sensitive! It's "Server", not "server".
+    if OS.has_feature("Server"):
+        # Run your server startup code here...
+        # Note that using this check may break unit testing scripts when
+        # running them with headless or server binaries.
+        pass
+
+If your client and server are separate Godot projects, your server should most
+likely be configured in a way where running the main scene starts a server
+automatically.
+
 Next steps
 ----------
 

getting_started/workflow/export/exporting_for_pc.rst

@@ -12,3 +12,8 @@ export system. When exporting for PC (Linux, Windows, macOS), the exporter
 takes all the project files and creates a ``data.pck`` file. This file is
 bundled with a specially optimized binary that is smaller, faster and
 does not contain the editor and debugger.
+
+.. warning::
+
+    If you export for Windows with embedded PCK files, you will not be able to
+    sign the program, it will break.

getting_started/workflow/export/index.rst

@@ -10,11 +10,11 @@ Export
    exporting_pcks
    feature_tags
    exporting_for_pc
-   exporting_for_ios
+   changing_application_icon_for_windows
    exporting_for_uwp
+   exporting_for_ios
    exporting_for_android
+   android_custom_build
    exporting_for_web
    exporting_for_dedicated_servers
    one-click_deploy
-   android_custom_build
-   changing_application_icon_for_windows

getting_started/workflow/project_setup/version_control_systems.rst

@@ -35,3 +35,12 @@ There are some folders Godot creates you should have your VCS ignore:
   project, including sensitive information such as Android keystore credentials.
 - ``.mono/``: This folder stores automatically-generated Mono files. It only exists
   in projects that use the Mono version of Godot.
+
+Working with Git on Windows
+---------------------------
+
+Most Git for Windows clients are configured with the ``core.autocrlf`` set to ``true``.
+This can lead to files unnecessarily being marked as modified by Git due to their line endings being converted automatically.
+It is better to set this option as::
+
+    git config --global core.autocrlf input