Merge branch 'master' into 3.2

_static/js/custom.js

@@ -115,7 +115,7 @@ const registerOnScrollEvent = (function(){
 
       $menu.scroll(function() {
         handleSidebarScroll();
-      })
+      });
 
       handleMainScroll(window.scrollY);
       handleSidebarScroll();

about/list_of_features.rst

@@ -22,6 +22,7 @@ Platforms
 - Windows 7 and later (64-bit and 32-bit).
 - macOS 10.12 and later (64-bit, x86 and ARM).
 - Linux (64-bit and 32-bit, x86 and ARM).
+
    - Binaries are statically linked and can run on any distribution if compiled
      on an old enough base distribution.
    - Official binaries are compiled on Ubuntu 14.04.
@@ -46,15 +47,22 @@ Editor
 - Support for :ref:`external script editors <doc_external_editor>` such as
   Visual Studio Code or Vim.
 - GDScript :ref:`debugger <doc_debugger_panel>`.
+
    - No support for debugging in threads yet.
 - Performance monitoring tools.
 - Live script reloading.
 - Live scene editing.
+
    - Changes will reflect in the editor and will be kept after closing the running project.
+
 - Remote inspector.
+
    - Changes won't reflect in the editor and won't be kept after closing the running project.
+
 - Live camera replication.
+
    - Move the in-editor camera and see the result in the running project.
+
 - Use the editor in dozens of languages contributed by the community.
 
 **Plugins:**
@@ -77,18 +85,26 @@ Editor
 **Features:**
 
 - Sprite, polygon and line rendering.
+
    - High-level tools to draw lines and polygons such as Polygon2D and Line2D.
+
 - AnimatedSprite as a helper for creating animated sprites.
 - Parallax layers.
+
    - Pseudo-3D support by automatically duplicating a layer several times.
+
 - 2D lighting with normal maps.
+
    - Hard or soft shadows.
+
 - Font rendering using bitmaps (BitmapFont) or rasterization using FreeType (DynamicFont).
+
    - Bitmap fonts can be exported using tools like BMFont.
    - DynamicFont supports monochrome fonts as well as colored fonts.
      Supported formats are TTF and OTF.
    - DynamicFont supports optional font outlines with adjustable width and color.
    - Support for font oversampling to keep fonts sharp at higher resolutions.
+
 - GPU-based particles with support for custom particle shaders.
 - CPU-based particles.
 
@@ -97,8 +113,10 @@ Editor
 
 - 2D camera with built-in smoothing and drag margins.
 - Path2D node to represent a path in 2D space.
+
    - Can be drawn in the editor or generated procedurally.
    - PathFollow2D node to make nodes follow a Path2D.
+
 - 2D geometry helper class.
 - Line2D node to draw textured 2D lines.
 
@@ -158,14 +176,16 @@ Editor
 
 - *DirectionalLight:* Orthogonal (fastest), PSSM 2-split and 4-split.
   Supports blending between splits.
