classref: Sync with current master branch (c64afeb)

Author: Godot Organization

classes/class_@gdscript.rst

@@ -133,7 +133,7 @@ Mark the following property as exported (editable in the Inspector dock and save
     @export var string = ""
     @export var int_number = 5
     @export var float_number: float = 5
-    @export var image : Image
+    @export var image: Image
 
 .. rst-class:: classref-item-separator
 
@@ -173,7 +173,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_COLOR_NO_ALPHA<class_@GlobalScope_cons
 
 ::
 
-    @export_color_no_alpha var dye_color : Color
+    @export_color_no_alpha var dye_color: Color
 
 .. rst-class:: classref-item-separator
 
@@ -418,6 +418,24 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_3D_RENDER<class_@GlobalScope_co
 
 ----
 
+.. _class_@GDScript_annotation_@export_flags_avoidance:
+
+.. rst-class:: classref-annotation
+
+**@export_flags_avoidance** **(** **)**
+
+Export an integer property as a bit flag field for navigation avoidance layers. The widget in the Inspector dock will use the layer names defined in :ref:`ProjectSettings.layer_names/avoidance/layer_1<class_ProjectSettings_property_layer_names/avoidance/layer_1>`.
+
+See also :ref:`@GlobalScope.PROPERTY_HINT_LAYERS_AVOIDANCE<class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_AVOIDANCE>`.
+
+::
+
+    @export_flags_avoidance var avoidance_layers: int
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_@GDScript_annotation_@export_global_dir:
 
 .. rst-class:: classref-annotation
@@ -465,7 +483,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_GLOBAL_FILE<class_@GlobalScope_constan
 
 Define a new group for the following exported properties. This helps to organize properties in the Inspector dock. Groups can be added with an optional ``prefix``, which would make group to only consider properties that have this prefix. The grouping will break on the first property that doesn't have a prefix. The prefix is also removed from the property's name in the Inspector dock.
 
-If no ``prefix`` is provided, the every following property is added to the group. The group ends when then next group or category is defined. You can also force end a group by using this annotation with empty strings for parameters, ``@export_group("", "")``.
+If no ``prefix`` is provided, then every following property will be added to the group. The group ends when then next group or category is defined. You can also force end a group by using this annotation with empty strings for parameters, ``@export_group("", "")``.
 
 Groups cannot be nested, use :ref:`@export_subgroup<class_@GDScript_annotation_@export_subgroup>` to add subgroups within groups.
 
@@ -662,6 +680,18 @@ The order of ``mode``, ``sync`` and ``transfer_mode`` does not matter and all ar
 
 ----
 
+.. _class_@GDScript_annotation_@static_unload:
+
+.. rst-class:: classref-annotation
+
+**@static_unload** **(** **)**
+
+Make a script with static variables to not persist after all references are lost. If the script is loaded again the static variables will revert to their default values.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_@GDScript_annotation_@tool:
 
 .. rst-class:: classref-annotation
@@ -712,14 +742,16 @@ Method Descriptions
 
 :ref:`Color<class_Color>` **Color8** **(** :ref:`int<class_int>` r8, :ref:`int<class_int>` g8, :ref:`int<class_int>` b8, :ref:`int<class_int>` a8=255 **)**
 
-Returns a :ref:`Color<class_Color>` constructed from red (``r8``), green (``g8``), blue (``b8``), and optionally alpha (``a8``) integer channels, each divided by ``255.0`` for their final value.
+Returns a :ref:`Color<class_Color>` constructed from red (``r8``), green (``g8``), blue (``b8``), and optionally alpha (``a8``) integer channels, each divided by ``255.0`` for their final value. Using :ref:`Color8<class_@GDScript_method_Color8>` instead of the standard :ref:`Color<class_Color>` constructor is useful when you need to match exact color values in an :ref:`Image<class_Image>`.
 
 ::
 
     var red = Color8(255, 0, 0)             # Same as Color(1, 0, 0).
     var dark_blue = Color8(0, 0, 51)        # Same as Color(0, 0, 0.2).
     var my_color = Color8(306, 255, 0, 102) # Same as Color(1.2, 1, 0, 0.4).
 
+\ **Note:** Due to the lower precision of :ref:`Color8<class_@GDScript_method_Color8>` compared to the standard :ref:`Color<class_Color>` constructor, a color created with :ref:`Color8<class_@GDScript_method_Color8>` will generally not be equal to the same color created with the standard :ref:`Color<class_Color>` constructor. Use :ref:`Color.is_equal_approx<class_Color_method_is_equal_approx>` for comparisons to avoid issues with floating-point precision error.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -887,7 +919,7 @@ Examples:
     print(is_instance_of(a, MyClass))
     print(is_instance_of(a, MyClass.InnerClass))
 
-\ **Note:** If ``value`` and/or ``type`` are freed objects (see :ref:`@GlobalScope.is_instance_valid<class_@GlobalScope_method_is_instance_valid>`), or ``type`` is not one of the above options, this method will raise an runtime error.
+\ **Note:** If ``value`` and/or ``type`` are freed objects (see :ref:`@GlobalScope.is_instance_valid<class_@GlobalScope_method_is_instance_valid>`), or ``type`` is not one of the above options, this method will raise a runtime error.
 
 See also :ref:`@GlobalScope.typeof<class_@GlobalScope_method_typeof>`, :ref:`type_exists<class_@GDScript_method_type_exists>`, :ref:`Array.is_same_typed<class_Array_method_is_same_typed>` (and other :ref:`Array<class_Array>` methods).
 
@@ -936,6 +968,8 @@ This function is a simplified version of :ref:`ResourceLoader.load<class_Resourc
 
 \ **Note:** Files have to be imported into the engine first to load them using this function. If you want to load :ref:`Image<class_Image>`\ s at run-time, you may use :ref:`Image.load<class_Image_method_load>`. If you want to import audio files, you can use the snippet described in :ref:`AudioStreamMP3.data<class_AudioStreamMP3_property_data>`.
 
+\ **Note:** If :ref:`ProjectSettings.editor/export/convert_text_resources_to_binary<class_ProjectSettings_property_editor/export/convert_text_resources_to_binary>` is ``true``, :ref:`load<class_@GDScript_method_load>` will not be able to read converted files in an exported project. If you rely on run-time loading of files present within the PCK, set :ref:`ProjectSettings.editor/export/convert_text_resources_to_binary<class_ProjectSettings_property_editor/export/convert_text_resources_to_binary>` to ``false``.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -1034,8 +1068,8 @@ To iterate over an :ref:`Array<class_Array>` backwards, use:
 ::
 
     var array = [3, 6, 9]
-    for i in range(array.size(), 0, -1):
-        print(array[i - 1])
+    for i in range(array.size() - 1, -1, -1):
+        print(array[i])
 
 Output:
 

classes/class_@globalscope.rst

@@ -3509,6 +3509,14 @@ Hints that an :ref:`int<class_int>` property is a bitmask using the optionally n
 
 Hints that an :ref:`int<class_int>` property is a bitmask using the optionally named 3D navigation layers.
 
+.. _class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_AVOIDANCE:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`PropertyHint<enum_@GlobalScope_PropertyHint>` **PROPERTY_HINT_LAYERS_AVOIDANCE** = ``37``
+
+Hints that an integer property is a bitmask using the optionally named avoidance layers.
+
 .. _class_@GlobalScope_constant_PROPERTY_HINT_FILE:
 
 .. rst-class:: classref-enumeration-constant
@@ -3714,7 +3722,7 @@ Hints that a string property is a password, and every character is replaced with
 
 .. rst-class:: classref-enumeration-constant
 
-:ref:`PropertyHint<enum_@GlobalScope_PropertyHint>` **PROPERTY_HINT_MAX** = ``37``
+:ref:`PropertyHint<enum_@GlobalScope_PropertyHint>` **PROPERTY_HINT_MAX** = ``38``
 
 Represents the size of the :ref:`PropertyHint<enum_@GlobalScope_PropertyHint>` enum.
 
@@ -3758,7 +3766,7 @@ The property is shown in the :ref:`EditorInspector<class_EditorInspector>` (defa
 
 :ref:`PropertyUsageFlags<enum_@GlobalScope_PropertyUsageFlags>` **PROPERTY_USAGE_INTERNAL** = ``8``
 
-
+The property is excluded from the class reference.
 
 .. _class_@GlobalScope_constant_PROPERTY_USAGE_CHECKABLE:
 
@@ -3960,6 +3968,14 @@ The property is only shown in the editor if modern renderers are supported (the
 
 The property is read-only in the :ref:`EditorInspector<class_EditorInspector>`.
 
+.. _class_@GlobalScope_constant_PROPERTY_USAGE_SECRET:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`PropertyUsageFlags<enum_@GlobalScope_PropertyUsageFlags>` **PROPERTY_USAGE_SECRET** = ``536870912``
+
+An export preset property with this flag contains confidential information and is stored separately from the rest of the export preset configuration.
+
 .. _class_@GlobalScope_constant_PROPERTY_USAGE_DEFAULT:
 
 .. rst-class:: classref-enumeration-constant
@@ -5114,7 +5130,7 @@ Returns the absolute value of int parameter ``x`` (i.e. positive value).
 
 :ref:`float<class_float>` **acos** **(** :ref:`float<class_float>` x **)**
 
-Returns the arc cosine of ``x`` in radians. Use to get the angle of cosine ``x``. ``x`` must be between ``-1.0`` and ``1.0`` (inclusive), otherwise, :ref:`acos<class_@GlobalScope_method_acos>` will return :ref:`@GDScript.NAN<class_@GDScript_constant_NAN>`.
+Returns the arc cosine of ``x`` in radians. Use to get the angle of cosine ``x``. ``x`` will be clamped between ``-1.0`` and ``1.0`` (inclusive), in order to prevent :ref:`acos<class_@GlobalScope_method_acos>` from returning :ref:`@GDScript.NAN<class_@GDScript_constant_NAN>`.
 
 ::
 
@@ -5131,7 +5147,7 @@ Returns the arc cosine of ``x`` in radians. Use to get the angle of cosine ``x``
 
 :ref:`float<class_float>` **asin** **(** :ref:`float<class_float>` x **)**
 
-Returns the arc sine of ``x`` in radians. Use to get the angle of sine ``x``. ``x`` must be between ``-1.0`` and ``1.0`` (inclusive), otherwise, :ref:`asin<class_@GlobalScope_method_asin>` will return :ref:`@GDScript.NAN<class_@GDScript_constant_NAN>`.
+Returns the arc sine of ``x`` in radians. Use to get the angle of sine ``x``. ``x`` will be clamped between ``-1.0`` and ``1.0`` (inclusive), in order to prevent :ref:`asin<class_@GlobalScope_method_asin>` from returning :ref:`@GDScript.NAN<class_@GDScript_constant_NAN>`.
 
 ::
 
@@ -5904,7 +5920,7 @@ Linearly interpolates between two values by the factor defined in ``weight``. To
 
 ::
 
-    lerp(0, 4, 0.75) # Returns 3.0
+    lerpf(0, 4, 0.75) # Returns 3.0
 
 See also :ref:`inverse_lerp<class_@GlobalScope_method_inverse_lerp>` which performs the reverse of this operation. To perform eased interpolation with :ref:`lerp<class_@GlobalScope_method_lerp>`, combine it with :ref:`ease<class_@GlobalScope_method_ease>` or :ref:`smoothstep<class_@GlobalScope_method_smoothstep>`.
 
@@ -5939,9 +5955,9 @@ Converts from linear energy to decibels (audio). This can be used to implement v
 
 :ref:`float<class_float>` **log** **(** :ref:`float<class_float>` x **)**
 
-Returns the natural logarithm of ``x``. This is the amount of time needed to reach a certain level of continuous growth.
+Returns the `natural logarithm <https://en.wikipedia.org/wiki/Natural_logarithm>`__ of ``x`` (base `[i]e[/i] <https://en.wikipedia.org/wiki/E_(mathematical_constant)>`__, with *e* being approximately 2.71828). This is the amount of time needed to reach a certain level of continuous growth.
 
-\ **Note:** This is not the same as the "log" function on most calculators, which uses a base 10 logarithm.
+\ **Note:** This is not the same as the "log" function on most calculators, which uses a base 10 logarithm. To use base 10 logarithm, use ``log(x) / log(10)``.
 
 ::
 
@@ -6208,25 +6224,33 @@ Converts one or more arguments of any type to string in the best way possible an
 
 void **print_rich** **(** ... **)** |vararg|
 
-Converts one or more arguments of any type to string in the best way possible and prints them to the console. The following BBCode tags are supported: b, i, u, s, indent, code, url, center, right, color, bgcolor, fgcolor. Color tags only support named colors such as ``red``, *not* hexadecimal color codes. Unsupported tags will be left as-is in standard output.
+Converts one or more arguments of any type to string in the best way possible and prints them to the console.
+
+The following BBCode tags are supported: ``b``, ``i``, ``u``, ``s``, ``indent``, ``code``, ``url``, ``center``, ``right``, ``color``, ``bgcolor``, ``fgcolor``.
 
-When printing to standard output, the supported subset of BBCode is converted to ANSI escape codes for the terminal emulator to display. Displaying ANSI escape codes is currently only supported on Linux and macOS. Support for ANSI escape codes may vary across terminal emulators, especially for italic and strikethrough.
+Color tags only support the following named colors: ``black``, ``red``, ``green``, ``yellow``, ``blue``, ``magenta``, ``pink``, ``purple``, ``cyan``, ``white``, ``orange``, ``gray``. Hexadecimal color codes are not supported.
+
+URL tags only support URLs wrapped by an URL tag, not URLs with a different title.
+
+When printing to standard output, the supported subset of BBCode is converted to ANSI escape codes for the terminal emulator to display. Support for ANSI escape codes varies across terminal emulators, especially for italic and strikethrough. In standard output, ``code`` is represented with faint text but without any font change. Unsupported tags are left as-is in standard output.
 
 
 .. tabs::
 
  .. code-tab:: gdscript
 
-    print_rich("[code][b]Hello world![/b][/code]") # Prints out: [b]Hello world![/b]
+    print_rich("[color=green][b]Hello world![/b][/color]") # Prints out "Hello world!" in green with a bold font
 
  .. code-tab:: csharp
 
-    GD.PrintRich("[code][b]Hello world![/b][/code]"); // Prints out: [b]Hello world![/b]
+    GD.PrintRich("[color=green][b]Hello world![/b][/color]"); // Prints out "Hello world!" in green with a bold font
 
 
 
 \ **Note:** Consider using :ref:`push_error<class_@GlobalScope_method_push_error>` and :ref:`push_warning<class_@GlobalScope_method_push_warning>` to print error and warning messages instead of :ref:`print<class_@GlobalScope_method_print>` or :ref:`print_rich<class_@GlobalScope_method_print_rich>`. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed.
 
+\ **Note:** On Windows, only Windows 10 and later correctly displays ANSI escape codes in standard output.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -6735,9 +6759,9 @@ Returns ``-1.0`` if ``x`` is negative, ``1.0`` if ``x`` is positive, and ``0.0``
 
 ::
 
-    sign(-6.5) # Returns -1.0
-    sign(0.0)  # Returns 0.0
-    sign(6.5)  # Returns 1.0
+    signf(-6.5) # Returns -1.0
+    signf(0.0)  # Returns 0.0
+    signf(6.5)  # Returns 1.0
 
 .. rst-class:: classref-item-separator
 
@@ -6753,9 +6777,9 @@ Returns ``-1`` if ``x`` is negative, ``1`` if ``x`` is positive, and ``0`` if if
 
 ::
 
-    sign(-6) # Returns -1
-    sign(0)  # Returns 0
-    sign(6)  # Returns 1
+    signi(-6) # Returns -1
+    signi(0)  # Returns 0
+    signi(6)  # Returns 1
 
 .. rst-class:: classref-item-separator
 
@@ -6859,8 +6883,8 @@ A type-safe version of :ref:`snapped<class_@GlobalScope_method_snapped>`, return
 
 ::
 
-    snapped(32.0, 2.5)  # Returns 32.5
-    snapped(3.14159, 0.01)  # Returns 3.14
+    snappedf(32.0, 2.5)  # Returns 32.5
+    snappedf(3.14159, 0.01)  # Returns 3.14
 
 .. rst-class:: classref-item-separator
 
@@ -6878,8 +6902,8 @@ A type-safe version of :ref:`snapped<class_@GlobalScope_method_snapped>`, return
 
 ::
 
-    snapped(53, 16)  # Returns 48
-    snapped(4096, 100)  # Returns 4100
+    snappedi(53, 16)  # Returns 48
+    snappedi(4096, 100)  # Returns 4100
 
 .. rst-class:: classref-item-separator
 

classes/class_aabb.rst

@@ -502,7 +502,7 @@ Returns ``true`` if the **AABB** is on both sides of a plane.
 
 :ref:`Variant<class_Variant>` **intersects_ray** **(** :ref:`Vector3<class_Vector3>` from, :ref:`Vector3<class_Vector3>` dir **)** |const|
 
-Returns ``true`` if the given ray intersects with this **AABB**. Ray length is infinite.
+Returns the point of intersection of the given ray with this **AABB** or ``null`` if there is no intersection. Ray length is infinite.
 
 .. rst-class:: classref-item-separator
 
@@ -514,7 +514,7 @@ Returns ``true`` if the given ray intersects with this **AABB**. Ray length is i
 
 :ref:`Variant<class_Variant>` **intersects_segment** **(** :ref:`Vector3<class_Vector3>` from, :ref:`Vector3<class_Vector3>` to **)** |const|
 
-Returns ``true`` if the **AABB** intersects the line segment between ``from`` and ``to``.
+Returns the point of intersection between ``from`` and ``to`` with this **AABB** or ``null`` if there is no intersection.
 
 .. rst-class:: classref-item-separator
 
@@ -567,7 +567,7 @@ Operator Descriptions
 
 :ref:`bool<class_bool>` **operator !=** **(** :ref:`AABB<class_AABB>` right **)**
 
-Returns ``true`` if the vectors are not equal.
+Returns ``true`` if the AABBs are not equal.
 
 \ **Note:** Due to floating-point precision errors, consider using :ref:`is_equal_approx<class_AABB_method_is_equal_approx>` instead, which is more reliable.