classref: Sync with current master branch (89cc635)

classes/class_@gdscript.rst

@@ -972,7 +972,7 @@ See also :ref:`@GlobalScope.typeof<class_@GlobalScope_method_typeof>`, :ref:`typ
 
 :ref:`int<class_int>` **len** **(** :ref:`Variant<class_Variant>` var **)**
 
-Returns the length of the given Variant ``var``. The length can be the character count of a :ref:`String<class_String>`, the element count of any array type or the size of a :ref:`Dictionary<class_Dictionary>`. For every other Variant type, a run-time error is generated and execution is stopped.
+Returns the length of the given Variant ``var``. The length can be the character count of a :ref:`String<class_String>` or :ref:`StringName<class_StringName>`, the element count of any array type, or the size of a :ref:`Dictionary<class_Dictionary>`. For every other Variant type, a run-time error is generated and execution is stopped.
 
 ::
 
@@ -992,7 +992,7 @@ Returns the length of the given Variant ``var``. The length can be the character
 
 :ref:`Resource<class_Resource>` **load** **(** :ref:`String<class_String>` path **)**
 
-Returns a :ref:`Resource<class_Resource>` from the filesystem located at the absolute ``path``. Unless it's already referenced elsewhere (such as in another script or in the scene), the resource is loaded from disk on function call, which might cause a slight delay, especially when loading large scenes. To avoid unnecessary delays when loading something multiple times, either store the resource in a variable or use :ref:`preload<class_@GDScript_method_preload>`.
+Returns a :ref:`Resource<class_Resource>` from the filesystem located at the absolute ``path``. Unless it's already referenced elsewhere (such as in another script or in the scene), the resource is loaded from disk on function call, which might cause a slight delay, especially when loading large scenes. To avoid unnecessary delays when loading something multiple times, either store the resource in a variable or use :ref:`preload<class_@GDScript_method_preload>`. This method is equivalent of using :ref:`ResourceLoader.load<class_ResourceLoader_method_load>` with :ref:`ResourceLoader.CACHE_MODE_REUSE<class_ResourceLoader_constant_CACHE_MODE_REUSE>`.
 
 \ **Note:** Resource paths can be obtained by right-clicking on a resource in the FileSystem dock and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script.
 

classes/class_@globalscope.rst

@@ -5480,20 +5480,10 @@ Clamps the ``value``, returning a :ref:`Variant<class_Variant>` not less than ``
 
     var b = clamp(8.1, 0.9, 5.5)
     # b is 5.5
-
-    var c = clamp(Vector2(-3.5, -4), Vector2(-3.2, -2), Vector2(2, 6.5))
-    # c is (-3.2, -2)
-
-    var d = clamp(Vector2i(7, 8), Vector2i(-3, -2), Vector2i(2, 6))
-    # d is (2, 6)
-
-    var e = clamp(Vector3(-7, 8.5, -3.8), Vector3(-3, -2, 5.4), Vector3(-2, 6, -4.1))
-    # e is (-3, -2, 5.4)
-
-    var f = clamp(Vector3i(-7, -8, -9), Vector3i(-1, 2, 3), Vector3i(-4, -5, -6))
-    # f is (-4, -5, -6)
 
-\ **Note:** For better type safety, use :ref:`clampf<class_@GlobalScope_method_clampf>`, :ref:`clampi<class_@GlobalScope_method_clampi>`, :ref:`Vector2.clamp<class_Vector2_method_clamp>`, :ref:`Vector2i.clamp<class_Vector2i_method_clamp>`, :ref:`Vector3.clamp<class_Vector3_method_clamp>`, :ref:`Vector3i.clamp<class_Vector3i_method_clamp>`, :ref:`Vector4.clamp<class_Vector4_method_clamp>`, :ref:`Vector4i.clamp<class_Vector4i_method_clamp>`, or :ref:`Color.clamp<class_Color_method_clamp>`.
+\ **Note:** For better type safety, use :ref:`clampf<class_@GlobalScope_method_clampf>`, :ref:`clampi<class_@GlobalScope_method_clampi>`, :ref:`Vector2.clamp<class_Vector2_method_clamp>`, :ref:`Vector2i.clamp<class_Vector2i_method_clamp>`, :ref:`Vector3.clamp<class_Vector3_method_clamp>`, :ref:`Vector3i.clamp<class_Vector3i_method_clamp>`, :ref:`Vector4.clamp<class_Vector4_method_clamp>`, :ref:`Vector4i.clamp<class_Vector4i_method_clamp>`, or :ref:`Color.clamp<class_Color_method_clamp>` (not currently supported by this method).
+
+\ **Note:** When using this on vectors it will *not* perform component-wise clamping, and will pick ``min`` if ``value < min`` or ``max`` if ``value > max``. To perform component-wise clamping use the methods listed above.
 
 .. rst-class:: classref-item-separator
 
@@ -7225,7 +7215,7 @@ Converts the given ``variant`` to the given ``type``, using the :ref:`Variant.Ty
 
 If the type conversion cannot be done, this method will return the default value for that type, for example converting :ref:`Rect2<class_Rect2>` to :ref:`Vector2<class_Vector2>` will always return :ref:`Vector2.ZERO<class_Vector2_constant_ZERO>`. This method will never show error messages as long as ``type`` is a valid Variant type.
 