-- *OmniLight:* Dual parabolid (fast) or cubemap (slower but more accurate).
+- *OmniLight:* Dual paraboloid (fast) or cubemap (slower but more accurate).
   Supports colored projector textures in the form of panoramas.
 - *SpotLight:* Single texture.
 
 **Global illumination with indirect lighting:**
 
 - Baked lightmaps (fast, but can't be updated at run-time).
+
    - Lightmaps are baked on the CPU.
+
 - *GLES3:* GI probes (slower, semi-real-time). Supports reflections.
 
 **Reflections:**
@@ -230,8 +250,10 @@ improve quality. This can be helpful when using Godot for offline rendering.
 - Tools for :ref:`procedural geometry generation <doc_procedural_geometry>`.
 - :ref:`Constructive solid geometry <doc_csg_tools>` (intended for prototyping).
 - Path3D node to represent a path in 3D space.
+
    - Can be drawn in the editor or generated procedurally.
    - PathFollow3D node to make nodes follow a Path3D.
+
 - 3D geometry helper class.
 
 3D physics
@@ -261,6 +283,7 @@ Shaders
 - *3D:* Custom vertex, fragment, light, and sky shaders.
 - Text-based shaders using a `shader language inspired by GLSL <doc_shading_language>`.
 - Visual shader editor.
+
    - Support for visual shader plugins.
 
 Scripting
@@ -286,7 +309,9 @@ Scripting
 
 - Packaged in a separate binary to keep file sizes and dependencies down.
 - Uses Mono 6.x.
+
    - Full support for the C# 7.0 syntax and features.
+
 - Supports all platforms.
 - Using an external editor is recommended to benefit from IDE functionality.
 
@@ -299,10 +324,14 @@ Scripting
 **GDNative (C, C++, Rust, D, ...):**
 
 - When you need it, link to native libraries for higher performance and third-party integrations.
+
    - For scripting game logic, GDScript or C# are recommended if their
      performance is suitable.
+
 - Official bindings for C and C++.
+
    - Use any build system and language features you wish.
+
 - Maintained D, Kotlin, Python, Nim, and Rust bindings provided by the community.
 
 Audio
@@ -312,12 +341,15 @@ Audio
 
 - Mono, stereo, 5.1 and 7.1 output.
 - Non-positional and positional playback in 2D and 3D.
+
    - Optional Doppler effect in 2D and 3D.
-- Support for re-routable :ref:`audio buses <doc_audio_buses>` and effects.
-   - Dozens of effects included.
+
+- Support for re-routable :ref:`audio buses <doc_audio_buses>` and effects
+  with dozens of effects included.
 - Listener3D node to listen from a position different than the camera in 3D.
 - Audio input to record microphones.
 - MIDI input.
+
    - No support for MIDI output yet.
 
 **APIs used:**
@@ -333,11 +365,14 @@ Import
 
 **Formats:**
 
-- *Images:* See :ref:`doc_importing_images_supported_formats`.
+- *Images:* See :ref:`doc_import_images`.
 - *Audio:*
+
    - WAV with optional IMA-ADPCM compression.
    - Ogg Vorbis.
+
 - *3D scenes:*
+
    - glTF 2.0 *(recommended)*.
    - `ESCN <https://github.com/godotengine/godot-blender-exporter>`__
      (direct export from Blender).
@@ -349,13 +384,20 @@ Input
 ^^^^^
 
 - Input mapping system using hardcoded input events or remappable input actions.
+
    - Axis values can be mapped to two different actions with a configurable deadzone.
    - Use the same code to support both keyboards and gamepads.
+
 - Keyboard input.
+
+   - Keys can be mapped in "physical" mode to be independent of the keyboard layout.
+
 - Mouse input.
+
    - The mouse cursor can be visible, hidden, captured or confined within the window.
    - When captured, raw input will be used on Windows and Linux to
      sidestep the OS' mouse acceleration settings.
+
 - Gamepad input (up to 8 simulatenous controllers).
 - Pen/tablet input with pressure support.
 
@@ -374,10 +416,14 @@ Networking
 - Low-level UDP networking using PacketPeer and UDPServer.
 - Low-level HTTP requests using HTTPClient.
 - High-level HTTP requests using HTTPRequest.
+
    - Supports HTTPS out of the box using bundled certificates.
+
 - High-level multiplayer API using UDP and ENet.
+
    - Automatic replication using remote procedure calls (RPCs).
    - Supports unreliable, reliable and ordered transfers.
+
 - WebSocket client and server, available on all platforms.
 - WebRTC client and server, available on all platforms.
 - Support for UPnP to sidestep the requirement to forward ports when hosting
@@ -400,8 +446,10 @@ Windowing and OS integration
 - Change the window title and icon.
 - Request attention (will cause the title bar to blink on most platforms).
 - Fullscreen mode.
+
    - Doesn't use exclusive fullscreen, so the screen resolution can't be changed this way.
      Use a Viewport with a different resolution instead.
+
 - Borderless window (fullscreen or non-fullscreen).
 - Ability to keep the window always on top.
 - Transparent window with per-pixel transparency.
@@ -446,20 +494,26 @@ The editor UI can easily be extended in many ways using add-ons.
 
 - Anchors to keep GUI elements in a specific corner, edge or centered.
 - Containers to place GUI elements automatically following certain rules.
+
    - :ref:`Stack <class_BoxContainer>` layouts.
    - :ref:`Grid <class_GridContainer>` layouts.
    - :ref:`Margin <class_MarginContainer>` and :ref:`centered <class_CenterContainer>`
      layouts.
    - :ref:`Draggable splitter <class_SplitContainer>` layouts.
+
 - Scale to multiple resolutions using the ``2d`` or ``viewport`` stretch modes.
 - Support any aspect ratio using anchors and the ``expand`` stretch aspect.
 
 **Theming:**
 
 - Built-in theme editor.
+
    - Generate a theme based on the current editor theme settings.
+
 - Procedural vector-based theming using :ref:`class_StyleBoxFlat`.
+
    - Supports rounded/beveled corners, drop shadows and per-border widths.
+
 - Texture-based theming using :ref:`class_StyleBoxTexture`.
 
 Godot's small distribution size can make it a suitable alternative to frameworks
@@ -478,13 +532,19 @@ Formats
 ^^^^^^^
 
 - Scenes and resources can be saved in :ref:`text-based <doc_tscn_file_format>` or binary formats.
+
    - Text-based formats are human-readable and more friendly to version control.
    - Binary formats are faster to save/load for large scenes/resources.
+
 - Read and write text or binary files using :ref:`class_File`.
+
    - Can optionally be compressed or encrypted.
+
 - Read and write :ref:`class_JSON` files.
 - Read and write INI-style configuration files using :ref:`class_ConfigFile`.
+
    - Can (de)serialize any Godot datatype, including Vector, Color, ...
+
 - Read XML files using :ref:`class_XMLParser`.
 - Pack game data into a PCK file (custom format optimized for fast seeking),
   into a ZIP archive, or directly into the executable for single-file distribution.
@@ -497,19 +557,24 @@ Miscellaneous
 - :ref:`Low-level access to servers <doc_using_servers>` which allows bypassing
   the scene tree's overhead when needed.
 - Command line interface for automation.
+
    - Export and deploy projects using continuous integration platforms.
    - `Completion scripts <https://github.com/godotengine/godot/tree/master/misc/dist/shell>`__
      are available for Bash, zsh and fish.
+
 - Support for :ref:`C++ modules <doc_custom_modules_in_c++>` statically linked
   into the engine binary.
 - Engine and editor written in C++03.
+
    - Can be :ref:`compiled <doc_introduction_to_the_buildsystem>` using GCC,
      Clang and MSVC. MinGW is also supported.
-   - Friendly towards packagers: in most cases, system libraries can be used
+   - Friendly towards packagers. In most cases, system libraries can be used
      instead of the ones provided by Godot. The build system doesn't download anything.
      Builds can be fully reproducible.
    - Godot 4.0 will be written in C++17.
+
 - Licensed under the permissive MIT license.
+
    - Open developement process with :ref:`contributions welcome <doc_ways_to_contribute>`.
 
 .. seealso::

community/contributing/best_practices_for_engine_contributors.rst

@@ -234,3 +234,12 @@ link libraries dynamically. Instead, we bundle them in our source tree.
 As a result, we are very picky with what goes in, and we tend to prefer smaller
 libraries (in fact, single header ones are our favorite). Only in cases where
 there is no other choice we end up bundling something larger.
+
+Also, libraries must use a permissive enough license to be included into Godot.
+Some examples of acceptable licenses are Apache 2.0, BSD, MIT, ISC, and MPL 2.0.
+In particular, we cannot accept libraries licensed under the GPL or LGPL since
+these licenses effectively disallow static linking in proprietary software
+(which Godot is distributed as in most exported projects). This requirement also
+applies to the editor, since we may want to run it on iOS in the long term.
+Since iOS doesn't support dynamic linking, static linking the only option on
+that platform.

community/contributing/bisecting_regressions.rst

@@ -95,9 +95,11 @@ folder and enter the following command:
 
 .. code-block:: shell
 
-    # <good> is the commit hash of the build that works as expected.
-    # <bad> is the commit hash of the build exhibiting the bug.
-    $ git bisect start <good> <bad>
+    # <good commit hash> is hash of the build that works as expected.
+    # <bad commit hash> is hash of the build exhibiting the bug.
+    $ git bisect start
+    $ git bisect good <good commit hash>
+    $ git bisect bad <bad commit hash>
 
 Compile Godot. This assumes you've set up a build environment:
 

community/contributing/code_style_guidelines.rst

@@ -248,7 +248,56 @@ Python
 Godot's SCons buildsystem is written in Python, and various scripts included
 in the source tree are also using Python.
 
-For those, we follow the `PEP-8 style guide <https://www.python.org/dev/peps/pep-0008/>`__,
-this is however not as strongly enforced as for the C++ code. If you are so
-inclined, you can check and format your Python changes using
-`autopep8 <https://pypi.org/project/autopep8/>`__.
+For those, we follow the `Black style guide <https://github.com/psf/black#the-black-code-style>`__.
+Blacken your Python changes using `Black <https://pypi.org/project/black/>`__.
+
+Using black locally
+~~~~~~~~~~~~~~~~~~~
+
+First of all, you will need to install black. Black requires Python 3.6.0+ 
+to run.
+
+Installation
+^^^^^^^^^^^^
+
+Here's how to install black:
+
+::
+
+    pip install black --user
+
+
+You then have different possibilities to apply black to your changes:
+
+Manual usage
+^^^^^^^^^^^^
+
+You can apply ``black`` manually to one or more files with the following
+command:
+
+::
+
+    black -l 120 <path/to/file(s)>
+
+- ``-l 120`` means that the allowed number of characters per line is 120.
+  This number was agreed upon by the developers.
+- The path can point to several files, either one after the other or using
+  wildcards like in a typical Unix shell.
+
+Pre-commit hook
+^^^^^^^^^^^^^^^
+
+For ease of use, we provide a pre-commit hook for Git that will run
+black automatically on all your commits to check them, and let you apply
+its changes in the final commit.
+
+This "hook" is a script which can be found in ``misc/hooks``. Refer to that
+folder's ``README.md`` for installation instructions.
+
+
+Editor integration
+^^^^^^^^^^^^^^^^^^
+
+Many IDEs or code editors have beautifier plugins that can be configured to run
+black automatically, for example each time you save a file. For details you can
+check `Black editor integration <https://github.com/psf/black#editor-integration>`__.

community/contributing/docs_writing_guidelines.rst

@@ -298,7 +298,7 @@ The exception is topics that explain static typing concepts to users.
     var body_sprite := $Sprite as Sprite
 
 
-**Do** write constants variables with dynamic typing:
+**Do** write constants and variables with dynamic typing:
 
 ::
 
@@ -312,7 +312,7 @@ The exception is topics that explain static typing concepts to users.
 
 ::
 
-    func choose(arguments: Array):
+    func choose(arguments: PoolStringArray) -> String:
         # Chooses one of the arguments from array with equal chances
         randomize()
         var size := arguments.size()
@@ -392,7 +392,7 @@ functionality, in up to 200 characters.
 ::
 
     **Node2D**
-    2D game object, parent of all 2D related nodes. Has a position, rotation, scale and z-index.
+    A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.
 
 Use the node's full description to provide more information, and a code
 example, if possible.
@@ -518,10 +518,18 @@ Screenshot sizes should not exceed 1920×1080 to ensure fast loading on slower
 connections.
 
 When you need to highlight an area of the editor to show something, like a
-button or option, use a 2 pixel thick outline without a bevel.
+button or option, use a 2 pixel-thick yellow outline without a bevel. If the
+outline is on a dark background, the outline should be yellow so it can be
+easily seen by colorblind people. Please do not use red as it won't be visible
+for some users.
 
 Before you add or replace any images in the documentation, they should be run
-through a PNG compressor to save size. The built in lossless compressor in
-programs like Krita or Photoshop should be enough. For heavier images, also look
-into using a lossy compressor, such as `pngquant <https://pngquant.org/>`_ where
-almost no image quality is lost during compression.
+through a PNG compressor to save size. You can use the lossless OxiPNG
+compressor included in `Squoosh <https://squoosh.app/>`__ for this purpose. For
+heavier images, consider using a lossy compressor like `pngquant
+<https://pngquant.org/>`_. With it, almost no image quality is lost during
+compression.
+
+.. note::
+
+    The program pngquant must be installed locally as it's not available in Squoosh.

community/contributing/updating_the_class_reference.rst

@@ -280,6 +280,30 @@ Will display as:
         var sprite = get_node("Sprite")
         print(sprite.get_pos())
 
+To denote important information, add a paragraph starting with "[b]Note:[/b]" at
+the end of the description:
+
+.. code-block:: none
+
+    [b]Note:[/b] Only available when using the GLES2 renderer.
+
+To denote crucial information that could cause security issues or loss of data
+if not followed carefully, add a paragraph starting with "[b]Warning:[/b] at the
+end of the description:
+
+.. code-block:: none
+
+    [b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.
+
+For deprecated properties, add a paragraph starting with "[i]Deprecated.[/i]".
+Notice the use of italics instead of bold:
+
+.. code-block:: none
+
+    [i]Deprecated.[/i] This property has been replaced by [member other_property].
+
+In all the paragraphs described above, make sure the punctuation is part of the
+BBCode tags for consistency.
 
 I don't know what this method does!
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

development/compiling/optimizing_for_size.rst

@@ -159,6 +159,10 @@ 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.

development/cpp/configuring_an_ide/qt_creator.rst

@@ -93,7 +93,7 @@ Code style configuration
 Developers must follow the project's :ref:`code style <doc_code_style_guidelines>`
 and the IDE should help them follow it. By default, Qt Creator uses spaces
 for indentation which doesn't match the Godot code style guidelines. You can
-change this behavior by changing the **Code Style** in **Options > C++**.
+change this behavior by changing the **Code Style** in **Tools > Options > C++**.
 
 .. figure:: img/qtcreator-options-cpp.png
    :figclass: figure-w480

development/cpp/custom_godot_servers.rst

@@ -7,7 +7,7 @@ Introduction
 ------------
 
 Godot implements multi-threading as servers. Servers are daemons which
-manages data, processes, and pushes the result. Servers implement the
+manage data, process it, and push the result. Servers implement the
 mediator pattern which interprets resource ID and process data for the
 engine and other modules. In addition, the server claims ownership for
 its RID allocations.

getting_started/editor/index.rst

@@ -1,3 +1,4 @@
+
 Editor manual
 =============
 
@@ -5,10 +6,7 @@ Editor manual
    :maxdepth: 1
    :name: toc-learn-editor
 
-   unity_to_godot
    command_line_tutorial
    external_editor
    default_key_mapping
-
-.. ue4_to_godot
-.. debugging
+   unity_to_godot

getting_started/scripting/gdscript/gdscript_basics.rst

@@ -284,7 +284,7 @@ Literals
 +--------------------------+----------------------------------------+
 | ``45``                   | Base 10 integer                        |
 +--------------------------+----------------------------------------+
-| ``0x8F51``               | Base 16 (hexadecimal) integer          |
+| ``0x8f51``               | Base 16 (hexadecimal) integer          |
 +--------------------------+----------------------------------------+
 | ``0b101010``             | Base 2 (binary) integer                |
 +--------------------------+----------------------------------------+
@@ -299,6 +299,14 @@ Literals
 | ``$NodePath``            | Shorthand for ``get_node("NodePath")`` |
 +--------------------------+----------------------------------------+
 
+Integers and floats can have their numbers separated with ``_`` to make them more readable.
+The following ways to write numbers are all valid::
+
+    12_345_678  # Equal to 12345678.
+    3.141_592_7  # Equal to 3.1415927.
+    0x8080_0000_ffff  # Equal to 0x80800000ffff.
+    0b11_00_11_00  # Equal to 0b11001100.
+
 Comments
 ~~~~~~~~
 

getting_started/scripting/gdscript/gdscript_styleguide.rst

@@ -418,6 +418,53 @@ characters in a given string. See the examples below:
     # Both quote styles would require 2 escapes; prefer double quotes if it's a tie.
     print("'hello' \"world\"")
 
+Numbers
+~~~~~~~
+
+Don't omit the leading or trailing zero in floating-point numbers. Otherwise,
+this makes them less readable and harder to distinguish from integers at a
+glance.
+
+**Good**::
+
+    var float_number = 0.234
+    var other_float_number = 13.0
+
+**Bad**::
+
+    var float_number = .234
+    var other_float_number = 13.
+
+Use lowercase for letters in hexadecimal numbers, as their lower height makes
+the number easier to read.
+
+**Good**::
+
+    var hex_number = 0xfb8c0b
+
+**Bad**::
+
+    var hex_number = 0xFB8C0B
+
+Take advantage of GDScript's underscores in literals to make large numbers more
+readable.
+
+**Good**::
+
+    var large_number = 1_234_567_890
+    var large_hex_number = 0xffff_f8f8_0000
+    var large_bin_number = 0b1101_0010_1010
+    # Numbers lower than 1000000 generally don't need separators.
+    var small_number = 12345
+
+**Bad**::
+
+    var large_number = 1234567890
+    var large_hex_number = 0xfffff8f80000
+    var large_bin_number = 0b110100101010
+    # Numbers lower than 1000000 generally don't need separators.
+    var small_number = 12_345
+
 .. _naming_conventions:
 
 Naming conventions

getting_started/scripting/visual_script/nodes_purposes.rst

@@ -267,7 +267,7 @@ These are nodes you can use as temporary storage for your graphs. Make sure they
 .. image:: img/visual_script41.png
 
 
-As it can be seen above, there are two nodes available: A simple getter, and a sequenced getter (setting requires a sequence port).
+As it can be seen above, there are two nodes available: A simple getter, and a sequenced setter (setting requires a sequence port).
 
 
 Scene Node

getting_started/step_by_step/instancing.rst

@@ -102,8 +102,9 @@ 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. 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".
+to make it unique. Click on the tools button in the top-right of the Inspector
+dock and select "Make Sub-Resources Unique". Set its ``Bounce`` to ``1`` and
+press "Play".
 
 .. image:: img/instancing_property.png
 

getting_started/step_by_step/scripting.rst

@@ -104,6 +104,8 @@ easier to get an overview of the concepts.
 Scene setup
 ~~~~~~~~~~~
 
+If you still have the "instancing" project open from the previous tutorial, then close that out (Project -> Quit to Project List) and create a New Project.
+
 Use the "Add Child Node" dialogue accessed from the Scene tab (or by pressing :kbd:`Ctrl + A`) to create a hierarchy with the following
 nodes:
 
@@ -259,7 +261,7 @@ using :ref:`Object.connect() <class_Object_method_connect>`.
  .. code-tab:: gdscript GDScript
 
     func _ready():
-        get_node("Button").connect("pressed", self, "_on_Button_pressed")
+        get_node("Button").connect("pressed", self._on_Button_pressed)
 
  .. code-tab:: csharp
 
@@ -276,7 +278,7 @@ The final script should look like this:
     extends Panel
 
     func _ready():
-        get_node("Button").connect("pressed", self, "_on_Button_pressed")
+        get_node("Button").connect("pressed", self._on_Button_pressed)
 
     func _on_Button_pressed():
         get_node("Label").text = "HELLO!"

getting_started/step_by_step/ui_introduction_to_the_ui_system.rst

@@ -97,7 +97,7 @@ the ``Modulate`` property and use the color picker.
 TextureButton
 ~~~~~~~~~~~~~
 
-**TextureButton** is like TextureRect, except it has 5 texture slots:
+**TextureButton** is like TextureRect, except it has 6 texture slots:
 one for each of the button's states. Most of the time, you'll use the
 Normal, Pressed, and Hover textures. Focused is useful if your interface
 listens to the keyboard's input. The sixth image slot, the Click Mask,

getting_started/step_by_step/your_first_game.rst

@@ -704,8 +704,9 @@ you will see some new buttons at the top of the editor:
 
 Select the middle one ("Add Point") and draw the path by clicking to add
 the points at the corners shown. To have the points snap to the grid, make
-sure "Use Grid Snap" is selected. This option can be found to the left of
-the "Lock" button, appearing as a magnet next to some intersecting lines.
+sure "Use Grid Snap" and "Use Snap" are both selected. These options can be 
+found to the left of the "Lock" button, appearing as a magnet next to some
+dots and intersecting lines, respectively.
 
 .. image:: img/grid_snap_button.png
 
@@ -897,11 +898,11 @@ Note that a new instance must be added to the scene using ``add_child()``.
         mobInstance.Position = mobSpawnLocation.Position;
 
         // Add some randomness to the direction.
-        direction += RandRange(-Mathf.Pi / 4, Mathf.Pi / 4);
+        direction += GD.RandRange(-Mathf.Pi / 4, Mathf.Pi / 4);
         mobInstance.Rotation = direction;
 
         // Choose the velocity.
-        mobInstance.LinearVelocity = new Vector2(RandRange(150f, 250f), 0).Rotated(direction);
+        mobInstance.LinearVelocity = new Vector2(GD.RandRange(150f, 250f), 0).Rotated(direction);
     }
 
 .. important:: Why ``PI``? In functions requiring angles, GDScript uses *radians*,

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
-====================================
-
-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>`_.
-
-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.
-
-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.
-
-Making sense of classes in Godot
---------------------------------
-
-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.
-
-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:
-
-- properties
-- methods
-- constants
-- signals
-
-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.
-
-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.
-
-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.
-
-.. 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>`
+Applying object-oriented principles in Godot
+============================================
 
+The engine offers two main ways to create reusable objects: scripts and scenes. Neither of these
+technically define classes under the hood.
 
-Scripting performances and PackedScene
---------------------------------------
+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.
 
-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.
+This guide briefly explains how scripts and scenes work in the engine's core to help you understand
+how they work under the hood.
 
-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:
+How scripts work in the engine
+------------------------------
 
-.. tabs::
-  .. code-tab:: gdscript GDScript
+The engine provides built-in classes like :ref:`Node <class_Node>`. You can extend those to create
+derived types using a script.
 
-    # Main.gd
-    extends Node
+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.
 
-    func _init():
-        var child = Node.new()
-        child.name = "Child"
-        child.script = preload("Child.gd")
-        child.owner = self
-        add_child(child)
+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:
 
-  .. code-tab:: csharp
+- Properties.
+- Methods.
+- Constants.
+- Signals.
 
-    using System;
-    using Godot;
+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.
 
-    namespace ExampleProject
-    {
-        public class Main : Resource
-        {
-            public Node Child { get; set; }
+Attaching a :ref:`Script <class_Script>` to your object extends the methods, properties, and signals
+available from the ``ClassDB``.
 
-            public Main()
-            {
-                Child = new Node();
-                Child.Name = "Child";
-                Child.Script = (Script)ResourceLoader.Load("child.gd");
-                Child.Owner = this;
-                AddChild(Child);
-            }
-        }
-    }
+.. note::
 
-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.
+    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 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
+------
 
-Scenes and scripts are objects
-------------------------------
+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()``.
 
-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

requirements.txt

@@ -10,4 +10,4 @@ sphinx_rtd_theme==0.4.3
 sphinx-tabs==1.1.13
 
 # Full-page search UI for RTD: https://readthedocs-sphinx-search.readthedocs.io
-git+https://github.com/readthedocs/readthedocs-sphinx-search@faa85a9dabb71e53bb01832edc9a3be07d22bd5a
+readthedocs-sphinx-search==0.1.0rc3

tutorials/2d/particle_systems_2d.rst

@@ -178,21 +178,20 @@ means particles are drawn according to their emission order (default).
 ParticlesMaterial settings
 --------------------------
 
-.. Commented out as not implemented in 3.x for now.
-..
-   Direction
-   ~~~~~~~~~
-..
-   This is the base angle at which particles emit. Default is ``0`` (down):
-..
-   .. image:: img/paranim1.gif
-..
-   Changing it will change the emissor direction, but gravity will still affect them:
-..
-   .. image:: img/paranim2.gif
-..
-   This parameter is useful because, by rotating the node, gravity will
-   also be rotated. Changing direction allows them to be separated.
+Direction
+~~~~~~~~~
+
+This is the base direction at which particles emit. The default is
+``Vector3(1, 0, 0)`` which makes particles emit to the right. However,
+with the default gravity settings, particles will go straight down.
+
+.. image:: img/direction1.png
+
+For this property to be noticeable, you need an *initial velocity* greater
+than 0. Here, we set the initial velocity to 40. You'll notice that
+particles emit toward the right, then go down because of gravity.
+
+.. image:: img/direction2.png
 
 Spread
 ~~~~~~
@@ -204,6 +203,11 @@ parameter must be greater than 0.
 
 .. image:: img/paranim3.gif
 
+Flatness
+~~~~~~~~
+
+This property is only useful for 3D particles.
+
 Gravity
 ~~~~~~~
 

tutorials/3d/csg_tools.rst

@@ -1,7 +1,7 @@
 .. _doc_csg_tools:
 
-CSG
-===
+Prototyping levels with CSG
+===========================
 
 CSG stands for **Constructive Solid Geometry**, and is a tool to combine basic
 shapes or custom meshes to create more complex shapes. In 3D modelling software,

tutorials/3d/environment_and_post_processing.rst

@@ -265,8 +265,6 @@ 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):
@@ -279,8 +277,6 @@ 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):
@@ -298,8 +294,6 @@ 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.
@@ -345,14 +339,13 @@ interesting glow patterns:
 Finally, as the highest layers are created by stretching small blurred images,
 it is possible that some blockiness may be visible. Enabling **Bicubic Upscaling**
 gets rids of it, at a minimal performance cost.
