Document PackedScene.instantiate() for purpose of @tool scripts

[ballerburg9005]

When you instantiate a scene in a @tool script and add it as child in the tree, it doesn't do the same thing as when you are adding it inside the editor. First what you have to do is to use set_owner or else it will not show up in the scene tree. Now great, in the editor it seems to work and looks all the same, but actually it is not. If you look at the raw .tscn file, it is something else entirely. Apparently you have to instantiate with the paramenter PackedScene.GEN_EDIT_STATE_INSTANCE as well, or else it will result in various error messages, which you only get once you save then reopen the scene, depending on the stuff you have going on inside this child scene (for example signals). Even more frustrating is the fact that the errors give the false impression of being generated by your script directly, rather than a faulty entry of the node in the root scene, caused by using instantiate() without parameters.

To my current knowledge, this is the proper way to do it:

var item = load("res://child.tscn").instantiate(PackedScene.GEN_EDIT_STATE_INSTANCE)
add_child(item)
item.set_owner(get_tree().get_edited_scene_root())

This is quite undocumented, mysterious and time-consuming to figure out on your own. Also it easily escapes understanding what all the different flavors of enum GenEditState are really all about, and what the actual default value of it is that the editor uses.

It would make a whole lot of sense to me if all this was done simply by add_child() directly.

This page seems to be the perfect place to add this information:

https://docs.godotengine.org/en/stable/tutorials/scripting/nodes_and_scene_instances.html

Mystery errors I got for the sake of Google:

  Signal 'focus_entered' is already connected to given callable 'TextureRect(IventoryItem.gd)::_on_focus_entered' in that object.