-The returned value is a :ref:`Variant<class_Variant>`, but the data inside and the :ref:`Variant.Type<enum_@GlobalScope_Variant.Type>` will be the same as the requested type.
+The returned value is a :ref:`Variant<class_Variant>`, but the data inside and its type will be the same as the requested type.
 
 ::
 

classes/class_animationnodestatemachine.rst

@@ -413,9 +413,7 @@ Renames the given animation node.
 
 void **replace_node** **(** :ref:`StringName<class_StringName>` name, :ref:`AnimationNode<class_AnimationNode>` node **)**
 
-.. container:: contribute
-
-	There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+Replaces the given animation node with a new animation node.
 
 .. rst-class:: classref-item-separator
 

classes/class_area2d.rst

@@ -23,6 +23,8 @@ Description
 
 This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses.
 
+\ **Note:** Areas and bodies created with :ref:`PhysicsServer2D<class_PhysicsServer2D>` might not interact as expected with **Area2D**\ s, and might not emit signals or track objects correctly.
+
 .. rst-class:: classref-introduction-group
 
 Tutorials

classes/class_area3d.rst

@@ -23,6 +23,8 @@ Description
 
 This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses.
 
+\ **Note:** Areas and bodies created with :ref:`PhysicsServer3D<class_PhysicsServer3D>` might not interact as expected with **Area3D**\ s, and might not emit signals or track objects correctly.
+
 \ **Warning:** Using a :ref:`ConcavePolygonShape3D<class_ConcavePolygonShape3D>` inside a :ref:`CollisionShape3D<class_CollisionShape3D>` child of this node (created e.g. by using the **Create Trimesh Collision Sibling** option in the **Mesh** menu that appears when selecting a :ref:`MeshInstance3D<class_MeshInstance3D>` node) may give unexpected results, since this collision shape is hollow. If this is not desired, it has to be split into multiple :ref:`ConvexPolygonShape3D<class_ConvexPolygonShape3D>`\ s or primitive shapes like :ref:`BoxShape3D<class_BoxShape3D>`, or in some cases it may be replaceable by a :ref:`CollisionPolygon3D<class_CollisionPolygon3D>`.
 
 .. rst-class:: classref-introduction-group

classes/class_array.rst

@@ -1047,6 +1047,8 @@ Removes an element from the array by index. If the index does not exist in the a
 
 Resizes the array to contain a different number of elements. If the array size is smaller, elements are cleared, if bigger, new elements are ``null``. Returns :ref:`@GlobalScope.OK<class_@GlobalScope_constant_OK>` on success, or one of the other :ref:`Error<enum_@GlobalScope_Error>` values if the operation failed.
 