+*Note that this is effective only when using the GLES3 backend.*
 
 .. image:: img/environment_glow_bicubic.png
 
 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/high_dynamic_range.rst

@@ -1,7 +1,7 @@
 .. _doc_high_dynamic_range:
 
-Light transport in game engines
-===============================
+High dynamic range lighting
+===========================
 
 Introduction
 ------------
@@ -32,6 +32,14 @@ through a virtual camera. Here, our virtual camera would apply a particular
 camera rendering transform to the scene data, and the output would be ready
 for display on a particular display type.
 
+.. note::
+
+    Godot does not support high dynamic range *output* yet. It can only perform
+    lighting in HDR and tonemap the result to a low dynamic range image.
+
+    For advanced users, it is still possible to get a non-tonemapped image
+    of the viewport with full HDR data, which can then be saved to an OpenEXR file.
+
 Computer displays
 -----------------
 
@@ -88,7 +96,7 @@ The GPU will do the conversion after reading the texel using floating-point.
 This works fine on PC and consoles, but most mobile devices don't support it,
 or they don't support it on compressed texture formats (iOS for example).
 
-Scene linear to display referred nonlinear
+Scene linear to display-referred nonlinear
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 After all the rendering is done, the scene linear render requires transforming

tutorials/animation/animation_tree.rst

