Merge pull request #65045 from akien-mga/3.5-cherrypicks

core/error_macros.h

@@ -518,8 +518,6 @@ void _err_flush_stdout();
 	} else                                                                                                                                                        \
 		((void)0)
 
-#endif
-
 /**
  * This should be a 'free' assert for program flow and should not be needed in any releases,
  *  only used in dev builds.
@@ -558,5 +556,6 @@ void _err_flush_stdout();
 		((void)0)
 #else
 #define DEV_CHECK_ONCE(m_cond)
+#endif
 
 #endif // ERROR_MACROS_H

core/io/resource_loader.cpp

@@ -724,6 +724,8 @@ String ResourceLoader::_path_remap(const String &p_path, bool *r_translation_rem
 		// We also fall back in case of regional locales as done in TranslationServer::translate
 		// (e.g. 'ru_RU' -> 'ru' if the former has no specific mapping).
 
+		// An extra remap may still be necessary afterwards due to the text -> binary converter on export.
+
 		String locale = TranslationServer::get_singleton()->get_locale();
 		ERR_FAIL_COND_V_MSG(locale.length() < 2, p_path, "Could not remap path '" + p_path + "' for translation as configured locale '" + locale + "' is invalid.");
 		String lang = TranslationServer::get_language_code(locale);
@@ -763,12 +765,10 @@ String ResourceLoader::_path_remap(const String &p_path, bool *r_translation_rem
 
 	if (path_remaps.has(new_path)) {
 		new_path = path_remaps[new_path];
-	}
-
-	if (new_path == p_path) { // Did not remap.
+	} else {
 		// Try file remap.
 		Error err;
-		FileAccess *f = FileAccess::open(p_path + ".remap", FileAccess::READ, &err);
+		FileAccess *f = FileAccess::open(new_path + ".remap", FileAccess::READ, &err);
 
 		if (f) {
 			VariantParser::StreamFile stream;

core/project_settings.cpp

@@ -358,6 +358,15 @@ void ProjectSettings::_convert_to_last_version(int p_from_version) {
  *    If nothing was found, error out.
  */
 Error ProjectSettings::_setup(const String &p_path, const String &p_main_pack, bool p_upwards, bool p_ignore_override) {
+	if (OS::get_singleton()->get_resource_dir() != "") {
+		// OS will call ProjectSettings->get_resource_path which will be empty if not overridden!
+		// If the OS would rather use a specific location, then it will not be empty.
+		resource_path = OS::get_singleton()->get_resource_dir().replace("\\", "/");
+		if (resource_path != "" && resource_path[resource_path.length() - 1] == '/') {
+			resource_path = resource_path.substr(0, resource_path.length() - 1); // Chop end.
+		}
+	}
+
 	// If looking for files in a network client, use it directly
 
 	if (FileAccessNetworkClient::get_singleton()) {
@@ -439,13 +448,6 @@ Error ProjectSettings::_setup(const String &p_path, const String &p_main_pack, b
 	// (Only Android -when reading from pck- and iOS use this.)
 
 	if (OS::get_singleton()->get_resource_dir() != "") {
-		// OS will call ProjectSettings->get_resource_path which will be empty if not overridden!
-		// If the OS would rather use a specific location, then it will not be empty.
-		resource_path = OS::get_singleton()->get_resource_dir().replace("\\", "/");
-		if (resource_path != "" && resource_path[resource_path.length() - 1] == '/') {
-			resource_path = resource_path.substr(0, resource_path.length() - 1); // Chop end.
-		}
-
 		Error err = _load_settings_text_or_binary("res://project.godot", "res://project.binary");
 		if (err == OK && !p_ignore_override) {
 			// Optional, we don't mind if it fails.

doc/classes/AnimationNode.xml

@@ -57,20 +57,20 @@
 		<method name="get_caption" qualifiers="virtual">
 			<return type="String" />
 			<description>
-				Gets the text caption for this node (used by some editors).
+				When inheriting from [AnimationRootNode], implement this virtual method to override the text caption for this node.
 			</description>
 		</method>
 		<method name="get_child_by_name" qualifiers="virtual">
 			<return type="Object" />
 			<argument index="0" name="name" type="String" />
 			<description>
-				Gets a child node by index (used by editors inheriting from [AnimationRootNode]).
+				When inheriting from [AnimationRootNode], implement this virtual method to return a child node by its [code]name[/code].
 			</description>
 		</method>
 		<method name="get_child_nodes" qualifiers="virtual">
 			<return type="Dictionary" />
 			<description>
-				Gets all children nodes in order as a [code]name: node[/code] dictionary. Only useful when inheriting [AnimationRootNode].
+				When inheriting from [AnimationRootNode], implement this virtual method to return all children nodes in order as a [code]name: node[/code] dictionary.
 			</description>
 		</method>
 		<method name="get_input_count" qualifiers="const">
@@ -97,19 +97,19 @@
 			<return type="Variant" />
 			<argument index="0" name="name" type="String" />
 			<description>
-				Gets the default value of a parameter. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees.
+				When inheriting from [AnimationRootNode], implement this virtual method to return the default value of parameter "[code]name[/code]". Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees.
 			</description>
 		</method>
 		<method name="get_parameter_list" qualifiers="virtual">
 			<return type="Array" />
 			<description>
-				Gets the property information for parameter. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees. Format is similar to [method Object.get_property_list].
+				When inheriting from [AnimationRootNode], implement this virtual method to return a list of the properties on this node. Parameters are custom local memory used for your nodes, given a resource can be reused in multiple trees. Format is similar to [method Object.get_property_list].
 			</description>
 		</method>
 		<method name="has_filter" qualifiers="virtual">
-			<return type="String" />
+			<return type="bool" />
 			<description>
-				Returns [code]true[/code] whether you want the blend tree editor to display filter editing on this node.
+				When inheriting from [AnimationRootNode], implement this virtual method to return whether the blend tree editor should display filter editing on this node.
 			</description>
 		</method>
 		<method name="is_path_filtered" qualifiers="const">
@@ -124,7 +124,7 @@
 			<argument index="0" name="time" type="float" />
 			<argument index="1" name="seek" type="bool" />
 			<description>
-				User-defined callback called when a custom node is processed. The [code]time[/code] parameter is a relative delta, unless [code]seek[/code] is [code]true[/code], in which case it is absolute.
+				When inheriting from [AnimationRootNode], implement this virtual method to run some code when this node is processed. The [code]time[/code] parameter is a relative delta, unless [code]seek[/code] is [code]true[/code], in which case it is absolute.
 				Here, call the [method blend_input], [method blend_node] or [method blend_animation] functions. You can also use [method get_parameter] and [method set_parameter] to modify local memory.
 				This function should return the time left for the current animation to finish (if unsure, pass the value from the main blend being called).
 			</description>

doc/classes/AnimationNodeStateMachineTransition.xml

@@ -11,7 +11,7 @@
 	</methods>
 	<members>
 		<member name="advance_condition" type="String" setter="set_advance_condition" getter="get_advance_condition" default="&quot;&quot;">
-			Turn on auto advance when this condition is set. The provided name will become a boolean parameter on the [AnimationTree] that can be controlled from code (see [url=$DOCS_URL/tutorials/animation/animation_tree.html#controlling-from-code][/url]). For example, if [member AnimationTree.tree_root] is an [AnimationNodeStateMachine] and [member advance_condition] is set to [code]"idle"[/code]:
+			Turn on auto advance when this condition is set. The provided name will become a boolean parameter on the [AnimationTree] that can be controlled from code (see [url=$DOCS_URL/tutorials/animation/animation_tree.html#controlling-from-code]Using AnimationTree[/url]). For example, if [member AnimationTree.tree_root] is an [AnimationNodeStateMachine] and [member advance_condition] is set to [code]"idle"[/code]:
 			[codeblock]
 			$animation_tree["parameters/conditions/idle"] = is_on_floor and (linear_velocity.x == 0)
 			[/codeblock]

doc/classes/AnimationPlayer.xml

@@ -67,7 +67,7 @@
 			<return type="Animation" />
 			<argument index="0" name="name" type="String" />
 			<description>
-				Returns the [Animation] with key [code]name[/code] or [code]null[/code] if not found.
+				Returns the [Animation] with the key [code]name[/code]. If the animation does not exist, [code]null[/code] is returned and an error is logged.
 			</description>
 		</method>
 		<method name="get_animation_list" qualifiers="const">

doc/classes/AudioStreamPlayer2D.xml

@@ -4,7 +4,8 @@
 		Plays positional sound in 2D space.
 	</brief_description>
 	<description>
-		Plays audio that dampens with distance from screen center.
+		Plays audio that dampens with distance from a given position.
+		By default, audio is heard from the screen center. This can be changed by adding a [Listener2D] node to the scene and enabling it by calling [method Listener2D.make_current] on it.
 		See also [AudioStreamPlayer] to play a sound non-positionally.
 		[b]Note:[/b] Hiding an [AudioStreamPlayer2D] node does not disable its audio output. To temporarily disable an [AudioStreamPlayer2D]'s audio output, set [member volume_db] to a very low value like [code]-100[/code] (which isn't audible to human hearing).
 	</description>

doc/classes/Camera.xml

@@ -179,7 +179,7 @@
 			The camera's projection mode. In [constant PROJECTION_PERSPECTIVE] mode, objects' Z distance from the camera's local space scales their perceived size.
 		</member>
 		<member name="size" type="float" setter="set_size" getter="get_size" default="1.0">
-			The camera's size measured as 1/2 the width or height. Only applicable in orthogonal and frustum modes. Since [member keep_aspect] locks on axis, [code]size[/code] sets the other axis' size length.
+			The camera's size in meters measured as the diameter of the width or height, depending on [member keep_aspect]. Only applicable in orthogonal and frustum modes.
 		</member>
 		<member name="v_offset" type="float" setter="set_v_offset" getter="get_v_offset" default="0.0">
 			The vertical (Y) offset of the camera viewport.

doc/classes/CanvasItem.xml

@@ -5,7 +5,7 @@
 	</brief_description>
 	<description>
 		Base class of anything 2D. Canvas items are laid out in a tree; children inherit and extend their parent's transform. [CanvasItem] is extended by [Control] for anything GUI-related, and by [Node2D] for anything related to the 2D engine.
-		Any [CanvasItem] can draw. For this, [method update] must be called, then [constant NOTIFICATION_DRAW] will be received on idle time to request redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the [CanvasItem] are provided (see [code]draw_*[/code] functions). However, they can only be used inside the [method Object._notification], signal or [method _draw] virtual functions.
+		Any [CanvasItem] can draw. For this, [method update] is called by the engine, then [constant NOTIFICATION_DRAW] will be received on idle time to request redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the [CanvasItem] are provided (see [code]draw_*[/code] functions). However, they can only be used inside [method _draw], its corresponding [method Object._notification] or methods connected to the [signal draw] signal.
 		Canvas items are drawn in tree order. By default, children are on top of their parents so a root [CanvasItem] will be drawn behind everything. This behavior can be changed on a per-item basis.
 		A [CanvasItem] can also be hidden, which will also hide its children. It provides many ways to change parameters such as modulation (for itself and its children) and self modulation (only for itself), as well as its blend mode.
 		Ultimately, a transform notification can be requested, which will notify the node that its global position changed in case the parent tree changed.
@@ -20,7 +20,8 @@
 		<method name="_draw" qualifiers="virtual">
 			<return type="void" />
 			<description>
-				Overridable function called by the engine (if defined) to draw the canvas item.
+				Called when [CanvasItem] has been requested to redraw (when [method update] is called, either manually or by the engine).
+				Corresponds to the [constant NOTIFICATION_DRAW] notification in [method Object._notification].
 			</description>
 		</method>
 		<method name="draw_arc">
@@ -366,7 +367,7 @@
 		<method name="is_visible_in_tree" qualifiers="const">
 			<return type="bool" />
 			<description>
-				Returns [code]true[/code] if the node is present in the [SceneTree], its [member visible] property is [code]true[/code] and all its antecedents are also visible. If any antecedent is hidden, this node will not be visible in the scene tree.
+				Returns [code]true[/code] if the node is present in the [SceneTree], its [member visible] property is [code]true[/code] and all its antecedents are also visible. If any antecedent is hidden, this node will not be visible in the scene tree, and is consequently not drawn (see [method _draw]).
 			</description>
 		</method>
 		<method name="make_canvas_position_local" qualifiers="const">
@@ -413,7 +414,7 @@
 		<method name="update">
 			<return type="void" />
 			<description>
-				Queue the [CanvasItem] for update. [constant NOTIFICATION_DRAW] will be called on idle time to request redraw.
+				Queues the [CanvasItem] to redraw. During idle time, if [CanvasItem] is visible, [constant NOTIFICATION_DRAW] is sent and [method _draw] is called. This only occurs [b]once[/b] per frame, even if this method has been called multiple times.
 			</description>
 		</method>
 	</methods>
@@ -447,7 +448,8 @@
 	<signals>
 		<signal name="draw">
 			<description>
-				Emitted when the [CanvasItem] must redraw. This can only be connected realtime, as deferred will not allow drawing.
+				Emitted when the [CanvasItem] must redraw, [i]after[/i] the related [constant NOTIFICATION_DRAW] notification, and [i]before[/i] [method _draw] is called.
+				[b]Note:[/b] Deferred connections do not allow drawing through the [code]draw_*[/code] methods.
 			</description>
 		</signal>
 		<signal name="hide">
@@ -492,7 +494,7 @@
 			The [CanvasItem]'s local transform has changed. This notification is only received if enabled by [method set_notify_local_transform].
 		</constant>
 		<constant name="NOTIFICATION_DRAW" value="30">
-			The [CanvasItem] is requested to draw.
+			The [CanvasItem] is requested to draw (see [method _draw]).
 		</constant>
 		<constant name="NOTIFICATION_VISIBILITY_CHANGED" value="31">
 			The [CanvasItem]'s visibility has changed.

doc/classes/Curve2D.xml

@@ -15,10 +15,10 @@
 			<argument index="0" name="position" type="Vector2" />
 			<argument index="1" name="in" type="Vector2" default="Vector2( 0, 0 )" />
 			<argument index="2" name="out" type="Vector2" default="Vector2( 0, 0 )" />
-			<argument index="3" name="at_position" type="int" default="-1" />
+			<argument index="3" name="index" type="int" default="-1" />
 			<description>
-				Adds a point to a curve at [code]position[/code] relative to the [Curve2D]'s position, with control points [code]in[/code] and [code]out[/code].
-				If [code]at_position[/code] is given, the point is inserted before the point number [code]at_position[/code], moving that point (and every point after) after the inserted point. If [code]at_position[/code] is not given, or is an illegal value ([code]at_position &lt;0[/code] or [code]at_position &gt;= [method get_point_count][/code]), the point will be appended at the end of the point list.
+				Adds a point with the specified [code]position[/code] relative to the curve's own position, with control points [code]in[/code] and [code]out[/code]. Appends the new point at the end of the point list.
+				If [code]index[/code] is given, the new point is inserted before the existing point identified by index [code]index[/code]. Every existing point starting from [code]index[/code] is shifted further down the list of points. The index must be greater than or equal to [code]0[/code] and must not exceed the number of existing points in the line. See [method get_point_count].
 			</description>
 		</method>
 		<method name="clear_points">

doc/classes/Curve3D.xml

@@ -15,10 +15,10 @@
 			<argument index="0" name="position" type="Vector3" />
 			<argument index="1" name="in" type="Vector3" default="Vector3( 0, 0, 0 )" />
 			<argument index="2" name="out" type="Vector3" default="Vector3( 0, 0, 0 )" />
-			<argument index="3" name="at_position" type="int" default="-1" />
+			<argument index="3" name="index" type="int" default="-1" />
 			<description>
-				Adds a point to a curve at [code]position[/code] relative to the [Curve3D]'s position, with control points [code]in[/code] and [code]out[/code].
-				If [code]at_position[/code] is given, the point is inserted before the point number [code]at_position[/code], moving that point (and every point after) after the inserted point. If [code]at_position[/code] is not given, or is an illegal value ([code]at_position &lt;0[/code] or [code]at_position &gt;= [method get_point_count][/code]), the point will be appended at the end of the point list.
+				Adds a point with the specified [code]position[/code] relative to the curve's own position, with control points [code]in[/code] and [code]out[/code]. Appends the new point at the end of the point list.
+				If [code]index[/code] is given, the new point is inserted before the existing point identified by index [code]index[/code]. Every existing point starting from [code]index[/code] is shifted further down the list of points. The index must be greater than or equal to [code]0[/code] and must not exceed the number of existing points in the line. See [method get_point_count].
 			</description>
 		</method>
 		<method name="clear_points">

doc/classes/EditorProperty.xml

@@ -96,6 +96,8 @@
 		<signal name="property_changed">
 			<argument index="0" name="property" type="String" />
 			<argument index="1" name="value" type="Variant" />
+			<argument index="2" name="field" type="String" />
+			<argument index="3" name="changing" type="bool" />
 			<description>
 				Do not emit this manually, use the [method emit_changed] method instead.
 			</description>

doc/classes/Font.xml

@@ -35,6 +35,7 @@
 			<argument index="5" name="outline" type="bool" default="false" />
 			<description>
 				Draw character [code]char[/code] into a canvas item using the font at a given position, with [code]modulate[/code] color, and optionally kerning if [code]next[/code] is passed. clipping the width. [code]position[/code] specifies the baseline, not the top. To draw from the top, [i]ascent[/i] must be added to the Y axis. The width used by the character is returned, making this function useful for drawing strings character by character.
+				If [code]outline[/code] is [code]true[/code], the outline of the character is drawn instead of the character itself.
 			</description>
 		</method>
 		<method name="get_ascent" qualifiers="const">