Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Notifiche di Godot

Ogni oggetto in Godot implementa un metodo _notification. Il suo scopo è consentire all'oggetto di rispondere a una varietà di callback a livello di motore che potrebbero riguardarlo. Ad esempio, se il motore indica a un CanvasItem di "disegnare", chiamerà _notification(NOTIFICATION_DRAW).

Alcune di queste notifiche, come "draw", sono utili da sovrascrivere negli script. Tanto che Godot ne espone molte con funzioni dedicate:

_ready(): NOTIFICATION_READY
_enter_tree(): NOTIFICATION_ENTER_TREE
_exit_tree(): NOTIFICATION_EXIT_TREE
_process(delta): NOTIFICATION_PROCESS
_physics_process(delta): NOTIFICATION_PHYSICS_PROCESS
_draw(): NOTIFICATION_DRAW

Ciò che gli utenti potrebbero non intuire è che le notifiche esistono anche per i tipi diversi da Node, ad esempio:

Object::NOTIFICATION_POSTINITIALIZE: una callback che viene attivato durante l'inizializzazione dell'oggetto. Non accessibile agli script.
Object::NOTIFICATION_PREDELETE: un callback che viene attivato prima che il motore elimini un oggetto, ovvero un "distruttore".

E inoltre molti dei callback che esistono nei nodi non hanno metodi dedicati, ma sono comunque molto utili.

Node::NOTIFICATION_PARENTED: un callback che viene attivato ogni volta che viene aggiunto un nodo figlio a un altro nodo.
Node::NOTIFICATION_UNPARENTED: un callback che viene attivato ogni volta che viene rimosso un nodo figlio da un altro nodo.

Il metodo universale _notification() fornisce l'accesso a tutte queste notifiche personalizzate.

Nota

Anche i metodi nella documentazione etichettati come "virtuali" sono concepiti per essere sovrascritti dagli script.