@@ -245,11 +245,11 @@ object from the ``AnimationTree`` node (it is exported as a property).
 .. tabs::
  .. code-tab:: gdscript GDScript
 
-    var state_machine = anim_tree["parameters/StateMachine/playback"]
+    var state_machine = anim_tree["parameters/playback"]
 
  .. code-tab:: csharp
 
-    AnimationNodeStateMachinePlayback stateMachine = (AnimationNodeStateMachinePlayback)animTree.Get("parameters/StateMachine/playback");
+    AnimationNodeStateMachinePlayback stateMachine = (AnimationNodeStateMachinePlayback)animTree.Get("parameters/playback");
 
 Once retrieved, it can be used by calling one of the many functions it offers:
 

tutorials/assetlib/using_assetlib.rst

@@ -1,7 +1,7 @@
 .. _doc_using_assetlib:
 
-Using the AssetLib
-==================
+Using the Asset Library
+=======================
 
 On the website
 --------------
@@ -9,9 +9,9 @@ On the website
 Overview
 ~~~~~~~~
 
-As mentioned before, you can access the web frontend of the AssetLib
-on `Godot's official website <https://godotengine.org/asset-library/asset>`_, and this
-is what it looks like when you first visit it:
+As mentioned before, you can access the web frontend of the Asset Library on
+`Godot's official website <https://godotengine.org/asset-library/asset>`_.
+This is what it looks like when you first visit it:
 
 |image0|
 

