Merge pull request #9728 from godotengine/classref/sync-88f3b5f

classref: Sync with current master branch (88f3b5f)

classes/class_animationnodeanimation.rst

@@ -126,6 +126,8 @@ Animation to use as an output. It is one of the animations provided by :ref:`Ani
 
 If :ref:`use_custom_timeline<class_AnimationNodeAnimation_property_use_custom_timeline>` is ``true``, override the loop settings of the original :ref:`Animation<class_Animation>` resource with the value.
 
+\ **Note:** If the :ref:`Animation.loop_mode<class_Animation_property_loop_mode>` isn't set to looping, the :ref:`Animation.track_set_interpolation_loop_wrap<class_Animation_method_track_set_interpolation_loop_wrap>` option will not be respected. If you cannot get the expected behavior, consider duplicating the :ref:`Animation<class_Animation>` resource and changing the loop settings.
+
 .. rst-class:: classref-item-separator
 
 ----

classes/class_audiostreamplayer.rst

@@ -24,7 +24,7 @@ Description
 
 The **AudioStreamPlayer** node plays an audio stream non-positionally. It is ideal for user interfaces, menus, or background music.
 
-To use this node, :ref:`stream<class_AudioStreamPlayer_property_stream>` needs to be set to a valid :ref:`AudioStream<class_AudioStream>` resource. Playing more than one sound at the time is also supported, see :ref:`max_polyphony<class_AudioStreamPlayer_property_max_polyphony>`.
+To use this node, :ref:`stream<class_AudioStreamPlayer_property_stream>` needs to be set to a valid :ref:`AudioStream<class_AudioStream>` resource. Playing more than one sound at the same time is also supported, see :ref:`max_polyphony<class_AudioStreamPlayer_property_max_polyphony>`.
 
 If you need to play audio at a specific position, use :ref:`AudioStreamPlayer2D<class_AudioStreamPlayer2D>` or :ref:`AudioStreamPlayer3D<class_AudioStreamPlayer3D>` instead.
 

classes/class_audiostreamsynchronized.rst

@@ -66,7 +66,7 @@ Constants
 
 **MAX_STREAMS** = ``32`` :ref:`🔗<class_AudioStreamSynchronized_constant_MAX_STREAMS>`
 
-Maximum amount of streams that can be synchrohized.
+Maximum amount of streams that can be synchronized.
 
 .. rst-class:: classref-section-separator
 

classes/class_dictionary.rst

@@ -615,8 +615,6 @@ This method is useful for quickly making dictionaries with default values:
     # Prints { "fruit": "apple", "vegetable": "potato", "dressing": "vinegar" }
     print(extra.merged(base, true))
 
-See also :ref:`merge<class_Dictionary_method_merge>`.
-
 .. rst-class:: classref-item-separator
 
 ----

classes/class_editorexportplatformios.rst

@@ -983,7 +983,7 @@ Indicates whether your app uses advertising data for tracking.
 
 :ref:`bool<class_bool>` **privacy/collected_data/audio_data/collected** :ref:`🔗<class_EditorExportPlatformIOS_property_privacy/collected_data/audio_data/collected>`
 
-Indicates whether your app collects audio data data.
+Indicates whether your app collects audio data.
 
 .. rst-class:: classref-item-separator
 
@@ -1007,7 +1007,7 @@ The reasons your app collects audio data. See `Describing data use in privacy ma
 
 :ref:`bool<class_bool>` **privacy/collected_data/audio_data/linked_to_user** :ref:`🔗<class_EditorExportPlatformIOS_property_privacy/collected_data/audio_data/linked_to_user>`
 
-Indicates whether your app links audio data data to the user's identity.
+Indicates whether your app links audio data to the user's identity.
 
 .. rst-class:: classref-item-separator
 
@@ -1019,7 +1019,7 @@ Indicates whether your app links audio data data to the user's identity.
 
 :ref:`bool<class_bool>` **privacy/collected_data/audio_data/used_for_tracking** :ref:`🔗<class_EditorExportPlatformIOS_property_privacy/collected_data/audio_data/used_for_tracking>`
 
-Indicates whether your app uses audio data data for tracking.
+Indicates whether your app uses audio data for tracking.
 
 .. rst-class:: classref-item-separator
 

classes/class_editorexportplatformmacos.rst

@@ -1335,7 +1335,7 @@ Indicates whether your app uses advertising data for tracking.
 
 :ref:`bool<class_bool>` **privacy/collected_data/audio_data/collected** :ref:`🔗<class_EditorExportPlatformMacOS_property_privacy/collected_data/audio_data/collected>`
 
