Extending the Editor with Plugins in Godot

Plugins are a great way to add functionality to Godot’s editor with minimal effort. They allow you to add features like custom tools, useful shortcuts, and menu items to speed up your workflow. This article will guide you through the process of creating your own plugins to unlock the full potential of Godot.

Note: This article assumes you’re familiar with Godot’s editor and have a good understanding of GDScript.

Getting Started

To get started, download the project materials via the Download Materials link at the top and bottom of this page. Next, open the EditorPlugins project you find in the starter folder and open it in Godot.
Before delving into plugins, I’ll give a quick tour of the project. It comes with a single scene named main.tscn and some sprites. Open the main scene and take a look at the nodes inside.

There’s a collection of StaticBody2D and RigidBody2D nodes here that make up a non-interactive physics scene. If you direct your attention to the Scene dock, you’ll see there are all named according to their function.

Notice that only the top level nodes can be selected and moved, while their children are locked. This is intentional to avoid moving the collision shapes and sprites by themselves by accident.

Now try running the project by pressing F5 and see what happens.

Shortly after running the project, you’ll see the little blue avatar falling down on a red box, while the other red box falls off a platform. There’s no actual gameplay involved here as the focus is on extending the editor.
Now you know your way around the scene, it’s time to learn about plugins!

Plugin Overview

In Godot, plugins are scripts that extend the functionality of the editor. You can write these scripts using GDScript or C# and there’s no need to recompile the engine to make them work. Besides the main plugin script, you can add scenes and extra scripts to the plugin to make it even more versatile. These work the same way like the rest of your project, meaning you can use your existing knowledge of Godot to extend it!

You can use plugins to add buttons, shortcuts and even whole new screens to the editor. Here are some examples of what you can do with plugins:

• Create a conversation manager
• Integrate Google Sheets into your project to load data from
• Add custom resource importers
• Make your own node types
• Automatically create the right size of colliders for sprites

These are just a handful of ideas to give you a taste of what you can do with plugins. If you ever thought about a feature you’d want in Godot, there’s a good chance you can find it in a plugin or create your own.

Creating Your First Plugin

For your first plugin, you’ll add a button to the toolbar that toggles the visibility of a selected node.

Scaffolding

Plugins need three things to work:

Thankfully, Godot makes it easy to create new plugins as it’s built into the editor. To get started, open the Project Settings via Project ▸ Project Settings… in the top menu. Now select the Plugins tab and you should see an empty list.

• They need to be in a folder named addons in the root of the project
• They need a file named plugin.cfg containing the metadata
• They need at least one script that derives from EditorPlugin

Now click the Create New Plugin button and the Create a Plugin dialog window will pop up.

Godot will create the necessary files for you based on the information you provide, pretty neat! For this visibility button plugin, fill in the following information:

• Plugin Name: Visibility Button
• Subfolder: visibility_button
• Description: Easily show and hide a selected node.
• Author: Your name or username
• Script Name: visibility_button.gd

Here’s what it should look like:

Next, click the Create button to let Godot create the necessary files for you. This will also automatically open the visibility_button.gd script in the script editor.
Before editing the script, take a look at the files and folders Godot has created for you in the FileSystem dock.

There’s a new folder named addons now that contains a folder for the plugin named visibility_button. Inside that folder, there’s a file named plugin.cfg and a script named visibility_button.gd. plugin.cfg contains the metadata for the plugin, while the script contains the actual code.

Note: You may be wondering why the addons folder isn’t named plugins instead. In Godot, it’s possible to add add-ons that extend the functionality of the editor, but aren’t plugins. Plugins are editor plugins specifically, which use a script that derives from EditorPlugin.

Enough scaffolding, time to take a look at the code!

Taking a Closer Look

The visibility_button.gd script that Godot generated for you contains the following code:

@tool # 1
extends EditorPlugin # 2


func _enter_tree() -> void: # 3
    # Initialization of the plugin goes here.
    pass


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

I took the liberty to add some numbered comments to make it easier to explain what each line does:

1. The @tool annotation turns a regular script into a tool script. This means that any code in the script will be executed in the editor. This is powerful, but it also makes it easy to break entire scenes when not careful. You’ll learn more about the @tool annotation in another article. If you want to know more about it in the meantime, check out the Running code in the editor page of Godot’s documentation.
2. All editor plugins must inherit from EditorPlugin. This class comes with a ton of useful functions to access and edit Godot’s editor.
3. The _enter_tree function is called when you activate the plugin. This where you set up all needed variables and references for later use.
4. The _exit_tree function is called when you disable the plugin. This is where you clean up all references.

Handling Node Selection

For the visibility button plugin, you won’t need the _enter_tree and _exit_tree functions so delete them. You’ll be handling the initialization and cleanup with other functions. Now add the function below in the place of the removed ones:

func _handles(object) -> bool:
    return object is Node

Godot calls the _handles function when you select an object. The Object class is the base class for all other classes in Godot. This function returns true if the selected object can be handled by your plugin. In this case, the plugin only edits nodes, so it returns true if the selected object is a Node class, or derives from it.

You’ll need to keep track of the selected node yourself, so add a new variable above the _handles function named node_to_edit:

var node_to_edit : Node

With this variable in place, add the _edit function below the _handles function:

func _edit(object: Object) -> void: # 1
    if !object: # 2
        return

    node_to_edit = object # 3

The _edit function is called by Godot right after the _handles function returns true. It requests the editor to edit the given object and it’s the perfect place to store a reference to the selected object. Here’s an overview of what’s happening here:

1. The _edit function gets passed the selected object, a Node in case of this plugin.
2. There’s a possibility that the selected object is null, so you need to check if it’s not. If it’s null, return from the function and don’t do anything.
3. Store a reference to the selected object for later use.

To check if this code is working correctly, add a temporary print statement at the end of the _edit function:

print(node_to_edit)

Now save the script and try selecting some nodes in the scene tree. You should see the name of the selected node in the console.

As you can see, the plugin already works!

Note: When you select a root node like Main in this case, the console will call _edit twice. Thankfully, this won’t affect the functionality of the plugin.

Now remove or comment out the print statement you’ve added and save the script again. The last function to bring it all together is the _make_visible function, add it below the _edit function:

func _make_visible(visible: bool) -> void: # 1
    if visible: # 2
        _add_button()
    else: # 3
        _remove_button()

Like the _edit function, Godot calls the _make_visible function after the _handles function returns true. It handles the showing and hiding of the plugin UI. It also gets called when disabling the plugin. When showing the button, you’ll create it and add it to the toolbar. When hiding the button, you’ll remove it from the toolbar and destroy it. This is an alternative to using the _enter_tree and _exit_tree functions for initialization and cleanup.
Here’s the code above in more detail:

1. The _make_visible function gets passed a boolean value, visible to tell the UI to show or hide.
2. If visible is true, add the button to the toolbar via the _add_button function.
3. If visible is false, remove the button from the toolbar via the _remove_button function.

After adding the code, you’ll get some errors as you haven’t added the _add_button and _remove_button functions yet. Add these empty functions to get rid of the errors:

func _add_button() -> void:
    pass


func _remove_button() -> void:
    pass

These will act as placeholders for now. In the next section you’ll add the logic.