tutorials/debug/debugger_panel.rst

@@ -32,6 +32,12 @@ You can use the buttons in the top-right corner to:
 - **Break**. This button pauses the game's execution.
 - **Continue**. This button resumes the game after a breakpoint or pause.
 
+.. warning::
+
+    Breakpoints won't break on code if it's
+    :ref:`running in a thread <doc_using_multiple_threads>`.
+    This is a current limitation of the GDScript debugger.
+
 Errors
 ++++++
 

tutorials/debug/overview_of_debugging_tools.rst

@@ -90,6 +90,12 @@ The **Keep Debugger Open** option keeps the debugger open after a scene
 has been closed. And the **Debug with External Editor** option lets you
 debug your game with an external editor.
 
+.. warning::
+
+    Breakpoints won't break on code if it's
+    :ref:`running in a thread <doc_using_multiple_threads>`.
+    This is a current limitation of the GDScript debugger.
+
 Debug project settings
 ----------------------
 

tutorials/gui/bbcode_in_richtextlabel.rst

@@ -232,6 +232,7 @@ Ghost
 
     tool
     extends RichTextEffect
+    class_name RichTextGhost
 
     # Syntax: [ghost freq=5.0 span=10.0][/ghost]
 
@@ -254,6 +255,7 @@ Pulse
 
     tool
     extends RichTextEffect