-Indicates whether your app collects audio data data.
+Indicates whether your app collects audio data.
 
 .. rst-class:: classref-item-separator
 
@@ -1359,7 +1359,7 @@ The reasons your app collects audio data. See `Describing data use in privacy ma
 
 :ref:`bool<class_bool>` **privacy/collected_data/audio_data/linked_to_user** :ref:`🔗<class_EditorExportPlatformMacOS_property_privacy/collected_data/audio_data/linked_to_user>`
 
-Indicates whether your app links audio data data to the user's identity.
+Indicates whether your app links audio data to the user's identity.
 
 .. rst-class:: classref-item-separator
 
@@ -1371,7 +1371,7 @@ Indicates whether your app links audio data data to the user's identity.
 
 :ref:`bool<class_bool>` **privacy/collected_data/audio_data/used_for_tracking** :ref:`🔗<class_EditorExportPlatformMacOS_property_privacy/collected_data/audio_data/used_for_tracking>`
 
-Indicates whether your app uses audio data data for tracking.
+Indicates whether your app uses audio data for tracking.
 
 .. rst-class:: classref-item-separator
 

classes/class_editorplugin.rst

@@ -586,7 +586,7 @@ Called by the engine when the 3D editor's viewport is updated. Use the ``overlay
 
     func _forward_3d_draw_over_viewport(overlay):
         # Draw a circle at cursor position.
-        overlay.draw_circle(overlay.get_local_mouse_position(), 64)
+        overlay.draw_circle(overlay.get_local_mouse_position(), 64, Color.WHITE)
 
     func _forward_3d_gui_input(camera, event):
         if event is InputEventMouseMotion:

classes/class_editorsettings.rst

@@ -2807,7 +2807,9 @@ The default **Auto** value will only enable this if the editor was compiled with
 
 :ref:`bool<class_bool>` **interface/editor/single_window_mode** :ref:`🔗<class_EditorSettings_property_interface/editor/single_window_mode>`
 
-If ``true``, embed modal windows such as docks inside the main editor window. When single-window mode is enabled, tooltips will also be embedded inside the main editor window, which means they can't be displayed outside of the editor window.
+If ``true``, embed modal windows such as docks inside the main editor window. When single-window mode is enabled, tooltips will also be embedded inside the main editor window, which means they can't be displayed outside of the editor window. Single-window mode can be faster as it does not need to create a separate window for every popup and tooltip, which can be a slow operation depending on the operating system and rendering method in use.
+
+This is equivalent to :ref:`ProjectSettings.display/window/subwindows/embed_subwindows<class_ProjectSettings_property_display/window/subwindows/embed_subwindows>` in the running project, except the setting's value is inverted.
 
 \ **Note:** To query whether the editor can use multiple windows in an editor plugin, use :ref:`EditorInterface.is_multi_window_enabled<class_EditorInterface_method_is_multi_window_enabled>` instead of querying the value of this editor setting.
 

classes/class_json.rst

@@ -19,7 +19,7 @@ Helper class for creating and parsing JSON data.
 Description
 -----------
 
-The **JSON** enables all data types to be converted to and from a JSON string. This useful for serializing data to save to a file or send over the network.
+The **JSON** class enables all data types to be converted to and from a JSON string. This is useful for serializing data, e.g. to save to a file or send over the network.
 
 \ :ref:`stringify<class_JSON_method_stringify>` is used to convert any data type into a JSON string.
 
@@ -45,7 +45,7 @@ The **JSON** enables all data types to be converted to and from a JSON string. T
     else:
         print("JSON Parse Error: ", json.get_error_message(), " in ", json_string, " at line ", json.get_error_line())
 
-Alternatively, you can parse string using the static :ref:`parse_string<class_JSON_method_parse_string>` method, but it doesn't allow to handle errors.
+Alternatively, you can parse strings using the static :ref:`parse_string<class_JSON_method_parse_string>` method, but it doesn't handle errors.
 
 ::
 
@@ -156,7 +156,7 @@ Returns an empty string if the last call to :ref:`parse<class_JSON_method_parse>
 
 :ref:`String<class_String>` **get_parsed_text**\ (\ ) |const| :ref:`🔗<class_JSON_method_get_parsed_text>`
 
-Return the text parsed by :ref:`parse<class_JSON_method_parse>` as long as the function is instructed to keep it.
+Return the text parsed by :ref:`parse<class_JSON_method_parse>` (requires passing ``keep_text`` to :ref:`parse<class_JSON_method_parse>`).
 
 .. rst-class:: classref-item-separator
 
