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

Erstellen von Plugins

Über Plugins

Ein Plugin ist eine Möglichkeit, dem Editor weitere nützliche Tools hinzuzufügen. Dies kann nur durch GDScript und Standard-Szenen erfolgen, ohne überhaupt den Editor neu starten zu müssen. Im Gegensatz zu Modulen muss kein C++ Programm geschrieben, oder der Editor neu kompiliert werden. Dies macht Plugins zwar weniger leistungsfähig, man kann aber noch immer viel damit anfangen. Solch eine Erweiterung ist ähnlich wie eine Szene, die man erzeugen kann, mit der Ausnahme, daß es mittels eines Skripts die Editor-Funktionalität erweitert.

Dieses Tutorial wird Sie durch die Erstellung von zwei Plugins führen, damit Sie verstehen, wie sie funktionieren, und in der Lage sind, Ihre eigenen zu entwickeln. Das erste ist ein benutzerdefinierter Node, den Sie zu jeder Szene im Projekt hinzufügen können, und das andere ist ein benutzerdefiniertes Dock, das dem Editor hinzugefügt wird.

Erstellen eines Plugins

Bevor es losgeht, erstellen Sie ein neues leeres Projekt wo Sie möchten. Dies wird der Grundstein zum Entwickeln und Testen des Plugins.

Damit der Editor das neue Plugin erkennt, müssen zwei Dateien erstellt werden: eine plugin.cfg zur Konfiguration und ein Skript mit der Funktionalität. Plugins haben einen Standard-Pfad wie addons/plugin_name innerhalb des Projektverzeichnisses. Godot stellt einen Dialog zur Verfügung um diese Dateien zu erzeugen und sie an der richtigen Stelle zu speichern.

In the main toolbar, click the Project dropdown. Then click Project Settings.... Go to the Plugins tab and then click on the Create New Plugin button in the top-right.

Der Dialog wird wie folgt angezeigt:

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

Der Platzhaltertext in jedem Feld beschreibt, wie es sich auf die Erstellung der Dateien durch das Plugin und die Werte der Konfigurationsdatei auswirkt.

Um mit dem Beispiel fortzufahren, verwenden Sie die folgenden Werte:

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

Warnung

In C#, the EditorPlugin script needs to be compiled, which requires building the project. After building the project the plugin can be enabled in the Plugins tab of Project Settings.

Die Verzeichnisstruktur sollte am Ende so aussehen:

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

Die Datei plugin.cfg ist eine INI-Datei mit Metadaten über Ihr Plugin. Der Name und die Beschreibung helfen den Leuten zu verstehen, was es tut. Ihr Name hilft Ihnen, für Ihre Arbeit zitiert zu werden. Die Versionsnummer hilft anderen, zu erkennen, ob sie eine veraltete Version haben; wenn Sie sich nicht sicher sind, wie Sie die Versionsnummer herausfinden können, lesen Sie Semantic Versioning. Die Hauptskriptdatei teilt Godot mit, was Ihr Plugin im Editor macht, sobald es aktiv ist.

Die Skript-Datei

Bei der Erstellung des Plugins wird der Dialog automatisch das EditorPlugin-Skript für Sie öffnen. Das Skript hat zwei Anforderungen, die Sie nicht ändern können: Es muss ein @tool-Skript sein, sonst wird es nicht richtig im Editor geladen, und es muss von EditorPlugin erben.

Warnung

Neben dem EditorPlugin-Skript muss auch jedes andere GDSkript, das Ihr Plugin verwendet, auch ein Tool sein. Jedes GDScript ohne @tool, das vom Editor verwendet wird, verhält sich wie eine leere Datei!

Es ist wichtig, sich mit der Initialisierung und dem Aufräumen von Ressourcen zu befassen. Eine gute Praxis ist es, die virtuelle Funktion _enter_tree() zu verwenden, um Ihr Plugin zu initialisieren und _exit_tree(), um es zu löschen. Glücklicherweise generiert der Dialog diese Callbacks für Sie. Ihr Skript sollte in etwa wie folgt aussehen:

@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

Dies ist eine gute Vorlage, um neue Plugins zu erstellen.

Ein benutzerdefinierter Node

Manchmal möchten Sie ein bestimmtes Verhalten in vielen Nodes, z.B. in einer benutzerdefinierten Szene oder einem Control, das wiederverwendet werden kann. Die Instanziierung ist in vielen Fällen hilfreich, kann jedoch manchmal umständlich sein, insbesondere wenn Sie sie in vielen Projekten verwenden. Eine gute Lösung hierfür besteht darin, ein Plugin zu erstellen, das einen Node mit einem benutzerdefinierten Verhalten hinzufügt.

In diesem Tutorial werden wir einen Button erstellen, der eine Nachricht ausgibt, wenn er angeklickt wird. Dafür brauchen wir ein Skript, das von Button ausgeht. Es könnte auch BaseButton erweitern, wenn Sie das bevorzugen:

# 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")).

Tipp