+    class_name RichTextPulse
 
     # Syntax: [pulse color=#00FFAA height=0.0 freq=2.0][/pulse]
 
@@ -280,6 +282,7 @@ Matrix
 
     tool
     extends RichTextEffect
+    class_name RichTextMatrix
 
     # Syntax: [matrix clean=2.0 dirty=1.0 span=50][/matrix]
 

tutorials/io/saving_games.rst

@@ -265,7 +265,7 @@ load function:
         // it represents.
         saveGame.Open("user://savegame.save", (int)File.ModeFlags.Read);
 
-        while (saveGame.GetPosition() < save_game.GetLen())
+        while (saveGame.GetPosition() < saveGame.GetLen())
         {
             // Get the saved dictionary from the next line in the save file
             var nodeData = new Godot.Collections.Dictionary<string, object>((Godot.Collections.Dictionary)JSON.Parse(saveGame.GetLine()).Result);

tutorials/misc/change_scenes_manually.rst

@@ -12,7 +12,7 @@ scenes which one instances and adds to the tree at runtime:
 .. tabs::
  .. code-tab:: gdscript GDScript
 
-    var simultaneous_scene = preload("res://levels/level2.tscn")
+    var simultaneous_scene = preload("res://levels/level2.tscn").instance()
 
     func _add_a_scene_manually():
         # This is like autoloading the scene, only
@@ -25,7 +25,7 @@ scenes which one instances and adds to the tree at runtime:
 
     public MyClass()
     {
-        simultaneousScene = (PackedScene)ResourceLoader.Load("res://levels/level2.tscn");
+        simultaneousScene = (PackedScene)ResourceLoader.Load("res://levels/level2.tscn").instance();
     }
 
     public void _AddASceneManually()

tutorials/misc/running_code_in_the_editor.rst

@@ -39,6 +39,13 @@ For example, if you want to execute some code only in the editor, use:
     if Engine.editor_hint:
         # Code to execute when in editor.
 
+ .. code-tab:: csharp
+
+    if (Engine.EditorHint)
+    {
+        // Code to execute when in editor.
+    }
+
 On the other hand, if you want to execute code only in game, simply negate the same statement:
 
 .. tabs::
@@ -47,6 +54,13 @@ On the other hand, if you want to execute code only in game, simply negate the s
     if not Engine.editor_hint:
         # Code to execute when in game.
 
+ .. code-tab:: csharp
+
+    if (!Engine.EditorHint)
+    {
+        // Code to execute when in game.
+    }
+
 Pieces of code do not have either of the 2 conditions above will run both in-editor and in-game.
 
 Here is how a ``_process()`` function might look for you:
@@ -63,6 +77,23 @@ Here is how a ``_process()`` function might look for you:
 
         # Code to execute both in editor and in game.
 
+ .. code-tab:: csharp
+
+    public override void _Process(float delta)
+    {
+        if (Engine.EditorHint)
+        {
+            // Code to execute in editor.
+        }
+
+        if (!Engine.EditorHint)
+        {
+            // Code to execute in game.
+        }
+
+        // Code to execute both in editor and in game.
+    }
+
 .. note:: Modifications in editor are permanent. For example, in the following case, when we remove the script, the node will keep its rotation. Be careful to avoid making unwanted modifications.
 
 Try it out
@@ -79,6 +110,20 @@ Add a ``Sprite`` node to your scene and set the texture to Godot icon. Attach an
     func _process(delta):
         rotation_degrees += 180 * delta
 
+ .. code-tab:: csharp
+
+    using Godot;
+    using System;
+
+    [Tool]
+    public class MySprite : Sprite
+    {
+        public override void _Process(float delta)
+        {
+            RotationDegrees += 180 * delta;
+        }
+    }
+
 Save the script and return to the editor. You should now see your object rotate. If you run the game, it will also rotate.
 
 .. image:: img/rotating_in_editor.gif
@@ -96,6 +141,20 @@ Now let's choose which code runs when. Modify your ``_process()`` function to lo
         else:
             rotation_degrees -= 180 * delta
 
+ .. code-tab:: csharp
+
+    public override void _Process(float delta)
+    {
+        if (Engine.EditorHint)
+        {
+            RotationDegrees += 180 * delta;
+        }
+        else
+        {
+            RotationDegrees -= 180 * delta;
+        }
+    }
+
 Save the script. Now the object will spin clockwise in the editor, but if you run the game, it will spin counter-clockwise.
 
 Editing variables
@@ -122,6 +181,35 @@ Modify  ``_process()`` to include the rotation speed.
     func _process(delta):
     	rotation_degrees += 180 * delta * speed
 
+ .. code-tab:: csharp
+
+    using Godot;
+    using System;
+
+    [Tool]
+    public class MySprite : Sprite
+    {
+        private float speed = 1;
+
+        [Export]
+        public float Speed {
+            get => speed;
+            set => SetSpeed(value);
+        }
+
+        // Update speed and reset the rotation.
+        private void SetSpeed(float newSpeed)
+        {
+            speed = newSpeed;
+            RotationDegrees = 0;
+        }
+
+        public override void _Process(float delta)
+        {
+            RotationDegrees += 180 * delta * speed;
+        }
+    }
+
 .. note:: Code from other nodes doesn't run in the editor. Your access to other nodes is limited. You can access the tree and nodes, and their default properties, but you can't access user variables. If you want to do so, other nodes have to run in the editor too. AutoLoad nodes cannot be accessed in the editor at all.
 
 Instancing scenes
@@ -139,6 +227,15 @@ If you are using ``tool``:
         add_child(node) # Parent could be any node in the scene
         node.set_owner(get_tree().edited_scene_root)
 
+ .. code-tab:: csharp
+
+    public override void _Ready()
+    {
+        var node = new Spatial();
+        AddChild(node); // Parent could be any node in the scene
+        node.Owner = GetTree().EditedSceneRoot;
+    }
+
 If you are using :ref:`EditorScript<class_EditorScript>`:
 
 .. tabs::
@@ -150,4 +247,14 @@ If you are using :ref:`EditorScript<class_EditorScript>`:
         parent.add_child(node)
         node.set_owner(get_scene())
 
+ .. code-tab:: csharp
+
+    public override void _Run()
+    {
+        var parent = GetScene().FindNode("Parent"); // Parent could be any node in the scene
+        var node = new Spatial();
+        parent.AddChild(node);
+        node.Owner = GetScene();
+    }
+
 .. warning:: Using ``tool`` improperly can yield many errors. It is advised to first write the code how you want it, and only then add the ``tool`` keyword to the top. Also, make sure to separate code that runs in-editor from code that runs in-game. This way, you can find bugs more easily.

tutorials/physics/using_kinematic_body_2d.rst

@@ -130,6 +130,8 @@ and ``get_slide_collision()``:
         var collision = get_slide_collision(i)
         print("I collided with ", collision.collider.name)
 
+.. note:: `get_slide_count()` only counts times the body has collided and changed direction.      
+
 See :ref:`KinematicCollision2D <class_KinematicCollision2D>` for details on what
 collision data is returned.
 

tutorials/plugins/gdnative/files/cpp_example/SConstruct

@@ -1,5 +1,5 @@
 #!python
-import os, subprocess
+import os
 
 opts = Variables([], ARGUMENTS)
 

tutorials/shading/shading_reference/canvas_item_shader.rst

@@ -125,7 +125,7 @@ is usually:
 |                                | For a Sprite with a texture of size 64x32px,                   |
 |                                | **TEXTURE_PIXEL_SIZE** = :code:`vec2(1/64, 1/32)`              |
 +--------------------------------+----------------------------------------------------------------+
-| inout vec2 **UV**              | UV.                                                            |
+| inout vec2 **UV**              | Texture coordinates.                                           |
 +--------------------------------+----------------------------------------------------------------+
 | inout vec4 **COLOR**           | Color from vertex primitive.                                   |
 +--------------------------------+----------------------------------------------------------------+

tutorials/shading/your_first_shader/your_first_spatial_shader.rst

@@ -169,13 +169,15 @@ Once you set it up and should look like this.
 
 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
+channels of ``VERTEX`` to determine where on the texture to look up. Note that the PlaneMesh coordinates are
+within the [-1,1] range (for a size of 2), while the texture coordinates are within [0,1], so to normalize
+we divide by the size of the PlaneMesh 2.0 and add 0.5. ``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 ).x; //divide by the size of the PlaneMesh
+  float height = texture(noise, VERTEX.xz / 2.0 + 0.5).x;
   VERTEX.y += height;
 
 Note: ``xyzw`` is the same as ``rgba`` in GLSL, so instead of ``texture().x`` above, we could use ``texture().r``.
