classref: Sync with current master branch (6da4ad1)

classes/class_array.rst

@@ -567,7 +567,7 @@ void **erase** **(** :ref:`Variant<class_Variant>` value **)**
 
 Removes the first occurrence of a value from the array. If the value does not exist in the array, nothing happens. To remove an element by index, use :ref:`remove_at<class_Array_method_remove_at>` instead.
 
-\ **Note:** This method acts in-place and doesn't return a value.
+\ **Note:** This method acts in-place and doesn't return a modified array.
 
 \ **Note:** On large arrays, this method will be slower if the removed element is close to the beginning of the array (index 0). This is because all elements placed after the removed element have to be reindexed.
 
@@ -770,9 +770,9 @@ Returns a hashed 32-bit integer value representing the array and its contents.
 
 :ref:`int<class_int>` **insert** **(** :ref:`int<class_int>` position, :ref:`Variant<class_Variant>` value **)**
 
-Inserts a new element at a given position in the array. The position must be valid, or at the end of the array (``pos == size()``).
+Inserts a new element at a given position in the array. The position must be valid, or at the end of the array (``pos == size()``). Returns :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` on success, or one of the other :ref:`Error<enum_@GlobalScope_Error>` values if the operation failed.
 
-\ **Note:** This method acts in-place and doesn't return a value.
+\ **Note:** This method acts in-place and doesn't return a modified array.
 
 \ **Note:** On large arrays, this method will be slower if the inserted element is close to the beginning of the array (index 0). This is because all elements placed after the newly inserted element have to be reindexed.
 
@@ -909,7 +909,7 @@ See also :ref:`max<class_Array_method_max>` for an example of using a custom com
 
 :ref:`Variant<class_Variant>` **pick_random** **(** **)** |const|
 
-Returns a random value from the target array.
+Returns a random value from the target array. Prints an error and returns ``null`` if the array is empty.
 
 
 .. tabs::
@@ -1029,7 +1029,7 @@ void **remove_at** **(** :ref:`int<class_int>` position **)**
 
 Removes an element from the array by index. If the index does not exist in the array, nothing happens. To remove an element by searching for its value, use :ref:`erase<class_Array_method_erase>` instead.
 
-\ **Note:** This method acts in-place and doesn't return a value.
+\ **Note:** This method acts in-place and doesn't return a modified array.
 
 \ **Note:** On large arrays, this method will be slower if the removed element is close to the beginning of the array (index 0). This is because all elements placed after the removed element have to be reindexed.
 
@@ -1045,7 +1045,9 @@ Removes an element from the array by index. If the index does not exist in the a
 
 :ref:`int<class_int>` **resize** **(** :ref:`int<class_int>` size **)**
 
-Resizes the array to contain a different number of elements. If the array size is smaller, elements are cleared, if bigger, new elements are ``null``.
+Resizes the array to contain a different number of elements. If the array size is smaller, elements are cleared, if bigger, new elements are ``null``. Returns :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` on success, or one of the other :ref:`Error<enum_@GlobalScope_Error>` values if the operation failed.
+
+\ **Note:** This method acts in-place and doesn't return a modified array.
 
 .. rst-class:: classref-item-separator
 

classes/class_arrayoccluder3d.rst

@@ -23,6 +23,13 @@ Description
 
 See :ref:`OccluderInstance3D<class_OccluderInstance3D>`'s documentation for instructions on setting up occlusion culling.
 
+.. rst-class:: classref-introduction-group
+
+Tutorials
+---------
+
+- :doc:`Occlusion culling <../tutorials/3d/occlusion_culling>`
+
 .. rst-class:: classref-reftable-group
 
 Properties

classes/class_audiostreammicrophone.rst

@@ -28,6 +28,8 @@ When used directly in an :ref:`AudioStreamPlayer<class_AudioStreamPlayer>` node,
 Tutorials
 ---------
 
