Merge pull request #38695 from dreamsComeTrue/node-swap-order-arguments

Replace 'add_child_below_node' with 'add_sibling' in Node

doc/classes/Node.xml

@@ -129,21 +129,19 @@
 				    child_node.get_parent().remove_child(child_node)
 				add_child(child_node)
 				[/codeblock]
-				If you need the child node to be added below a specific node in the list of children, use [method add_child_below_node] instead of this method.
+				If you need the child node to be added below a specific node in the list of children, use [method add_sibling] instead of this method.
 				[b]Note:[/b] If you want a child to be persisted to a [PackedScene], you must set [member owner] in addition to calling [method add_child]. This is typically relevant for [url=https://godot.readthedocs.io/en/latest/tutorials/misc/running_code_in_the_editor.html]tool scripts[/url] and [url=https://godot.readthedocs.io/en/latest/tutorials/plugins/editor/index.html]editor plugins[/url]. If [method add_child] is called without setting [member owner], the newly added [Node] will not be visible in the scene tree, though it will be visible in the 2D/3D view.
 			</description>
 		</method>
-		<method name="add_child_below_node">
+		<method name="add_sibling">
 			<return type="void">
 			</return>
-			<argument index="0" name="preceding_node" type="Node">
+			<argument index="0" name="sibling" type="Node">
 			</argument>
-			<argument index="1" name="node" type="Node">
-			</argument>
-			<argument index="2" name="legible_unique_name" type="bool" default="false">
+			<argument index="1" name="legible_unique_name" type="bool" default="false">
 			</argument>
 			<description>
-				Adds a child node below the [code]preceding_node[/code].
+				Adds a [code]sibling[/code] node to current's node parent, at the the same level as that node, right below it.
 				If [code]legible_unique_name[/code] is [code]true[/code], the child node will have an human-readable name based on the name of the node being instanced instead of its type.
 				Use [method add_child] instead of this method if you don't need the child node to be added below a specific node in the list of children.
 			</description>

editor/scene_tree_dock.cpp

@@ -579,7 +579,8 @@ void SceneTreeDock::_tool_selected(int p_tool, bool p_confirm_override) {
 
 				dup->set_name(parent->validate_child_name(dup));
 
-				editor_data->get_undo_redo().add_do_method(parent, "add_child_below_node", add_below_node, dup);
+				editor_data->get_undo_redo().add_do_method(add_below_node, "add_sibling", dup);
+
 				for (List<Node *>::Element *F = owned.front(); F; F = F->next()) {
 					if (!duplimap.has(F->get())) {
 						continue;

scene/main/node.cpp

@@ -1234,17 +1234,13 @@ void Node::add_child(Node *p_child, bool p_legible_unique_name) {
 	_add_child_nocheck(p_child, p_child->data.name);
 }
 
-void Node::add_child_below_node(Node *p_node, Node *p_child, bool p_legible_unique_name) {
-	ERR_FAIL_NULL(p_node);
-	ERR_FAIL_NULL(p_child);
-
-	add_child(p_child, p_legible_unique_name);
+void Node::add_sibling(Node *p_sibling, bool p_legible_unique_name) {
+	ERR_FAIL_NULL(p_sibling);
+	ERR_FAIL_COND_MSG(p_sibling == this, "Can't add sibling '" + p_sibling->get_name() + "' to itself."); // adding to itself!
+	ERR_FAIL_COND_MSG(data.blocked > 0, "Parent node is busy setting up children, add_sibling() failed. Consider using call_deferred(\"add_sibling\", sibling) instead.");
 
-	if (is_a_parent_of(p_node)) {
-		move_child(p_child, p_node->get_index() + 1);
-	} else {
-		WARN_PRINT("Cannot move under node " + p_node->get_name() + " as " + p_child->get_name() + " does not share a parent.");
-	}
+	get_parent()->add_child(p_sibling, p_legible_unique_name);
+	get_parent()->move_child(p_sibling, this->get_index() + 1);
 }
 
 void Node::_propagate_validate_owner() {
@@ -2710,7 +2706,7 @@ void Node::_bind_methods() {
 	GLOBAL_DEF("node/name_casing", NAME_CASING_PASCAL_CASE);
 	ProjectSettings::get_singleton()->set_custom_property_info("node/name_casing", PropertyInfo(Variant::INT, "node/name_casing", PROPERTY_HINT_ENUM, "PascalCase,camelCase,snake_case"));
 
-	ClassDB::bind_method(D_METHOD("add_child_below_node", "preceding_node", "node", "legible_unique_name"), &Node::add_child_below_node, DEFVAL(false));
+	ClassDB::bind_method(D_METHOD("add_sibling", "sibling", "legible_unique_name"), &Node::add_sibling, DEFVAL(false));
 
 	ClassDB::bind_method(D_METHOD("set_name", "name"), &Node::set_name);
 	ClassDB::bind_method(D_METHOD("get_name"), &Node::get_name);

scene/main/node.h

@@ -266,7 +266,7 @@ public:
 	void set_name(const String &p_name);
 
 	void add_child(Node *p_child, bool p_legible_unique_name = false);
-	void add_child_below_node(Node *p_node, Node *p_child, bool p_legible_unique_name = false);
+	void add_sibling(Node *p_sibling, bool p_legible_unique_name = false);
 	void remove_child(Node *p_child);
 
 	int get_child_count() const;