Merge pull request #11062 from godotengine/classref/sync-ebc36a7

classref: Sync with current master branch (ebc36a7)

Author: skyace65

classes/[email protected]

@@ -124,6 +124,37 @@ Positive floating-point infinity. This is the result of floating-point division
 Annotations
 -----------
 
+.. _class_@GDScript_annotation_@abstract:
+
+.. rst-class:: classref-annotation
+
+**@abstract**\ (\ ) :ref:`🔗<class_@GDScript_annotation_@abstract>`
+
+Marks a class or a method as abstract.
+
+An abstract class is a class that cannot be instantiated directly. Instead, it is meant to be inherited by other classes. Attempting to instantiate an abstract class will result in an error.
+
+An abstract method is a method that has no implementation. Therefore, a newline or a semicolon is expected after the function header. This defines a contract that inheriting classes must conform to, because the method signature must be compatible when overriding.
+
+Inheriting classes must either provide implementations for all abstract methods, or the inheriting class must be marked as abstract. If a class has at least one abstract method (either its own or an unimplemented inherited one), then it must also be marked as abstract. However, the reverse is not true: an abstract class is allowed to have no abstract methods.
+
+::
+
+    @abstract class Shape:
+        @abstract func draw()
+
+    class Circle extends Shape:
+        func draw():
+            print("Drawing a circle.")
+
+    class Square extends Shape:
+        func draw():
+            print("Drawing a square.")
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_@GDScript_annotation_@export:
 
 .. rst-class:: classref-annotation
@@ -856,6 +887,8 @@ The order of ``mode``, ``sync`` and ``transfer_mode`` does not matter, but value
     @rpc("authority", "call_remote", "unreliable", 0) # Equivalent to @rpc
     func fn_default(): pass
 