+- :doc:`Recording with microphone <../tutorials/audio/recording_with_microphone>`
+
 - `Audio Mic Record Demo <https://github.com/godotengine/godot-demo-projects/tree/master/audio/mic_record>`__
 
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`

classes/class_boxoccluder3d.rst

@@ -23,6 +23,13 @@ Description
 
 See :ref:`OccluderInstance3D<class_OccluderInstance3D>`'s documentation for instructions on setting up occlusion culling.
 
+.. rst-class:: classref-introduction-group
+
+Tutorials
+---------
+
+- :doc:`Occlusion culling <../tutorials/3d/occlusion_culling>`
+
 .. rst-class:: classref-reftable-group
 
 Properties

classes/class_cameraattributesphysical.rst

@@ -27,6 +27,13 @@ The default settings are intended for use in an outdoor environment, tips for se
 
 \ **Note:** Depth of field blur is only supported in the Forward+ and Mobile rendering methods, not Compatibility.
 
+.. rst-class:: classref-introduction-group
+
+Tutorials
+---------
+
+- :doc:`Physical light and camera units <../tutorials/3d/physical_light_and_camera_units>`
+
 .. rst-class:: classref-reftable-group
 
 Properties

classes/class_color.rst

@@ -1883,7 +1883,7 @@ Returns ``true`` if ``color`` is a valid HTML hexadecimal color string. The stri
     Color.html_is_valid("55AAFF")    # Returns true
     Color.html_is_valid("#F2C")      # Returns true
 
-    Color.html_is_valid("#AABBC)     # Returns false
+    Color.html_is_valid("#AABBC")    # Returns false
     Color.html_is_valid("#55aaFF5")  # Returns false
 
  .. code-tab:: csharp

classes/class_control.rst

@@ -52,6 +52,8 @@ Tutorials
 
 - :doc:`Control node gallery <../tutorials/ui/control_node_gallery>`
 
+- :doc:`Multiple resolutions <../tutorials/rendering/multiple_resolutions>`
+
 - `All GUI Demos <https://github.com/godotengine/godot-demo-projects/tree/master/gui>`__
 
 .. rst-class:: classref-reftable-group

classes/class_cpuparticles3d.rst

@@ -23,6 +23,13 @@ CPU-based 3D particle node used to create a variety of particle systems and effe
 
 See also :ref:`GPUParticles3D<class_GPUParticles3D>`, which provides the same functionality with hardware acceleration, but may not run on older devices.
 
+.. rst-class:: classref-introduction-group
+
+Tutorials
+---------
+
+- :doc:`Particle systems (3D) <../tutorials/3d/particles/index>`
+
 .. rst-class:: classref-reftable-group
 
 Properties

classes/class_cryptokey.rst

@@ -23,6 +23,13 @@ The CryptoKey class represents a cryptographic key. Keys can be loaded and saved
 
 They can be used to generate a self-signed :ref:`X509Certificate<class_X509Certificate>` via :ref:`Crypto.generate_self_signed_certificate<class_Crypto_method_generate_self_signed_certificate>` and as private key in :ref:`StreamPeerTLS.accept_stream<class_StreamPeerTLS_method_accept_stream>` along with the appropriate certificate.
 
+.. rst-class:: classref-introduction-group
+
+Tutorials
+---------
+
+- :doc:`SSL certificates <../tutorials/networking/ssl_certificates>`
+
 .. rst-class:: classref-reftable-group
 
 Methods

classes/class_directionallight3d.rst

@@ -26,7 +26,9 @@ A directional light is a type of :ref:`Light3D<class_Light3D>` node that models
 Tutorials
 ---------
 
-- :doc:`Lights and shadows <../tutorials/3d/lights_and_shadows>`
+- :doc:`3D lights and shadows <../tutorials/3d/lights_and_shadows>`
+
+- :doc:`Faking global illumination <../tutorials/3d/global_illumination/faking_global_illumination>`
 
 .. rst-class:: classref-reftable-group
 

classes/class_editorexportplatform.rst

@@ -25,6 +25,13 @@ Base resource that provides the functionality of exporting a release build of a
 
 Used in scripting by :ref:`EditorExportPlugin<class_EditorExportPlugin>` to configure platform-specific customization of scenes and resources. See :ref:`EditorExportPlugin._begin_customize_scenes<class_EditorExportPlugin_method__begin_customize_scenes>` and :ref:`EditorExportPlugin._begin_customize_resources<class_EditorExportPlugin_method__begin_customize_resources>` for more details.
 
+.. rst-class:: classref-introduction-group
+
+Tutorials
+---------
+
+- `$DOCS_URL/tutorials/platform/consoles.html <Console support in Godot>`__
+
 .. |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_editorexportplatformandroid.rst

@@ -23,6 +23,8 @@ Tutorials
 
 - :doc:`Custom builds for Android <../tutorials/export/android_custom_build>`
 
+- :doc:`Android plugins documentation index <../tutorials/platform/index>`
+
 .. rst-class:: classref-reftable-group
 
 Properties

classes/class_editorexportplatformios.rst

@@ -21,6 +21,8 @@ Tutorials
 
 - :doc:`Exporting for iOS <../tutorials/export/exporting_for_ios>`
 
+- :doc:`iOS plugins documentation index <../tutorials/platform/ios/index>`
+
 .. rst-class:: classref-reftable-group
 
 Properties

classes/class_editorexportplatformmacos.rst

@@ -790,7 +790,7 @@ If enabled, a wrapper that can be used to run the application with console outpu
 
 :ref:`bool<class_bool>` **display/high_res**
 
-If ``true``, the application is rendered at native display resolution, otherwise it is always rendered at loHPI resolution and upscaled by OS when required.
+If ``true``, the application is rendered at native display resolution, otherwise it is always rendered at loDPI resolution and upscaled by OS when required.
 
 .. rst-class:: classref-item-separator
 

classes/class_editorexportplatformweb.rst

@@ -21,6 +21,8 @@ Tutorials
 
 - :doc:`Exporting for the Web <../tutorials/export/exporting_for_web>`
 
+- :doc:`Web documentation index <../tutorials/platform/web/index>`
+
 .. rst-class:: classref-reftable-group
 
 Properties

classes/class_editorplugin.rst

