Merge pull request godotengine#87540 from YuriSizov/4.1-cherrypicks

Cherry-picks for the 4.1 branch (future 4.1.4) - 2nd batch

COPYRIGHT.txt

@@ -487,7 +487,7 @@ License: Expat
 
 Files: ./thirdparty/zlib/
 Comment: zlib
-Copyright: 1995-2023, Jean-loup Gailly and Mark Adler
+Copyright: 1995-2024, Jean-loup Gailly and Mark Adler
 License: Zlib
 
 Files: ./thirdparty/zstd/

core/io/image.cpp

@@ -509,6 +509,7 @@ static void _convert(int p_width, int p_height, const uint8_t *p_src, uint8_t *p
 }
 
 void Image::convert(Format p_new_format) {
+	ERR_FAIL_INDEX_MSG(p_new_format, FORMAT_MAX, "The Image format specified (" + itos(p_new_format) + ") is out of range. See Image's Format enum.");
 	if (data.size() == 0) {
 		return;
 	}

doc/classes/Animation.xml

@@ -8,21 +8,23 @@
 		[codeblocks]
 		[gdscript]
 		# This creates an animation that makes the node "Enemy" move to the right by
-		# 100 pixels in 0.5 seconds.
+		# 100 pixels in 2.0 seconds.
 		var animation = Animation.new()
 		var track_index = animation.add_track(Animation.TYPE_VALUE)
 		animation.track_set_path(track_index, "Enemy:position:x")
 		animation.track_insert_key(track_index, 0.0, 0)
-		animation.track_insert_key(track_index, 0.5, 100)
+		animation.track_insert_key(track_index, 2.0, 100)
+		animation.length = 2.0
 		[/gdscript]
 		[csharp]
 		// This creates an animation that makes the node "Enemy" move to the right by
-		// 100 pixels in 0.5 seconds.
+		// 100 pixels in 2.0 seconds.
 		var animation = new Animation();
 		int trackIndex = animation.AddTrack(Animation.TrackType.Value);
 		animation.TrackSetPath(trackIndex, "Enemy:position:x");
 		animation.TrackInsertKey(trackIndex, 0.0f, 0);
-		animation.TrackInsertKey(trackIndex, 0.5f, 100);
+		animation.TrackInsertKey(trackIndex, 2.0f, 100);
+		animation.Length = 2.0f;
 		[/csharp]
 		[/codeblocks]
 		Animations are just data containers, and must be added to nodes such as an [AnimationPlayer] to be played back. Animation tracks have different types, each with its own set of dedicated methods. Check [enum TrackType] to see available types.

doc/classes/CollisionPolygon2D.xml

@@ -25,6 +25,7 @@
 		</member>
 		<member name="polygon" type="PackedVector2Array" setter="set_polygon" getter="get_polygon" default="PackedVector2Array()">
 			The polygon's list of vertices. Each point will be connected to the next, and the final point will be connected to the first.
+			[b]Note:[/b] The returned vertices are in the local coordinate space of the given [CollisionPolygon2D].
 			[b]Warning:[/b] The returned value is a clone of the [PackedVector2Array], not a reference.
 		</member>
 	</members>

doc/classes/Image.xml

@@ -18,6 +18,7 @@
 			<param index="1" name="contrast" type="float" />
 			<param index="2" name="saturation" type="float" />
 			<description>
+				Adjusts this image's [param brightness], [param contrast], and [param saturation] by the given values. Does not work if the image is compressed (see [method is_compressed]).
 			</description>
 		</method>
 		<method name="blend_rect">
@@ -162,6 +163,7 @@
 			<return type="int" enum="Image.UsedChannels" />
 			<param index="0" name="source" type="int" enum="Image.CompressSource" default="0" />
 			<description>
+				Returns the color channels used by this image, as one of the [enum UsedChannels] constants. If the image is compressed, the original [param source] must be specified.
 			</description>
 		</method>
 		<method name="fill">
@@ -572,6 +574,7 @@
 			OpenGL texture format [code]RGBA[/code] with four components, each with a bitdepth of 4.
 		</constant>
 		<constant name="FORMAT_RGB565" value="7" enum="Format">
+			OpenGL texture format [code]RGB[/code] with three components. Red and blue have a bitdepth of 5, and green has a bitdepth of 6.
 		</constant>
 		<constant name="FORMAT_RF" value="8" enum="Format">
 			OpenGL texture format [code]GL_R32F[/code] where there's one component, a 32-bit floating-point value.
@@ -656,8 +659,10 @@
 			[b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed.
 		</constant>
 		<constant name="FORMAT_ETC2_RA_AS_RG" value="33" enum="Format">
+			[url=https://en.wikipedia.org/wiki/Ericsson_Texture_Compression#ETC2_and_EAC]Ericsson Texture Compression format 2[/url] ([code]RGBA8[/code] variant), which compresses RA data and interprets it as two channels (red and green). See also [constant FORMAT_ETC2_RGBA8].
 		</constant>
 		<constant name="FORMAT_DXT5_RA_AS_RG" value="34" enum="Format">
+			The [url=https://en.wikipedia.org/wiki/S3_Texture_Compression]S3TC[/url] texture format also known as Block Compression 3 or BC3, which compresses RA data and interprets it as two channels (red and green). See also [constant FORMAT_DXT5].
 		</constant>
 		<constant name="FORMAT_ASTC_4x4" value="35" enum="Format">
 			[url=https://en.wikipedia.org/wiki/Adaptive_scalable_texture_compression]Adaptive Scalable Texutre Compression[/url]. This implements the 4x4 (high quality) mode.
@@ -721,16 +726,22 @@
 			Represents the size of the [enum CompressMode] enum.
 		</constant>
 		<constant name="USED_CHANNELS_L" value="0" enum="UsedChannels">
+			The image only uses one channel for luminance (grayscale).
 		</constant>
 		<constant name="USED_CHANNELS_LA" value="1" enum="UsedChannels">
+			The image uses two channels for luminance and alpha, respectively.
 		</constant>
 		<constant name="USED_CHANNELS_R" value="2" enum="UsedChannels">
+			The image only uses the red channel.
 		</constant>
 		<constant name="USED_CHANNELS_RG" value="3" enum="UsedChannels">
+			The image uses two channels for red and green.
 		</constant>
 		<constant name="USED_CHANNELS_RGB" value="4" enum="UsedChannels">
+			The image uses three channels for red, green, and blue.
 		</constant>
 		<constant name="USED_CHANNELS_RGBA" value="5" enum="UsedChannels">
+			The image uses four channels for red, green, blue, and alpha.
 		</constant>
 		<constant name="COMPRESS_SOURCE_GENERIC" value="0" enum="CompressSource">
 			Source texture (before compression) is a regular texture. Default for all textures.

doc/classes/PackedByteArray.xml

@@ -174,6 +174,7 @@
 			<param index="1" name="compression_mode" type="int" default="0" />
 			<description>
 				Returns a new [PackedByteArray] with the data decompressed. Set [param buffer_size] to the size of the uncompressed data. Set the compression mode using one of [enum FileAccess.CompressionMode]'s constants.
+				[b]Note:[/b] Decompression is not guaranteed to work with data not compressed by Godot, for example if data compressed with the deflate compression mode lacks a checksum or header.
 			</description>
 		</method>
 		<method name="decompress_dynamic" qualifiers="const">
@@ -184,6 +185,7 @@
 				Returns a new [PackedByteArray] with the data decompressed. Set the compression mode using one of [enum FileAccess.CompressionMode]'s constants. [b]This method only accepts brotli, gzip, and deflate compression modes.[/b]
 				This method is potentially slower than [code]decompress[/code], as it may have to re-allocate its output buffer multiple times while decompressing, whereas [code]decompress[/code] knows it's output buffer size from the beginning.
 				GZIP has a maximal compression ratio of 1032:1, meaning it's very possible for a small compressed payload to decompress to a potentially very large output. To guard against this, you may provide a maximum size this function is allowed to allocate in bytes via [param max_output_size]. Passing -1 will allow for unbounded output. If any positive value is passed, and the decompression exceeds that amount in bytes, then an error will be returned.
+				[b]Note:[/b] Decompression is not guaranteed to work with data not compressed by Godot, for example if data compressed with the deflate compression mode lacks a checksum or header.
 			</description>
 		</method>
 		<method name="duplicate">

doc/classes/PrimitiveMesh.xml

@@ -12,6 +12,7 @@
 		<method name="_create_mesh_array" qualifiers="virtual const">
 			<return type="Array" />
 			<description>
+				Override this method to customize how this primitive mesh should be generated. Should return an [Array] where each element is another Array of values required for the mesh (see the [enum Mesh.ArrayType] constants).
 			</description>
 		</method>
 		<method name="get_mesh_arrays" qualifiers="const">

doc/classes/ProjectSettings.xml

@@ -774,7 +774,9 @@
 			Main window can't be focused. No-focus window will ignore all input, except mouse clicks.
 		</member>
 		<member name="display/window/size/resizable" type="bool" setter="" getter="" default="true">
-			Allows the window to be resizable by default.
+			If [code]true[/code], allows the window to be resizable by default.
+			[b]Note:[/b] This property is only read when the project starts. To change whether the window is resizable at runtime, set [member Window.unresizable] instead on the root Window, which can be retrieved using [code]get_viewport().get_window()[/code]. [member Window.unresizable] takes the opposite value of this setting.
+			[b]Note:[/b] Certain window managers can be configured to ignore the non-resizable status of a window. Do not rely on this setting as a guarantee that the window will [i]never[/i] be resizable.
 			[b]Note:[/b] This setting is ignored on iOS.
 		</member>
 		<member name="display/window/size/transparent" type="bool" setter="" getter="" default="false">
@@ -2467,6 +2469,7 @@
 			[b]Note:[/b] This setting is only effective when using the Compatibility rendering method, not Forward+ and Mobile.
 		</member>
 		<member name="rendering/limits/spatial_indexer/threaded_cull_minimum_instances" type="int" setter="" getter="" default="1000">
+			The minimum number of instances that must be present in a scene to enable culling computations on multiple threads. If a scene has fewer instances than this number, culling is done on a single thread.
 		</member>
 		<member name="rendering/limits/spatial_indexer/update_iterations_per_frame" type="int" setter="" getter="" default="10">
 		</member>

doc/classes/RayCast2D.xml

@@ -74,7 +74,7 @@
 		<method name="get_collision_point" qualifiers="const">
 			<return type="Vector2" />
 			<description>
-				Returns the collision point at which the ray intersects the closest object.
+				Returns the collision point at which the ray intersects the closest object. If [member hit_from_inside] is [code]true[/code] and the ray starts inside of a collision shape, this function will return the origin point of the ray.
 				[b]Note:[/b] This point is in the [b]global[/b] coordinate system.
 			</description>
 		</method>

doc/classes/RayCast3D.xml

@@ -75,7 +75,7 @@
 		<method name="get_collision_point" qualifiers="const">
 			<return type="Vector3" />
 			<description>
-				Returns the collision point at which the ray intersects the closest object.
+				Returns the collision point at which the ray intersects the closest object. If [member hit_from_inside] is [code]true[/code] and the ray starts inside of a collision shape, this function will return the origin point of the ray.
 				[b]Note:[/b] This point is in the [b]global[/b] coordinate system.
 			</description>
 		</method>

doc/classes/RenderingServer.xml

@@ -918,6 +918,14 @@
 				[b]Note:[/b] When using the OpenGL backend or when running in headless mode, this function always returns [code]null[/code].
 			</description>
 		</method>
+		<method name="debug_canvas_item_get_rect">
+			<return type="Rect2" />
+			<param index="0" name="item" type="RID" />
+			<description>
+				Returns the bounding rectangle for a canvas item in local space, as calculated by the renderer. This bound is used internally for culling.
+				[b]Warning:[/b] This function is intended for debugging in the editor, and will pass through and return a zero [Rect2] in exported projects.
+			</description>
+		</method>
 		<method name="decal_create">
 			<return type="RID" />
 			<description>

doc/classes/RichTextEffect.xml

@@ -4,7 +4,7 @@
 		A custom effect for a [RichTextLabel].
 	</brief_description>
 	<description>
-		A custom effect for a [RichTextLabel].
+		A custom effect for a [RichTextLabel], which can be loaded in the [RichTextLabel] inspector or using [method RichTextLabel.install_effect].
 		[b]Note:[/b] For a [RichTextEffect] to be usable, a BBCode tag must be defined as a member variable called [code]bbcode[/code] in the script.
 		[codeblocks]
 		[gdscript]

doc/classes/RichTextLabel.xml

@@ -218,7 +218,28 @@
 			<return type="void" />
 			<param index="0" name="effect" type="Variant" />
 			<description>
-				Installs a custom effect. [param effect] should be a valid [RichTextEffect].
+				Installs a custom effect. This can also be done in the RichTextLabel inspector using the [member custom_effects] property. [param effect] should be a valid [RichTextEffect].
+				Example RichTextEffect:
+				[codeblock]
+				# effect.gd
+				class_name MyCustomEffect
+				extends RichTextEffect
+
+				var bbcode = "my_custom_effect"
+
+				# ...
+				[/codeblock]
+				Registering the above effect in RichTextLabel from script:
+				[codeblock]
+				# rich_text_label.gd
+				extends RichTextLabel
+
+				func _ready():
+				    install_effect(MyCustomEffect.new())
+
+				    # Alternatively, if not using `class_name` in the script that extends RichTextEffect:
+				    install_effect(preload("res://effect.gd").new())
+				[/codeblock]
 			</description>
 		</method>
 		<method name="is_menu_visible" qualifiers="const">

doc/classes/Skeleton3D.xml

@@ -7,7 +7,6 @@
 		[Skeleton3D] provides an interface for managing a hierarchy of bones, including pose, rest and animation (see [Animation]). It can also use ragdoll physics.
 		The overall transform of a bone with respect to the skeleton is determined by bone pose. Bone rest defines the initial transform of the bone pose.
 		Note that "global pose" below refers to the overall transform of the bone with respect to skeleton, so it is not the actual global/world transform of the bone.
-		To setup different types of inverse kinematics, consider using [SkeletonIK3D], or add a custom IK implementation in [method Node._process] as a child node.
 	</description>
 	<tutorials>
 		<link title="3D Inverse Kinematics Demo">https://godotengine.org/asset-library/asset/523</link>

doc/classes/SoftBody3D.xml

@@ -41,6 +41,7 @@
 		<method name="get_physics_rid" qualifiers="const">
 			<return type="RID" />
 			<description>
+				Returns the internal [RID] used by the [PhysicsServer3D] for this body.
 			</description>
 		</method>
 		<method name="get_point_transform">
@@ -100,11 +101,14 @@
 			[b]Note:[/b] Object A can detect a contact with object B only if object B is in any of the layers that object A scans. See [url=$DOCS_URL/tutorials/physics/physics_introduction.html#collision-layers-and-masks]Collision layers and masks[/url] in the documentation for more information.
 		</member>
 		<member name="damping_coefficient" type="float" setter="set_damping_coefficient" getter="get_damping_coefficient" default="0.01">
+			The body's damping coefficient. Higher values will slow down the body more noticeably when forces are applied.
 		</member>
 		<member name="disable_mode" type="int" setter="set_disable_mode" getter="get_disable_mode" enum="SoftBody3D.DisableMode" default="0">
 			Defines the behavior in physics when [member Node.process_mode] is set to [constant Node.PROCESS_MODE_DISABLED]. See [enum DisableMode] for more details about the different modes.
 		</member>
 		<member name="drag_coefficient" type="float" setter="set_drag_coefficient" getter="get_drag_coefficient" default="0.0">
+			The body's drag coefficient. Higher values increase this body's air resistance.
+			[b]Note:[/b] This value is currently unused by Godot's default physics implementation.
 		</member>
 		<member name="linear_stiffness" type="float" setter="set_linear_stiffness" getter="get_linear_stiffness" default="0.5">
 			Higher values will result in a stiffer body, while lower values will increase the body's ability to bend. The value can be between [code]0.0[/code] and [code]1.0[/code] (inclusive).
@@ -113,6 +117,7 @@
 			[NodePath] to a [CollisionObject3D] this SoftBody3D should avoid clipping.
 		</member>
 		<member name="pressure_coefficient" type="float" setter="set_pressure_coefficient" getter="get_pressure_coefficient" default="0.0">
+			The pressure coefficient of this soft body. Simulate pressure build-up from inside this body. Higher values increase the strength of this effect.
 		</member>
 		<member name="ray_pickable" type="bool" setter="set_ray_pickable" getter="is_ray_pickable" default="true">
 			If [code]true[/code], the [SoftBody3D] will respond to [RayCast3D]s.

doc/classes/String.xml

@@ -96,13 +96,14 @@
 				[gdscript]
 				"move_local_x".capitalize()   # Returns "Move Local X"
 				"sceneFile_path".capitalize() # Returns "Scene File Path"
+				"2D, FPS, PNG".capitalize()   # Returns "2d, Fps, Png"
 				[/gdscript]
 				[csharp]
 				"move_local_x".Capitalize();   // Returns "Move Local X"
 				"sceneFile_path".Capitalize(); // Returns "Scene File Path"
+				"2D, FPS, PNG".Capitalize();   // Returns "2d, Fps, Png"
 				[/csharp]
 				[/codeblocks]
-				[b]Note:[/b] This method not the same as the default appearance of properties in the Inspector dock, as it does not capitalize acronyms ([code]"2D"[/code], [code]"FPS"[/code], [code]"PNG"[/code], etc.) as you may expect.
 			</description>
 		</method>
 		<method name="casecmp_to" qualifiers="const">
@@ -943,7 +944,7 @@
 		<method name="to_lower" qualifiers="const">
 			<return type="String" />
 			<description>
-				Returns the string converted to lowercase.
+				Returns the string converted to [code]lowercase[/code].
 			</description>
 		</method>
 		<method name="to_pascal_case" qualifiers="const">
@@ -956,12 +957,25 @@
 			<return type="String" />
 			<description>
 				Returns the string converted to [code]snake_case[/code].
+				[b]Note:[/b] Numbers followed by a [i]single[/i] letter are not separated in the conversion to keep some words (such as "2D") together.
+				[codeblocks]
+				[gdscript]
+				"Node2D".to_snake_case()               # Returns "node_2d"
+				"2nd place".to_snake_case()            # Returns "2_nd_place"
+				"Texture3DAssetFolder".to_snake_case() # Returns "texture_3d_asset_folder"
+				[/gdscript]
+				[csharp]
+				"Node2D".ToSnakeCase();               // Returns "node_2d"
+				"2nd place".ToSnakeCase();            // Returns "2_nd_place"
+				"Texture3DAssetFolder".ToSnakeCase(); // Returns "texture_3d_asset_folder"
+				[/csharp]
+				[/codeblocks]
 			</description>
 		</method>
 		<method name="to_upper" qualifiers="const">
 			<return type="String" />
 			<description>
-				Returns the string converted to uppercase.
+				Returns the string converted to [code]UPPERCASE[/code].
 			</description>
 		</method>
 		<method name="to_utf8_buffer" qualifiers="const">