Godot: The names "change_scene" and "change_scene_to" are too similar

[Jayman2000]

Godot version:
v3.1

Issue description:
According to the documentation, SceneTree has two methods that do the same thing. One is called "change_scene" and takes a String as an argument. The other one is called "change_scene_to" and takes a PackedScene as an argument.

I would expect these two names to reflect the fundamental difference between the two methods. I would expect them to be named something along the lines of "change_scene_path" and "change_scene_packed", to make the code more self-documenting.

[akien-mga]

Once a consensus is reached, if a change should be made, it should likely be added to #16863 and this issue closed.

[KoBeWi]

Or just rename change_scene_to to change_scene_to_packed.
Anyways, I'm ok with their current names.

[Calinou]

Maybe change_scene() could be removed entirely? change_scene_to(preload(…)) isn't much longer and leads to more consistency and less confusion.

[Jayman2000]

Maybe change_scene() could be removed entirely? change_scene_to(preload(…)) isn't much longer and leads to more consistency and less confusion.

I think that this is a good idea. If this change is made, change_scene_to(preload(…)) should be mentioned in the docs as a common way of useing change_scene_to.

[KoBeWi]

Maybe change_scene() could be removed entirely?

Isn't change_scene more straight-forward though? To use change_scene_to, you need a PackedScene resource, instead of just giving the scene name (which #26812 makes very easy).

[Eoin-ONeill-Yokai]

Stupid question, but couldn't we just use a variant argument that checks for either a string (meaning a path) or a packed scene resource and will return an error code if neither are fulfilled?

[Calinou]

@TheYokai That can be done, but it'll make documentation less clear if you just look at the function signature (and autocompletion/error checking will be less smart).

[Eoin-ONeill-Yokai]

I see. In that case, a decent work around would be an Option wrapper type which allows us to specify two (or more) potential options. Frankly, the change_scene vs change_scene_to complication seems to mostly be inside-baseball regarding how gdscript can't have two functions that share the same name but take in different arguments. An Option type that restricted potential Variant types could solve this problem to some degree.

[aaronfranke]

@Calinou change_scene_to(preload(…)) would not be obvious to beginners. Out of curiosity, would there be any disadvantage to only having the string version?

I would suggest change_scene_to -> change_scene_packed.

[mateusak]

@aaronfranke A packed scene variable that is editable through the inspector. While it's possible to do the same with a string, it's not as convenient. Besides that, there were times I needed it, although I can't say if it was because of bad design (since if I knew it was bad design I would surely fix it).

[KoBeWi]

Related: https://github.com/godotengine/godot/pull/26833#issuecomment-503566150