[4.3] Cherry-picks for the 4.3 (4.3.1) branch - 1st docs batch

core/io/pck_packer.cpp

@@ -49,12 +49,12 @@ static int _get_pad(int p_alignment, int p_n) {
 }
 
 void PCKPacker::_bind_methods() {
-	ClassDB::bind_method(D_METHOD("pck_start", "pck_name", "alignment", "key", "encrypt_directory"), &PCKPacker::pck_start, DEFVAL(32), DEFVAL("0000000000000000000000000000000000000000000000000000000000000000"), DEFVAL(false));
+	ClassDB::bind_method(D_METHOD("pck_start", "pck_path", "alignment", "key", "encrypt_directory"), &PCKPacker::pck_start, DEFVAL(32), DEFVAL("0000000000000000000000000000000000000000000000000000000000000000"), DEFVAL(false));
 	ClassDB::bind_method(D_METHOD("add_file", "pck_path", "source_path", "encrypt"), &PCKPacker::add_file, DEFVAL(false));
 	ClassDB::bind_method(D_METHOD("flush", "verbose"), &PCKPacker::flush, DEFVAL(false));
 }
 
-Error PCKPacker::pck_start(const String &p_file, int p_alignment, const String &p_key, bool p_encrypt_directory) {
+Error PCKPacker::pck_start(const String &p_pck_path, int p_alignment, const String &p_key, bool p_encrypt_directory) {
 	ERR_FAIL_COND_V_MSG((p_key.is_empty() || !p_key.is_valid_hex_number(false) || p_key.length() != 64), ERR_CANT_CREATE, "Invalid Encryption Key (must be 64 characters long).");
 	ERR_FAIL_COND_V_MSG(p_alignment <= 0, ERR_CANT_CREATE, "Invalid alignment, must be greater then 0.");
 
@@ -85,8 +85,8 @@ Error PCKPacker::pck_start(const String &p_file, int p_alignment, const String &
 	}
 	enc_dir = p_encrypt_directory;
 
-	file = FileAccess::open(p_file, FileAccess::WRITE);
-	ERR_FAIL_COND_V_MSG(file.is_null(), ERR_CANT_CREATE, "Can't open file to write: " + String(p_file) + ".");
+	file = FileAccess::open(p_pck_path, FileAccess::WRITE);
+	ERR_FAIL_COND_V_MSG(file.is_null(), ERR_CANT_CREATE, "Can't open file to write: " + String(p_pck_path) + ".");
 
 	alignment = p_alignment;
 
@@ -108,7 +108,7 @@ Error PCKPacker::pck_start(const String &p_file, int p_alignment, const String &
 	return OK;
 }
 
-Error PCKPacker::add_file(const String &p_file, const String &p_src, bool p_encrypt) {
+Error PCKPacker::add_file(const String &p_pck_path, const String &p_src, bool p_encrypt) {
 	ERR_FAIL_COND_V_MSG(file.is_null(), ERR_INVALID_PARAMETER, "File must be opened before use.");
 
 	Ref<FileAccess> f = FileAccess::open(p_src, FileAccess::READ);
@@ -119,7 +119,7 @@ Error PCKPacker::add_file(const String &p_file, const String &p_src, bool p_encr
 	File pf;
 	// Simplify path here and on every 'files' access so that paths that have extra '/'
 	// symbols in them still match to the MD5 hash for the saved path.
-	pf.path = p_file.simplify_path();
+	pf.path = p_pck_path.simplify_path();
 	pf.src_path = p_src;
 	pf.ofs = ofs;
 	pf.size = f->get_length();

core/io/pck_packer.h

@@ -60,8 +60,8 @@ class PCKPacker : public RefCounted {
 	Vector<File> files;
 
 public:
-	Error pck_start(const String &p_file, int p_alignment = 32, const String &p_key = "0000000000000000000000000000000000000000000000000000000000000000", bool p_encrypt_directory = false);
-	Error add_file(const String &p_file, const String &p_src, bool p_encrypt = false);
+	Error pck_start(const String &p_pck_path, int p_alignment = 32, const String &p_key = "0000000000000000000000000000000000000000000000000000000000000000", bool p_encrypt_directory = false);
+	Error add_file(const String &p_pck_path, const String &p_src, bool p_encrypt = false);
 	Error flush(bool p_verbose = false);
 
 	PCKPacker() {}

doc/classes/@GlobalScope.xml

@@ -370,7 +370,7 @@
 				Returns an "eased" value of [param x] based on an easing function defined with [param curve]. This easing function is based on an exponent. The [param curve] can be any floating-point number, with specific values leading to the following behaviors:
 				[codeblock lang=text]
 				- Lower than -1.0 (exclusive): Ease in-out
-				- 1.0: Linear
+				- -1.0: Linear
 				- Between -1.0 and 0.0 (exclusive): Ease out-in
 				- 0.0: Constant
 				- Between 0.0 to 1.0 (exclusive): Ease out
@@ -2144,49 +2144,49 @@
 			Space key.
 		</constant>
 		<constant name="KEY_EXCLAM" value="33" enum="Key">
-			! key.
+			Exclamation mark ([code]![/code]) key.
 		</constant>
 		<constant name="KEY_QUOTEDBL" value="34" enum="Key">
-			" key.
+			Double quotation mark ([code]"[/code]) key.
 		</constant>
-		<constant name="KEY_NUMBERSIGN" value="35" enum="Key">
-			# key.
+		<constant name="KEY_NUMBERSIGN" value="35" enum="Key" keywords="pound, hash">
+			Number sign or [i]hash[/i] ([code]#[/code]) key.
 		</constant>
 		<constant name="KEY_DOLLAR" value="36" enum="Key">
-			$ key.
+			Dollar sign ([code]$[/code]) key.
 		</constant>
 		<constant name="KEY_PERCENT" value="37" enum="Key">
-			% key.
+			Percent sign ([code]%[/code]) key.
 		</constant>
 		<constant name="KEY_AMPERSAND" value="38" enum="Key">
-			&amp; key.
+			Ampersand ([code]&amp;[/code]) key.
 		</constant>
 		<constant name="KEY_APOSTROPHE" value="39" enum="Key">
-			' key.
+			Apostrophe ([code]'[/code]) key.
 		</constant>
-		<constant name="KEY_PARENLEFT" value="40" enum="Key">
-			( key.
+		<constant name="KEY_PARENLEFT" value="40" enum="Key" keywords="open round bracket">
+			Left parenthesis ([code]([/code]) key.
 		</constant>
-		<constant name="KEY_PARENRIGHT" value="41" enum="Key">
-			) key.
+		<constant name="KEY_PARENRIGHT" value="41" enum="Key" keywords="close round bracket">
+			Right parenthesis ([code])[/code]) key.
 		</constant>
 		<constant name="KEY_ASTERISK" value="42" enum="Key">
-			* key.
+			Asterisk ([code]*[/code]) key.
 		</constant>
 		<constant name="KEY_PLUS" value="43" enum="Key">
-			+ key.
+			Plus ([code]+[/code]) key.
 		</constant>
 		<constant name="KEY_COMMA" value="44" enum="Key">
-			, key.
+			Comma ([code],[/code]) key.
 		</constant>
-		<constant name="KEY_MINUS" value="45" enum="Key">
-			- key.
+		<constant name="KEY_MINUS" value="45" enum="Key" keywords="hyphen">
+			Minus ([code]-[/code]) key.
 		</constant>
-		<constant name="KEY_PERIOD" value="46" enum="Key">
-			. key.
+		<constant name="KEY_PERIOD" value="46" enum="Key" keywords="dot">
+			Period ([code].[/code]) key.
 		</constant>
 		<constant name="KEY_SLASH" value="47" enum="Key">
-			/ key.
+			Slash ([code]/[/code]) key.
 		</constant>
 		<constant name="KEY_0" value="48" enum="Key">
 			Number 0 key.
@@ -2219,25 +2219,25 @@
 			Number 9 key.
 		</constant>
 		<constant name="KEY_COLON" value="58" enum="Key">
-			: key.
+			Colon ([code]:[/code]) key.
 		</constant>
 		<constant name="KEY_SEMICOLON" value="59" enum="Key">
-			; key.
+			Semicolon ([code];[/code]) key.
 		</constant>
 		<constant name="KEY_LESS" value="60" enum="Key">
-			&lt; key.
+			Less-than sign ([code]&lt;[/code]) key.
 		</constant>
 		<constant name="KEY_EQUAL" value="61" enum="Key">
-			= key.
+			Equal sign ([code]=[/code]) key.
 		</constant>
 		<constant name="KEY_GREATER" value="62" enum="Key">
-			&gt; key.
+			Greater-than sign ([code]&gt;[/code]) key.
 		</constant>
 		<constant name="KEY_QUESTION" value="63" enum="Key">
-			? key.
+			Question mark ([code]?[/code]) key.
 		</constant>
-		<constant name="KEY_AT" value="64" enum="Key">
-			@ key.
+		<constant name="KEY_AT" value="64" enum="Key" keywords="commercial at">
+			At sign ([code]@[/code]) key.
 		</constant>
 		<constant name="KEY_A" value="65" enum="Key">
 			A key.
@@ -2317,41 +2317,41 @@
 		<constant name="KEY_Z" value="90" enum="Key">
 			Z key.
 		</constant>
-		<constant name="KEY_BRACKETLEFT" value="91" enum="Key">
-			[ key.
+		<constant name="KEY_BRACKETLEFT" value="91" enum="Key" keywords="open square bracket">
+			Left bracket ([code][lb][/code]) key.
 		</constant>
 		<constant name="KEY_BACKSLASH" value="92" enum="Key">
-			\ key.
+			Backslash ([code]\[/code]) key.
 		</constant>
-		<constant name="KEY_BRACKETRIGHT" value="93" enum="Key">
-			] key.
+		<constant name="KEY_BRACKETRIGHT" value="93" enum="Key" keywords="close square bracket">
+			Right bracket ([code][rb][/code]) key.
 		</constant>
-		<constant name="KEY_ASCIICIRCUM" value="94" enum="Key">
-			^ key.
+		<constant name="KEY_ASCIICIRCUM" value="94" enum="Key" keywords="caret">
+			Caret ([code]^[/code]) key.
 		</constant>
-		<constant name="KEY_UNDERSCORE" value="95" enum="Key">
-			_ key.
+		<constant name="KEY_UNDERSCORE" value="95" enum="Key" keywords="underline">
+			Underscore ([code]_[/code]) key.
 		</constant>
-		<constant name="KEY_QUOTELEFT" value="96" enum="Key">
-			` key.
+		<constant name="KEY_QUOTELEFT" value="96" enum="Key" keywords="backtick, backquote">
+			Backtick ([code]`[/code]) key.
 		</constant>
-		<constant name="KEY_BRACELEFT" value="123" enum="Key">
-			{ key.
+		<constant name="KEY_BRACELEFT" value="123" enum="Key" keywords="open curly bracket">
+			Left brace ([code]{[/code]) key.
 		</constant>
-		<constant name="KEY_BAR" value="124" enum="Key">
-			| key.
+		<constant name="KEY_BAR" value="124" enum="Key" keywords="pipe">
+			Vertical bar or [i]pipe[/i] ([code]|[/code]) key.
 		</constant>
-		<constant name="KEY_BRACERIGHT" value="125" enum="Key">
-			} key.
+		<constant name="KEY_BRACERIGHT" value="125" enum="Key" keywords="close curly bracket">
+			Right brace ([code]}[/code]) key.
 		</constant>
 		<constant name="KEY_ASCIITILDE" value="126" enum="Key">
-			~ key.
+			Tilde ([code]~[/code]) key.
 		</constant>
 		<constant name="KEY_YEN" value="165" enum="Key">
-			¥ key.
+			Yen symbol ([code]¥[/code]) key.
 		</constant>
-		<constant name="KEY_SECTION" value="167" enum="Key">
-			§ key.
+		<constant name="KEY_SECTION" value="167" enum="Key" keywords="silcrow">
+			Section sign ([code]§[/code]) key.
 		</constant>
 		<constant name="KEY_CODE_MASK" value="8388607" enum="KeyModifierMask" is_bitfield="true">
 			Key Code mask.
@@ -2972,7 +2972,7 @@
 			Editing the property prompts the user for restarting the editor.
 		</constant>
 		<constant name="PROPERTY_USAGE_SCRIPT_VARIABLE" value="4096" enum="PropertyUsageFlags" is_bitfield="true">
-			The property is a script variable which should be serialized and saved in the scene file.
+			The property is a script variable. [constant PROPERTY_USAGE_SCRIPT_VARIABLE] can be used to distinguish between exported script variables from built-in variables (which don't have this usage flag). By default, [constant PROPERTY_USAGE_SCRIPT_VARIABLE] is [b]not[/b] applied to variables that are created by overriding [method Object._get_property_list] in a script.
 		</constant>
 		<constant name="PROPERTY_USAGE_STORE_IF_NULL" value="8192" enum="PropertyUsageFlags" is_bitfield="true">
 			The property value of type [Object] will be stored even if its value is [code]null[/code].

doc/classes/AABB.xml

@@ -345,14 +345,14 @@
 	</methods>
 	<members>
 		<member name="end" type="Vector3" setter="" getter="" default="Vector3(0, 0, 0)">
-			The ending point. This is usually the corner on the top-right and forward of the bounding box, and is equivalent to [code]position + size[/code]. Setting this point affects the [member size].
+			The ending point. This is usually the corner on the top-right and back of the bounding box, and is equivalent to [code]position + size[/code]. Setting this point affects the [member size].
 		</member>
 		<member name="position" type="Vector3" setter="" getter="" default="Vector3(0, 0, 0)">
-			The origin point. This is usually the corner on the bottom-left and back of the bounding box.
+			The origin point. This is usually the corner on the bottom-left and forward of the bounding box.
 		</member>
 		<member name="size" type="Vector3" setter="" getter="" default="Vector3(0, 0, 0)">
 			The bounding box's width, height, and depth starting from [member position]. Setting this value also affects the [member end] point.
-			[b]Note:[/b] It's recommended setting the width, height, and depth to non-negative values. This is because most methods in Redot assume that the [member position] is the bottom-left-back corner, and the [member end] is the top-right-forward corner. To get an equivalent bounding box with non-negative size, use [method abs].
+			[b]Note:[/b] It's recommended setting the width, height, and depth to non-negative values. This is because most methods in Redot assume that the [member position] is the bottom-left-forward corner, and the [member end] is the top-right-back corner. To get an equivalent bounding box with non-negative size, use [method abs].
 		</member>
 	</members>
 	<operators>

doc/classes/AStar2D.xml

@@ -276,7 +276,7 @@
 			<return type="void" />
 			<param index="0" name="num_nodes" type="int" />
 			<description>
-				Reserves space internally for [param num_nodes] points, useful if you're adding a known large number of points at once, such as points on a grid. New capacity must be greater or equals to old capacity.
+				Reserves space internally for [param num_nodes] points. Useful if you're adding a known large number of points at once, such as points on a grid. The new capacity must be greater or equal to the old capacity.
 			</description>
 		</method>
 		<method name="set_point_disabled">

doc/classes/AStar3D.xml

@@ -6,29 +6,42 @@
 	<description>
 		A* (A star) is a computer algorithm used in pathfinding and graph traversal, the process of plotting short paths among vertices (points), passing through a given set of edges (segments). It enjoys widespread use due to its performance and accuracy. Redot's A* implementation uses points in 3D space and Euclidean distances by default.
 		You must add points manually with [method add_point] and create segments manually with [method connect_points]. Once done, you can test if there is a path between two points with the [method are_points_connected] function, get a path containing indices by [method get_id_path], or one containing actual coordinates with [method get_point_path].
-		It is also possible to use non-Euclidean distances. To do so, create a class that extends [AStar3D] and override methods [method _compute_cost] and [method _estimate_cost]. Both take two indices and return a length, as is shown in the following example.
+		It is also possible to use non-Euclidean distances. To do so, create a script that extends [AStar3D] and override the methods [method _compute_cost] and [method _estimate_cost]. Both should take two point IDs and return the distance between the corresponding points.
+		[b]Example:[/b] Use Manhattan distance instead of Euclidean distance:
 		[codeblocks]
 		[gdscript]
-		class MyAStar:
-		    extends AStar3D
+		class_name MyAStar3D
+		extends AStar3D
 
-		    func _compute_cost(u, v):
-		        return abs(u - v)
+		func _compute_cost(u, v):
+		    var u_pos = get_point_position(u)
+		    var v_pos = get_point_position(v)
+		    return abs(u_pos.x - v_pos.x) + abs(u_pos.y - v_pos.y) + abs(u_pos.z - v_pos.z)
 
-		    func _estimate_cost(u, v):
-		        return min(0, abs(u - v) - 1)
+		func _estimate_cost(u, v):
+		    var u_pos = get_point_position(u)
+		    var v_pos = get_point_position(v)
+		    return abs(u_pos.x - v_pos.x) + abs(u_pos.y - v_pos.y) + abs(u_pos.z - v_pos.z)
 		[/gdscript]
 		[csharp]
-		public partial class MyAStar : AStar3D
+		using Godot;
+
+		[GlobalClass]
+		public partial class MyAStar3D : AStar3D
 		{
 		    public override float _ComputeCost(long fromId, long toId)
 		    {
-		        return Mathf.Abs((int)(fromId - toId));
+		        Vector3 fromPoint = GetPointPosition(fromId);
+		        Vector3 toPoint = GetPointPosition(toId);
+
+		        return Mathf.Abs(fromPoint.X - toPoint.X) + Mathf.Abs(fromPoint.Y - toPoint.Y) + Mathf.Abs(fromPoint.Z - toPoint.Z);
 		    }
 
 		    public override float _EstimateCost(long fromId, long toId)
 		    {
-		        return Mathf.Min(0, Mathf.Abs((int)(fromId - toId)) - 1);
+		        Vector3 fromPoint = GetPointPosition(fromId);
+		        Vector3 toPoint = GetPointPosition(toId);
+		        return Mathf.Abs(fromPoint.X - toPoint.X) + Mathf.Abs(fromPoint.Y - toPoint.Y) + Mathf.Abs(fromPoint.Z - toPoint.Z);
 		    }
 		}
 		[/csharp]

doc/classes/ArrayMesh.xml

@@ -72,7 +72,7 @@
 				The [param arrays] argument is an array of arrays. Each of the [constant Mesh.ARRAY_MAX] elements contains an array with some of the mesh data for this surface as described by the corresponding member of [enum Mesh.ArrayType] or [code]null[/code] if it is not used by the surface. For example, [code]arrays[0][/code] is the array of vertices. That first vertex sub-array is always required; the others are optional. Adding an index array puts this surface into "index mode" where the vertex and other arrays become the sources of data and the index array defines the vertex order. All sub-arrays must have the same length as the vertex array (or be an exact multiple of the vertex array's length, when multiple elements of a sub-array correspond to a single vertex) or be empty, except for [constant Mesh.ARRAY_INDEX] if it is used.
 				The [param blend_shapes] argument is an array of vertex data for each blend shape. Each element is an array of the same structure as [param arrays], but [constant Mesh.ARRAY_VERTEX], [constant Mesh.ARRAY_NORMAL], and [constant Mesh.ARRAY_TANGENT] are set if and only if they are set in [param arrays] and all other entries are [code]null[/code].
 				The [param lods] argument is a dictionary with [float] keys and [PackedInt32Array] values. Each entry in the dictionary represents an LOD level of the surface, where the value is the [constant Mesh.ARRAY_INDEX] array to use for the LOD level and the key is roughly proportional to the distance at which the LOD stats being used. I.e., increasing the key of an LOD also increases the distance that the objects has to be from the camera before the LOD is used.
-				The [param flags] argument is the bitwise or of, as required: One value of [enum Mesh.ArrayCustomFormat] left shifted by [code]ARRAY_FORMAT_CUSTOMn_SHIFT[/code] for each custom channel in use, [constant Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE], [constant Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS], or [constant Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY].
+				The [param flags] argument is the bitwise OR of, as required: One value of [enum Mesh.ArrayCustomFormat] left shifted by [code]ARRAY_FORMAT_CUSTOMn_SHIFT[/code] for each custom channel in use, [constant Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE], [constant Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS], or [constant Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY].
 				[b]Note:[/b] When using indices, it is recommended to only use points, lines, or triangles.
 			</description>
 		</method>

doc/classes/BaseButton.xml

@@ -57,7 +57,7 @@
 		</member>
 		<member name="button_pressed" type="bool" setter="set_pressed" getter="is_pressed" default="false">
 			If [code]true[/code], the button's state is pressed. Means the button is pressed down or toggled (if [member toggle_mode] is active). Only works if [member toggle_mode] is [code]true[/code].
-			[b]Note:[/b] Setting [member button_pressed] will result in [signal toggled] to be emitted. If you want to change the pressed state without emitting that signal, use [method set_pressed_no_signal].
+			[b]Note:[/b] Changing the value of [member button_pressed] will result in [signal toggled] to be emitted. If you want to change the pressed state without emitting that signal, use [method set_pressed_no_signal].
 		</member>
 		<member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false" keywords="enabled">
 			If [code]true[/code], the button is in disabled state and can't be clicked or toggled.