Rename change_scene() and change_scene_to()

Before this change, the SceneTree had methods named “change_scene” and
“change_scene_to”. One of them accepted a String as a parameter and the
other accepted a PackedScene, but you couldn’t tell which one was which
just by looking at their names.

This change renames those two methods to “change_scene_to_file” and
“change_scene_to_packed”. These new names came from this suggestion [1].
These new names make the difference between the two methods more clear
and hint at the fact that there’s more than one change_scene method.

[1]: <https://github.com/godotengine/godot/issues/27640#issuecomment-1081870955>

Fixes #27640.

4 files changed, 17 insertions, 13 deletions

diff --git a/doc/classes/SceneTree.xml b/doc/classes/SceneTree.xml
index 221e627e35..070b98f21d 100644
--- a/doc/classes/SceneTree.xml
+++ b/doc/classes/SceneTree.xml
@@ -36,22 +36,22 @@
 				[b]Note:[/b] Group call flags are used to control the method calling behavior. By default, methods will be called immediately in a way similar to [method call_group]. However, if the [constant GROUP_CALL_DEFERRED] flag is present in the [param flags] argument, methods will be called with a one-frame delay in a way similar to [method Object.set_deferred].
 			</description>
 		</method>
-		<method name="change_scene">
+		<method name="change_scene_to_file">
 			<return type="int" enum="Error" />
 			<param index="0" name="path" type="String" />
 			<description>
 				Changes the running scene to the one at the given [param path], after loading it into a [PackedScene] and creating a new instance.
 				Returns [constant OK] on success, [constant ERR_CANT_OPEN] if the [param path] cannot be loaded into a [PackedScene], or [constant ERR_CANT_CREATE] if that scene cannot be instantiated.
-				[b]Note:[/b] The scene change is deferred, which means that the new scene node is added on the next idle frame. You won't be able to access it immediately after the [method change_scene] call.
+				[b]Note:[/b] The scene change is deferred, which means that the new scene node is added on the next idle frame. You won't be able to access it immediately after the [method change_scene_to_file] call.
 			</description>
 		</method>
-		<method name="change_scene_to">
+		<method name="change_scene_to_packed">
 			<return type="int" enum="Error" />
 			<param index="0" name="packed_scene" type="PackedScene" />
 			<description>
 				Changes the running scene to a new instance of the given [PackedScene].
 				Returns [constant OK] on success or [constant ERR_CANT_CREATE] if the scene cannot be instantiated.
-				[b]Note:[/b] The scene change is deferred, which means that the new scene node is added on the next idle frame. You won't be able to access it immediately after the [method change_scene_to] call.
+				[b]Note:[/b] The scene change is deferred, which means that the new scene node is added on the next idle frame. You won't be able to access it immediately after the [method change_scene_to_packed] call.
 			</description>
 		</method>
 		<method name="create_timer">
