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...

Creare estenzioni

Informazioni sulle estensioni

Un'estensione è un ottimo modo per estendere l'editor con strumenti utili. Può essere realizzato interamente con GDScript e scene standard, senza nemmeno ricaricare l'editor. A differenza dei moduli, non è necessario creare codice C++ né ricompilare il motore. Sebbene questo renda le stensioni meno potenti, ci sono comunque molte cose che si possono fare con loro. Nota che un'estensione è simile a qualsiasi scena che puoi già creare, eccetto che viene creato utilizzando uno script per aggiungere funzionalità all'editor.

Questo tutorial ti guiderà attraverso la creazione di due plugin, così potrai capirne il funzionamento e svilupparne di tuoi. Il primo è un nodo personalizzato che puoi aggiungere a qualsiasi scena del progetto, mentre il secondo è un pannello personalizzato aggiunto all'editor.

Creare un'estensione

Prima di cominciare, crea un nuovo progetto vuoto dove vuoi. Questo servirà come base per sviluppare e testare le estensioni.

La prima cosa di cui l'editor ha bisogno per identificare una nuova estensione è creare due file: un plugin.cfg per la configurazione e uno script con la funzionalità. Le estensioni hanno un percorso standard come addons/plugin_name all'interno della cartella del progetto. Godot fornisce una finestra di dialogo per generare questi file e posizionarli dove devono stare.

Nella barra degli strumenti principale, clicca sul menu a discesa Progetto. Quindi clicca su Impostazioni del progetto.... Vai alla scheda Estensioni e clicca sul pulsante Create New Plugin in alto a destra.

Vedrai apparire la finestra di dialogo seguente:

../../../_images/making_plugins-create_plugin_dialog.webp

Il testo segnaposto in ogni campo descrive come influisce sulla creazione dei file e sui valori del file di configurazione dell'estensione.

Per continuare con l'esempio, utilizzare i seguenti valori:

Plugin Name: My Custom Node
Subfolder: my_custom_node
Description: A custom node made to extend the Godot Engine.
Author: Your Name Here
Version: 1.0.0
Language: GDScript
Script Name: custom_node.gd

Plugin Name: My Custom Node
Subfolder: MyCustomNode
Description: A custom node made to extend the Godot Engine.
Author: Your Name Here
Version: 1.0.0
Language: C#
Script Name: CustomNode.cs

Avvertimento

In C#, lo script EditorPlugin deve essere compilato, il che richiede la compilazione del progetto. Dopo aver compilato il progetto, l'estensione può essere abilitata nella scheda Estensioni di Impostazioni del progetto.

Dovresti ottenere una struttura di cartelle come questa:

../../../_images/making_plugins-my_custom_mode_folder.webp

plugin.cfg è un file INI con metadati sulla tua estensione. Il nome e la descrizione aiutano gli utenti a capire cosa fa. Il tuo nome aiuta a ottenere il giusto riconoscimento per il tuo lavoro. Il numero di versione aiuta gli altri a sapere se hanno una versione obsoleta; se non sei sicuro di come trovare il numero di versione, dai un'occhiata a Semantic Versioning. Il file di script principale indicherà a Godot cosa fa la tua estensione nell'editor una volta attiva.

Il file di script

Dopo la creazione dell'estensione, la finestra di dialogo aprirà automaticamente lo script EditorPlugin. Lo script ha due requisiti che non è possibile modificare: deve essere uno script @tool, altrimenti non verrà caricato correttamente nell'editor, e deve ereditare da EditorPlugin.

Avvertimento

Oltre allo script EditorPlugin, qualsiasi altro GDScript utilizzato dall'estensione deve anche essere uno strumento (tool). Qualsiasi GDScript senza @tool utilizzato dall'editor si comporterà come un file vuoto!

È importante occuparsi dell'inizializzazione e della pulizia delle risorse. Una buona pratica è quella di utilizzare la funzione virtuale _enter_tree() per inizializzare l'estensione e _exit_tree() per ripulirla. Fortunatamente, la finestra di dialogo genera automaticamente questi callback. Lo script dovrebbe assomigliare a questo:

@tool
extends EditorPlugin


func _enter_tree():
    # Initialization of the plugin goes here.
    pass


func _exit_tree():
    # Clean-up of the plugin goes here.
    pass

#if TOOLS
using Godot;

[Tool]
public partial class CustomNode : EditorPlugin
{
    public override void _EnterTree()
    {
        // Initialization of the plugin goes here.
    }

    public override void _ExitTree()
    {
        // Clean-up of the plugin goes here.
    }
}
#endif

Questo è un buon modello da utilizzare quando si creano nuove estensioni.

Un nodo personalizzato

A volte si desidera un determinato comportamento in più nodi, ad esempio una scena personalizzata o un controllo riutilizzabile. L'istanziazione è utile in molti casi, ma a volte può essere macchinosa, soprattutto se utilizzata in molti progetti. Una buona soluzione a questo problema è creare un'estensione che aggiunga un nodo con un comportamento personalizzato.

Per questo tutorial, creeremo un pulsante che stampi un messaggio quando viene cliccato. Per farlo, avremo bisogno di uno script che estenda Button. Se preferisci, puoi anche estendere BaseButton:

# Optional, add to execute in the editor.
@tool

# Icons are optional.
# Alternatively, you may use the UID of the icon or the absolute path.
@icon("icon.svg")

# Automatically register the node in the Create New Node dialog
# and make it available for use with other scripts.
class_name MyButton
extends Button


func _enter_tree():
    pressed.connect(clicked)


func clicked():
    print("You clicked me!")

using Godot;

// Optional, add to execute in the editor.
[Tool]

// Icons are optional.
// Alternatively, you may use the UID of the icon or the absolute path.
[Icon("icon.svg")]

// Automatically register the node in the Create New Node dialog
// and make it available for use with other scripts.
[GlobalClass]
public partial class MyButton : Button
{
    public override void _EnterTree()
    {
        Pressed += Clicked;
    }

    public void Clicked()
    {
        GD.Print("You clicked me!");
    }
}

That's it for our basic button. You can save this as my_button.gd inside the plugin folder. You may have a 16×16 icon to show in the scene tree. If you don't have one, you can grab the default one from the engine and save it in your addons/my_custom_node folder as icon.svg, or use the default Godot logo (@icon("res://icon.svg")).

Suggerimento

Le immagini SVG utilizzate come icone dei nodi personalizzati devono avere le opzioni di importazione Editor > Scala con la scala dell'editor e Editor > Converti i colori con il tema dell'editor abilitate. Questo consente alle icone di seguire le impostazioni di scala e tema dell'editor se sono progettate con la stessa tavolozza di colori delle icone di Godot.

Fatto ciò, l'estensione dovrebbe essere già disponibile nell'elenco delle estensioni nelle Impostazioni del progetto, quindi attivalo come spiegato in Verifica dei risultati.

Poi provalo aggiungendo il tuo nuovo nodo:

../../../_images/making_plugins-custom_node_create.webp

Quando aggiungi il nodo, puoi vedere che ha già allegato lo script creato da te. Imposta un testo per il pulsante, salva ed esegui la scena. Quando clicchi sul pulsante, puoi vedere del testo nella console:

../../../_images/making_plugins-custom_node_console.webp

Un pannello personalizzato

A volte, è necessario estendere l'editor e aggiungere strumenti sempre disponibili. Un modo semplice per farlo è aggiungere un nuovo pannello con un'estensione. I pannelli sono solo scene basate su Control, quindi si creano in modo simile alle normali scene dell'interfaccia grafica.

La creazione di un pannello personalizzato avviene esattamente come per un nodo personalizzato. Crea un nuovo file plugin.cfg nella cartella addons/my_custom_dock, quindi aggiungi il seguente contenuto:

[plugin]

name="My Custom Dock"
description="A custom dock made so I can learn how to make plugins."
author="Your Name Here"
version="1.0"
script="custom_dock.gd"

[plugin]

name="My Custom Dock"
description="A custom dock made so I can learn how to make plugins."
author="Your Name Here"
version="1.0"
script="CustomDock.cs"

Poi crea lo script custom_dock.gd nella stessa cartella. Riempilo con il modello che abbiamo visto prima per cominciare bene.

Dato che stiamo cercando di aggiungere un nuovo pannello personalizzato, dobbiamo crearne il contenuto. Questa non è altro che una scena standard di Godot: basta creare una nuova scena nell'editor e modificarla.

Per un pannello dell'editor, il nodo radice deve essere un Control o una delle sue classi figlie. Per questo tutorial, puoi creare un singolo pulsante. Inoltre, non dimenticare di aggiungere del testo al pulsante.

../../../_images/making_plugins-my_custom_dock_scene.webp

Salva questa scena come my_dock.tscn. Ora dobbiamo ricavare la scena che abbiamo creato e aggiungerla come pannello nell'editor. Per farlo, possiamo usare la funzione add_dock() dalla classe EditorPlugin.

Devi selezionare una posizione per il pannello e definire il controllo da aggiungere (ovvero la scena appena creata). Non dimenticare di rimuovere il pannello quando l'estensione è disattivata. Lo script potrebbe apparire così:

@tool
extends EditorPlugin


# A class member to hold the dock during the plugin life cycle.
var dock


func _enter_tree():
    # Initialization of the plugin goes here.
    # Load the dock scene and instantiate it.
    var dock_scene = preload("res://addons/my_custom_dock/my_dock.tscn").instantiate()

    # Create the dock and add the loaded scene to it.
    dock = EditorDock.new()
    dock.add_child(dock_scene)

    dock.title = "My Dock"

    # Note that LEFT_UL means the left of the editor, upper-left dock.
    dock.default_slot = DOCK_SLOT_LEFT_UL

    # Allow the dock to be on the left or right of the editor, and to be made floating.
    dock.available_layouts = EditorDock.DOCK_LAYOUT_VERTICAL | EditorDock.DOCK_LAYOUT_FLOATING

    add_dock(dock)


func _exit_tree():
    # Clean-up of the plugin goes here.
    # Remove the dock.
    remove_dock(dock)
    # Erase the control from the memory.
    dock.queue_free()

