Extending the Editor with Plugins in Godot
- Getting Started
- Plugin Overview
- Creating Your First Plugin
- Taking a Closer Look
- Handling Node Selection
- Adding the Button
- Developing an Advanced Plugin
- Creating the Menu Scene
- Loading and Unloading the Menu
- Getting Selected Nodes
- 2D Physics in Godot
- Starting and Stopping Physics
- Custom Physics Spaces
- Physics Frames
- Adding Quality of Life Features
- Where to Go From Here?
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.
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!
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.
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
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.
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.
func _exit_tree() -> void: # 4
# Clean-up of the plugin goes here.
I took the liberty to add some numbered comments to make it easier to explain what each line does:
@toolannotation 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
@toolannotation 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.
- All editor plugins must inherit from
EditorPlugin. This class comes with a ton of useful functions to access and edit Godot’s editor.
_enter_treefunction is called when you activate the plugin. This where you set up all needed variables and references for later use.
_exit_treefunction 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
_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
var node_to_edit : Node
With this variable in place, add the
_edit function below the
func _edit(object: Object) -> void: # 1
if !object: # 2
node_to_edit = object # 3
_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:
_editfunction gets passed the selected object, a
Nodein case of this plugin.
- 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.
- 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
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!
_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
func _make_visible(visible: bool) -> void: # 1
if visible: # 2
else: # 3
_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
_exit_tree functions for initialization and cleanup.
Here’s the code above in more detail:
_make_visiblefunction gets passed a boolean value,
visibleto tell the UI to show or hide.
true, add the button to the toolbar via the
false, remove the button from the toolbar via the
After adding the code, you’ll get some errors as you haven’t added the
_remove_button functions yet. Add these empty functions to get rid of the errors:
func _add_button() -> void:
func _remove_button() -> void:
These will act as placeholders for now. In the next section you’ll add the logic.