A plugin is a great way to extend the editor with useful tools. It can be made entirely with GDScript and standard scenes, without even reloading the editor. Unlike modules, you don’t need to create C++ code nor recompile the engine. While this makes plugins less powerful, there are still many things you can do with them. Note that a plugin is similar to any scene you can already make, except it is created using a script to add editor functionality.
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
plugin.cfg for configuration and a tool script with the
functionality. Plugins have a standard path like
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
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:
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 Activate now: No
You should end up with a directory structure like this:
plugin.cfg is a simple INI file with metadata about your plugin.
The name and description help people undersatnd 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 class_EditorPlugin.
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 _enter_tree() 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:
有时您希望在许多节点中存在某种行为，例如可以重复使用的自定义场景或控件。 实例化在很多情况下都很有用，但有时它会很麻烦，特别是如果您在许多项目中使用它。 一个很好的解决方案是创建一个插件，添加一个具有自定义行为的节点。
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 them instead.
To create a new node type, you can use the function
add_custom_type() from the
class_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
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 class_Button. It could also extend class_BaseButton if you prefer:
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:
完成后，插件应该已经在 项目设置 的插件列表中可用，因此请按照 Checking the results 中的说明激活它。
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:
有时，您需要扩展编辑器并添加始终可用的工具。 一种简单的方法是添加一个带插件的新扩展面板。 Docks只是基于Control的场景，因此它们的创建方式与通常的GUI场景类似。
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:
custom_dock.gd 。 使用 template we’ve seen before 填充它以获得良好的开端。
对于编辑器停靠站，根节点 必须是 Control 或其子类之一。 在本教程中，您可以创建一个按钮。 根节点的名称也将是面板对话框中显示的名称，因此请务必为其指定一个简短的描述性名称。 另外，不要忘记在按钮上添加一些文字。
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_control_to_dock() from the
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:
Note that, while the dock will initially appear at its specified position, the user can freely change its position and save the resulting layout.
现在是检查工作结果的时候了。 打开 项目设置 ，然后单击 插件 选项卡。 您的插件应该是列表中唯一的插件。 如果未显示，请单击右上角的 更新 按钮。
您可以在 Status 列中看到该插件处于非激活状态; 点击状态选择 Active 。 在您关闭设置窗口之前，该扩展窗口应该可见。 您现在应该看到一个自定义窗口: