classref: Sync with current master branch (9ce3194)

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
 
@@ -465,7 +465,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 +662,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 +724,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
 
 ----
@@ -1034,8 +1048,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

@@ -3758,7 +3758,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:
 
@@ -5904,7 +5904,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 +5939,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 +6208,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 +6743,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 +6761,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 +6867,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 +6886,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.
 

classes/class_aescontext.rst

@@ -34,27 +34,27 @@ This class provides access to AES encryption/decryption of raw data. Both AES-EC
         var key = "My secret key!!!" # Key must be either 16 or 32 bytes.
         var data = "My secret text!!" # Data size must be multiple of 16 bytes, apply padding if needed.
         # Encrypt ECB
-        aes.start(AESContext.MODE_ECB_ENCRYPT, key.to_utf8())
-        var encrypted = aes.update(data.to_utf8())
+        aes.start(AESContext.MODE_ECB_ENCRYPT, key.to_utf8_buffer())
+        var encrypted = aes.update(data.to_utf8_buffer())
         aes.finish()
         # Decrypt ECB
-        aes.start(AESContext.MODE_ECB_DECRYPT, key.to_utf8())
+        aes.start(AESContext.MODE_ECB_DECRYPT, key.to_utf8_buffer())
         var decrypted = aes.update(encrypted)
         aes.finish()
         # Check ECB
-        assert(decrypted == data.to_utf8())
+        assert(decrypted == data.to_utf8_buffer())
 
         var iv = "My secret iv!!!!" # IV must be of exactly 16 bytes.
         # Encrypt CBC
-        aes.start(AESContext.MODE_CBC_ENCRYPT, key.to_utf8(), iv.to_utf8())
-        encrypted = aes.update(data.to_utf8())
+        aes.start(AESContext.MODE_CBC_ENCRYPT, key.to_utf8_buffer(), iv.to_utf8_buffer())
+        encrypted = aes.update(data.to_utf8_buffer())
         aes.finish()
         # Decrypt CBC
-        aes.start(AESContext.MODE_CBC_DECRYPT, key.to_utf8(), iv.to_utf8())
+        aes.start(AESContext.MODE_CBC_DECRYPT, key.to_utf8_buffer(), iv.to_utf8_buffer())
         decrypted = aes.update(encrypted)
         aes.finish()
         # Check CBC
-        assert(decrypted == data.to_utf8())
+        assert(decrypted == data.to_utf8_buffer())
 
  .. code-tab:: csharp
 
@@ -70,27 +70,27 @@ This class provides access to AES encryption/decryption of raw data. Both AES-EC
             string key = "My secret key!!!"; // Key must be either 16 or 32 bytes.
             string data = "My secret text!!"; // Data size must be multiple of 16 bytes, apply padding if needed.
             // Encrypt ECB
-            _aes.Start(AesContext.Mode.EcbEncrypt, key.ToUtf8());
-            byte[] encrypted = _aes.Update(data.ToUtf8());
+            _aes.Start(AesContext.Mode.EcbEncrypt, key.ToUtf8Buffer());
+            byte[] encrypted = _aes.Update(data.ToUtf8Buffer());
             _aes.Finish();
             // Decrypt ECB
-            _aes.Start(AesContext.Mode.EcbDecrypt, key.ToUtf8());
+            _aes.Start(AesContext.Mode.EcbDecrypt, key.ToUtf8Buffer());
             byte[] decrypted = _aes.Update(encrypted);
             _aes.Finish();
             // Check ECB
-            Debug.Assert(decrypted == data.ToUtf8());
+            Debug.Assert(decrypted == data.ToUtf8Buffer());
 
             string iv = "My secret iv!!!!"; // IV must be of exactly 16 bytes.
             // Encrypt CBC
-            _aes.Start(AesContext.Mode.EcbEncrypt, key.ToUtf8(), iv.ToUtf8());
-            encrypted = _aes.Update(data.ToUtf8());
+            _aes.Start(AesContext.Mode.EcbEncrypt, key.ToUtf8Buffer(), iv.ToUtf8Buffer());
+            encrypted = _aes.Update(data.ToUtf8Buffer());
             _aes.Finish();
             // Decrypt CBC
-            _aes.Start(AesContext.Mode.EcbDecrypt, key.ToUtf8(), iv.ToUtf8());
+            _aes.Start(AesContext.Mode.EcbDecrypt, key.ToUtf8Buffer(), iv.ToUtf8Buffer());
             decrypted = _aes.Update(encrypted);
             _aes.Finish();
             // Check CBC
-            Debug.Assert(decrypted == data.ToUtf8());
+            Debug.Assert(decrypted == data.ToUtf8Buffer());
         }
     }
 

classes/class_animatablebody2d.rst

@@ -12,7 +12,7 @@ AnimatableBody2D
 
 **Inherits:** :ref:`StaticBody2D<class_StaticBody2D>` **<** :ref:`PhysicsBody2D<class_PhysicsBody2D>` **<** :ref:`CollisionObject2D<class_CollisionObject2D>` **<** :ref:`Node2D<class_Node2D>` **<** :ref:`CanvasItem<class_CanvasItem>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`
 
-Physics body for 2D physics which moves only by script or animation. Useful for moving platforms and doors.
+Physics body for 2D physics which moves only by script or animation (while affecting other bodies on its path). Useful for moving platforms and doors.
 
 .. rst-class:: classref-introduction-group
 

classes/class_animatablebody3d.rst

@@ -12,7 +12,7 @@ AnimatableBody3D
 
 **Inherits:** :ref:`StaticBody3D<class_StaticBody3D>` **<** :ref:`PhysicsBody3D<class_PhysicsBody3D>` **<** :ref:`CollisionObject3D<class_CollisionObject3D>` **<** :ref:`Node3D<class_Node3D>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`
 
-Physics body for 3D physics which moves only by script or animation. Useful for moving platforms and doors.
+Physics body for 3D physics which moves only by script or animation (while affecting other bodies on its path). Useful for moving platforms and doors.
 
 .. rst-class:: classref-introduction-group