[4.3] Cherry-picks for the 4.3 branch - 1st batch

core/math/basis.h

@@ -43,11 +43,11 @@ struct [[nodiscard]] Basis {
 		Vector3(0, 0, 1)
 	};
 
-	_FORCE_INLINE_ const Vector3 &operator[](int p_axis) const {
-		return rows[p_axis];
+	_FORCE_INLINE_ const Vector3 &operator[](int p_row) const {
+		return rows[p_row];
 	}
-	_FORCE_INLINE_ Vector3 &operator[](int p_axis) {
-		return rows[p_axis];
+	_FORCE_INLINE_ Vector3 &operator[](int p_row) {
+		return rows[p_row];
 	}
 
 	void invert();

doc/classes/BackBufferCopy.xml

@@ -8,6 +8,7 @@
 		[b]Note:[/b] Since this node inherits from [Node2D] (and not [Control]), anchors and margins won't apply to child [Control]-derived nodes. This can be problematic when resizing the window. To avoid this, add [Control]-derived nodes as [i]siblings[/i] to the [BackBufferCopy] node instead of adding them as children.
 	</description>
 	<tutorials>
+		<link title="Screen-reading shaders">$DOCS_URL/tutorials/shaders/screen-reading_shaders.html</link>
 	</tutorials>
 	<members>
 		<member name="copy_mode" type="int" setter="set_copy_mode" getter="get_copy_mode" enum="BackBufferCopy.CopyMode" default="1">

doc/classes/EditorDebuggerPlugin.xml

@@ -15,18 +15,20 @@
 
 		class ExampleEditorDebugger extends EditorDebuggerPlugin:
 
-		    func _has_capture(prefix):
-		        # Return true if you wish to handle message with this prefix.
-		        return prefix == "my_plugin"
+		    func _has_capture(capture):
+		        # Return true if you wish to handle messages with the prefix "my_plugin:".
+		        return capture == "my_plugin"
 
 		    func _capture(message, data, session_id):
 		        if message == "my_plugin:ping":
 		            get_session(session_id).send_message("my_plugin:echo", data)
+		            return true
+		        return false
 
 		    func _setup_session(session_id):
 		        # Add a new tab in the debugger session UI containing a label.
 		        var label = Label.new()
-		        label.name = "Example plugin"
+		        label.name = "Example plugin" # Will be used as the tab title.
 		        label.text = "Example plugin"
 		        var session = get_session(session_id)
 		        # Listens to the session started and stopped signals.
@@ -43,6 +45,24 @@
 		    remove_debugger_plugin(debugger)
 		[/gdscript]
 		[/codeblocks]
+		To connect on the running game side, use the [EngineDebugger] singleton:
+		[codeblocks]
+		[gdscript]
+		extends Node
+
+		func _ready():
+		    EngineDebugger.register_message_capture("my_plugin", _capture)
+		    EngineDebugger.send_message("my_plugin:ping", ["test"])
+
+		func _capture(message, data):
+		    # Note that the "my_plugin:" prefix is not used here.
+		    if message == "echo":
+		        prints("Echo received:", data)
+		        return true
+		    return false
+		[/gdscript]
+		[/codeblocks]
+		[b]Note:[/b] While the game is running, [method @GlobalScope.print] and similar functions [i]called in the editor[/i] do not print anything, the Output Log prints only game messages.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -68,7 +88,7 @@
 			<param index="1" name="data" type="Array" />
 			<param index="2" name="session_id" type="int" />
 			<description>
-				Override this method to process incoming messages. The [param session_id] is the ID of the [EditorDebuggerSession] that received the message (which you can retrieve via [method get_session]).
+				Override this method to process incoming messages. The [param session_id] is the ID of the [EditorDebuggerSession] that received the [param message]. Use [method get_session] to retrieve the session. This method should return [code]true[/code] if the message is recognized.
 			</description>
 		</method>
 		<method name="_goto_script_line" qualifiers="virtual">
@@ -90,7 +110,7 @@
 			<return type="void" />
 			<param index="0" name="session_id" type="int" />
 			<description>
-				Override this method to be notified whenever a new [EditorDebuggerSession] is created (the session may be inactive during this stage).
+				Override this method to be notified whenever a new [EditorDebuggerSession] is created. Note that the session may be inactive during this stage.
 			</description>
 		</method>
 		<method name="get_session">

doc/classes/EditorDebuggerSession.xml

@@ -14,7 +14,7 @@
 			<return type="void" />
 			<param index="0" name="control" type="Control" />
 			<description>
-				Adds the given [param control] to the debug session UI in the debugger bottom panel.
+				Adds the given [param control] to the debug session UI in the debugger bottom panel. The [param control]'s node name will be used as the tab title.
 			</description>
 		</method>
 		<method name="is_active">

doc/classes/EditorSettings.xml

@@ -956,7 +956,17 @@
 			If [code]true[/code], on Linux/BSD, the editor will check for Wayland first instead of X11 (if available).
 		</member>
 		<member name="run/window_placement/android_window" type="int" setter="" getter="">
-			The Android window to display the project on when starting the project from the editor.
+			Specifies how the Play window is launched relative to the Android editor.
+			- [b]Auto (based on screen size)[/b] (default) will automatically choose how to launch the Play window based on the device and screen metrics. Defaults to [b]Same as Editor[/b] on phones and [b]Side-by-side with Editor[/b] on tablets.
+			- [b]Same as Editor[/b] will launch the Play window in the same window as the Editor.
+			- [b]Side-by-side with Editor[/b] will launch the Play window side-by-side with the Editor window.
+			[b]Note:[/b] Only available in the Android editor.
+		</member>
+		<member name="run/window_placement/play_window_pip_mode" type="int" setter="" getter="">
+			Specifies the picture-in-picture (PiP) mode for the Play window.
+			- [b]Disabled:[/b] PiP is disabled for the Play window.
+			- [b]Enabled:[/b] If the device supports it, PiP is always enabled for the Play window. The Play window will contain a button to enter PiP mode.
+			- [b]Enabled when Play window is same as Editor[/b] (default for Android editor): If the device supports it, PiP is enabled when the Play window is the same as the Editor. The Play window will contain a button to enter PiP mode.
 			[b]Note:[/b] Only available in the Android editor.
 		</member>
 		<member name="run/window_placement/rect" type="int" setter="" getter="">

doc/classes/EngineDebugger.xml

@@ -113,7 +113,8 @@
 			<param index="1" name="callable" type="Callable" />
 			<description>
 				Registers a message capture with given [param name]. If [param name] is "my_message" then messages starting with "my_message:" will be called with the given callable.
-				Callable must accept a message string and a data array as argument. If the message and data are valid then callable must return [code]true[/code] otherwise [code]false[/code].
+				The callable must accept a message string and a data array as argument. The callable should return [code]true[/code] if the message is recognized.
+				[b]Note:[/b] The callable will receive the message with the prefix stripped, unlike [method EditorDebuggerPlugin._capture]. See the [EditorDebuggerPlugin] description for an example.
 			</description>
 		</method>
 		<method name="register_profiler">

doc/classes/FileDialog.xml

@@ -153,7 +153,7 @@
 		</member>
 		<member name="title" type="String" setter="set_title" getter="get_title" overrides="Window" default="&quot;Save a File&quot;" />
 		<member name="use_native_dialog" type="bool" setter="set_use_native_dialog" getter="get_use_native_dialog" default="false">
-			If [code]true[/code], [member access] is set to [constant ACCESS_FILESYSTEM], and it is supported by the current [DisplayServer], OS native dialog will be used instead of custom one.
+			If [code]true[/code], and if supported by the current [DisplayServer], OS native dialog will be used instead of custom one.
 			[b]Note:[/b] On Linux and macOS, sandboxed apps always use native dialogs to access the host file system.
 			[b]Note:[/b] On macOS, sandboxed apps will save security-scoped bookmarks to retain access to the opened folders across multiple sessions. Use [method OS.get_granted_permissions] to get a list of saved bookmarks.
 			[b]Note:[/b] Native dialogs are isolated from the base process, file dialog properties can't be modified once the dialog is shown.

doc/classes/HTTPRequest.xml

@@ -275,6 +275,7 @@
 			Request successful.
 		</constant>
 		<constant name="RESULT_CHUNKED_BODY_SIZE_MISMATCH" value="1" enum="Result">
+			Request failed due to a mismatch between the expected and actual chunked body size during transfer. Possible causes include network errors, server misconfiguration, or issues with chunked encoding.
 		</constant>
 		<constant name="RESULT_CANT_CONNECT" value="2" enum="Result">
 			Request failed while connecting.
@@ -295,6 +296,7 @@
 			Request exceeded its maximum size limit, see [member body_size_limit].
 		</constant>
 		<constant name="RESULT_BODY_DECOMPRESS_FAILED" value="8" enum="Result">
+			Request failed due to an error while decompressing the response body. Possible causes include unsupported or incorrect compression format, corrupted data, or incomplete transfer.
 		</constant>
 		<constant name="RESULT_REQUEST_FAILED" value="9" enum="Result">
 			Request failed (currently unused).

doc/classes/Node.xml

@@ -73,6 +73,7 @@
 			<description>
 				Called during the physics processing step of the main loop. Physics processing means that the frame rate is synced to the physics, i.e. the [param delta] variable should be constant. [param delta] is in seconds.
 				It is only called if physics processing is enabled, which is done automatically if this method is overridden, and can be toggled with [method set_physics_process].
+				Processing happens in order of [member process_physics_priority], lower priority values are called first. Nodes with the same priority are processed in tree order, or top to bottom as seen in the editor (also known as pre-order traversal).
 				Corresponds to the [constant NOTIFICATION_PHYSICS_PROCESS] notification in [method Object._notification].
 				[b]Note:[/b] This method is only called if the node is present in the scene tree (i.e. if it's not an orphan).
 			</description>
@@ -83,6 +84,7 @@
 			<description>
 				Called during the processing step of the main loop. Processing happens at every frame and as fast as possible, so the [param delta] time since the previous frame is not constant. [param delta] is in seconds.
 				It is only called if processing is enabled, which is done automatically if this method is overridden, and can be toggled with [method set_process].
+				Processing happens in order of [member process_priority], lower priority values are called first. Nodes with the same priority are processed in tree order, or top to bottom as seen in the editor (also known as pre-order traversal).
 				Corresponds to the [constant NOTIFICATION_PROCESS] notification in [method Object._notification].
 				[b]Note:[/b] This method is only called if the node is present in the scene tree (i.e. if it's not an orphan).
 			</description>
@@ -1026,10 +1028,10 @@
 			The node's processing behavior (see [enum ProcessMode]). To check if the node can process in its current mode, use [method can_process].
 		</member>
 		<member name="process_physics_priority" type="int" setter="set_physics_process_priority" getter="get_physics_process_priority" default="0">
-			Similar to [member process_priority] but for [constant NOTIFICATION_PHYSICS_PROCESS], [method _physics_process] or the internal version.
+			Similar to [member process_priority] but for [constant NOTIFICATION_PHYSICS_PROCESS], [method _physics_process], or [constant NOTIFICATION_INTERNAL_PHYSICS_PROCESS].
 		</member>
 		<member name="process_priority" type="int" setter="set_process_priority" getter="get_process_priority" default="0">
-			The node's execution order of the process callbacks ([method _process], [method _physics_process], and internal processing). Nodes whose priority value is [i]lower[/i] call their process callbacks first, regardless of tree order.
+			The node's execution order of the process callbacks ([method _process], [constant NOTIFICATION_PROCESS], and [constant NOTIFICATION_INTERNAL_PROCESS]). Nodes whose priority value is [i]lower[/i] call their process callbacks first, regardless of tree order.
 		</member>
 		<member name="process_thread_group" type="int" setter="set_process_thread_group" getter="get_process_thread_group" enum="Node.ProcessThreadGroup" default="0">
 			Set the process thread group for this node (basically, whether it receives [constant NOTIFICATION_PROCESS], [constant NOTIFICATION_PHYSICS_PROCESS], [method _process] or [method _physics_process] (and the internal versions) on the main thread or in a sub-thread.

doc/classes/ProjectSettings.xml

@@ -10,6 +10,7 @@
 		[b]Overriding:[/b] Any project setting can be overridden by creating a file named [code]override.cfg[/code] in the project's root directory. This can also be used in exported projects by placing this file in the same directory as the project binary. Overriding will still take the base project settings' [url=$DOCS_URL/tutorials/export/feature_tags.html]feature tags[/url] in account. Therefore, make sure to [i]also[/i] override the setting with the desired feature tags if you want them to override base project settings on all platforms and configurations.
 	</description>
 	<tutorials>
+		<link title="Project Settings">$DOCS_URL/tutorials/editor/project_settings.html</link>
 		<link title="3D Physics Tests Demo">https://godotengine.org/asset-library/asset/2747</link>
 		<link title="3D Platformer Demo">https://godotengine.org/asset-library/asset/2748</link>
 		<link title="Operating System Testing Demo">https://godotengine.org/asset-library/asset/2789</link>

doc/classes/String.xml

@@ -6,6 +6,7 @@
 	<description>
 		This is the built-in string Variant type (and the one used by GDScript). Strings may contain any number of Unicode characters, and expose methods useful for manipulating and generating strings. Strings are reference-counted and use a copy-on-write approach (every modification to a string returns a new [String]), so passing them around is cheap in resources.
 		Some string methods have corresponding variations. Variations suffixed with [code]n[/code] ([method countn], [method findn], [method replacen], etc.) are [b]case-insensitive[/b] (they make no distinction between uppercase and lowercase letters). Method variations prefixed with [code]r[/code] ([method rfind], [method rsplit], etc.) are reversed, and start from the end of the string, instead of the beginning.
+		To convert any Variant to or from a string, see [method @GlobalScope.str], [method @GlobalScope.str_to_var], and [method @GlobalScope.var_to_str].
 		[b]Note:[/b] In a boolean context, a string will evaluate to [code]false[/code] if it is empty ([code]""[/code]). Otherwise, a string will always evaluate to [code]true[/code]. The [code]not[/code] operator cannot be used. Instead, [method is_empty] should be used to check for empty strings.
 	</description>
 	<tutorials>

doc/classes/Transform2D.xml

@@ -251,14 +251,14 @@
 		</member>
 		<member name="y" type="Vector2" setter="" getter="" default="Vector2(0, 1)">
 			The transform basis's Y axis, and the column [code]1[/code] of the matrix. Combined with [member x], this represents the transform's rotation, scale, and skew.
-			On the identity transform, this vector points up ([constant Vector2.UP]).
+			On the identity transform, this vector points down ([constant Vector2.DOWN]).
 		</member>
 	</members>
 	<constants>
 		<constant name="IDENTITY" value="Transform2D(1, 0, 0, 1, 0, 0)">
 			The identity [Transform2D]. A transform with no translation, no rotation, and its scale being [code]1[/code]. When multiplied by another [Variant] such as [Rect2] or another [Transform2D], no transformation occurs. This means that:
 			- The [member x] points right ([constant Vector2.RIGHT]);
-			- The [member y] points up ([constant Vector2.UP]).
+			- The [member y] points down ([constant Vector2.DOWN]).
 			[codeblock]
 			var transform = Transform2D.IDENTITY
 			print("| X | Y | Origin")

editor/debugger/script_editor_debugger.cpp

@@ -819,7 +819,7 @@ void ScriptEditorDebugger::_parse_message(const String &p_msg, uint64_t p_thread
 
 		bool parsed = EditorDebuggerNode::get_singleton()->plugins_capture(this, p_msg, p_data);
 		if (!parsed) {
-			WARN_PRINT("unknown message " + p_msg);
+			WARN_PRINT("Unknown message: " + p_msg);
 		}
 	}
 }

editor/editor_file_system.cpp

@@ -1940,7 +1940,7 @@ void EditorFileSystem::_update_scene_groups() {
 		}
 
 		if (ep) {
-			ep->step(TTR("Updating Scene Groups..."), step_count++);
+			ep->step(TTR("Updating Scene Groups..."), step_count++, false);
 		}
 	}
 
@@ -2658,6 +2658,16 @@ void EditorFileSystem::reimport_files(const Vector<String> &p_files) {
 
 	EditorProgress pr("reimport", TTR("(Re)Importing Assets"), p_files.size());
 
+	// The method reimport_files runs on the main thread, and if VSync is enabled
+	// or Update Continuously is disabled, Main::Iteration takes longer each frame.
+	// Each EditorProgress::step can trigger a redraw, and when there are many files to import,
+	// this could lead to a slow import process, especially when the editor is unfocused.
+	// Temporarily disabling VSync and low_processor_usage_mode while reimporting fixes this.
+	const bool old_low_processor_usage_mode = OS::get_singleton()->is_in_low_processor_usage_mode();
+	const DisplayServer::VSyncMode old_vsync_mode = DisplayServer::get_singleton()->window_get_vsync_mode(DisplayServer::MAIN_WINDOW_ID);
+	OS::get_singleton()->set_low_processor_usage_mode(false);
+	DisplayServer::get_singleton()->window_set_vsync_mode(DisplayServer::VSyncMode::VSYNC_DISABLED);
+
 	Vector<ImportFile> reimport_files;
 
 	HashSet<String> groups_to_reimport;
@@ -2784,11 +2794,17 @@ void EditorFileSystem::reimport_files(const Vector<String> &p_files) {
 			}
 		}
 	}
+	pr.step(TTR("Finalizing Asset Import..."), p_files.size());
 
 	ResourceUID::get_singleton()->update_cache(); // After reimporting, update the cache.
 
 	_save_filesystem_cache();
 	_process_update_pending();
+
+	// Revert to previous values to restore editor settings for VSync and Update Continuously.
+	OS::get_singleton()->set_low_processor_usage_mode(old_low_processor_usage_mode);
+	DisplayServer::get_singleton()->window_set_vsync_mode(old_vsync_mode);
+
 	importing = false;
 	if (!is_scanning()) {
 		emit_signal(SNAME("filesystem_changed"));

editor/editor_settings.cpp

@@ -821,6 +821,12 @@ void EditorSettings::_load_defaults(Ref<ConfigFile> p_extra_config) {
 	String android_window_hints = "Auto (based on screen size):0,Same as Editor:1,Side-by-side with Editor:2";
 	EDITOR_SETTING(Variant::INT, PROPERTY_HINT_ENUM, "run/window_placement/android_window", 0, android_window_hints)
 
+	int default_play_window_pip_mode = 0;
+#ifdef ANDROID_ENABLED
+	default_play_window_pip_mode = 2;
+#endif
+	EDITOR_SETTING(Variant::INT, PROPERTY_HINT_ENUM, "run/window_placement/play_window_pip_mode", default_play_window_pip_mode, "Disabled:0,Enabled:1,Enabled when Play window is same as Editor:2")
+
 	// Auto save
 	_initial_set("run/auto_save/save_before_running", true);
 

editor/plugins/canvas_item_editor_plugin.cpp

@@ -1462,10 +1462,12 @@ bool CanvasItemEditor::_gui_input_rotate(const Ref<InputEvent> &p_event) {
 				List<CanvasItem *> selection = _get_edited_canvas_items(false, true, &has_locked_items);
 
 				// Remove not movable nodes
-				for (CanvasItem *E : selection) {
-					if (!_is_node_movable(E, true)) {
+				for (List<CanvasItem *>::Element *E = selection.front(); E;) {
+					List<CanvasItem *>::Element *N = E->next();
+					if (!_is_node_movable(E->get(), true)) {
 						selection.erase(E);
 					}
+					E = N;
 				}
 
 				drag_selection = selection;