@@ -203,6 +203,8 @@ Emitted when user changes the workspace (**2D**, **3D**, **Script**, **AssetLib*
 
 Emitted when any project setting has changed.
 
+\ *Deprecated.* Use :ref:`ProjectSettings.settings_changed<class_ProjectSettings_signal_settings_changed>` instead.
+
 .. rst-class:: classref-item-separator
 
 ----

classes/class_editorresourcepreview.rst

@@ -19,7 +19,7 @@ A node used to generate previews of resources or files.
 Description
 -----------
 
-This node is used to generate previews for resources of files.
+This node is used to generate previews for resources or files.
 
 \ **Note:** This class shouldn't be instantiated directly. Instead, access the singleton using :ref:`EditorInterface.get_resource_previewer<class_EditorInterface_method_get_resource_previewer>`.
 

classes/class_editorresourcepreviewgenerator.rst

@@ -76,7 +76,7 @@ Returning an empty texture is an OK way to fail and let another generator take c
 
 Care must be taken because this function is always called from a thread (not the main thread).
 
-\ ``metadata`` dictionary can modified to store file-specific metadata that can be used in :ref:`EditorResourceTooltipPlugin._make_tooltip_for_path<class_EditorResourceTooltipPlugin_method__make_tooltip_for_path>` (like image size, sample length etc.).
+\ ``metadata`` dictionary can be modified to store file-specific metadata that can be used in :ref:`EditorResourceTooltipPlugin._make_tooltip_for_path<class_EditorResourceTooltipPlugin_method__make_tooltip_for_path>` (like image size, sample length etc.).
 
 .. rst-class:: classref-item-separator
 
@@ -94,7 +94,7 @@ Returning an empty texture is an OK way to fail and let another generator take c
 
 Care must be taken because this function is always called from a thread (not the main thread).
 
-\ ``metadata`` dictionary can modified to store file-specific metadata that can be used in :ref:`EditorResourceTooltipPlugin._make_tooltip_for_path<class_EditorResourceTooltipPlugin_method__make_tooltip_for_path>` (like image size, sample length etc.).
+\ ``metadata`` dictionary can be modified to store file-specific metadata that can be used in :ref:`EditorResourceTooltipPlugin._make_tooltip_for_path<class_EditorResourceTooltipPlugin_method__make_tooltip_for_path>` (like image size, sample length etc.).
 
 .. rst-class:: classref-item-separator
 

classes/class_editorsettings.rst

@@ -1083,7 +1083,7 @@ The grid division bias to use in the 3D editor. Negative values will cause small
 
 :ref:`int<class_int>` **editors/3d/grid_division_level_max**
 
-The largest grid division to use in the 3D editor. Together with :ref:`editors/3d/primary_grid_steps<class_EditorSettings_property_editors/3d/primary_grid_steps>`, this determines how large the grid divisions can be. The grid divisions will not be able to get larger than ``primary_grid_steps ^ grid_division_level_max`` units. By default, when :ref:`editors/3d/primary_grid_steps<class_EditorSettings_property_editors/3d/primary_grid_steps>` is ``8``, this means grid divisions cannot get larger than ``64`` uints each (so primary grid lines are ``512`` uints apart), no matter how far away the camera is from the grid.
+The largest grid division to use in the 3D editor. Together with :ref:`editors/3d/primary_grid_steps<class_EditorSettings_property_editors/3d/primary_grid_steps>`, this determines how large the grid divisions can be. The grid divisions will not be able to get larger than ``primary_grid_steps ^ grid_division_level_max`` units. By default, when :ref:`editors/3d/primary_grid_steps<class_EditorSettings_property_editors/3d/primary_grid_steps>` is ``8``, this means grid divisions cannot get larger than ``64`` units each (so primary grid lines are ``512`` units apart), no matter how far away the camera is from the grid.
 
 .. rst-class:: classref-item-separator
 

classes/class_editorsyntaxhighlighter.rst

@@ -21,7 +21,7 @@ Description
 
 Base class that all :ref:`SyntaxHighlighter<class_SyntaxHighlighter>`\ s used by the :ref:`ScriptEditor<class_ScriptEditor>` extend from.
 
-Add a syntax highlighter to an individual script by calling :ref:`ScriptEditorBase.add_syntax_highlighter<class_ScriptEditorBase_method_add_syntax_highlighter>`. To apply to all scripts on open, call :ref:`ScriptEditor.register_syntax_highlighter<class_ScriptEditor_method_register_syntax_highlighter>`
+Add a syntax highlighter to an individual script by calling :ref:`ScriptEditorBase.add_syntax_highlighter<class_ScriptEditorBase_method_add_syntax_highlighter>`. To apply to all scripts on open, call :ref:`ScriptEditor.register_syntax_highlighter<class_ScriptEditor_method_register_syntax_highlighter>`.
 
 .. rst-class:: classref-reftable-group
 

classes/class_editorvcsinterface.rst

@@ -21,6 +21,13 @@ Description
 
 Defines the API that the editor uses to extract information from the underlying VCS. The implementation of this API is included in VCS plugins, which are GDExtension plugins that inherit **EditorVCSInterface** and are attached (on demand) to the singleton instance of **EditorVCSInterface**. Instead of performing the task themselves, all the virtual functions listed below are calling the internally overridden functions in the VCS plugins to provide a plug-n-play experience. A custom VCS plugin is supposed to inherit from **EditorVCSInterface** and override each of these virtual functions.
 
+.. rst-class:: classref-introduction-group
+
+Tutorials
+---------
+
+- :doc:`Version control systems <../tutorials/best_practices/version_control_systems>`
+
 .. rst-class:: classref-reftable-group
 
 Methods

classes/class_environment.rst

@@ -36,7 +36,7 @@ Tutorials
 
 - :doc:`Environment and post-processing <../tutorials/3d/environment_and_post_processing>`
 
-- :doc:`Light transport in game engines <../tutorials/3d/high_dynamic_range>`
+- :doc:`High dynamic range lighting <../tutorials/3d/high_dynamic_range>`
 
 - `3D Material Testers Demo <https://godotengine.org/asset-library/asset/123>`__
 

classes/class_fileaccess.rst

@@ -730,7 +730,7 @@ Returns an MD5 String representing the file at the given path or an empty :ref:`
 
 :ref:`int<class_int>` **get_modified_time** **(** :ref:`String<class_String>` file **)** |static|
 
-Returns the last time the ``file`` was modified in Unix timestamp format or returns a :ref:`String<class_String>` "ERROR IN ``file``". This Unix timestamp can be converted to another format using the :ref:`Time<class_Time>` singleton.
+Returns the last time the ``file`` was modified in Unix timestamp format, or ``0`` on error. This Unix timestamp can be converted to another format using the :ref:`Time<class_Time>` singleton.
 
 .. rst-class:: classref-item-separator
 

classes/class_fogvolume.rst

@@ -25,6 +25,13 @@ Performance of **FogVolume**\ s is directly related to their relative size on th
 
 \ **Note:** **FogVolume**\ s only have a visible effect if :ref:`Environment.volumetric_fog_enabled<class_Environment_property_volumetric_fog_enabled>` is ``true``. If you don't want fog to be globally visible (but only within **FogVolume** nodes), set :ref:`Environment.volumetric_fog_density<class_Environment_property_volumetric_fog_density>` to ``0.0``.
 
+.. rst-class:: classref-introduction-group
+
+Tutorials
+---------
+
+- :doc:`Volumetric fog and fog volumes <../tutorials/3d/volumetric_fog>`
+
 .. rst-class:: classref-reftable-group
 
 Properties

classes/class_geometryinstance3d.rst

@@ -23,6 +23,13 @@ Description
 
 Base node for geometry-based visual instances. Shares some common functionality like visibility and custom materials.
 
+.. rst-class:: classref-introduction-group
+
+Tutorials
+---------
+
+- :doc:`Visibility ranges (HLOD) <../tutorials/3d/visibility_ranges>`
+
 .. rst-class:: classref-reftable-group
 
 Properties

classes/class_gpuparticles2d.rst

@@ -101,6 +101,8 @@ Methods
    +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | :ref:`Rect2<class_Rect2>` | :ref:`capture_rect<class_GPUParticles2D_method_capture_rect>` **(** **)** |const|                                                                                                                                                                               |
    +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+   | void                      | :ref:`convert_from_particles<class_GPUParticles2D_method_convert_from_particles>` **(** :ref:`Node<class_Node>` particles **)**                                                                                                                                 |
+   +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | void                      | :ref:`emit_particle<class_GPUParticles2D_method_emit_particle>` **(** :ref:`Transform2D<class_Transform2D>` xform, :ref:`Vector2<class_Vector2>` velocity, :ref:`Color<class_Color>` color, :ref:`Color<class_Color>` custom, :ref:`int<class_int>` flags **)** |
    +---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | void                      | :ref:`restart<class_GPUParticles2D_method_restart>` **(** **)**                                                                                                                                                                                                 |
@@ -620,6 +622,18 @@ Returns a rectangle containing the positions of all existing particles.
 
 ----
 
+.. _class_GPUParticles2D_method_convert_from_particles:
+
+.. rst-class:: classref-method
+
+void **convert_from_particles** **(** :ref:`Node<class_Node>` particles **)**
+
+Sets this node's properties to match a given :ref:`CPUParticles2D<class_CPUParticles2D>` node.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_GPUParticles2D_method_emit_particle:
 
 .. rst-class:: classref-method