Merge branch 'master' into 3.2

about/faq.rst

@@ -243,6 +243,12 @@ as well as the `unofficial Python support <https://github.com/touilleMan/godot-p
 This would be a good starting point to see how another third-party library
 integrates with Godot.
 
+When is the next release of Godot out?
+--------------------------------------
+
+When it's ready! See :ref:`doc_release_policy_when_is_next_release_out` for more
+information.
+
 I would like to contribute! How can I get started?
 --------------------------------------------------
 

about/release_policy.rst

@@ -65,6 +65,8 @@ for each Godot version:
 Pre-release Godot versions aren't intended to be used in production and are
 provided on a best-effort basis.
 
+.. _doc_release_policy_when_is_next_release_out:
+
 When is the next release out?
 -----------------------------
 

development/compiling/optimizing_for_size.rst

@@ -151,18 +151,3 @@ If you build from source, remember to strip debug symbols from binaries:
 ::
 
     strip godot.64
-
-Using UPX to compress binaries
-------------------------------
-
-If you are targeting desktop platforms, the
-`UPX <https://upx.github.io/>`_ compressor can be used.
-This can reduce binary size considerably.
-
-.. warning::
-
-    You cannot use embedded PCK files with UPX compression.
-
-However, keep in mind that some antivirus programs may detect UPX-packed
-binaries as a virus. Therefore, if you are releasing a commercial game,
-make sure to sign your binaries or use a platform that will distribute them.

getting_started/workflow/export/changing_application_icon_for_windows.rst

@@ -12,7 +12,7 @@ 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 
+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
@@ -40,7 +40,7 @@ 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. 
+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.
 
@@ -69,8 +69,10 @@ Go to **Editor → Editor Settings → Export → Windows**.
 Click on the folder icon for the **rcedit** entry.
 Navigate to and select the rcedit executable.
 
-.. note:: Linux and macOS users will also need to install
-          `WINE <https://www.winehq.org/>`_ to use rcedit.
+.. note::
+
+    Linux and macOS users will also need to install
+    `WINE <https://www.winehq.org/>`_ to use rcedit.
 
 .. image:: img/icon_rcedit.png
 
@@ -82,6 +84,17 @@ the **Application → Icon** field.
 
 .. image:: img/icon_export_settings.png
 
+.. note::
+
+    If rcedit fails to change the icon, you can instead
+    :ref:`compile your own Windows export templates <doc_compiling_for_windows>`
+    with the icon changed. To do so, replace
+    `platform/windows/godot.ico <https://github.com/godotengine/godot/blob/master/platform/windows/godot.ico>`__
+    with your own ICO file *before* compiling export templates.
+
+    Once this is done, you can specify your export templates as custom export
+    templates in your project's Windows export preset.
+
 Testing the result
 ------------------
 
@@ -89,6 +102,8 @@ You can now export the project. If it worked correctly, you should see this:
 
 .. image:: img/icon_result.png
 
-.. 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``.
+.. note::
+
+    If your icon isn't showing up properly, on Windows 10, try clearing the icon
+    cache. To do so, open the **Run** dialog and enter ``ie4uinit.exe
+    -ClearIconCache`` or ``ie4uinit.exe -show``.

getting_started/workflow/export/exporting_projects.rst

@@ -147,3 +147,24 @@ flag, and to create a dedicated export preset for automated export:
 .. code-block:: shell
 
     godot --path path/to/project --export "pck" game_name.pck
+
+PCK versus ZIP pack file formats
+--------------------------------
+
+Each format has its upsides and downsides. PCK is the default and recommended
+format for most use cases, but you may want to use a ZIP archive instead
+depending on your needs.
+
+**PCK format:**
+
+- Uncompressed format. Larger file size, but faster to read/write.
+- Not readable and writable using tools normally present on the user's
+  operating system, even though there are
+  `third-party tools <https://github.com/hhyyrylainen/GodotPckTool>`__
+  to extract and create PCK files.
+
+**ZIP format:**
+
+- Compressed format. Smaller file size, but slower to read/write.
+- Readable and writable using tools normally present on the user's operating system.
+  This can be useful to make modding easier (see also :ref:`doc_exporting_pcks`).

