Early initialization of instantiated scene

[dalexeev]

• PR: Add Node._scene_instantiated() method and @oninstantiated annotation godot#87594

See also:

• oninstance var #4323
• Using setget set with child node throws null instance error godot#78843

Summary

In some cases, @onready variables, virtual methods _enter_tree and _ready are too late and _init is too early. Add an annotation and/or a virtual method to early initialize the instantiated scene (before _enter_tree and _ready) or properly document the current solution with NOTIFICATION_SCENE_INSTANTIATED. Pay attention to the issue of scene and class relationships (related #1935).

Example

Let's say we want to create a control like this:

When you select an item in Items (ItemList), information about it in ItemInfo is updated. Let's also assume that this control is the base for other controls, and the set of item action buttons may differ in different controls.

The first version of our script will look like this:

extends VBoxContainer
class_name ItemStorageControl

var title: String:
    get: return _title.text
    set(value): _title.text = value

@onready var _title: Label = %Title
@onready var _buttons: VBoxContainer = %Buttons

func add_button(button: Button) -> void:
    _buttons.show()
    _buttons.add_child(button)

func clear_buttons() -> void:
    _buttons.hide()
    for button in _buttons.get_children():
        button.queue_free()

This works great in most cases, but what happens if we create an ItemStorageControl from code?¹

var isc := ItemStorageControl.instantiate()
isc.title = "Inventory" # Will not work, the Title node is not ready yet.
isc.add_button(_use_button) # Will not work, the Buttons node is not ready yet.
isc.add_button(_drop_button) # Same.
add_child(isc)

---

In the Godot source code, when initializing composite nodes and not only, the approach of describing and adding all child nodes is used, for example:

ScrollContainer::ScrollContainer() {
    h_scroll = memnew(HScrollBar);
    h_scroll->set_name("_h_scroll");
    add_child(h_scroll, false, INTERNAL_MODE_BACK);
    h_scroll->connect("value_changed", callable_mp(this, &ScrollContainer::_scroll_moved));

    v_scroll = memnew(VScrollBar);
    v_scroll->set_name("_v_scroll");
    add_child(v_scroll, false, INTERNAL_MODE_BACK);
    v_scroll->connect("value_changed", callable_mp(this, &ScrollContainer::_scroll_moved));

    deadzone = GLOBAL_GET("gui/common/default_scroll_deadzone");

    set_clip_contents(true);
};

In GDScript you can do the same thing: add nodes in _init and they will be available immediately, before _enter_tree and _ready. This can be used in simple cases (few child nodes, few properties to set up), but it is impractical in complex ones: it is more convenient to edit the scene in the editor.

---

You can try to "solve" it like this:

extends VBoxContainer
class_name ItemStorageControl

var title: String:
    set(value):
        title = value
        if _title:
            _title.text = value

@onready var _title: Label = %Title

func _ready() -> void:
    _title.text = title

However, this is the wrong approach: duplication of the title value, redundant and more confusing code. Especially if you try to do the same with buttons.

---

In #1935, another workaround is mentioned: store the scene body in the scene file, instantiate the scene in _init of the class and add it as a child.

var _title: Label
var _buttons: VBoxContainer

func _init() -> void:
    var body = preload("res://ui/item_storage_control_body.tscn").instantiate()
    add_child(body)
    
    _title = body.get_node("%Title")
    _buttons = body.get_node("%Buttons")

---

But the use case for NOTIFICATION_SCENE_INSTANTIATED seems to me the most correct. The notification is sent the moment the scene is instantiated (only on the scene's root, which is the owner of all other scene nodes), well before _enter_tree and _ready, but later than _init (which is called when the root is initialized, before the other nodes are added as children or perhaps even created).

extends VBoxContainer
class_name ItemStorageControl

var title: String:
    get: return _title.text
    set(value): _title.text = value

var _title: Label
var _buttons: VBoxContainer

func _notification(what: int) -> void:
    if what == NOTIFICATION_SCENE_INSTANTIATED:
        _title = %Title
        _buttons = %Buttons

func add_button(button: Button) -> void:
    _buttons.show()
    _buttons.add_child(button)

func clear_buttons() -> void:
    _buttons.hide()
    for button in _buttons.get_children():
        button.queue_free()

Proposal?

Similar to @onready and _ready, we could add an annotation and/or a virtual method:

# Now the title property, the add_button and clear_button methods
# will work before the node is inserted into the tree.
@on_scene_instantiated var _title: Label = %Title
@on_scene_instantiated var _buttons: VBoxContainer = %Buttons

# Called when the scene has been instantiated but not yet added to the scene tree.
func _scene_instantiated() -> void:
    # Clear placeholders.
    _item_name.text = ""
    _item_desc.text = ""
    clear_buttons()

But I'm not sure if this is necessary. Firstly, the name is quite long (is there a short but not confusing one?). Secondly, this method cannot be a replacement for _ready, as it is only called when the scene is instantiated (NOTIFICATION_SCENE_INSTANTIATED not sent to child nodes of the scene or if the node is created via new()). In contrast, _init is always called when an object is created, and _ready is always called when a node becomes "ready" (roughly equals "first enters the tree").

Since the solution already exists (just not documented in detail), I start this discussion rather than opening a proposal. The question is, do we need a separate virtual method instead of using _notification² (which is called in other cases as well, like NOTIFICATION_PROCESS if processing is enabled)?

But I think that in some cases people may be interested in early initialization of the scene. And this approach is not covered in the documentation. Also, this is another case at the intersection of scenes and classes, and if we implement #1935, then this case should also be taken into account.

Footnotes

1. instantiate is a static method that instantiates the scene of the class.
   See Add scene binding for optional tight-coupling between Node-extending Scripts and PackedScene resources #1935 for details. ↩

2. See also Really need Node destroy callback function, just like "OnDestroy" in Unity #707. ↩

[kubecz3k]

I'm using "NOTIFICATION_INSTANCED" a lot in TailQuest, I think it's the best place to do internal initialization of a scene, in many cases it helped to prevent a lot of issues with setters and getters not being able to operate properly (since some dependent members are not initialized yet)
I think both new virtual method as well as annotation would be helpful.
For the annotation name I would go with short @oninstanced

[dalexeev]

See

• Rename NOTIFICATION_INSTANCED to NOTIFICATION_SCENE_INSTANTIATED godot#64410

Besides the obvious INSTANCED -> INSTANTIATED, the SCENE prefix has been added to avoid confusion with object/scene instantiation.

I'm glad you too are finding this feature useful and actively using the notification. I would like this "secret feature" to become more known. But at the same time, I'm afraid that it may confuse people in which cases it should be used.

[kubecz3k]

after the rename I think @oninstantiated is the way to go, anything else is just way to long. I would not be too concerned about the confusion, the moment someone discovers it one is able to read doc about this, usability is way more important here, one can be confused only once by this (just the same how he can get confused only once by @onready)

[Maran23]

I agree, the annotation is a good way to go.
Tbh, I would then always use @oninstantiated, as this is what I want most of the times and it is not limitated as @onready is.
I'm very interested how other people will feel about this once implemented.

[dalexeev]

• I opened PR Add Node._scene_instantiated() method and @oninstantiated annotation godot#87594.

[theraot]

I want to comment on the "try to solve" code you have. My current approach for reusable custom nodes (not for scenes) is to have a method that does all the initialization, and:

1. Call it from the setters or other methods that need it, but only if is_inside_tree.
2. Call it from _enter_tree.

This way if I'm setting/changing things before adding to (or while removed from) the scene tree, it is storing the changes but not acting on it until it enters the scene tree. But if it is inside the tree, then it will act on the changes right away. Furthermore, it will not act on the changes twice, nor I duplicate that code. I want to emphasize that this approach allows me to remove the node, modify the values and add it again.

I'm not saying you should use this for scene (I reiterate it is for reusable custom nodes). But I'm saying you can "try to solve" better. Don't straw man the "try to solve".

Addendum: it can get complex to know changes has been applied, for example if you have an array property where the elements can change.

---

With that said, yes, the instant you are looking for is the instanced notification. It is a very good place for scene initialization.

[dalexeev]

for reusable custom nodes (not for scenes)

this approach allows me to remove the node, modify the values and add it again.

This is a different case, I didn't mean to say that this approach is wrong at all. But in my example, it is obvious that it is better to initially be sure of correct initialization, and not check in each method whether the node is "ready" or not and keep a copy of the data that will be applied in _ready.