@@ -289,16 +291,18 @@ Lastly, in order to ensure that we are reading from the same places on the noise
 texture, we are going to pass the ``VERTEX.xz`` position from the ``vertex()`` function to the ``fragment()``
 function. We do that with varyings.
 
-Above the ``vertex()`` define a ``vec2`` called ``vertex_position``. And inside the ``vertex()`` function
-assign ``VERTEX.xz`` to ``vertex_position``.
+Above the ``vertex()`` define a ``vec2`` called ``tex_position``. And inside the ``vertex()`` function
+assign ``VERTEX.xz`` to ``tex_position``.
 
 .. code-block:: glsl
 
-  varying vec2 vertex_position;
+  varying vec2 tex_position;
 
   void vertex() {
     ...
-    vertex_position = VERTEX.xz / 2.0;
+    tex_position = VERTEX.xz / 2.0 + 0.5;
+    float height = texture(noise, tex_position).x;
+    ...
   }
 
 And now we can access ``vertex_position`` from the ``fragment()`` function.
@@ -328,16 +332,16 @@ most of the difficult stuff for you.
   uniform sampler2D noise;
   uniform sampler2D normalmap;
 
-  varying vec2 vertex_position;
+  varying vec2 tex_position;
 
   void vertex() {
-    vertex_position = VERTEX.xz / 2.0;
-    float height = texture(noise, vertex_position).x * height_scale;
+    tex_position = VERTEX.xz / 2.0 + 0.5;
+    float height = texture(noise, tex_position).x;
     VERTEX.y += height * height_scale;
   }
 
   void fragment() {
-    NORMALMAP = texture(normalmap, vertex_position).xyz;
+    NORMALMAP = texture(normalmap, tex_position).xyz;
   }
 
 That is everything for this part. Hopefully, you now understand the basics of vertex

tutorials/viewports/custom_postprocessing.rst