@@ -170,7 +170,7 @@ Return the text parsed by :ref:`parse<class_JSON_method_parse>` as long as the f
 
 Attempts to parse the ``json_text`` provided.
 
-Returns an :ref:`Error<enum_@GlobalScope_Error>`. If the parse was successful, it returns :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` and the result can be retrieved using :ref:`data<class_JSON_property_data>`. If unsuccessful, use :ref:`get_error_line<class_JSON_method_get_error_line>` and :ref:`get_error_message<class_JSON_method_get_error_message>` for identifying the source of the failure.
+Returns an :ref:`Error<enum_@GlobalScope_Error>`. If the parse was successful, it returns :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` and the result can be retrieved using :ref:`data<class_JSON_property_data>`. If unsuccessful, use :ref:`get_error_line<class_JSON_method_get_error_line>` and :ref:`get_error_message<class_JSON_method_get_error_message>` to identify the source of the failure.
 
 Non-static variant of :ref:`parse_string<class_JSON_method_parse_string>`, if you want custom error handling.
 
@@ -204,7 +204,7 @@ Converts a :ref:`Variant<class_Variant>` var to JSON text and returns the result
 
 \ **Note:** If ``full_precision`` is ``true``, when stringifying floats, the unreliable digits are stringified in addition to the reliable digits to guarantee exact decoding.
 
-The ``indent`` parameter controls if and how something is indented, the string used for this parameter will be used where there should be an indent in the output, even spaces like ``"   "`` will work. ``\t`` and ``\n`` can also be used for a tab indent, or to make a newline for each indent respectively.
+The ``indent`` parameter controls if and how something is indented; its contents will be used where there should be an indent in the output. Even spaces like ``"   "`` will work. ``\t`` and ``\n`` can also be used for a tab indent, or to make a newline for each indent respectively.
 
 \ **Example output:**\ 
 

classes/class_multimesh.rst

@@ -426,6 +426,8 @@ Returns the :ref:`Transform2D<class_Transform2D>` of a specific instance.
 
 Sets the color of a specific instance by *multiplying* the mesh's existing vertex colors. This allows for different color tinting per instance.
 
+\ **Note:** Each component is stored in 32 bits in the Forward+ and Mobile rendering methods, but is packed into 16 bits in the Compatibility rendering method.
+
 For the color to take effect, ensure that :ref:`use_colors<class_MultiMesh_property_use_colors>` is ``true`` on the **MultiMesh** and :ref:`BaseMaterial3D.vertex_color_use_as_albedo<class_BaseMaterial3D_property_vertex_color_use_as_albedo>` is ``true`` on the material. If you intend to set an absolute color instead of tinting, make sure the material's albedo color is set to pure white (``Color(1, 1, 1)``).
 
 .. rst-class:: classref-item-separator
