Merge pull request #9662 from godotengine/classref/sync-607b230

classref: Sync with current master branch (607b230)

classes/class_animationplayer.rst

@@ -661,7 +661,7 @@ If ``duration`` is a negative value, the duration is set to the interval between
 
 |void| **queue**\ (\ name\: :ref:`StringName<class_StringName>`\ ) :ref:`🔗<class_AnimationPlayer_method_queue>`
 
-Queues an animation for playback once the current one is done.
+Queues an animation for playback once the current animation and all previously queued animations are done.
 
 \ **Note:** If a looped animation is currently playing, the queued animation will never play unless the looped animation is stopped somehow.
 

classes/class_arraymesh.rst

@@ -197,7 +197,9 @@ Overrides the :ref:`AABB<class_AABB>` with one defined by user for use with frus
 - |void| **set_shadow_mesh**\ (\ value\: :ref:`ArrayMesh<class_ArrayMesh>`\ )
 - :ref:`ArrayMesh<class_ArrayMesh>` **get_shadow_mesh**\ (\ )
 
-An optional mesh which is used for rendering shadows and can be used for the depth prepass. Can be used to increase performance of shadow rendering by using a mesh that only contains vertex position data (without normals, UVs, colors, etc.).
+An optional mesh which can be used for rendering shadows and the depth prepass. Can be used to increase performance by supplying a mesh with fused vertices and only vertex position data (without normals, UVs, colors, etc.).
+
+\ **Note:** This mesh must have exactly the same vertex positions as the source mesh (including the source mesh's LODs, if present). If vertex positions differ, then the mesh will not draw correctly.
 
 .. rst-class:: classref-section-separator
 

classes/class_editorsettings.rst

@@ -2795,6 +2795,8 @@ The default **Auto** value will only enable this if the editor was compiled with
 
 \ **Note:** If :ref:`interface/editor/update_continuously<class_EditorSettings_property_interface/editor/update_continuously>` is ``true``, the spinner icon displays in red.
 
+\ **Note:** If the editor was started with the ``--debug-canvas-item-redraw`` :doc:`command line argument <../tutorials/editor/command_line_tutorial>`, the update spinner will *never* display regardless of this setting's value. This is to avoid confusion with what would cause redrawing in real world scenarios.
+
 .. rst-class:: classref-item-separator
 
 ----

classes/class_filedialog.rst

@@ -279,7 +279,7 @@ Property Descriptions
 
 The file system access scope. See :ref:`Access<enum_FileDialog_Access>` constants.
 
-\ **Warning:** Currently, in sandboxed environments such as Web builds or sandboxed macOS apps, FileDialog cannot access the host file system. See `godot-proposals#1123 <https://github.com/godotengine/godot-proposals/issues/1123>`__.
+\ **Warning:** In Web builds, FileDialog cannot access the host file system. In sandboxed Linux and macOS environments, :ref:`use_native_dialog<class_FileDialog_property_use_native_dialog>` is automatically used to allow limited access to host file system.
 
 .. rst-class:: classref-item-separator
 
@@ -298,6 +298,8 @@ The file system access scope. See :ref:`Access<enum_FileDialog_Access>` constant
 
 The current working directory of the file dialog.
 
+\ **Note:** For native file dialogs, this property is only treated as a hint and may not be respected by specific OS implementations.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -419,6 +421,8 @@ The number of additional :ref:`OptionButton<class_OptionButton>`\ s and :ref:`Ch
 
 If non-empty, the given sub-folder will be "root" of this **FileDialog**, i.e. user won't be able to go to its parent directory.
 
+\ **Note:** This property is ignored by native file dialogs.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -436,6 +440,8 @@ If non-empty, the given sub-folder will be "root" of this **FileDialog**, i.e. u
 
 If ``true``, the dialog will show hidden files.
 
+\ **Note:** This property is ignored by native file dialogs on Linux.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -453,7 +459,11 @@ If ``true``, the dialog will show hidden files.
 
 If ``true``, :ref:`access<class_FileDialog_property_access>` is set to :ref:`ACCESS_FILESYSTEM<class_FileDialog_constant_ACCESS_FILESYSTEM>`, and it is supported by the current :ref:`DisplayServer<class_DisplayServer>`, OS native dialog will be used instead of custom one.
 
-\ **Note:** On macOS, sandboxed apps always use native dialogs to access host filesystem.
+\ **Note:** On Linux and macOS, sandboxed apps always use native dialogs to access the host file system.
+
+\ **Note:** On macOS, sandboxed apps will save security-scoped bookmarks to retain access to the opened folders across multiple sessions. Use :ref:`OS.get_granted_permissions<class_OS_method_get_granted_permissions>` to get a list of saved bookmarks.
+
+\ **Note:** Native dialogs are isolated from the base process, file dialog properties can't be modified once the dialog is shown.
 
 .. rst-class:: classref-section-separator
 
@@ -590,6 +600,8 @@ Returns the vertical box container of the dialog, custom controls can be added t
 
 \ **Warning:** This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their :ref:`CanvasItem.visible<class_CanvasItem_property_visible>` property.
 
+\ **Note:** Changes to this node are ignored by native file dialogs, use :ref:`add_option<class_FileDialog_method_add_option>` to add custom elements to the dialog instead.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -602,6 +614,8 @@ Returns the vertical box container of the dialog, custom controls can be added t
 
 Invalidate and update the current dialog content list.
 
+\ **Note:** This method does nothing on native file dialogs.
+
 .. rst-class:: classref-item-separator
 
 ----

classes/class_physicsserver2d.rst

@@ -208,6 +208,8 @@ Methods
    +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | |void|                                                            | :ref:`body_set_state<class_PhysicsServer2D_method_body_set_state>`\ (\ body\: :ref:`RID<class_RID>`, state\: :ref:`BodyState<enum_PhysicsServer2D_BodyState>`, value\: :ref:`Variant<class_Variant>`\ )                                                                                                                       |
    +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+   | |void|                                                            | :ref:`body_set_state_sync_callback<class_PhysicsServer2D_method_body_set_state_sync_callback>`\ (\ body\: :ref:`RID<class_RID>`, callable\: :ref:`Callable<class_Callable>`\ )                                                                                                                                                |
+   +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | :ref:`bool<class_bool>`                                           | :ref:`body_test_motion<class_PhysicsServer2D_method_body_test_motion>`\ (\ body\: :ref:`RID<class_RID>`, parameters\: :ref:`PhysicsTestMotionParameters2D<class_PhysicsTestMotionParameters2D>`, result\: :ref:`PhysicsTestMotionResult2D<class_PhysicsTestMotionResult2D>` = null\ )                                         |
    +-------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | :ref:`RID<class_RID>`                                             | :ref:`capsule_shape_create<class_PhysicsServer2D_method_capsule_shape_create>`\ (\ )                                                                                                                                                                                                                                          |
@@ -2151,6 +2153,24 @@ Sets the value of a body's state. See :ref:`BodyState<enum_PhysicsServer2D_BodyS
 
 ----
 
+.. _class_PhysicsServer2D_method_body_set_state_sync_callback:
+
+.. rst-class:: classref-method
+
+|void| **body_set_state_sync_callback**\ (\ body\: :ref:`RID<class_RID>`, callable\: :ref:`Callable<class_Callable>`\ ) :ref:`🔗<class_PhysicsServer2D_method_body_set_state_sync_callback>`
+
+Sets the body's state synchronization callback function to ``callable``. Use an empty :ref:`Callable<class_Callable>` (``Callable()``) to clear the callback.
+
+The function ``callable`` will be called every physics frame, assuming that the body was active during the previous physics tick, and can be used to fetch the latest state from the physics server.
+
+The function ``callable`` must take the following parameters:
+
+1. ``state``: a :ref:`PhysicsDirectBodyState2D<class_PhysicsDirectBodyState2D>`, used to retrieve the body's state.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_PhysicsServer2D_method_body_test_motion:
 
 .. rst-class:: classref-method

classes/class_physicsserver2dextension.rst

@@ -1386,7 +1386,7 @@ Overridable version of :ref:`PhysicsServer2D.body_set_state<class_PhysicsServer2
 
 Assigns the ``body`` to call the given ``callable`` during the synchronization phase of the loop, before :ref:`_step<class_PhysicsServer2DExtension_private_method__step>` is called. See also :ref:`_sync<class_PhysicsServer2DExtension_private_method__sync>`.
 
-Overridable version of :ref:`PhysicsServer2D<class_PhysicsServer2D>`'s internal ``body_set_state_sync_callback`` method.
+Overridable version of :ref:`PhysicsServer2D.body_set_state_sync_callback<class_PhysicsServer2D_method_body_set_state_sync_callback>`.
 
 .. rst-class:: classref-item-separator
 

classes/class_physicsserver3d.rst

@@ -206,6 +206,8 @@ Methods
    +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | |void|                                                            | :ref:`body_set_state<class_PhysicsServer3D_method_body_set_state>`\ (\ body\: :ref:`RID<class_RID>`, state\: :ref:`BodyState<enum_PhysicsServer3D_BodyState>`, value\: :ref:`Variant<class_Variant>`\ )                                                                                             |
    +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+   | |void|                                                            | :ref:`body_set_state_sync_callback<class_PhysicsServer3D_method_body_set_state_sync_callback>`\ (\ body\: :ref:`RID<class_RID>`, callable\: :ref:`Callable<class_Callable>`\ )                                                                                                                      |
+   +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | :ref:`bool<class_bool>`                                           | :ref:`body_test_motion<class_PhysicsServer3D_method_body_test_motion>`\ (\ body\: :ref:`RID<class_RID>`, parameters\: :ref:`PhysicsTestMotionParameters3D<class_PhysicsTestMotionParameters3D>`, result\: :ref:`PhysicsTestMotionResult3D<class_PhysicsTestMotionResult3D>` = null\ )               |
    +-------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | :ref:`RID<class_RID>`                                             | :ref:`box_shape_create<class_PhysicsServer3D_method_box_shape_create>`\ (\ )                                                                                                                                                                                                                        |
@@ -2887,6 +2889,24 @@ Sets a body state (see :ref:`BodyState<enum_PhysicsServer3D_BodyState>` constant
 
 ----
 
+.. _class_PhysicsServer3D_method_body_set_state_sync_callback:
+
+.. rst-class:: classref-method
+
+|void| **body_set_state_sync_callback**\ (\ body\: :ref:`RID<class_RID>`, callable\: :ref:`Callable<class_Callable>`\ ) :ref:`🔗<class_PhysicsServer3D_method_body_set_state_sync_callback>`
+
+Sets the body's state synchronization callback function to ``callable``. Use an empty :ref:`Callable<class_Callable>` (``Callable()``) to clear the callback.
+
+The function ``callable`` will be called every physics frame, assuming that the body was active during the previous physics tick, and can be used to fetch the latest state from the physics server.
+
+The function ``callable`` must take the following parameters:
+
+1. ``state``: a :ref:`PhysicsDirectBodyState3D<class_PhysicsDirectBodyState3D>`, used to retrieve the body's state.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_PhysicsServer3D_method_body_test_motion:
 
 .. rst-class:: classref-method

classes/class_scenetree.rst

@@ -730,7 +730,7 @@ Returns ``true`` if a node added to the given group ``name`` exists in the tree.
 
 |void| **notify_group**\ (\ group\: :ref:`StringName<class_StringName>`, notification\: :ref:`int<class_int>`\ ) :ref:`🔗<class_SceneTree_method_notify_group>`
 
-Calls :ref:`Object.notification<class_Object_method_notification>` with the given ``notification`` to all nodes inside this tree added to the ``group``. See also :ref:`call_group<class_SceneTree_method_call_group>` and :ref:`set_group<class_SceneTree_method_set_group>`.
+Calls :ref:`Object.notification<class_Object_method_notification>` with the given ``notification`` to all nodes inside this tree added to the ``group``. See also :doc:`Godot notifications <../tutorials/best_practices/godot_notifications>` and :ref:`call_group<class_SceneTree_method_call_group>` and :ref:`set_group<class_SceneTree_method_set_group>`.
 
 \ **Note:** This method acts immediately on all selected nodes at once, which may cause stuttering in some performance-intensive situations.
 

classes/class_textparagraph.rst

@@ -593,7 +593,7 @@ Returns TextServer line buffer RID.
 
 :ref:`Vector2<class_Vector2>` **get_line_size**\ (\ line\: :ref:`int<class_int>`\ ) |const| :ref:`🔗<class_TextParagraph_method_get_line_size>`
 
-Returns size of the bounding box of the line of text.
+Returns size of the bounding box of the line of text. Returned size is rounded up.
 
 .. rst-class:: classref-item-separator
 

classes/class_websocketpeer.rst

@@ -482,7 +482,7 @@ Sends the given ``message`` using WebSocket text mode. Prefer this method over :
 
 |void| **set_no_delay**\ (\ enabled\: :ref:`bool<class_bool>`\ ) :ref:`🔗<class_WebSocketPeer_method_set_no_delay>`
 
-Disable Nagle's algorithm on the underling TCP socket (default). See :ref:`StreamPeerTCP.set_no_delay<class_StreamPeerTCP_method_set_no_delay>` for more information.
+Disable Nagle's algorithm on the underlying TCP socket (default). See :ref:`StreamPeerTCP.set_no_delay<class_StreamPeerTCP_method_set_no_delay>` for more information.
 
 \ **Note:** Not available in the Web export.