+\ **Note:** Methods annotated with :ref:`@rpc<class_@GDScript_annotation_@rpc>` cannot receive objects which define required parameters in :ref:`Object._init()<class_Object_private_method__init>`. See :ref:`Object._init()<class_Object_private_method__init>` for more details.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -1073,7 +1106,7 @@ Converts a ``dictionary`` (created with :ref:`inst_to_dict()<class_@GDScript_met
 
 :ref:`Array<class_Array>` **get_stack**\ (\ ) :ref:`🔗<class_@GDScript_method_get_stack>`
 
-Returns an array of dictionaries representing the current call stack. See also :ref:`print_stack()<class_@GDScript_method_print_stack>`.
+Returns an array of dictionaries representing the current call stack.
 
 ::
 
@@ -1092,9 +1125,9 @@ Starting from ``_ready()``, ``bar()`` 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:** This function 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.
+See also :ref:`print_debug()<class_@GDScript_method_print_debug>`, :ref:`print_stack()<class_@GDScript_method_print_stack>`, and :ref:`Engine.capture_script_backtraces()<class_Engine_method_capture_script_backtraces>`.
 
-\ **Note:** Calling this function from a :ref:`Thread<class_Thread>` is not supported. Doing so will return an empty array.
+\ **Note:** By default, backtraces are only available in editor builds and debug builds. To enable them for release builds as well, you need to enable :ref:`ProjectSettings.debug/settings/gdscript/always_track_call_stacks<class_ProjectSettings_property_debug/settings/gdscript/always_track_call_stacks>`.
 
 .. rst-class:: classref-item-separator
 
@@ -1268,7 +1301,9 @@ The output in the console may look like the following:
     Test print
     At: res://test.gd:15:_process()
 
-\ **Note:** Calling this function from a :ref:`Thread<class_Thread>` is not supported. Doing so will instead print the thread ID.
+See also :ref:`print_stack()<class_@GDScript_method_print_stack>`, :ref:`get_stack()<class_@GDScript_method_get_stack>`, and :ref:`Engine.capture_script_backtraces()<class_Engine_method_capture_script_backtraces>`.
+
+\ **Note:** By default, backtraces are only available in editor builds and debug builds. To enable them for release builds as well, you need to enable :ref:`ProjectSettings.debug/settings/gdscript/always_track_call_stacks<class_ProjectSettings_property_debug/settings/gdscript/always_track_call_stacks>`.
 
 .. rst-class:: classref-item-separator
 
@@ -1280,17 +1315,17 @@ The output in the console may look like the following:
 
 |void| **print_stack**\ (\ ) :ref:`🔗<class_@GDScript_method_print_stack>`
 
-Prints a stack trace at the current code location. See also :ref:`get_stack()<class_@GDScript_method_get_stack>`.
+Prints a stack trace at the current code location.
 
 The output in the console may look like the following:
 
 .. code:: text
 
     Frame 0 - res://test.gd:16 in function '_process'
 
-\ **Note:** This function 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.
+See also :ref:`print_debug()<class_@GDScript_method_print_debug>`, :ref:`get_stack()<class_@GDScript_method_get_stack>`, and :ref:`Engine.capture_script_backtraces()<class_Engine_method_capture_script_backtraces>`.
 
-\ **Note:** Calling this function from a :ref:`Thread<class_Thread>` is not supported. Doing so will instead print the thread ID.
+\ **Note:** By default, backtraces are only available in editor builds and debug builds. To enable them for release builds as well, you need to enable :ref:`ProjectSettings.debug/settings/gdscript/always_track_call_stacks<class_ProjectSettings_property_debug/settings/gdscript/always_track_call_stacks>`.
 
 .. rst-class:: classref-item-separator
 

classes/[email protected]

@@ -3887,9 +3887,9 @@ Hints that a property will be changed on its own after setting, such as :ref:`Au
 
 :ref:`PropertyHint<enum_@GlobalScope_PropertyHint>` **PROPERTY_HINT_GROUP_ENABLE** = ``42``
 
-Hints that a boolean property will enable the feature associated with the group that it occurs in. Only works within a group or subgroup. Use the optional hint string ``"feature"`` when the group only has properties that are meaningful when the feature is enabled.
+Hints that a boolean property will enable the feature associated with the group that it occurs in. The property will be displayed as a checkbox on the group header. Only works within a group or subgroup.
 
-\ **Note:** The ``"feature"`` hint string does not modify or reset any values.
+By default, disabling the property hides all properties in the group. Use the optional hint string ``"checkbox_only"`` to disable this behavior.
 
 .. _class_@GlobalScope_constant_PROPERTY_HINT_INPUT_NAME:
 

classes/class_aabb.rst

@@ -23,7 +23,7 @@ It uses floating-point coordinates. The 2D counterpart to **AABB** is :ref:`Rect
 
 \ **Note:** Negative values for :ref:`size<class_AABB_property_size>` are not supported. With negative size, most **AABB** methods do not work correctly. Use :ref:`abs()<class_AABB_method_abs>` to get an equivalent **AABB** with a non-negative size.
 
-\ **Note:** In a boolean context, a **AABB** evaluates to ``false`` if both :ref:`position<class_AABB_property_position>` and :ref:`size<class_AABB_property_size>` are zero (equal to :ref:`Vector3.ZERO<class_Vector3_constant_ZERO>`). Otherwise, it always evaluates to ``true``.
+\ **Note:** In a boolean context, an **AABB** evaluates to ``false`` if both :ref:`position<class_AABB_property_position>` and :ref:`size<class_AABB_property_size>` are zero (equal to :ref:`Vector3.ZERO<class_Vector3_constant_ZERO>`). Otherwise, it always evaluates to ``true``.
 
 .. note::
 
@@ -366,7 +366,7 @@ Returns the center point of the bounding box. This is the same as ``position + (
 
 :ref:`Vector3<class_Vector3>` **get_endpoint**\ (\ idx\: :ref:`int<class_int>`\ ) |const| :ref:`🔗<class_AABB_method_get_endpoint>`
 
-Returns the position of one of the 8 vertices that compose this bounding box. With a ``idx`` of ``0`` this is the same as :ref:`position<class_AABB_property_position>`, and a ``idx`` of ``7`` is the same as :ref:`end<class_AABB_property_end>`.
+Returns the position of one of the 8 vertices that compose this bounding box. With an ``idx`` of ``0`` this is the same as :ref:`position<class_AABB_property_position>`, and an ``idx`` of ``7`` is the same as :ref:`end<class_AABB_property_end>`.
 
 .. rst-class:: classref-item-separator
 

classes/class_array.rst

@@ -679,7 +679,7 @@ If ``deep`` is ``true``, a **deep** copy is returned: all nested arrays and dict
 
 Duplicates this array, deeply, like :ref:`duplicate()<class_Array_method_duplicate>`\ ``(true)``, with extra control over how subresources are handled.
 
-\ ``deep_subresources_mode`` must be one of the values from :ref:`ResourceDeepDuplicateMode<enum_Resource_ResourceDeepDuplicateMode>`. By default, only internal resources will be duplicated (recursively).
+\ ``deep_subresources_mode`` must be one of the values from :ref:`DeepDuplicateMode<enum_Resource_DeepDuplicateMode>`. By default, only internal resources will be duplicated (recursively).
 
 .. rst-class:: classref-item-separator
 

classes/class_bitmap.rst

@@ -72,7 +72,7 @@ Method Descriptions
 
 :ref:`Image<class_Image>` **convert_to_image**\ (\ ) |const| :ref:`🔗<class_BitMap_method_convert_to_image>`
 
-Returns an image of the same size as the bitmap and with a :ref:`Format<enum_Image_Format>` of type :ref:`Image.FORMAT_L8<class_Image_constant_FORMAT_L8>`. ``true`` bits of the bitmap are being converted into white pixels, and ``false`` bits into black.
+Returns an image of the same size as the bitmap and with an :ref:`Format<enum_Image_Format>` of type :ref:`Image.FORMAT_L8<class_Image_constant_FORMAT_L8>`. ``true`` bits of the bitmap are being converted into white pixels, and ``false`` bits into black.
 
 .. rst-class:: classref-item-separator
 

classes/class_capsulemesh.rst

@@ -61,6 +61,8 @@ Property Descriptions
 
 Total height of the capsule mesh (including the hemispherical ends).
 
+\ **Note:** The :ref:`height<class_CapsuleMesh_property_height>` of a capsule must be at least twice its :ref:`radius<class_CapsuleMesh_property_radius>`. Otherwise, the capsule becomes a circle. If the :ref:`height<class_CapsuleMesh_property_height>` is less than twice the :ref:`radius<class_CapsuleMesh_property_radius>`, the properties adjust to a valid value.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -95,6 +97,8 @@ Number of radial segments on the capsule mesh.
 
 Radius of the capsule mesh.
 
+\ **Note:** The :ref:`radius<class_CapsuleMesh_property_radius>` of a capsule cannot be greater than half of its :ref:`height<class_CapsuleMesh_property_height>`. Otherwise, the capsule becomes a circle. If the :ref:`radius<class_CapsuleMesh_property_radius>` is greater than half of the :ref:`height<class_CapsuleMesh_property_height>`, the properties adjust to a valid value.
+
 .. rst-class:: classref-item-separator
 
 ----

classes/class_capsuleshape2d.rst

@@ -61,6 +61,8 @@ Property Descriptions
 
 The capsule's full height, including the semicircles.
 
+\ **Note:** The :ref:`height<class_CapsuleShape2D_property_height>` of a capsule must be at least twice its :ref:`radius<class_CapsuleShape2D_property_radius>`. Otherwise, the capsule becomes a circle. If the :ref:`height<class_CapsuleShape2D_property_height>` is less than twice the :ref:`radius<class_CapsuleShape2D_property_radius>`, the properties adjust to a valid value.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -95,6 +97,8 @@ The capsule's height, excluding the semicircles. This is the height of the centr
 
 The capsule's radius.
 
+\ **Note:** The :ref:`radius<class_CapsuleShape2D_property_radius>` of a capsule cannot be greater than half of its :ref:`height<class_CapsuleShape2D_property_height>`. Otherwise, the capsule becomes a circle. If the :ref:`radius<class_CapsuleShape2D_property_radius>` is greater than half of the :ref:`height<class_CapsuleShape2D_property_height>`, the properties adjust to a valid value.
+
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
 .. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)`
 .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`

classes/class_capsuleshape3d.rst

@@ -68,6 +68,8 @@ Property Descriptions
 
 The capsule's full height, including the hemispheres.
 
+\ **Note:** The :ref:`height<class_CapsuleShape3D_property_height>` of a capsule must be at least twice its :ref:`radius<class_CapsuleShape3D_property_radius>`. Otherwise, the capsule becomes a sphere. If the :ref:`height<class_CapsuleShape3D_property_height>` is less than twice the :ref:`radius<class_CapsuleShape3D_property_radius>`, the properties adjust to a valid value.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -102,6 +104,8 @@ The capsule's height, excluding the hemispheres. This is the height of the centr
 
 The capsule's radius.
 
+\ **Note:** The :ref:`radius<class_CapsuleShape3D_property_radius>` of a capsule cannot be greater than half of its :ref:`height<class_CapsuleShape3D_property_height>`. Otherwise, the capsule becomes a sphere. If the :ref:`radius<class_CapsuleShape3D_property_radius>` is greater than half of the :ref:`height<class_CapsuleShape3D_property_height>`, the properties adjust to a valid value.
+
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
 .. |required| replace:: :abbr:`required (This method is required to be overridden when extending its base class.)`
 .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`

classes/class_codeedit.rst

@@ -892,7 +892,7 @@ Override this method to define how the selected entry should be inserted. If ``r
 
 Override this method to define what items in ``candidates`` should be displayed.
 
-Both ``candidates`` and the return is a :ref:`Array<class_Array>` of :ref:`Dictionary<class_Dictionary>`, see :ref:`get_code_completion_option()<class_CodeEdit_method_get_code_completion_option>` for :ref:`Dictionary<class_Dictionary>` content.
+Both ``candidates`` and the return is an :ref:`Array<class_Array>` of :ref:`Dictionary<class_Dictionary>`, see :ref:`get_code_completion_option()<class_CodeEdit_method_get_code_completion_option>` for :ref:`Dictionary<class_Dictionary>` content.
 
 .. rst-class:: classref-item-separator
 

classes/class_cubemaparray.rst

@@ -37,7 +37,7 @@ The expected image order is X+, X-, Y+, Y-, Z+, Z- (in Godot's coordinate system
 
 - `6×1 cubemap template <https://raw.githubusercontent.com/godotengine/godot-docs/master/tutorials/assets_pipeline/img/cubemap_template_6x1.webp>`__\ 
 
-Multiple layers are stacked on top of each other when using the default vertical import option (with the first layer at the top). Alternatively, you can choose an horizontal layout in the import options (with the first layer at the left).
+Multiple layers are stacked on top of each other when using the default vertical import option (with the first layer at the top). Alternatively, you can choose a horizontal layout in the import options (with the first layer at the left).
 
 \ **Note:** **CubemapArray** is not supported in the Compatibility renderer due to graphics API limitations.
 

classes/class_dictionary.rst

@@ -408,7 +408,7 @@ If ``deep`` is ``true``, a **deep** copy is returned: all nested arrays and dict
 
 Duplicates this dictionary, deeply, like :ref:`duplicate()<class_Dictionary_method_duplicate>`\ ``(true)``, with extra control over how subresources are handled.
 
-\ ``deep_subresources_mode`` must be one of the values from :ref:`ResourceDeepDuplicateMode<enum_Resource_ResourceDeepDuplicateMode>`. By default, only internal resources will be duplicated (recursively).
+\ ``deep_subresources_mode`` must be one of the values from :ref:`DeepDuplicateMode<enum_Resource_DeepDuplicateMode>`. By default, only internal resources will be duplicated (recursively).
 
 .. rst-class:: classref-item-separator
 

classes/class_displayserver.rst

@@ -3644,7 +3644,7 @@ Returns the user's clipboard as a string if possible.
 
 Returns the user's clipboard as an image if possible.
 
-\ **Note:** This method uses the copied pixel data, e.g. from a image editing software or a web browser, not an image file copied from file explorer.
+\ **Note:** This method uses the copied pixel data, e.g. from an image editing software or a web browser, not an image file copied from file explorer.
 
 .. rst-class:: classref-item-separator
 
@@ -3850,7 +3850,7 @@ Each filter string in the ``filters`` array should be formatted like this: ``*.p
 
 Callbacks have the following arguments: ``status: bool, selected_paths: PackedStringArray, selected_filter_index: int``. **On Android,** the third callback argument (``selected_filter_index``) is always ``0``.
 
-\ **Note:** This method is implemented if the display server has the :ref:`FEATURE_NATIVE_DIALOG_FILE<class_DisplayServer_constant_FEATURE_NATIVE_DIALOG_FILE>` feature. Supported platforms include Linux (X11/Wayland), Windows, macOS, and Android.
+\ **Note:** This method is implemented if the display server has the :ref:`FEATURE_NATIVE_DIALOG_FILE<class_DisplayServer_constant_FEATURE_NATIVE_DIALOG_FILE>` feature. Supported platforms include Linux (X11/Wayland), Windows, macOS, and Android (API level 29+).
 
 \ **Note:** ``current_directory`` might be ignored.
 
@@ -5841,7 +5841,7 @@ Note that Godot depends on system libraries for text-to-speech functionality. Th
 
 :ref:`PackedStringArray<class_PackedStringArray>` **tts_get_voices_for_language**\ (\ language\: :ref:`String<class_String>`\ ) |const| :ref:`🔗<class_DisplayServer_method_tts_get_voices_for_language>`
 
-Returns an :ref:`PackedStringArray<class_PackedStringArray>` of voice identifiers for the ``language``.
+Returns a :ref:`PackedStringArray<class_PackedStringArray>` of voice identifiers for the ``language``.
 
 \ **Note:** This method is implemented on Android, iOS, Web, Linux (X11/Wayland), macOS, and Windows.
 

classes/class_editordebuggersession.rst

@@ -19,7 +19,7 @@ A class to interact with the editor debugger.
 Description
 -----------
 
-This class cannot be directly instantiated and must be retrieved via a :ref:`EditorDebuggerPlugin<class_EditorDebuggerPlugin>`.
+This class cannot be directly instantiated and must be retrieved via an :ref:`EditorDebuggerPlugin<class_EditorDebuggerPlugin>`.
 
 You can add tabs to the session UI via :ref:`add_session_tab()<class_EditorDebuggerSession_method_add_session_tab>`, send messages via :ref:`send_message()<class_EditorDebuggerSession_method_send_message>`, and toggle :ref:`EngineProfiler<class_EngineProfiler>`\ s via :ref:`toggle_profiler()<class_EditorDebuggerSession_method_toggle_profiler>`.