tutorials/assetlib/uploading_to_assetlib.rst

@@ -38,7 +38,10 @@ are a few requirements your asset needs to meet to be approved.
   asset needs the contents of the submodule, your asset won't work.
 
 * The license needs to be correct. The license listed on the asset
-  library must match the license in the repository.
+  library must match the license in the repository. The repo MUST
+  have a license file, called either "LICENSE" or "LICENSE.md".
+  This file must contain the license text itself and a copyright
+  statement that includes the year(s) and copyright holder.
 
 * Use proper English for the name and description of your asset.
   This includes using correct capitalization, and using full

tutorials/optimization/cpu_optimization.rst

@@ -6,12 +6,12 @@ CPU optimization
 Measuring performance
 =====================
 
-To know how to speed up our program, we have to know where the "bottlenecks"
-are. Bottlenecks are the slowest parts of the program that limit the rate that
-everything can progress. This allows us to concentrate our efforts on optimizing
-the areas which will give us the greatest speed improvement, instead of spending
-a lot of time optimizing functions that will lead to small performance
-improvements.
+We have to know where the "bottlenecks" are to know how to speed up our program.
+Bottlenecks are the slowest parts of the program that limit the rate that
+everything can progress. Focussing on bottlenecks allows us to concentrate our
+efforts on optimizing the areas which will give us the greatest speed
+improvement, instead of spending a lot of time optimizing functions that will
+lead to small performance improvements.
 
 For the CPU, the easiest way to identify bottlenecks is to use a profiler.
 
@@ -45,7 +45,8 @@ When a project is running slowly, you will often see an obvious function or
 process taking a lot more time than others. This is your primary bottleneck, and
 you can usually increase speed by optimizing this area.
 
-For more info about using Godot's built-in profiler, see :ref:`doc_debugger_panel`.
+For more info about using Godot's built-in profiler, see
+:ref:`doc_debugger_panel`.
 
 External profilers
 ~~~~~~~~~~~~~~~~~~

tutorials/optimization/general_optimization.rst

@@ -145,8 +145,8 @@ Principles
 The messages are very important:
 
 - Developer time is limited. Instead of blindly trying to speed up
-  all aspects of a program, we should concentrate our efforts on the aspects that
-  really matter.
+  all aspects of a program, we should concentrate our efforts on the aspects
+  that really matter.
 - Efforts at optimization often end up with code that is harder to read and
   debug than non-optimized code. It is in our interests to limit this to areas
   that will really benefit.
@@ -156,9 +156,9 @@ mean that we *should*. Knowing when and when not to optimize is a great skill to
 develop.
 
 One misleading aspect of the quote is that people tend to focus on the subquote
-*"premature optimization is the root of all evil"*. While *premature* optimization
-is (by definition) undesirable, performant software is the result of performant
-design.
+*"premature optimization is the root of all evil"*. While *premature*
+optimization is (by definition) undesirable, performant software is the result
+of performant design.
 
 Performant design
 ~~~~~~~~~~~~~~~~~
@@ -166,9 +166,9 @@ Performant design
 The danger with encouraging people to ignore optimization until necessary, is
 that it conveniently ignores that the most important time to consider
 performance is at the design stage, before a key has even hit a keyboard. If the
-design or algorithms of a program are inefficient, then no amount of polishing the
-details later will make it run fast. It may run *faster*, but it will never run
-as fast as a program designed for performance.
+design or algorithms of a program are inefficient, then no amount of polishing
+the details later will make it run fast. It may run *faster*, but it will never
+run as fast as a program designed for performance.
 
 This tends to be far more important in game or graphics programming than in
 general programming. A performant design, even without low-level optimization,