Un esempio classico è il metodo _init in Object. Sebbene non abbia una NOTIFICATION_* equivalente, il motore lo chiama comunque. La maggior parte dei linguaggi (tranne C#) lo usano come costruttore.

Allora, in quali situazioni si dovrebbe utilizzare ciascuna di queste notifiche o funzioni virtuali?

_process vs _physics_process vs *_input

Usa _process() quando servono intervalli di tempo dipendenti dal frame rate. Se il codice che aggiorna i dati degli oggetti deve essere aggiornato il più spesso possibile, questo è il posto giusto. Qui sono spesso eseguiti controlli logici ricorrenti e memorizzazione dei dati nella cache, ma tutto dipende dalla frequenza con cui è necessario aggiornarli. Se non serve eseguirli ogni frame, un'altra opzione è implementare un ciclo Timer-timeout.

# Allows for recurring operations that don't trigger script logic
# every frame (or even every fixed frame).
func _ready():
    var timer = Timer.new()
    timer.autostart = true
    timer.wait_time = 0.5
    add_child(timer)
    timer.timeout.connect(func():
        print("This block runs every 0.5 seconds")
    )

using Godot;

public partial class MyNode : Node
{
    // Allows for recurring operations that don't trigger script logic
    // every frame (or even every fixed frame).
    public override void _Ready()
    {
        var timer = new Timer();
        timer.Autostart = true;
        timer.WaitTime = 0.5;
        AddChild(timer);
        timer.Timeout += () => GD.Print("This block runs every 0.5 seconds");
    }
}

using namespace godot;

class MyNode : public Node {
    GDCLASS(MyNode, Node)

public:
    // Allows for recurring operations that don't trigger script logic
    // every frame (or even every fixed frame).
    virtual void _ready() override {
        Timer *timer = memnew(Timer);
        timer->set_autostart(true);
        timer->set_wait_time(0.5);
        add_child(timer);
        timer->connect("timeout", callable_mp(this, &MyNode::run));
    }

    void run() {
        UtilityFunctions::print("This block runs every 0.5 seconds.");
    }
};

Usa _physics_process() quando servono intervalli di tempo indipendenti dal frame rate. Se il codice necessita di aggiornamenti costanti nel tempo, a prescindere dalla velocità con cui il tempo avanza, questo è il posto giusto. Le operazioni cinematiche e di trasformazione degli oggetti ricorrenti si dovrebbero eseguire qui.

Sebbene sia possibile, per ottenere le migliori prestazioni, si dovrebbe evitare di effettuare controlli di input durante questi callback. _process() e _physics_process() verranno attivati a ogni occasione (solitamente non "riposano"). Al contrario, i callback *_input() verranno attivati solo sui frame in cui il motore ha effettivamente rilevato l'input.

È possibile verificare le azioni di input all'interno dei callback di input allo stesso modo. Se c'è bisogno di utilizzare un intervallo di tempo (delta), è possibile recuperarlo dai metodi "delta time" corrispondenti.

# Called every frame, even when the engine detects no input.
func _process(delta):
    if Input.is_action_just_pressed("ui_select"):
        print(delta)

# Called during every input event.
func _unhandled_input(event):
    match event.get_class():
        "InputEventKey":
            if Input.is_action_just_pressed("ui_accept"):
                print(get_process_delta_time())

using Godot;

public partial class MyNode : Node
{

    // Called every frame, even when the engine detects no input.
    public void _Process(double delta)
    {
        if (Input.IsActionJustPressed("ui_select"))
        {
            GD.Print(delta);
        }
    }

    // Called during every input event. Equally true for _input().
    public void _UnhandledInput(InputEvent @event)
    {
        switch (@event)
        {
            case InputEventKey:
                if (Input.IsActionJustPressed("ui_accept"))
                {
                    GD.Print(GetProcessDeltaTime());
                }
                break;
        }
    }

}

using namespace godot;

class MyNode : public Node {
    GDCLASS(MyNode, Node)

public:
    // Called every frame, even when the engine detects no input.
    virtual void _process(double p_delta) override {
        if (Input::get_singleton->is_action_just_pressed("ui_select")) {
            UtilityFunctions::print(p_delta);
        }
    }

    // Called during every input event. Equally true for _input().
    virtual void _unhandled_input(const Ref<InputEvent> &p_event) override {
        Ref<InputEventKey> key_event = event;
        if (key_event.is_valid() && Input::get_singleton->is_action_just_pressed("ui_accept")) {
            UtilityFunctions::print(get_process_delta_time());
        }
    }
};

_init vs inizializzazione vs esportazione

Se lo script inizializza il proprio sotto-albero di nodi, senza una scena, il codice si dovrebbe eseguire in _init(). Anche altre inizializzazioni indipendenti dallo SceneTree o da proprietà si dovrebbero eseguire qui.

Nota

L'equivalente in C# al metodo _init() di GDScript è il costruttore.

_init() viene attivato prima di _enter_tree() o _ready(), ma dopo che uno script ha creato e inizializzato le sue proprietà. Quando si istanzia una scena, i valori delle proprietà vengono assegnati secondo la seguente sequenza:

Assegnazione del valore iniziale: alla proprietà viene assegnato il suo valore di inizializzazione, oppure il suo valore predefinito se non ne è specificato uno. Se esiste un setter, non viene utilizzato.
Assegnazione in _init(): il valore della proprietà viene sostituito da qualsiasi assegnazione effettuata in _init(), attivando il setter.
Assegnazione del valore esportato: il valore di una proprietà esportata viene nuovamente sostituito da qualsiasi valore impostato nell'Ispettore, attivando il setter.

# test is initialized to "one", without triggering the setter.
@export var test: String = "one":
    set(value):
        test = value + "!"

func _init():
    # Triggers the setter, changing test's value from "one" to "two!".
    test = "two"

# If you set test to "three" from the Inspector, it would trigger
# the setter, changing test's value from "two!" to "three!".

using Godot;

public partial class MyNode : Node
{
    private string _test = "one";

    [Export]
    public string Test
    {
        get { return _test; }
        set { _test = $"{value}!"; }
    }

    public MyNode()
    {
        // Triggers the setter, changing _test's value from "one" to "two!".
        Test = "two";
    }

    // If you set Test to "three" in the Inspector, it would trigger
    // the setter, changing _test's value from "two!" to "three!".
}

using namespace godot;

class MyNode : public Node {
    GDCLASS(MyNode, Node)

    String test = "one";

protected:
    static void _bind_methods() {
        ClassDB::bind_method(D_METHOD("get_test"), &MyNode::get_test);
        ClassDB::bind_method(D_METHOD("set_test", "test"), &MyNode::set_test);
        ADD_PROPERTY(PropertyInfo(Variant::STRING, "test"), "set_test", "get_test");
    }

public:
    String get_test() { return test; }
    void set_test(String p_test) { test = p_test + "!"; }

    MyNode() {
        // Triggers the setter, changing _test's value from "one" to "two!".
        set_test("two");
    }

    // If you set test to "three" in the Inspector, it would trigger
    // the setter, changing test's value from "two!" to "three!".
};

Come risultato, l'istanziazione di uno script anziché di una scena può influire sia sull'inizializzazione, sia sul numero di volte in cui il motore chiama il setter.

_ready vs _enter_tree vs NOTIFICATION_PARENTED

Quando viene istanziata una scena connessa alla prima scena eseguita, Godot istanzia i nodi lungo l'albero (effettuando chiamate a _init()) e costruisce l'albero verso il basso, partendo dalla radice. Ciò assicura che le chiamate a _enter_tree() vengano eseguite a cascata lungo l'albero. Una volta completato l'albero, i nodi foglia chiamano _ready. Un nodo chiamerà questo metodo una volta che tutti i nodi figlio avranno finito di chiamare il proprio. Ciò provocherà quindi una cascata inversa che risale fino alla radice dell'albero.

Quando viene istanziato uno script o una scena autonoma, i nodi non vengono aggiunti allo SceneTree al momento della creazione, quindi non vengono attivati i callback _enter_tree(). Viene invece eseguita solo la chiamata a _init(). Quando la scena viene aggiunta allo SceneTree, vengono eseguite le chiamate _enter_tree() e _ready().

Se è necessario attivare un comportamento che accade quando i nodi sono aggiunti a un nodo padre, a prescindere che accada o meno come parte della scena principale o attiva, è possibile usare la notifica PARENTED. Ad esempio, ecco uno frammento di codice che collega un metodo di un nodo a un segnale personalizzato sul nodo padre senza errori. Utile per i nodi incentrati sui dati che si potrebbero creare in fase di esecuzione.

extends Node

var parent_cache

func connection_check():
    return parent_cache.has_user_signal("interacted_with")

func _notification(what):
    match what:
        NOTIFICATION_PARENTED:
            parent_cache = get_parent()
            if connection_check():
                parent_cache.interacted_with.connect(_on_parent_interacted_with)
        NOTIFICATION_UNPARENTED:
            if connection_check():
                parent_cache.interacted_with.disconnect(_on_parent_interacted_with)

func _on_parent_interacted_with():
    print("I'm reacting to my parent's interaction!")

using Godot;

public partial class MyNode : Node
{
    private Node _parentCache;

    public bool ConnectionCheck()
    {
        return _parentCache.HasUserSignal("InteractedWith");
    }

    public override void _Notification(int what)
    {
        switch ((long)what)
        {
            case NotificationParented:
                _parentCache = GetParent();
                if (ConnectionCheck())
                {
                    _parentCache.Connect("InteractedWith", Callable.From(OnParentInteractedWith));
                }
                break;
            case NotificationUnparented:
                if (ConnectionCheck())
                {
                    _parentCache.Disconnect("InteractedWith", Callable.From(OnParentInteractedWith));
                }
                break;
        }
    }

    private void OnParentInteractedWith()
    {
        GD.Print("I'm reacting to my parent's interaction!");
    }
}

using namespace godot;

class MyNode : public Node {
    GDCLASS(MyNode, Node)

    Node *parent_cache = nullptr;

    void on_parent_interacted_with() {
        UtilityFunctions::print("I'm reacting to my parent's interaction!");
    }

public:
    void connection_check() {
        return parent_cache->has_user_signal("interacted_with");
    }

    void _notification(int p_what) {
        switch (p_what) {
            case NOTIFICATION_PARENTED:
                parent_cache = get_parent();
                if (connection_check()) {
                    parent_cache->connect("interacted_with", callable_mp(this, &MyNode::on_parent_interacted_with));
                }
                break;
            case NOTIFICATION_UNPARENTED:
                if (connection_check()) {
                    parent_cache->disconnect("interacted_with", callable_mp(this, &MyNode::on_parent_interacted_with));
                }
                break;
        }
    }
};