Making plugins

    This tutorial will guide you through the creation of two simple plugins so you can understand how they work and be able to develop your own. The first will be a custom node that you can add to any scene in the project and the other will be a custom dock added to the editor.

    Before starting, create a new empty project wherever you want. This will serve as a base to develop and test the plugins.

    The first thing you need for the editor to identify a new plugin is to create two files: a for configuration and a tool script with the functionality. Plugins have a standard path like addons/plugin_name inside the project folder. Godot provides a dialog for generating those files and placing them where they need to be.

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

    You will see the dialog appear, like so:

    The placeholder text in each field describes how it affects the plugin’s creation of the files and the config file’s values.

    To continue with the example, use the following values:

    You should end up with a directory structure like this:

    ../../../_images/making_plugins-my_custom_mode_folder.png

    plugin.cfg is a simple INI file with metadata about your plugin. The name and description help people understand what it does. Your name helps you get properly credited for your work. The version number helps others know if they have an outdated version; if you are unsure on how to come up with the version number, check out Semantic Versioning. The main script file will instruct Godot what your plugin does in the editor once it is active.

    Upon creation of the plugin, the dialog will automatically open the EditorPlugin script for you. The script has two requirements that you cannot change: it must be a tool script, or else it will not load properly in the editor, and it must inherit from EditorPlugin.

    Warning

    In addition to the EditorPlugin script, any other GDScript that your plugin uses must also be a tool. Any GDScript without tool imported into the editor will act like an empty file!

    It’s important to deal with initialization and clean-up of resources. A good practice is to use the virtual function to initialize your plugin and _exit_tree() to clean it up. Thankfully, the dialog generates these callbacks for you. Your script should look something like this:

    1. tool
    2. extends EditorPlugin
    5. func _enter_tree():
    6.     # Initialization of the plugin goes here.
    7.     pass
    10. func _exit_tree():
    11.     # Clean-up of the plugin goes here.
    12.     pass
    1. #if TOOLS
    2. using Godot;
    3. using System;
    5. [Tool]
    6. public class CustomNode : EditorPlugin
    7. {
    8.     public override void _EnterTree()
    9.     {
    10.         // Initialization of the plugin goes here.
    11.     }
    13.     public override void _ExitTree()
    14.     {
    15.         // Clean-up of the plugin goes here.
    16. }

    This is a good template to use when creating new plugins.

    Sometimes you want a certain behavior in many nodes, such as a custom scene or control that can be reused. Instancing is helpful in a lot of cases, but sometimes it can be cumbersome, especially if you’re using it in many projects. A good solution to this is to make a plugin that adds a node with a custom behavior.

    Warning

    Nodes added via an EditorPlugin are “CustomType” nodes. While they work with any scripting language, they have fewer features than the Script Class system. If you are writing GDScript or NativeScript, we recommend using Script Classes instead.

    To create a new node type, you can use the function from the EditorPlugin class. This function can add new types to the editor (nodes or resources). However, before you can create the type, you need a script that will act as the logic for the type. While that script doesn’t have to use the tool keyword, it can be added so the script runs in the editor.

    For this tutorial, we’ll create a simple button that prints a message when clicked. For that, we’ll need a simple script that extends from . It could also extend BaseButton if you prefer:

    GDScript   C#

    1. using Godot;
    2. using System;
    4. [Tool]
    5. public class MyButton : Button
    6. {
    7.     public override void _EnterTree()
    8.     {
    9.         Connect("pressed", this, "clicked");
    10.     }
    12.     public void clicked()
    13.     {
    14.         GD.Print("You clicked me!");
    15.     }
    16. }

    That’s it for our basic button. You can save this as my_button.gd inside the plugin folder. You’ll also need 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.png, or use the default Godot logo (preload(“res://icon.png”)). You can also use SVG icons if desired.

    Now, we need to add it as a custom type so it shows on the Create New Node dialog. For that, change the custom_node.gd script to the following:

    GDScript   C#

    1. tool
    2. extends EditorPlugin
    5. func _enter_tree():
    6.     # Initialization of the plugin goes here.
    7.     # Add the new type with a name, a parent type, a script and an icon.
    8.     add_custom_type("MyButton", "Button", preload("my_button.gd"), preload("icon.png"))
    11. func _exit_tree():
    12.     # Clean-up of the plugin goes here.
    13.     # Always remember to remove it from the engine when deactivated.
    14.     remove_custom_type("MyButton")

    With that done, the plugin should already be available in the plugin list in the Project Settings, so activate it as explained in .

    Then try it out by adding your new node:

    ../../../_images/making_plugins-custom_node_create.png

    When you add the node, you can see that it already has the script you created attached to it. Set a text to the button, save and run the scene. When you click the button, you can see some text in the console:

    Sometimes, you need to extend the editor and add tools that are always available. An easy way to do it is to add a new dock with a plugin. Docks are just scenes based on Control, so they are created in a way similar to usual GUI scenes.

    Creating a custom dock is done just like a custom node. Create a new plugin.cfg file in the addons/my_custom_dock folder, then add the following content to it:

    GDScript   C#

    1. [plugin]
    3. description="A custom dock made so I can learn how to make plugins."
    4. author="Your Name Here"
    5. version="1.0"
    6. script="custom_dock.gd"
    1. [plugin]
    3. name="My Custom Dock"
    4. description="A custom dock made so I can learn how to make plugins."
    5. author="Your Name Here"
    6. version="1.0"
    7. script="CustomDock.cs"

    Then create the script custom_dock.gd in the same folder. Fill it with the to get a good start.

    Since we’re trying to add a new custom dock, we need to create the contents of the dock. This is nothing more than a standard Godot scene: just create a new scene in the editor then edit it.

    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. The name of the root node will also be the name that appears on the dock tab, so be sure to give it a short and descriptive name. Also, don’t forget to add some text to your button.

    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 from the EditorPlugin class.

    You need to select a dock position and define the control to add (which is the scene you just created). Don’t forget to remove the dock when the plugin is deactivated. The script could look like this:

    GDScript   C#

    1. #if TOOLS
    2. using Godot;
    3. using System;
    5. [Tool]
    6. public class CustomDock : EditorPlugin
    7. {
    8.     Control dock;
    10.     public override void _EnterTree()
    11.     {
    12.         dock = (Control)GD.Load<PackedScene>("addons/my_custom_dock/my_dock.tscn").Instance();
    13.         AddControlToDock(DockSlot.LeftUl, dock);
    14.     }
    16.     public override void _ExitTree()
    17.     {
    18.         // Clean-up of the plugin goes here.
    19.         // Remove the dock.
    20.         RemoveControlFromDocks(dock);
    21.         // Erase the control from the memory.
    22.         dock.Free();
    23.     }

    Note that, while the dock will initially appear at its specified position, the user can freely change its position and save the resulting layout.

    It’s now time to check the results of your work. Open the Project Settings and click on the Plugins tab. Your plugin should be the only one on the list. If it is not showing, click on the Update button in the top-right corner.

    ../../../_images/making_plugins-project_settings.png

    You can see the plugin is inactive on the Status column; click on the status to select Active. The dock should become visible before you even close the settings window. You should now have a custom dock:

    You can make your own plugins to help yourself and share them in the so that people can benefit from your work.