Merge pull request #7220 from godotengine/classref/sync-338114d

classref: Sync with current 3.5 branch (338114d)

classes/[email protected]

@@ -646,7 +646,7 @@ Returns a reference to the specified function ``funcname`` in the ``instance`` n
 
 - :ref:`Array<class_Array>` **get_stack** **(** **)**
 
-Returns an array of dictionaries representing the current call stack.
+Returns an array of dictionaries representing the current call stack. See also :ref:`print_stack<class_@GDScript_method_print_stack>`.
 
 ::
 
@@ -665,6 +665,8 @@ would print
 
     [{function:bar, line:12, source:res://script.gd}, {function:foo, line:9, source:res://script.gd}, {function:_ready, line:6, source:res://script.gd}]
 
+\ **Note:** :ref:`get_stack<class_@GDScript_method_get_stack>` only works if the running instance is connected to a debugging server (i.e. an editor instance). :ref:`get_stack<class_@GDScript_method_get_stack>` will not work in projects exported in release mode, or in projects exported in debug mode if not connected to a debugging server.
+
 ----
 
 .. _class_@GDScript_method_hash:
@@ -1084,7 +1086,7 @@ Output in the console would look something like this:
 
 - void **print_stack** **(** **)**
 
-Prints a stack track at code location, only works when running with debugger turned on.
+Prints a stack trace at the current code location. See also :ref:`get_stack<class_@GDScript_method_get_stack>`.
 
 Output in the console would look something like this:
 
@@ -1092,6 +1094,8 @@ Output in the console would look something like this:
 
     Frame 0 - res://test.gd:16 in function '_process'
 
+\ **Note:** :ref:`print_stack<class_@GDScript_method_print_stack>` only works if the running instance is connected to a debugging server (i.e. an editor instance). :ref:`print_stack<class_@GDScript_method_print_stack>` will not work in projects exported in release mode, or in projects exported in debug mode if not connected to a debugging server.
+
 ----
 
 .. _class_@GDScript_method_printerr:

classes/[email protected]

@@ -1944,6 +1944,36 @@ Since :ref:`OK<class_@GlobalScope_constant_OK>` has value 0, and all other failu
 
 .. _class_@GlobalScope_constant_PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS:
 
+.. _class_@GlobalScope_constant_PROPERTY_HINT_OBJECT_ID:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_TYPE_STRING:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_METHOD_OF_VARIANT_TYPE:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_METHOD_OF_BASE_TYPE:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_METHOD_OF_INSTANCE:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_METHOD_OF_SCRIPT:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_PROPERTY_OF_VARIANT_TYPE:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_PROPERTY_OF_BASE_TYPE:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_PROPERTY_OF_INSTANCE:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_PROPERTY_OF_SCRIPT:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_OBJECT_TOO_BIG:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_NODE_PATH_VALID_TYPES:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_SAVE_FILE:
+
+.. _class_@GlobalScope_constant_PROPERTY_HINT_MAX:
+
 enum **PropertyHint**:
 
 - **PROPERTY_HINT_NONE** = **0** --- No hint for the edited property.
@@ -2000,6 +2030,45 @@ Unlike :ref:`PROPERTY_HINT_ENUM<class_@GlobalScope_constant_PROPERTY_HINT_ENUM>`
 
 - **PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS** = **24** --- Hints that an image is compressed using lossless compression.
 
+- **PROPERTY_HINT_OBJECT_ID** = **25**
+
+- **PROPERTY_HINT_TYPE_STRING** = **26** --- Hint that a property represents a particular type. If a property is :ref:`TYPE_STRING<class_@GlobalScope_constant_TYPE_STRING>`, allows to set a type from the create dialog. If you need to create an :ref:`Array<class_Array>` to contain elements of a specific type, the ``hint_string`` must encode nested types using ``":"`` and ``"/"`` for specifying :ref:`Resource<class_Resource>` types. For instance:
+
+::
+
+    hint_string = "%s:" % [TYPE_INT] # Array of inteters.
+    hint_string = "%s:%s:" % [TYPE_ARRAY, TYPE_REAL] # Two-dimensional array of floats.
+    hint_string = "%s/%s:Resource" % [TYPE_OBJECT, TYPE_OBJECT] # Array of resources.
+    hint_string = "%s:%s/%s:Resource" % [TYPE_ARRAY, TYPE_OBJECT, TYPE_OBJECT] # Two-dimensional array of resources.
+
+\ **Note:** The final colon is required to specify for properly detecting built-in types.
+
+- **PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE** = **27**
+
+- **PROPERTY_HINT_METHOD_OF_VARIANT_TYPE** = **28**
+
+- **PROPERTY_HINT_METHOD_OF_BASE_TYPE** = **29**
+
+- **PROPERTY_HINT_METHOD_OF_INSTANCE** = **30**
+
+- **PROPERTY_HINT_METHOD_OF_SCRIPT** = **31**
+
+- **PROPERTY_HINT_PROPERTY_OF_VARIANT_TYPE** = **32**
+
+- **PROPERTY_HINT_PROPERTY_OF_BASE_TYPE** = **33**
+
+- **PROPERTY_HINT_PROPERTY_OF_INSTANCE** = **34**
+
+- **PROPERTY_HINT_PROPERTY_OF_SCRIPT** = **35**
+
+- **PROPERTY_HINT_OBJECT_TOO_BIG** = **36**
+
+- **PROPERTY_HINT_NODE_PATH_VALID_TYPES** = **37**
+
+- **PROPERTY_HINT_SAVE_FILE** = **38**
+
+- **PROPERTY_HINT_MAX** = **40**
+
 ----
 
 .. _enum_@GlobalScope_PropertyUsageFlags:

classes/class_array.rst

@@ -308,6 +308,8 @@ Assigns the given value to all elements in the array. This can typically be used
     array.resize(10)
     array.fill(0) # Initialize the 10 elements to 0.
 
+\ **Note:** If ``value`` is of a reference type (:ref:`Object<class_Object>`-derived, ``Array``, :ref:`Dictionary<class_Dictionary>`, etc.) then the array is filled with the references to the same object, i.e. no duplicates are created.
+
 ----
 
 .. _class_Array_method_find:
@@ -509,6 +511,8 @@ Duplicates the subset described in the function and returns it in an array, deep
 
 Sorts the array.
 
+\ **Note:** The sorting algorithm used is not `stable <https://en.wikipedia.org/wiki/Sorting_algorithm#Stability>`__. This means that values considered equal may have their order changed when using :ref:`sort<class_Array_method_sort>`.
+
 \ **Note:** Strings are sorted in alphabetical order (as opposed to natural order). This may lead to unexpected behavior when sorting an array of strings ending with a sequence of numbers. Consider the following example:
 
 ::
@@ -527,7 +531,9 @@ Sorts the array using a custom method. The arguments are an object that holds th
 
 For two elements ``a`` and ``b``, if the given method returns ``true``, element ``b`` will be after element ``a`` in the array.
 
-\ **Note:** You cannot randomize the return value as the heapsort algorithm expects a deterministic result. Doing so will result in unexpected behavior.
+\ **Note:** The sorting algorithm used is not `stable <https://en.wikipedia.org/wiki/Sorting_algorithm#Stability>`__. This means that values considered equal may have their order changed when using :ref:`sort_custom<class_Array_method_sort_custom>`.
+
+\ **Note:** You cannot randomize the return value as the heapsort algorithm expects a deterministic result. Randomizing the return value will result in unexpected behavior.
 
 ::
 

classes/class_audiostreamgeneratorplayback.rst

@@ -66,7 +66,7 @@ Clears the audio sample data buffer.
 
 - :ref:`int<class_int>` **get_frames_available** **(** **)** |const|
 
-Returns the number of audio data frames left to play. If this returned number reaches ``0``, the audio will stop playing until frames are added again. Therefore, make sure your script can always generate and push new audio frames fast enough to avoid audio cracking.
+Returns the number of frames that can be pushed to the audio sample data buffer without overflowing it. If the result is ``0``, the buffer is full.
 
 ----
 

classes/class_backbuffercopy.rst

@@ -17,9 +17,9 @@ Copies a region of the screen (or the whole screen) to a buffer so it can be acc
 Description
 -----------
 
-Node for back-buffering the currently-displayed screen. The region defined in the BackBufferCopy node is buffered with the content of the screen it covers, or the entire screen according to the copy mode set. Use the ``texture(SCREEN_TEXTURE, ...)`` function in your shader scripts to access the buffer.
+Node for back-buffering the currently-displayed screen. The region defined in the ``BackBufferCopy`` node is buffered with the content of the screen it covers, or the entire screen according to the copy mode set. Use the ``texture(SCREEN_TEXTURE, ...)`` function in your shader scripts to access the buffer.
 
-\ **Note:** Since this node inherits from :ref:`Node2D<class_Node2D>` (and not :ref:`Control<class_Control>`), anchors and margins won't apply to child :ref:`Control<class_Control>`-derived nodes. This can be problematic when resizing the window. To avoid this, add :ref:`Control<class_Control>`-derived nodes as *siblings* to the BackBufferCopy node instead of adding them as children.
+\ **Note:** Since this node inherits from :ref:`Node2D<class_Node2D>` (and not :ref:`Control<class_Control>`), anchors and margins won't apply to child :ref:`Control<class_Control>`-derived nodes. This can be problematic when resizing the window. To avoid this, add :ref:`Control<class_Control>`-derived nodes as *siblings* to the ``BackBufferCopy`` node instead of adding them as children.
 
 Properties
 ----------
@@ -43,11 +43,11 @@ Enumerations
 
 enum **CopyMode**:
 
-- **COPY_MODE_DISABLED** = **0** --- Disables the buffering mode. This means the BackBufferCopy node will directly use the portion of screen it covers.
+- **COPY_MODE_DISABLED** = **0** --- Disables the buffering mode. This means the ``BackBufferCopy`` node will directly use the portion of screen it covers.
 
-- **COPY_MODE_RECT** = **1** --- BackBufferCopy buffers a rectangular region.
+- **COPY_MODE_RECT** = **1** --- ``BackBufferCopy`` buffers a rectangular region.
 
-- **COPY_MODE_VIEWPORT** = **2** --- BackBufferCopy buffers the entire screen.
+- **COPY_MODE_VIEWPORT** = **2** --- ``BackBufferCopy`` buffers the entire screen.
 
 Property Descriptions
 ---------------------
@@ -80,7 +80,7 @@ Buffer mode. See :ref:`CopyMode<enum_BackBufferCopy_CopyMode>` constants.
 | *Getter*  | get_rect()                        |
 +-----------+-----------------------------------+
 
-The area covered by the BackBufferCopy. Only used if :ref:`copy_mode<class_BackBufferCopy_property_copy_mode>` is :ref:`COPY_MODE_RECT<class_BackBufferCopy_constant_COPY_MODE_RECT>`.
+The area covered by the ``BackBufferCopy``. Only used if :ref:`copy_mode<class_BackBufferCopy_property_copy_mode>` is :ref:`COPY_MODE_RECT<class_BackBufferCopy_constant_COPY_MODE_RECT>`.
 
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
 .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`

classes/class_cylindershape.rst

@@ -19,6 +19,8 @@ Description
 
 Cylinder shape for collisions.
 
+\ **Note:** When using GodotPhysics instead of the default Bullet physics engine, there are several known bugs with cylinder collision shapes. Using :ref:`CapsuleShape<class_CapsuleShape>` or :ref:`BoxShape<class_BoxShape>` instead is recommended.
+
 Tutorials
 ---------
 

classes/class_editorscript.rst

@@ -33,6 +33,8 @@ Scripts extending this class and implementing its :ref:`_run<class_EditorScript_
 
 \ **Note:** The script is run in the Editor context, which means the output is visible in the console window started with the Editor (stdout) instead of the usual Godot **Output** dock.
 
+\ **Note:** EditorScript is reference counted, meaning it is destroyed when nothing references it. This can cause errors during asynchronous operations if there are no references to the script.
+
 Methods
 -------
 

classes/class_environment.rst

@@ -654,7 +654,7 @@ The :ref:`Color<class_Color>` displayed for clear areas of the scene. Only effec
 | *Getter*  | get_bg_energy()      |
 +-----------+----------------------+
 
-The power of the light emitted by the background.
+The power of the light emitted by the background. This affects the sky brightness, the ambient light (if :ref:`ambient_light_sky_contribution<class_Environment_property_ambient_light_sky_contribution>` is greater than ``0.0``) and specular light from the sky.
 
 ----
 

classes/class_input.rst

@@ -647,6 +647,8 @@ Sets a custom mouse cursor image, which is only visible inside the game window.
 
 \ **Note:** Only images imported with the **Lossless**, **Lossy** or **Uncompressed** compression modes are supported. The **Video RAM** compression mode can't be used for custom cursors.
 
+\ **Note:** On the web platform, the maximum allowed cursor image size is 128×128. Cursor images larger than 32×32 will also only be displayed if the mouse cursor image is entirely located within the page for `security reasons <https://chromestatus.com/feature/5825971391299584>`__.
+
 ----
 
 .. _class_Input_method_set_default_cursor_shape:

classes/class_light.rst

@@ -296,6 +296,8 @@ If ``true``, the light's effect is reversed, darkening areas and casting bright
 
 The size of the light in Godot units. Only considered in baked lightmaps and only if :ref:`light_bake_mode<class_Light_property_light_bake_mode>` is set to :ref:`BAKE_ALL<class_Light_constant_BAKE_ALL>`. Increasing this value will make the shadows appear blurrier. This can be used to simulate area lights to an extent.
 
+\ **Note:** :ref:`light_size<class_Light_property_light_size>` is not affected by :ref:`Spatial.scale<class_Spatial_property_scale>` (the light's scale or its parent's scale).
+
 ----
 
 .. _class_Light_property_light_specular:

classes/class_navigationagent.rst

@@ -21,6 +21,8 @@ Description
 
 \ **Note:** After :ref:`set_target_location<class_NavigationAgent_method_set_target_location>` is used it is required to use the :ref:`get_next_location<class_NavigationAgent_method_get_next_location>` function once every physics frame to update the internal path logic of the NavigationAgent. The returned vector position from this function should be used as the next movement position for the agent's parent Node.
 
+\ **Note:** By default, the expensive calculations for avoidance are done in a thread. In HTML5 exports without thread support, they will be done on the main thread, which can lead to performance issues.
+
 Properties
 ----------
 

classes/class_navigationagent2d.rst

@@ -21,6 +21,8 @@ Description
 
 \ **Note:** After :ref:`set_target_location<class_NavigationAgent2D_method_set_target_location>` is used it is required to use the :ref:`get_next_location<class_NavigationAgent2D_method_get_next_location>` function once every physics frame to update the internal path logic of the NavigationAgent. The returned vector position from this function should be used as the next movement position for the agent's parent Node.
 
+\ **Note:** By default, the expensive calculations for avoidance are done in a thread. In HTML5 exports without thread support, they will be done on the main thread, which can lead to performance issues.
+
 Properties
 ----------
 

classes/class_navigationserver.rst

@@ -29,6 +29,8 @@ To use the collision avoidance system, you may use agents. You can set an agent'
 
 \ **Note:** The collision avoidance system ignores regions. Using the modified velocity as-is might lead to pushing and agent outside of a navigable area. This is a limitation of the collision avoidance system, any more complex situation may require the use of the physics engine.
 
+\ **Note:** By default, the expensive calculations for avoidance are done in a thread. In HTML5 exports without thread support, they will be done on the main thread, which can lead to performance issues.
+
 This server keeps tracks of any call and executes them during the sync phase. This means that you can request any change to the map, using any thread, without worrying.
 
 Tutorials

classes/class_omnilight.rst

@@ -101,6 +101,8 @@ The light's attenuation (drop-off) curve. A number of presets are available in t
 
 The light's radius. Note that the effectively lit area may appear to be smaller depending on the :ref:`omni_attenuation<class_OmniLight_property_omni_attenuation>` in use. No matter the :ref:`omni_attenuation<class_OmniLight_property_omni_attenuation>` in use, the light will never reach anything outside this radius.
 
+\ **Note:** :ref:`omni_range<class_OmniLight_property_omni_range>` is not affected by :ref:`Spatial.scale<class_Spatial_property_scale>` (the light's scale or its parent's scale).
+
 ----
 
 .. _class_OmniLight_property_omni_shadow_detail:

classes/class_os.rst

@@ -1106,7 +1106,7 @@ Returns the audio driver name for the given index.
 
 - :ref:`String<class_String>` **get_cache_dir** **(** **)** |const|
 
-Returns the *global* cache data directory according to the operating system's standards. On desktop platforms, this path can be overridden by setting the ``XDG_CACHE_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_config_dir<class_OS_method_get_config_dir>` and :ref:`get_data_dir<class_OS_method_get_data_dir>`.
+Returns the *global* cache data directory according to the operating system's standards. On Linux, this path can be overridden by setting the ``XDG_CACHE_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_config_dir<class_OS_method_get_config_dir>` and :ref:`get_data_dir<class_OS_method_get_data_dir>`.
 
 Not to be confused with :ref:`get_user_data_dir<class_OS_method_get_user_data_dir>`, which returns the *project-specific* user data path.
 
@@ -1144,7 +1144,7 @@ Here's a minimal example on how to parse command-line arguments into a dictionar
 
 - :ref:`String<class_String>` **get_config_dir** **(** **)** |const|
 
-Returns the *global* user configuration directory according to the operating system's standards. On desktop platforms, this path can be overridden by setting the ``XDG_CONFIG_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_cache_dir<class_OS_method_get_cache_dir>` and :ref:`get_data_dir<class_OS_method_get_data_dir>`.
+Returns the *global* user configuration directory according to the operating system's standards. On Linux, this path can be overridden by setting the ``XDG_CONFIG_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_cache_dir<class_OS_method_get_cache_dir>` and :ref:`get_data_dir<class_OS_method_get_data_dir>`.
 
 Not to be confused with :ref:`get_user_data_dir<class_OS_method_get_user_data_dir>`, which returns the *project-specific* user data path.
 
@@ -1174,7 +1174,7 @@ Returns the currently used video driver, using one of the values from :ref:`Vide
 
 - :ref:`String<class_String>` **get_data_dir** **(** **)** |const|
 
-Returns the *global* user data directory according to the operating system's standards. On desktop platforms, this path can be overridden by setting the ``XDG_DATA_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_cache_dir<class_OS_method_get_cache_dir>` and :ref:`get_config_dir<class_OS_method_get_config_dir>`.
+Returns the *global* user data directory according to the operating system's standards. On Linux, this path can be overridden by setting the ``XDG_DATA_HOME`` environment variable before starting the project. See :doc:`File paths in Godot projects <../tutorials/io/data_paths>` in the documentation for more information. See also :ref:`get_cache_dir<class_OS_method_get_cache_dir>` and :ref:`get_config_dir<class_OS_method_get_config_dir>`.
 
 Not to be confused with :ref:`get_user_data_dir<class_OS_method_get_user_data_dir>`, which returns the *project-specific* user data path.
 
@@ -2255,6 +2255,8 @@ Requests the OS to open a resource with the most appropriate program. For exampl
 
 Use :ref:`ProjectSettings.globalize_path<class_ProjectSettings_method_globalize_path>` to convert a ``res://`` or ``user://`` path into a system path for use with this method.
 
+\ **Note:** Use :ref:`String.percent_encode<class_String_method_percent_encode>` to encode characters within URLs in a URL-safe, portable way. This is especially required for line breaks. Otherwise, :ref:`shell_open<class_OS_method_shell_open>` may not work correctly in a project exported to the Web platform.
+
 \ **Note:** This method is implemented on Android, iOS, HTML5, Linux, macOS and Windows.
 
 ----

classes/class_particles2d.rst

@@ -34,7 +34,9 @@ Tutorials
 
 - :doc:`Particle systems (2D) <../tutorials/2d/particle_systems_2d>`
 
-- `2D Dodge The Creeps Demo <https://godotengine.org/asset-library/asset/515>`__
+- `2D Particles Demo <https://godotengine.org/asset-library/asset/118>`__
+
+- `2D Dodge The Creeps Demo (uses GPUParticles2D for the trail behind the player) <https://godotengine.org/asset-library/asset/515>`__
 
 Properties
 ----------

classes/class_projectsettings.rst

@@ -6720,12 +6720,16 @@ If set to a value greater than ``0.0``, contrast-adaptive sharpening will be app
 | *Default* | ``false`` |
 +-----------+-----------+
 
-If ``true``, uses a fast post-processing filter to make banding significantly less visible. In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger.
+If ``true``, uses a fast post-processing filter to make banding significantly less visible in 3D. 2D rendering is *not* affected by debanding unless the :ref:`Environment.background_mode<class_Environment_property_background_mode>` is :ref:`Environment.BG_CANVAS<class_Environment_constant_BG_CANVAS>`. In this case, :ref:`rendering/quality/intended_usage/framebuffer_allocation<class_ProjectSettings_property_rendering/quality/intended_usage/framebuffer_allocation>` must also be set to **3D**.
+
+In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger.
 
 \ **Note:** Only available on the GLES3 backend. :ref:`rendering/quality/depth/hdr<class_ProjectSettings_property_rendering/quality/depth/hdr>` must also be ``true`` for debanding to be effective.
 
 \ **Note:** There are known issues with debanding breaking rendering on mobile platforms. Due to this, it is recommended to leave this option disabled when targeting mobile platforms.
 
+\ **Note:** This property is only read when the project starts. To set debanding at run-time, set :ref:`Viewport.debanding<class_Viewport_property_debanding>` on the root :ref:`Viewport<class_Viewport>` instead.
+
 ----
 
 .. _class_ProjectSettings_property_rendering/quality/filters/use_fxaa:

classes/class_regex.rst

@@ -151,7 +151,9 @@ Returns whether this object has a valid search pattern assigned.
 
 - :ref:`RegExMatch<class_RegExMatch>` **search** **(** :ref:`String<class_String>` subject, :ref:`int<class_int>` offset=0, :ref:`int<class_int>` end=-1 **)** |const|
 
-Searches the text for the compiled pattern. Returns a :ref:`RegExMatch<class_RegExMatch>` container of the first matching result if found, otherwise ``null``. The region to search within can be specified without modifying where the start and end anchor would be.
+Searches the text for the compiled pattern. Returns a :ref:`RegExMatch<class_RegExMatch>` container of the first matching result if found, otherwise ``null``.
+
+The region to search within can be specified with ``offset`` and ``end``. This is useful when searching for another match in the same ``subject`` by calling this method again after a previous success. Setting these parameters differs from passing over a shortened string. For example, the start anchor ``^`` is not affected by ``offset``, and the character before ``offset`` will be checked for the word boundary ``\b``.
 
 ----
 
@@ -159,7 +161,9 @@ Searches the text for the compiled pattern. Returns a :ref:`RegExMatch<class_Reg
 
 - :ref:`Array<class_Array>` **search_all** **(** :ref:`String<class_String>` subject, :ref:`int<class_int>` offset=0, :ref:`int<class_int>` end=-1 **)** |const|
 
-Searches the text for the compiled pattern. Returns an array of :ref:`RegExMatch<class_RegExMatch>` containers for each non-overlapping result. If no results were found, an empty array is returned instead. The region to search within can be specified without modifying where the start and end anchor would be.
+Searches the text for the compiled pattern. Returns an array of :ref:`RegExMatch<class_RegExMatch>` containers for each non-overlapping result. If no results were found, an empty array is returned instead.
+
+The region to search within can be specified with ``offset`` and ``end``. This is useful when searching for another match in the same ``subject`` by calling this method again after a previous success. Setting these parameters differs from passing over a shortened string. For example, the start anchor ``^`` is not affected by ``offset``, and the character before ``offset`` will be checked for the word boundary ``\b``.
 
 ----
 
@@ -167,7 +171,9 @@ Searches the text for the compiled pattern. Returns an array of :ref:`RegExMatch
 
 - :ref:`String<class_String>` **sub** **(** :ref:`String<class_String>` subject, :ref:`String<class_String>` replacement, :ref:`bool<class_bool>` all=false, :ref:`int<class_int>` offset=0, :ref:`int<class_int>` end=-1 **)** |const|
 
-Searches the text for the compiled pattern and replaces it with the specified string. Escapes and backreferences such as ``$1`` and ``$name`` are expanded and resolved. By default, only the first instance is replaced, but it can be changed for all instances (global replacement). The region to search within can be specified without modifying where the start and end anchor would be.
+Searches the text for the compiled pattern and replaces it with the specified string. Escapes and backreferences such as ``$1`` and ``$name`` are expanded and resolved. By default, only the first instance is replaced, but it can be changed for all instances (global replacement).
+
+The region to search within can be specified with ``offset`` and ``end``. This is useful when searching for another match in the same ``subject`` by calling this method again after a previous success. Setting these parameters differs from passing over a shortened string. For example, the start anchor ``^`` is not affected by ``offset``, and the character before ``offset`` will be checked for the word boundary ``\b``.
 
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
 .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`

classes/class_scenetree.rst

@@ -264,6 +264,8 @@ enum **GroupCallFlags**:
 
 - **GROUP_CALL_UNIQUE** = **4** --- Call a group only once even if the call is executed many times.
 
+\ **Note:** Arguments are not taken into account when deciding whether the call is unique or not. Therefore when the same method is called with different arguments, only the first call will be performed.
+
 ----
 
 .. _enum_SceneTree_StretchMode:

classes/class_spatial.rst

@@ -293,6 +293,8 @@ Scale part of the local transformation.
 
 \ **Note:** Mixed negative scales in 3D are not decomposable from the transformation matrix. Due to the way scale is represented with transformation matrices in Godot, the scale values will either be all positive or all negative.
 
+\ **Note:** Not all nodes are visually scaled by the :ref:`scale<class_Spatial_property_scale>` property. For example, :ref:`Light<class_Light>`\ s are not visually affected by :ref:`scale<class_Spatial_property_scale>`.
+
 ----
 
 .. _class_Spatial_property_transform:

classes/class_spotlight.rst

@@ -58,6 +58,8 @@ Property Descriptions
 
 The spotlight's angle in degrees.
 
+\ **Note:** :ref:`spot_angle<class_SpotLight_property_spot_angle>` is not affected by :ref:`Spatial.scale<class_Spatial_property_scale>` (the light's scale or its parent's scale).
+
 ----
 
 .. _class_SpotLight_property_spot_angle_attenuation:
@@ -106,6 +108,8 @@ The spotlight's light energy attenuation curve.
 
 The maximal range that can be reached by the spotlight. Note that the effectively lit area may appear to be smaller depending on the :ref:`spot_attenuation<class_SpotLight_property_spot_attenuation>` in use. No matter the :ref:`spot_attenuation<class_SpotLight_property_spot_attenuation>` in use, the light will never reach anything outside this range.
 
+\ **Note:** :ref:`spot_range<class_SpotLight_property_spot_range>` is not affected by :ref:`Spatial.scale<class_Spatial_property_scale>` (the light's scale or its parent's scale).
+
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
 .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
 .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`

classes/class_string.rst

@@ -867,7 +867,7 @@ Returns a copy of the string with characters removed from the left. The ``chars`
 
 - :ref:`bool<class_bool>` **match** **(** :ref:`String<class_String>` expr **)**
 
-Does a simple case-sensitive expression match, where ``"*"`` matches zero or more arbitrary characters and ``"?"`` matches any single character except a period (``"."``). An empty string or empty expression always evaluates to ``false``.
+Does a simple expression match (also called "glob" or "globbing"), where ``*`` matches zero or more arbitrary characters and ``?`` matches any single character except a period (``.``). An empty string or empty expression always evaluates to ``false``.
 
 ----
 
@@ -875,7 +875,7 @@ Does a simple case-sensitive expression match, where ``"*"`` matches zero or mor
 
 - :ref:`bool<class_bool>` **matchn** **(** :ref:`String<class_String>` expr **)**
 
-Does a simple case-insensitive expression match, where ``"*"`` matches zero or more arbitrary characters and ``"?"`` matches any single character except a period (``"."``). An empty string or empty expression always evaluates to ``false``.
+Does a simple **case-insensitive** expression match, where ``*`` matches zero or more arbitrary characters and ``?`` matches any single character except a period (``.``). An empty string or empty expression always evaluates to ``false``.
 
 ----
 
@@ -953,7 +953,7 @@ Formats a number to have an exact number of ``digits`` before the decimal point.
 
 - :ref:`String<class_String>` **percent_decode** **(** **)**
 
-Decode a percent-encoded string. See :ref:`percent_encode<class_String_method_percent_encode>`.
+Decode a percent-encoded string (also called URI-encoded string). See also :ref:`percent_encode<class_String_method_percent_encode>`.
 
 ----
 
@@ -961,7 +961,7 @@ Decode a percent-encoded string. See :ref:`percent_encode<class_String_method_pe
 
 - :ref:`String<class_String>` **percent_encode** **(** **)**
 
-Percent-encodes a string. Encodes parameters in a URL when sending a HTTP GET request (and bodies of form-urlencoded POST requests).
+Percent-encodes a string (also called URI-encoded string). Encodes parameters in a URL when sending a HTTP GET request (and bodies of form-urlencoded POST requests). See also :ref:`percent_decode<class_String_method_percent_decode>`.
 
 ----
 

classes/class_viewport.rst

@@ -21,7 +21,7 @@ A Viewport creates a different view into the screen, or a sub-view inside anothe
 
 Optionally, a viewport can have its own 2D or 3D world, so they don't share what they draw with other viewports.
 
-If a viewport is a child of a :ref:`ViewportContainer<class_ViewportContainer>`, it will automatically take up its size, otherwise it must be set manually.
+If a viewport is a child of a :ref:`ViewportContainer<class_ViewportContainer>`, the viewport will automatically take up the container's size, otherwise it must be set manually.
 
 Viewports can also choose to be audio listeners, so they generate positional audio depending on a 2D or 3D camera child of it.
 
@@ -465,7 +465,9 @@ The canvas transform of the viewport, useful for changing the on-screen position
 | *Getter*  | get_use_debanding()      |
 +-----------+--------------------------+
 
-If ``true``, uses a fast post-processing filter to make banding significantly less visible. In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger.
+If ``true``, uses a fast post-processing filter to make banding significantly less visible in 3D. 2D rendering is *not* affected by debanding unless the :ref:`Environment.background_mode<class_Environment_property_background_mode>` is :ref:`Environment.BG_CANVAS<class_Environment_constant_BG_CANVAS>`. In this case, :ref:`usage<class_Viewport_property_usage>` must also be set to :ref:`USAGE_3D<class_Viewport_constant_USAGE_3D>`. See also :ref:`ProjectSettings.rendering/quality/filters/use_debanding<class_ProjectSettings_property_rendering/quality/filters/use_debanding>`.
+
+In some cases, debanding may introduce a slightly noticeable dithering pattern. It's recommended to enable debanding only when actually needed since the dithering pattern will make lossless-compressed screenshots larger.
 
 \ **Note:** Only available on the GLES3 backend. :ref:`hdr<class_Viewport_property_hdr>` must also be ``true`` for debanding to be effective.
 
@@ -499,7 +501,7 @@ The overlay mode for test rendered geometry in debug purposes.
 | *Getter*  | is_3d_disabled()      |
 +-----------+-----------------------+
 
-If ``true``, the viewport will disable 3D rendering. For actual disabling use ``usage``.
+If ``true``, the viewport will disable 3D rendering. To actually disable allocation of 3D buffers, set :ref:`usage<class_Viewport_property_usage>` instead.
 
 ----
 
@@ -887,7 +889,7 @@ If ``true``, the viewport should render its background as transparent.
 | *Getter*  | get_usage()      |
 +-----------+------------------+
 
-The rendering mode of viewport.
+The viewport's rendering mode. This controls which buffers are allocated for the viewport (2D only, or 2D + 3D). 2D-only options can reduce memory usage and improve performance slightly, especially on low-end devices.
 
 \ **Note:** If set to :ref:`USAGE_2D<class_Viewport_constant_USAGE_2D>` or :ref:`USAGE_2D_NO_SAMPLING<class_Viewport_constant_USAGE_2D_NO_SAMPLING>`, :ref:`hdr<class_Viewport_property_hdr>` will have no effect when enabled since HDR is not supported for 2D.
 

classes/class_viewportcontainer.rst

@@ -17,7 +17,7 @@ Control for holding :ref:`Viewport<class_Viewport>`\ s.
 Description
 -----------
 
-A :ref:`Container<class_Container>` node that holds a :ref:`Viewport<class_Viewport>`, automatically setting its size.
+A :ref:`Container<class_Container>` node that holds a :ref:`Viewport<class_Viewport>`, automatically setting the viewport's size.
 
 \ **Note:** Changing a ViewportContainer's :ref:`Control.rect_scale<class_Control_property_rect_scale>` will cause its contents to appear distorted. To change its visual size without causing distortion, adjust the node's margins instead (if it's not already in a container).
 

classes/class_visualinstance.rst

@@ -24,9 +24,13 @@ The ``VisualInstance`` is used to connect a resource to a visual representation.
 Properties
 ----------
 
-+-----------------------+-----------------------------------------------------+-------+
-| :ref:`int<class_int>` | :ref:`layers<class_VisualInstance_property_layers>` | ``1`` |
-+-----------------------+-----------------------------------------------------+-------+
++---------------------------+---------------------------------------------------------------------------------------+----------+
+| :ref:`int<class_int>`     | :ref:`layers<class_VisualInstance_property_layers>`                                   | ``1``    |
++---------------------------+---------------------------------------------------------------------------------------+----------+
+| :ref:`float<class_float>` | :ref:`sorting_offset<class_VisualInstance_property_sorting_offset>`                   | ``0.0``  |
++---------------------------+---------------------------------------------------------------------------------------+----------+
+| :ref:`bool<class_bool>`   | :ref:`sorting_use_aabb_center<class_VisualInstance_property_sorting_use_aabb_center>` | ``true`` |
++---------------------------+---------------------------------------------------------------------------------------+----------+
 
 Methods
 -------
@@ -66,6 +70,40 @@ The render layer(s) this ``VisualInstance`` is drawn on.
 
 This object will only be visible for :ref:`Camera<class_Camera>`\ s whose cull mask includes the render object this ``VisualInstance`` is set to.
 
+----
+
+.. _class_VisualInstance_property_sorting_offset:
+
+- :ref:`float<class_float>` **sorting_offset**
+
++-----------+---------------------------+
+| *Default* | ``0.0``                   |
++-----------+---------------------------+
+| *Setter*  | set_sorting_offset(value) |
++-----------+---------------------------+
+| *Getter*  | get_sorting_offset()      |
++-----------+---------------------------+
+
+The sorting offset used by this ``VisualInstance``. Adjusting it to a higher value will make the ``VisualInstance`` reliably draw on top of other ``VisualInstance``\ s that are otherwise positioned at the same spot.
+
+----
+
+.. _class_VisualInstance_property_sorting_use_aabb_center:
+
+- :ref:`bool<class_bool>` **sorting_use_aabb_center**
+
++-----------+------------------------------------+
+| *Default* | ``true``                           |
++-----------+------------------------------------+
+| *Setter*  | set_sorting_use_aabb_center(value) |
++-----------+------------------------------------+
+| *Getter*  | is_sorting_use_aabb_center()       |
++-----------+------------------------------------+
+
+If ``true``, the object is sorted based on the :ref:`AABB<class_AABB>` center. Sorted based on the global position otherwise.
+
+The :ref:`AABB<class_AABB>` center based sorting is generally more accurate for 3D models. The position based sorting instead allows to better control the drawing order when working with :ref:`Particles<class_Particles>` and :ref:`CPUParticles<class_CPUParticles>`.
+
 Method Descriptions
 -------------------