#if TOOLS
using Godot;

[Tool]
public partial class CustomDock : EditorPlugin
{
    private EditorDock _dock;

    public override void _EnterTree()
    {
        var _dock_scene = GD.Load<PackedScene>("res://addons/MyCustomDock/MyDock.tscn").Instantiate<Control>();

        // Create the dock and add the loaded scene to it.
        _dock = new EditorDock();
        _dock.AddChild(dock_scene);

        _dock.Title = "My Dock";

        // Note that LeftUl means the left of the editor, upper-left dock.
        _dock.DefaultSlot = DockSlot.LeftUl;

        // Allow the dock to be on the left or right of the editor, and to be made floating.
        _dock.AvailableLayouts = DockLayout.Horizontal | DockLayout.Floating;

        AddDock(_dock);
    }

    public override void _ExitTree()
    {
        // Clean-up of the plugin goes here.
        // Remove the dock.
        RemoveDock(_dock);
        // Erase the control from the memory.
        _dock.QueueFree();
    }
}
#endif

Nota che, sebbene il pannello inizialmente apparirà nella posizione specificata, l'utente può cambiarne liberamente la posizione e salvare il layout risultante.

Verifica dei risultati

Ora è il momento di verificare i risultati del tuo lavoro. Apri le Impostazioni del progetto e clicca sulla scheda Estensioni. La tua estensione dovrebbe essere l'unica nell'elenco.

../../../_images/making_plugins-project_settings.webp

Come puoi vedere, l'estensione non è abilitato. Clicca sulla casella di spunta Abilita per attivarla. Il pannello dovrebbe diventare visibile prima ancora di chiudere la finestra delle impostazioni. Ora dovresti avere un pannello personalizzato:

../../../_images/making_plugins-custom_dock.webp

Registrare autoload/singleton nelle estensioni

È possibile alle estensioni dell'editor di registrare automaticamente gli autoload quando l'estensione è attivata. Ciò include anche la rimozione dell'autoload quando l'estensione è disattivata.

Ciò rende più veloce configurare le estensioni per gli utenti, poiché non devono più aggiungere manualmente gli autoload nelle impostazioni del progetto se l'estensione dell'editor richiede l'uso di un autoload.

Utilizzare il seguente codice per registrare un singleton da un'estensione dell'editor:

@tool
extends EditorPlugin

# Replace this value with a PascalCase autoload name, as per the GDScript style guide.
const AUTOLOAD_NAME = "SomeAutoload"


func _enable_plugin():
    # The autoload can be a scene or script file.
    add_autoload_singleton(AUTOLOAD_NAME, "res://addons/my_addon/some_autoload.tscn")


func _disable_plugin():
    remove_autoload_singleton(AUTOLOAD_NAME)

#if TOOLS
using Godot;

[Tool]
public partial class MyEditorPlugin : EditorPlugin
{
    // Replace this value with a PascalCase autoload name.
    private const string AutoloadName = "SomeAutoload";

    public override void _EnablePlugin()
    {
        // The autoload can be a scene or script file.
        AddAutoloadSingleton(AutoloadName, "res://addons/MyAddon/SomeAutoload.tscn");
    }

    public override void _DisablePlugin()
    {
        RemoveAutoloadSingleton(AutoloadName);
    }
}
#endif

Utilizzo di sotto-estensioni

Spesso un'estensione aggiunge più elementi, ad esempio un nodo personalizzato e un pannello. In questi casi potrebbe essere più semplice avere uno script di estensione separato per ciascuna di queste funzionalità. È possibile utilizzare delle sotto-estensioni per questo.

Per prima cosa crea tutte le estensioni e le sotto-estensioni come estensioni normali:

../../../_images/sub_plugin_creation.webp

Quindi sposta le sotto-estensioni nella cartella principale delle estensioni:

Godot nasconderà le sotto-estensioni dall'elenco delle estensioni, affinché l'utente non possa abilitarli o disabilitarli. Invece, lo script dell'estensione principale dovrebbe abilitare e disabilitare le sotto-estensioni in questo modo:

@tool
extends EditorPlugin

# The main plugin is located at res://addons/my_plugin/
const PLUGIN_NAME = "my_plugin"

func _enable_plugin():
    EditorInterface.set_plugin_enabled(PLUGIN_NAME + "/node", true)
    EditorInterface.set_plugin_enabled(PLUGIN_NAME + "/panel", true)

func _disable_plugin():
    EditorInterface.set_plugin_enabled(PLUGIN_NAME + "/node", false)
    EditorInterface.set_plugin_enabled(PLUGIN_NAME + "/panel", false)

Andare oltre

Ora che hai imparato a creare estensioni basilari, puoi estendere l'editor in diversi modi. è possibile aggiungere numerose funzionalità all'editor tramite GDScript; è un modo potente per creare editor specializzati senza dover approfondire i moduli C++.

Puoi creare le tue proprie estensioni per aiutare te stesso, e condividerle nella Libreria dei contenuti così che altre persone possano usufruire del tuo lavoro.