@@ -77,15 +77,15 @@ Copy the following code to your shader. The above code is a single pass edge det
   shader_type canvas_item;
 
   void fragment() {
-      vec3 col = -8.0 * texture(TEXTURE, SCREEN_UV).xyz;
-      col += texture(TEXTURE, SCREEN_UV + vec2(0.0, SCREEN_PIXEL_SIZE.y)).xyz;
-      col += texture(TEXTURE, SCREEN_UV + vec2(0.0, -SCREEN_PIXEL_SIZE.y)).xyz;
-      col += texture(TEXTURE, SCREEN_UV + vec2(SCREEN_PIXEL_SIZE.x, 0.0)).xyz;
-      col += texture(TEXTURE, SCREEN_UV + vec2(-SCREEN_PIXEL_SIZE.x, 0.0)).xyz;
-      col += texture(TEXTURE, SCREEN_UV + SCREEN_PIXEL_SIZE.xy).xyz;
-      col += texture(TEXTURE, SCREEN_UV - SCREEN_PIXEL_SIZE.xy).xyz;
-      col += texture(TEXTURE, SCREEN_UV + vec2(-SCREEN_PIXEL_SIZE.x, SCREEN_PIXEL_SIZE.y)).xyz;
-      col += texture(TEXTURE, SCREEN_UV + vec2(SCREEN_PIXEL_SIZE.x, -SCREEN_PIXEL_SIZE.y)).xyz;
+      vec3 col = -8.0 * texture(TEXTURE, UV).xyz;
+      col += texture(TEXTURE, UV + vec2(0.0, SCREEN_PIXEL_SIZE.y)).xyz;
+      col += texture(TEXTURE, UV + vec2(0.0, -SCREEN_PIXEL_SIZE.y)).xyz;
+      col += texture(TEXTURE, UV + vec2(SCREEN_PIXEL_SIZE.x, 0.0)).xyz;
+      col += texture(TEXTURE, UV + vec2(-SCREEN_PIXEL_SIZE.x, 0.0)).xyz;
+      col += texture(TEXTURE, UV + SCREEN_PIXEL_SIZE.xy).xyz;
+      col += texture(TEXTURE, UV - SCREEN_PIXEL_SIZE.xy).xyz;
+      col += texture(TEXTURE, UV + vec2(-SCREEN_PIXEL_SIZE.x, SCREEN_PIXEL_SIZE.y)).xyz;
+      col += texture(TEXTURE, UV + vec2(SCREEN_PIXEL_SIZE.x, -SCREEN_PIXEL_SIZE.y)).xyz;
       COLOR.xyz = col;
   }
 
@@ -135,15 +135,15 @@ does not matter:
 
   // Blurs the screen in the X-direction.
   void fragment() {
-      vec3 col = texture(TEXTURE, SCREEN_UV).xyz * 0.16;
-      col += texture(TEXTURE, SCREEN_UV + vec2(SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.15;
-      col += texture(TEXTURE, SCREEN_UV + vec2(-SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.15;
-      col += texture(TEXTURE, SCREEN_UV + vec2(2.0 * SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.12;
-      col += texture(TEXTURE, SCREEN_UV + vec2(2.0 * -SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.12;
-      col += texture(TEXTURE, SCREEN_UV + vec2(3.0 * SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.09;
-      col += texture(TEXTURE, SCREEN_UV + vec2(3.0 * -SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.09;
-      col += texture(TEXTURE, SCREEN_UV + vec2(4.0 * SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.05;
-      col += texture(TEXTURE, SCREEN_UV + vec2(4.0 * -SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.05;
+      vec3 col = texture(TEXTURE, UV).xyz * 0.16;
+      col += texture(TEXTURE, UV + vec2(SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.15;
+      col += texture(TEXTURE, UV + vec2(-SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.15;
+      col += texture(TEXTURE, UV + vec2(2.0 * SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.12;
+      col += texture(TEXTURE, UV + vec2(2.0 * -SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.12;
+      col += texture(TEXTURE, UV + vec2(3.0 * SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.09;
+      col += texture(TEXTURE, UV + vec2(3.0 * -SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.09;
+      col += texture(TEXTURE, UV + vec2(4.0 * SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.05;
+      col += texture(TEXTURE, UV + vec2(4.0 * -SCREEN_PIXEL_SIZE.x, 0.0)).xyz * 0.05;
       COLOR.xyz = col;
   }
 
@@ -153,15 +153,15 @@ does not matter:
 
   // Blurs the screen in the Y-direction.
   void fragment() {
-      vec3 col = texture(TEXTURE, SCREEN_UV).xyz * 0.16;
-      col += texture(TEXTURE, SCREEN_UV + vec2(0.0, SCREEN_PIXEL_SIZE.y)).xyz * 0.15;
-      col += texture(TEXTURE, SCREEN_UV + vec2(0.0, -SCREEN_PIXEL_SIZE.y)).xyz * 0.15;
-      col += texture(TEXTURE, SCREEN_UV + vec2(0.0, 2.0 * SCREEN_PIXEL_SIZE.y)).xyz * 0.12;
-      col += texture(TEXTURE, SCREEN_UV + vec2(0.0, 2.0 * -SCREEN_PIXEL_SIZE.y)).xyz * 0.12;
-      col += texture(TEXTURE, SCREEN_UV + vec2(0.0, 3.0 * SCREEN_PIXEL_SIZE.y)).xyz * 0.09;
-      col += texture(TEXTURE, SCREEN_UV + vec2(0.0, 3.0 * -SCREEN_PIXEL_SIZE.y)).xyz * 0.09;
-      col += texture(TEXTURE, SCREEN_UV + vec2(0.0, 4.0 * SCREEN_PIXEL_SIZE.y)).xyz * 0.05;
-      col += texture(TEXTURE, SCREEN_UV + vec2(0.0, 4.0 * -SCREEN_PIXEL_SIZE.y)).xyz * 0.05;
+      vec3 col = texture(TEXTURE, UV).xyz * 0.16;
+      col += texture(TEXTURE, UV + vec2(0.0, SCREEN_PIXEL_SIZE.y)).xyz * 0.15;
+      col += texture(TEXTURE, UV + vec2(0.0, -SCREEN_PIXEL_SIZE.y)).xyz * 0.15;
+      col += texture(TEXTURE, UV + vec2(0.0, 2.0 * SCREEN_PIXEL_SIZE.y)).xyz * 0.12;
+      col += texture(TEXTURE, UV + vec2(0.0, 2.0 * -SCREEN_PIXEL_SIZE.y)).xyz * 0.12;
+      col += texture(TEXTURE, UV + vec2(0.0, 3.0 * SCREEN_PIXEL_SIZE.y)).xyz * 0.09;
+      col += texture(TEXTURE, UV + vec2(0.0, 3.0 * -SCREEN_PIXEL_SIZE.y)).xyz * 0.09;
+      col += texture(TEXTURE, UV + vec2(0.0, 4.0 * SCREEN_PIXEL_SIZE.y)).xyz * 0.05;
+      col += texture(TEXTURE, UV + vec2(0.0, 4.0 * -SCREEN_PIXEL_SIZE.y)).xyz * 0.05;
       COLOR.xyz = col;
   }