Bei SVG-Bildern, die als benutzerdefinierte Node-Icons verwendet werden, sollten die Optionen Editor > Mit Editor-Skalierung skalieren und Editor > Farben mit Editor-Theme konvertieren Importoptionen aktiviert sein. Dies ermöglicht es den Icons, den Skalierungs- und Theme-Einstellungen des Editors zu folgen, wenn die Icons mit der gleichen Farbpalette wie die Godot-eigenen Icons gestaltet sind.

Danach sollte das Plugin bereits in der Plugin-Liste in den Projekteinstellungen verfügbar sein. Aktivieren Sie es, wie unter Überprüfen der Ergebnisse beschrieben.

Probieren Sie es dann aus, indem Sie Ihren neuen Node hinzufügen:

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

Wenn Sie den Node hinzufügen, können Sie sehen, dass ihm bereits das von Ihnen erstellte Skript angehängt ist. Setzen Sie einen Text auf den Button, speichern Sie die Szene und führen Sie sie aus. Wenn Sie auf den Button klicken, wird in der Konsole ein Text angezeigt:

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

Ein benutzerdefiniertes Dock

Manchmal müssen Sie den Editor erweitern und Tools hinzufügen, die immer verfügbar sind. Eine einfache Möglichkeit besteht darin, ein neues Dock mit einem Plugin hinzuzufügen. Docks sind nur Szenen, die auf Control basieren. Sie werden also ähnlich wie normale GUI-Szenen erstellt.

Das Erstellen eines benutzerdefinierten Docks erfolgt genauso wie das Erstellen eines benutzerdefinierten Nodes. Erstellen Sie eine neue Datei plugin.cfg im Ordner addons/my_custom_dock und fügen Sie ihr den folgenden Inhalt hinzu:

[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"

Dann erstellen Sie das Skript custom_dock.gd im gleichen Ordner. Füllen Sie es mit der Vorlage, die wir schon gesehen haben, um einen guten Start zu bekommen.

Da wir versuchen ein neues benutzerdefiniertes Dock hinzuzufügen, müssen wir den Inhalt des Docks erstellen. Dies ist nichts weiter als eine Standard-Godot-Szene: Erstellen Sie einfach eine neue Szene im Editor und bearbeiten diese.

For an editor dock, the root node must be a Control or one of its child classes. For this tutorial, you can create a single button. Don't forget to add some text to your button.

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

Save this scene as my_dock.tscn. Now, we need to grab the scene we created then add it as a dock in the editor. For this, you can rely on the function add_dock() from the EditorPlugin class.

Sie müssen eine Dock-Position auswählen und das hinzuzufügende Control definieren (das ist die Szene, die Sie gerade erstellt haben). Vergessen Sie nicht, das Dock zu entfernen, wenn das Plugin deaktiviert ist. Das Skript könnte wie folgt aussehen:

@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

Beachten Sie, dass das Dock zwar zunächst an der angegebenen Position erscheint, der Benutzer aber seine Position frei ändern und das resultierende Layout speichern kann.

Überprüfen der Ergebnisse

Nun ist es an der Zeit, die Ergebnisse Ihrer Arbeit zu überprüfen. Öffnen Sie die Projekteinstellungen und klicken Sie auf das Plugins-Tab. Ihr Plugin sollte das einzige in der Liste sein.

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

Sie können sehen, dass das Plugin nicht aktiviert ist. Klicken Sie auf die Checkbox Aktivieren, um das Plugin zu aktivieren. Das Dock sollte sichtbar werden, noch bevor Sie das Einstellungsfenster schließen. Sie sollten jetzt ein benutzerdefiniertes Dock haben:

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

Registrierung von Autoloads/Singletons in Plugins

Es ist möglich, dass sich Editor-Plugins automatisch autoloads registrieren, wenn das Plugin aktiviert wird. Dies beinhaltet auch die Aufhebung der Registrierung des Autoloads, wenn das Plugin deaktiviert wird.

Dies beschleunigt die Einrichtung von Plugins für die Benutzer, da sie nicht mehr manuell Autoloads zu ihren Projekteinstellungen hinzufügen müssen, wenn Ihr Editor-Plugin die Verwendung eines Autoloads erfordert.

Verwenden Sie den folgenden Code, um ein Singleton aus einem Editor-Plugin zu registrieren:

@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

Using sub-plugins

Often a plugin adds multiple things, for example a custom node and a panel. In those cases it might be easier to have a separate plugin script for each of those features. Sub-plugins can be used for this.

First create all plugins and sub plugins as normal plugins:

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

Then move the sub plugins into the main plugin folder:

Godot will hide sub-plugins from the plugin list, so that a user can't enable or disable them. Instead the main plugin script should enable and disable sub-plugins like this:

@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)

Darüber hinausgehen

Nachdem Sie nun gelernt haben, wie Sie grundlegende Plugins erstellen, können Sie den Editor auf verschiedene Arten erweitern. Mit GDScript können dem Editor viele Funktionen hinzugefügt werden. Es ist eine leistungsstarke Möglichkeit, spezialisierte Editoren zu erstellen, ohne sich mit C++ Modulen befassen zu müssen.

Sie können Ihre eigenen Plugins erstellen, um sich selbst zu helfen, und diese in der Asset-Bibliothek teilen, damit Andere von Ihrer Arbeit profitieren können.