@@ -179,18 +179,18 @@ Incremental design
 ~~~~~~~~~~~~~~~~~~
 
 Of course, in practice, unless you have prior knowledge, you are unlikely to
-come up with the best design the first time. Instead, you'll often make a series of
-versions of a particular area of code, each taking a different approach to the
-problem, until you come to a satisfactory solution. It's important not to spend
-too much time on the details at this stage until you have finalized the overall
-design. Otherwise, much of your work will be thrown out.
+come up with the best design the first time. Instead, you'll often make a series
+of versions of a particular area of code, each taking a different approach to
+the problem, until you come to a satisfactory solution. It's important not to
+spend too much time on the details at this stage until you have finalized the
+overall design. Otherwise, much of your work will be thrown out.
 
 It's difficult to give general guidelines for performant design because this is
-so dependent on the problem. One point worth mentioning though, on the CPU
-side, is that modern CPUs are nearly always limited by memory bandwidth. This
-has led to a resurgence in data-oriented design, which involves designing data
-structures and algorithms for *cache locality* of data and linear access, rather than
-jumping around in memory.
+so dependent on the problem. One point worth mentioning though, on the CPU side,
+is that modern CPUs are nearly always limited by memory bandwidth. This has led
+to a resurgence in data-oriented design, which involves designing data
+structures and algorithms for *cache locality* of data and linear access, rather
+than jumping around in memory.
 
 The optimization process
 ~~~~~~~~~~~~~~~~~~~~~~~~

tutorials/optimization/gpu_optimization.rst

@@ -176,8 +176,8 @@ amount of work the GPU has to do. You can do this by simplifying the shader
 (perhaps turn off expensive options if you are using a :ref:`SpatialMaterial
 <class_SpatialMaterial>`), or reducing the number and size of textures used.
 
-**When targeting mobile devices, consider using the simplest possible shaders you
-can reasonably afford to use.**
+**When targeting mobile devices, consider using the simplest possible shaders
+you can reasonably afford to use.**
 
 Reading textures
 ~~~~~~~~~~~~~~~~

tutorials/optimization/index.rst

@@ -8,11 +8,11 @@ Godot follows a balanced performance philosophy. In the performance world,
 there are always trade-offs, which consist of trading speed for usability
 and flexibility. Some practical examples of this are:
 
--  Rendering objects efficiently in high amounts is easy, but when a
+-  Rendering large amounts of objects efficiently is easy, but when a
    large scene must be rendered, it can become inefficient. To solve this,
    visibility computation must be added to the rendering. This makes rendering
-   less efficient, but at the same time, fewer objects are rendered.
-   Therefore, the overall rendering efficiency is improved.
+   less efficient, but at the same time, fewer objects are rendered. Therefore,
+   the overall rendering efficiency is improved.
 
 -  Configuring the properties of every material for every object that
    needs to be rendered is also slow. To solve this, objects are sorted by
@@ -24,14 +24,14 @@ and flexibility. Some practical examples of this are:
    insertion and removal, as well as raycasting, will not be able to handle as
    many active objects.
 
-And there are many more examples of this! Game engines strive to be general-purpose
-in nature. Balanced algorithms are always favored over algorithms
-that might be fast in some situations and slow in others, or algorithms that are
-fast but are more difficult to use.
+And there are many more examples of this! Game engines strive to be
+general-purpose in nature. Balanced algorithms are always favored over
+algorithms that might be fast in some situations and slow in others, or
+algorithms that are fast but are more difficult to use.
 
-Godot is not an exception to this. While it is designed to have backends swappable
-for different algorithms, the default backends prioritize balance and flexibility
-over performance.
+Godot is not an exception to this. While it is designed to have backends
+swappable for different algorithms, the default backends prioritize balance and
+flexibility over performance.
 
 With this clear, the aim of this tutorial section is to explain how to get the
 maximum performance out of Godot. While the tutorials can be read in any order,