@@ -440,6 +442,8 @@ For the color to take effect, ensure that :ref:`use_colors<class_MultiMesh_prope
 
 Sets custom data for a specific instance. ``custom_data`` is a :ref:`Color<class_Color>` type only to contain 4 floating-point numbers.
 
+\ **Note:** Each number is stored in 32 bits in the Forward+ and Mobile rendering methods, but is packed into 16 bits in the Compatibility rendering method.
+
 For the custom data to be used, ensure that :ref:`use_custom_data<class_MultiMesh_property_use_custom_data>` is ``true``.
 
 This custom instance data has to be manually accessed in your custom shader using ``INSTANCE_CUSTOM``.

classes/class_openxrinterface.rst

@@ -137,7 +137,7 @@ Informs the user queued a recenter of the player position.
 
 Informs the user the HMD refresh rate has changed.
 
-\ **Node:** Only emitted if XR runtime supports the refresh rate extension.
+\ **Note:** Only emitted if XR runtime supports the refresh rate extension.
 
 .. rst-class:: classref-item-separator
 

classes/class_projectsettings.rst

@@ -4278,7 +4278,11 @@ The policy to use to determine the final scale factor for 2D elements. This affe
 
 :ref:`bool<class_bool>` **display/window/subwindows/embed_subwindows** = ``true`` :ref:`🔗<class_ProjectSettings_property_display/window/subwindows/embed_subwindows>`
 
-If ``true`` subwindows are embedded in the main window.
+If ``true``, subwindows are embedded in the main window (this is also called single-window mode). Single-window mode can be faster as it does not need to create a separate window for every popup and tooltip, which can be a slow operation depending on the operating system and rendering method in use.
+
+If ``false``, subwindows are created as separate windows (this is also called multi-window mode). This allows them to be moved outside the main window and use native operating system window decorations.
+
+This is equivalent to :ref:`EditorSettings.interface/editor/single_window_mode<class_EditorSettings_property_interface/editor/single_window_mode>` in the editor, except the setting's value is inverted.
 
 .. rst-class:: classref-item-separator
 

classes/class_resourceimportertexture.rst

@@ -329,9 +329,9 @@ More information about normal maps (including a coordinate order table for popul
 
 An alternative to fixing darkened borders with :ref:`process/fix_alpha_border<class_ResourceImporterTexture_property_process/fix_alpha_border>` is to use premultiplied alpha. By enabling this option, the texture will be converted to this format. A premultiplied alpha texture requires specific materials to be displayed correctly:
 
-- In 2D, a :ref:`CanvasItemMaterial<class_CanvasItemMaterial>` will need to be created and configured to use the :ref:`CanvasItemMaterial.BLEND_MODE_PREMULT_ALPHA<class_CanvasItemMaterial_constant_BLEND_MODE_PREMULT_ALPHA>` blend mode on :ref:`CanvasItem<class_CanvasItem>`\ s that use this texture.
+- In 2D, a :ref:`CanvasItemMaterial<class_CanvasItemMaterial>` will need to be created and configured to use the :ref:`CanvasItemMaterial.BLEND_MODE_PREMULT_ALPHA<class_CanvasItemMaterial_constant_BLEND_MODE_PREMULT_ALPHA>` blend mode on :ref:`CanvasItem<class_CanvasItem>`\ s that use this texture. In custom ``@canvas_item`` shaders, ``render_mode blend_premul_alpha;`` should be used.
 
-- In 3D, there is no support for premultiplied alpha blend mode yet, so this option is only suited for 2D.
+- In 3D, a :ref:`BaseMaterial3D<class_BaseMaterial3D>` will need to be created and configured to use the :ref:`BaseMaterial3D.BLEND_MODE_PREMULT_ALPHA<class_BaseMaterial3D_constant_BLEND_MODE_PREMULT_ALPHA>` blend mode on materials that use this texture. In custom ``spatial`` shaders, ``render_mode blend_premul_alpha;`` should be used.
 
 .. rst-class:: classref-item-separator
 

classes/class_skeletonmodifier3d.rst

@@ -25,7 +25,7 @@ Description
 
 If there is :ref:`AnimationMixer<class_AnimationMixer>`, modification always performs after playback process of the :ref:`AnimationMixer<class_AnimationMixer>`.
 
-This node should be used to implement custom IK solvers, constraints, or skeleton physics
+This node should be used to implement custom IK solvers, constraints, or skeleton physics.
 
 .. rst-class:: classref-reftable-group
 

classes/class_tilemap.rst

@@ -13,7 +13,7 @@
 TileMap
 =======
 
-**Deprecated:** Use multiple :ref:`TileMapLayer<class_TileMapLayer>` nodes instead.
+**Deprecated:** Use multiple :ref:`TileMapLayer<class_TileMapLayer>` nodes instead. To convert a TileMap to a set of TileMapLayer nodes, open the TileMap bottom panel with the node selected, click the toolbox icon in the top-right corner and choose 'Extract TileMap layers as individual TileMapLayer nodes'.
 
 **Inherits:** :ref:`Node2D<class_Node2D>` **<** :ref:`CanvasItem<class_CanvasItem>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`
 

classes/class_window.rst

@@ -2137,6 +2137,12 @@ Causes the window to grab focus, allowing it to receive user input.
 
 Shows the **Window** and makes it transient (see :ref:`transient<class_Window_property_transient>`). If ``rect`` is provided, it will be set as the **Window**'s size. Fails if called on the main window.
 
+If :ref:`ProjectSettings.display/window/subwindows/embed_subwindows<class_ProjectSettings_property_display/window/subwindows/embed_subwindows>` is ``true`` (single-window mode), ``rect``'s coordinates are global and relative to the main window's top-left corner (excluding window decorations). If ``rect``'s position coordinates are negative, the window will be located outside the main window and may not be visible as a result.
+
+If :ref:`ProjectSettings.display/window/subwindows/embed_subwindows<class_ProjectSettings_property_display/window/subwindows/embed_subwindows>` is ``false`` (multi-window mode), ``rect``'s coordinates are global and relative to the top-left corner of the leftmost screen. If ``rect``'s position coordinates are negative, the window will be placed at the top-left corner of the screen.
+
+\ **Note:** ``rect`` must be in global coordinates if specified.
+
 .. rst-class:: classref-item-separator
 
 ----