+Calling :ref:`resize<class_Array_method_resize>` once and assigning the new values is faster than adding new elements one by one.
+
 \ **Note:** This method acts in-place and doesn't return a modified array.
 
 .. rst-class:: classref-item-separator

classes/class_astargrid2d.rst

@@ -56,6 +56,8 @@ Properties
 .. table::
    :widths: auto
 
+   +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+
+   | :ref:`CellShape<enum_AStarGrid2D_CellShape>`       | :ref:`cell_shape<class_AStarGrid2D_property_cell_shape>`                                 | ``0``                  |
    +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+
    | :ref:`Vector2<class_Vector2>`                      | :ref:`cell_size<class_AStarGrid2D_property_cell_size>`                                   | ``Vector2(1, 1)``      |
    +----------------------------------------------------+------------------------------------------------------------------------------------------+------------------------+
@@ -250,6 +252,48 @@ The pathfinding algorithm will avoid using diagonals if any obstacle has been pl
 
 Represents the size of the :ref:`DiagonalMode<enum_AStarGrid2D_DiagonalMode>` enum.
 
+.. rst-class:: classref-item-separator
+
+----
+
+.. _enum_AStarGrid2D_CellShape:
+
+.. rst-class:: classref-enumeration
+
+enum **CellShape**:
+
+.. _class_AStarGrid2D_constant_CELL_SHAPE_SQUARE:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`CellShape<enum_AStarGrid2D_CellShape>` **CELL_SHAPE_SQUARE** = ``0``
+
+Rectangular cell shape.
+
+.. _class_AStarGrid2D_constant_CELL_SHAPE_ISOMETRIC_RIGHT:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`CellShape<enum_AStarGrid2D_CellShape>` **CELL_SHAPE_ISOMETRIC_RIGHT** = ``1``
+
+Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes up-right, and the vertical one goes down-right.
+
+.. _class_AStarGrid2D_constant_CELL_SHAPE_ISOMETRIC_DOWN:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`CellShape<enum_AStarGrid2D_CellShape>` **CELL_SHAPE_ISOMETRIC_DOWN** = ``2``
+
+Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes down-right, and the vertical one goes down-left.
+
+.. _class_AStarGrid2D_constant_CELL_SHAPE_MAX:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`CellShape<enum_AStarGrid2D_CellShape>` **CELL_SHAPE_MAX** = ``3``
+
+Represents the size of the :ref:`CellShape<enum_AStarGrid2D_CellShape>` enum.
+
 .. rst-class:: classref-section-separator
 
 ----
@@ -259,6 +303,23 @@ Represents the size of the :ref:`DiagonalMode<enum_AStarGrid2D_DiagonalMode>` en
 Property Descriptions
 ---------------------
 
+.. _class_AStarGrid2D_property_cell_shape:
+
+.. rst-class:: classref-property
+
+:ref:`CellShape<enum_AStarGrid2D_CellShape>` **cell_shape** = ``0``
+
+.. rst-class:: classref-property-setget
+
+- void **set_cell_shape** **(** :ref:`CellShape<enum_AStarGrid2D_CellShape>` value **)**
+- :ref:`CellShape<enum_AStarGrid2D_CellShape>` **get_cell_shape** **(** **)**
+
+The cell shape. Affects how the positions are placed in the grid. If changed, :ref:`update<class_AStarGrid2D_method_update>` needs to be called before finding the next path.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_AStarGrid2D_property_cell_size:
 
 .. rst-class:: classref-property

classes/class_audioserver.rst

