Plugins are a convenient way to enhance the functionality of Godot’s editor without much effort. They allow you to add custom tools, shortcuts, and menu items to improve 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 that you are familiar with Godot’s editor and have a good understanding of GDScript.
Getting Started
To begin, download the project materials by clicking on the “Download Materials” link at the top and bottom of this page. Then, open the EditorPlugins project located in the starter folder and open it in Godot.
Before diving into plugins, let’s take a quick tour of the project. It contains a single scene called main.tscn and some sprites. Open the main scene and examine the nodes within it. You’ll see a collection of StaticBody2D and RigidBody2D nodes that create a non-interactive physics scene. If you look at the Scene dock, you’ll notice that the nodes are named according to their function. Only the top-level nodes can be selected and moved, while their children are locked to prevent accidental movement of collision shapes and sprites.
Now, run the project by pressing F5 and observe what happens. Shortly after running the project, you’ll see a blue avatar falling onto a red box, while another red box falls off a platform. The focus of this project is not on gameplay, but on extending the editor.
Now that you are familiar with the scene, let’s 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 is no need to recompile the engine for them to work. In addition to the main plugin script, you can add scenes and extra scripts to the plugin to make it even more versatile. These work just like the rest of your project, so you can leverage your existing knowledge of Godot to extend it! Plugins can be used to add buttons, shortcuts, and even entire 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
– Add custom resource importers
– Create your own node types
– Automatically generate colliders of the right size for sprites
These are just a few ideas to give you a sense of what you can achieve with plugins. If you have ever wished for a specific feature in Godot, chances are you can find it in a plugin or create your own.
Creating Your First Plugin
For your first plugin, you will add a button to the toolbar that toggles the visibility of a selected node.
Scaffolding
Plugins require three things to work:
1. They need to be in a folder named “addons” in the root of the project.
2. They need a file named “plugin.cfg” containing the metadata.
3. They need at least one script that derives from “EditorPlugin”.
Thankfully, Godot makes it easy to create new plugins directly within the editor. To get started, open the Project Settings by selecting “Project” -> “Project Settings” in the top menu. Then, go to the Plugins tab, where you will see an empty list.
Click on the “Create New Plugin” button, and a dialog window titled “Create a Plugin” will appear. Godot will automatically generate the necessary files based on the information you provide. 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
Click the “Create” button to let Godot create the required files for you. This will also automatically open the “visibility_button.gd” script in the script editor.
Before we make any changes to the script, take a look at the files and folders that Godot has created for you in the FileSystem dock. You will notice a new folder named “addons” that contains a folder for the plugin named “visibility_button”. Inside this folder, there is a file named “plugin.cfg” and a script named “visibility_button.gd”. The “plugin.cfg” file contains the metadata for the plugin, while the “visibility_button.gd” script contains the actual code.
Note: You might wonder why the “addons” folder is not named “plugins”. In Godot, “addons” can refer to extensions that enhance the functionality of the editor but are not specifically editor plugins. Editor plugins, on the other hand, use a script that derives from “EditorPlugin”.
Enough scaffolding, let’s take a closer look at the code!
Taking a Closer Look
The “visibility_button.gd” script generated by Godot contains the following code:
“`gd
@tool
extends EditorPlugin
func _enter_tree() -> void:
# Initialization of the plugin goes here.
pass
func _exit_tree() -> void:
# Clean-up of the plugin goes here.
pass
“`
I have added some numbered comments to make it easier to explain each line:
1. The `@tool` annotation turns a regular script into a tool script. This means that any code in the script will be executed within the editor. This can be powerful, but it also means that you can accidentally break scenes if you are not careful. You will learn more about the `@tool` annotation in another article. In the meantime, you can check out the “Running code in the editor” page in Godot’s documentation to learn more about it.
2. All editor plugins must inherit from `EditorPlugin`. This class provides many useful functions for accessing and modifying Godot’s editor.
3. The `_enter_tree` function is called when you activate the plugin. This is where you can set up any necessary variables and references for later use.
4. The `_exit_tree` function is called when you disable the plugin. This is where you can clean up any references.
Handling Node Selection
For the visibility button plugin, you don’t need the `_enter_tree` and `_exit_tree` functions, so you can delete them. Initialization and cleanup will be handled through other functions.
Now, add the following function below the deleted ones:
“`gd
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 works with nodes, so it returns `true` if the selected object is of the `Node` class or any of its subclasses.
You will need to keep track of the selected node yourself, so add a new variable named `node_to_edit` above the `_handles` function:
“`gd
var node_to_edit : Node
“`
With this variable in place, add the following `_edit` function below the `_handles` function:
“`gd
func _edit(object: Object) -> void:
if !object:
return
node_to_edit = object
“`
The `_edit` function is called by Godot immediately after the `_handles` function returns `true`. It informs 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 in the `_edit` function:
1. The `_edit` function receives the selected object as a parameter, which is a `Node` in the case of this plugin.
2. There is a possibility that the selected object is `null`, so you need to check if it’s not. If it is `null`, return from the function and do nothing.
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:
“`gd
print(node_to_edit)
“`
Save the script and try selecting some nodes in the scene tree. You should see the name of the selected node printed in the console. As you can see, the plugin is already functioning!
Note: When you select a root node like “Main” in this case, the `_edit` function will be called twice. However, this won’t affect the functionality of the plugin.
Now, remove or comment out the `print` statement you added and save the script again.
The final function to bring everything together is the `_make_visible` function. Add it below the `_edit` function:
“`gd
func _make_visible(visible: bool) -> void:
if visible:
_add_button()
else:
_remove_button()
“`
Similar to the `_edit` function, Godot calls the `_make_visible` function after the `_handles` function returns `true`. It passes a boolean parameter indicating whether the plugin should be visible or hidden.
In this case, if the plugin should be visible, the `_add_button` function is called. Otherwise, the `_remove_button` function is called.
And that’s it! You have created a basic plugin that adds a visibility button to the toolbar.
Source link