diff --git a/editor/project_converter_3_to_4.cpp b/editor/project_converter_3_to_4.cpp
index 47c4557f14..7512fbbe43 100644
--- a/editor/project_converter_3_to_4.cpp
+++ b/editor/project_converter_3_to_4.cpp
@@ -240,6 +240,8 @@ static const char *gdscript_function_renames[][2] = {
 	{ "can_instance", "can_instantiate" }, // PackedScene, Script
 	{ "canvas_light_set_scale", "canvas_light_set_texture_scale" }, // RenderingServer
 	{ "center_viewport_to_cursor", "center_viewport_to_caret" }, // TextEdit
+	{ "change_scene", "change_scene_to_file" }, // SceneTree
+	{ "change_scene_to", "change_scene_to_packed" }, // SceneTree
 	{ "clip_polygons_2d", "clip_polygons" }, // Geometry2D
 	{ "clip_polyline_with_polygon_2d", "clip_polyline_with_polygon" }, //Geometry2D
 	{ "commit_handle", "_commit_handle" }, // EditorNode3DGizmo
@@ -670,6 +672,8 @@ static const char *csharp_function_renames[][2] = {
 	{ "CanInstance", "CanInstantiate" }, // PackedScene, Script
 	{ "CanvasLightSetScale", "CanvasLightSetTextureScale" }, // RenderingServer
 	{ "CenterViewportToCursor", "CenterViewportToCaret" }, // TextEdit
+	{ "ChangeScene", "ChangeSceneToFile" }, // SceneTree
+	{ "ChangeSceneTo", "ChangeSceneToPacked" }, // SceneTree
 	{ "ClipPolygons2d", "ClipPolygons" }, // Geometry2D
 	{ "ClipPolylineWithPolygon2d", "ClipPolylineWithPolygon" }, //Geometry2D
 	{ "CommitHandle", "_CommitHandle" }, // EditorNode3DGizmo
diff --git a/scene/main/scene_tree.cpp b/scene/main/scene_tree.cpp
index 25c9b33ff9..cc58d799ab 100644
--- a/scene/main/scene_tree.cpp
+++ b/scene/main/scene_tree.cpp
@@ -1138,16 +1138,16 @@ void SceneTree::_change_scene(Node *p_to) {
 	}
 }
 
-Error SceneTree::change_scene(const String &p_path) {
+Error SceneTree::change_scene_to_file(const String &p_path) {
 	Ref<PackedScene> new_scene = ResourceLoader::load(p_path);
 	if (new_scene.is_null()) {
 		return ERR_CANT_OPEN;
 	}
 
-	return change_scene_to(new_scene);
+	return change_scene_to_packed(new_scene);
 }
 
-Error SceneTree::change_scene_to(const Ref<PackedScene> &p_scene) {
+Error SceneTree::change_scene_to_packed(const Ref<PackedScene> &p_scene) {
 	Node *new_scene = nullptr;
 	if (p_scene.is_valid()) {
 		new_scene = p_scene->instantiate();
@@ -1161,7 +1161,7 @@ Error SceneTree::change_scene_to(const Ref<PackedScene> &p_scene) {
 Error SceneTree::reload_current_scene() {
 	ERR_FAIL_COND_V(!current_scene, ERR_UNCONFIGURED);
 	String fname = current_scene->get_scene_file_path();
-	return change_scene(fname);
+	return change_scene_to_file(fname);
 }
 
 void SceneTree::add_current_scene(Node *p_current) {
@@ -1310,8 +1310,8 @@ void SceneTree::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_current_scene", "child_node"), &SceneTree::set_current_scene);
 	ClassDB::bind_method(D_METHOD("get_current_scene"), &SceneTree::get_current_scene);
 
-	ClassDB::bind_method(D_METHOD("change_scene", "path"), &SceneTree::change_scene);
-	ClassDB::bind_method(D_METHOD("change_scene_to", "packed_scene"), &SceneTree::change_scene_to);
+	ClassDB::bind_method(D_METHOD("change_scene_to_file", "path"), &SceneTree::change_scene_to_file);
+	ClassDB::bind_method(D_METHOD("change_scene_to_packed", "packed_scene"), &SceneTree::change_scene_to_packed);
 
 	ClassDB::bind_method(D_METHOD("reload_current_scene"), &SceneTree::reload_current_scene);
 
@@ -1366,7 +1366,7 @@ void SceneTree::add_idle_callback(IdleCallback p_callback) {
 }
 
 void SceneTree::get_argument_options(const StringName &p_function, int p_idx, List<String> *r_options) const {
-	if (p_function == "change_scene") {
+	if (p_function == "change_scene_to_file") {
 		Ref<DirAccess> dir_access = DirAccess::create(DirAccess::ACCESS_RESOURCES);
 		List<String> directories;
 		directories.push_back(dir_access->get_current_dir());
diff --git a/scene/main/scene_tree.h b/scene/main/scene_tree.h
index 45653001ca..51d000305c 100644
--- a/scene/main/scene_tree.h
+++ b/scene/main/scene_tree.h
@@ -366,8 +366,8 @@ public:
 
 	void set_current_scene(Node *p_scene);
 	Node *get_current_scene() const;
-	Error change_scene(const String &p_path);
-	Error change_scene_to(const Ref<PackedScene> &p_scene);
+	Error change_scene_to_file(const String &p_path);
+	Error change_scene_to_packed(const Ref<PackedScene> &p_scene);
 	Error reload_current_scene();
 
 	Ref<SceneTreeTimer> create_timer(double p_delay_sec, bool p_process_always = true, bool p_process_in_physics = false, bool p_ignore_time_scale = false);