@@ -289,7 +289,7 @@ Name of the current device for audio output (see :ref:`get_output_device_list<cl
 - void **set_playback_speed_scale** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_playback_speed_scale** **(** **)**
 
-Scales the rate at which audio is played (i.e. setting it to ``0.5`` will make the audio be played at half its speed).
+Scales the rate at which audio is played (i.e. setting it to ``0.5`` will make the audio be played at half its speed). See also :ref:`Engine.time_scale<class_Engine_property_time_scale>` to affect the general simulation speed, which is independent from :ref:`playback_speed_scale<class_AudioServer_property_playback_speed_scale>`.
 
 .. rst-class:: classref-section-separator
 

classes/class_basematerial3d.rst

@@ -479,47 +479,47 @@ enum **TextureFilter**:
 
 :ref:`TextureFilter<enum_BaseMaterial3D_TextureFilter>` **TEXTURE_FILTER_NEAREST** = ``0``
 
-The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized.
+The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled).
 
 .. _class_BaseMaterial3D_constant_TEXTURE_FILTER_LINEAR:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`TextureFilter<enum_BaseMaterial3D_TextureFilter>` **TEXTURE_FILTER_LINEAR** = ``1``
 
-The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps.
+The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled).
 
 .. _class_BaseMaterial3D_constant_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`TextureFilter<enum_BaseMaterial3D_TextureFilter>` **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS** = ``2``
 
-The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps.
+The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter<class_ProjectSettings_property_rendering/textures/default_filters/use_nearest_mipmap_filter>` is ``true``). This makes the texture look pixelated from up close, and smooth from a distance.
 
 .. _class_BaseMaterial3D_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`TextureFilter<enum_BaseMaterial3D_TextureFilter>` **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS** = ``3``
 
-The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for most cases as mipmaps are important to smooth out pixels that are far from the camera.
+The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter<class_ProjectSettings_property_rendering/textures/default_filters/use_nearest_mipmap_filter>` is ``true``). This makes the texture look smooth from up close, and smooth from a distance.
 
 .. _class_BaseMaterial3D_constant_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`TextureFilter<enum_BaseMaterial3D_TextureFilter>` **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC** = ``4``
 
-The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level<class_ProjectSettings_property_rendering/textures/default_filters/anisotropic_filtering_level>`.
+The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter<class_ProjectSettings_property_rendering/textures/default_filters/use_nearest_mipmap_filter>` is ``true``) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level<class_ProjectSettings_property_rendering/textures/default_filters/anisotropic_filtering_level>`.
 
 .. _class_BaseMaterial3D_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`TextureFilter<enum_BaseMaterial3D_TextureFilter>` **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC** = ``5``
 
-The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level<class_ProjectSettings_property_rendering/textures/default_filters/anisotropic_filtering_level>`.
+The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if :ref:`ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter<class_ProjectSettings_property_rendering/textures/default_filters/use_nearest_mipmap_filter>` is ``true``) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting :ref:`ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level<class_ProjectSettings_property_rendering/textures/default_filters/anisotropic_filtering_level>`.
 
 .. _class_BaseMaterial3D_constant_TEXTURE_FILTER_MAX:
 
@@ -3108,7 +3108,7 @@ If ``true``, enables subsurface scattering transmittance. Only effective if :ref
 - void **set_texture** **(** :ref:`TextureParam<enum_BaseMaterial3D_TextureParam>` param, :ref:`Texture2D<class_Texture2D>` texture **)**
 - :ref:`Texture2D<class_Texture2D>` **get_texture** **(** :ref:`TextureParam<enum_BaseMaterial3D_TextureParam>` param **)** |const|
 
-The texture to use for multiplying the intensity of the subsurface scattering transmitteance intensity. See also :ref:`subsurf_scatter_texture<class_BaseMaterial3D_property_subsurf_scatter_texture>`. Ignored if :ref:`subsurf_scatter_skin_mode<class_BaseMaterial3D_property_subsurf_scatter_skin_mode>` is ``true``.
+The texture to use for multiplying the intensity of the subsurface scattering transmittance intensity. See also :ref:`subsurf_scatter_texture<class_BaseMaterial3D_property_subsurf_scatter_texture>`. Ignored if :ref:`subsurf_scatter_skin_mode<class_BaseMaterial3D_property_subsurf_scatter_skin_mode>` is ``true``.
 
 .. rst-class:: classref-item-separator