Extending the Editor with Plugins in Godot

Plugins are a good way so as to add performance to Godot’s editor with minimal effort. They mean you can add options like customized instruments, helpful shortcuts, and menu gadgets to hurry up your workflow. This text will information you thru the method of making your personal plugins to unlock the total potential of Godot.

Observe: This text assumes you’re acquainted with Godot’s editor and have a great understanding of GDScript.

Getting Began

To get began, obtain the venture supplies by way of the Obtain Supplies hyperlink on the prime and backside of this web page. Subsequent, open the EditorPlugins venture you discover within the starter folder and open it in Godot.
Earlier than delving into plugins, I’ll give a fast tour of the venture. It comes with a single scene named fundamental.tscn and a few sprites. Open the fundamental scene and try the nodes inside.

There’s a set of StaticBody2D and RigidBody2D nodes right here that make up a non-interactive physics scene. Should you direct your consideration to the Scene dock, you’ll see there are all named based on their operate.

Discover that solely the highest stage nodes will be chosen and moved, whereas their kids are locked. That is intentional to keep away from transferring the collision shapes and sprites by themselves by chance.

Now attempt operating the venture by urgent F5 and see what occurs.

Shortly after operating the venture, you’ll see the little blue avatar falling down on a crimson field, whereas the opposite crimson field falls off a platform. There’s no precise gameplay concerned right here as the main target is on extending the editor.
Now your manner across the scene, it’s time to study plugins!

Plugin Overview

In Godot, plugins are scripts that reach the performance of the editor. You’ll be able to write these scripts utilizing GDScript or C# and there’s no have to recompile the engine to make them work. Apart from the principle plugin script, you possibly can add scenes and additional scripts to the plugin to make it much more versatile. These work the identical manner like the remainder of your venture, which means you should use your current information of Godot to increase it!

You need to use plugins so as to add buttons, shortcuts and even entire new screens to the editor. Listed below are some examples of what you are able to do with plugins:

• Create a dialog supervisor
• Combine Google Sheets into your venture to load knowledge from
• Add customized useful resource importers
• Make your personal node varieties
• Mechanically create the suitable measurement of colliders for sprites

These are only a handful of concepts to provide you a style of what you are able to do with plugins. Should you ever considered a characteristic you’d need in Godot, there’s a great likelihood you will discover it in a plugin or create your personal.

Creating Your First Plugin

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

Scaffolding

Plugins want three issues to work:

Fortunately, Godot makes it straightforward to create new plugins because it’s constructed into the editor. To get began, open the Undertaking Settings by way of Undertaking ▸ Undertaking Settings… within the prime menu. Now choose the Plugins tab and it is best to see an empty checklist.

• They should be in a folder named addons within the root of the venture
• They want a file named plugin.cfg containing the metadata
• They want at the least one script that derives from EditorPlugin

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

Godot will create the mandatory recordsdata for you based mostly on the knowledge you present, fairly neat! For this visibility button plugin, fill within the following data:

• Plugin Title: Visibility Button
• Subfolder: visibility_button
• Description: Simply present and conceal a specific node.
• Writer: Your title or username
• Script Title: visibility_button.gd

Right here’s what it ought to appear like:

Subsequent, click on the Create button to let Godot create the mandatory recordsdata for you. This may even routinely open the visibility_button.gd script within the script editor.
Earlier than enhancing the script, check out the recordsdata and folders Godot has created for you within the FileSystem dock.

There’s a brand new folder named addons now that incorporates 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 incorporates the metadata for the plugin, whereas the script incorporates the precise code.

Observe: Chances are you’ll be questioning why the addons folder isn’t named plugins as a substitute. In Godot, it’s doable so as to add add-ons that reach the performance of the editor, however aren’t plugins. Plugins are editor plugins particularly, which use a script that derives from EditorPlugin.

Sufficient scaffolding, time to check out the code!

Taking a Nearer Look

The visibility_button.gd script that Godot generated for you incorporates the next code:

@instrument # 1
extends EditorPlugin # 2


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


func _exit_tree() -> void: # 4
    # Clear-up of the plugin goes right here.
    cross

I took the freedom so as to add some numbered feedback to make it simpler to clarify what every line does:

1. The @instrument annotation turns an everyday script right into a instrument script. Which means any code within the script will likely be executed within the editor. That is highly effective, but it surely additionally makes it straightforward to interrupt complete scenes when not cautious. You’ll study extra concerning the @instrument annotation in one other article. If you wish to know extra about it within the meantime, take a look at the Working code within the editor web page of Godot’s documentation.
2. All editor plugins should inherit from EditorPlugin. This class comes with a ton of helpful features to entry and edit Godot’s editor.
3. The _enter_tree operate is known as once you activate the plugin. This the place you arrange all wanted variables and references for later use.
4. The _exit_tree operate is known as once you disable the plugin. That is the place you clear up all references.

Dealing with Node Choice

For the visibility button plugin, you received’t want the _enter_tree and _exit_tree features so delete them. You’ll be dealing with the initialization and cleanup with different features. Now add the operate beneath within the place of the eliminated ones:

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

Godot calls the _handles operate when you choose an object. The Object class is the bottom class for all different courses in Godot. This operate returns true if the chosen object will be dealt with by your plugin. On this case, the plugin solely edits nodes, so it returns true if the chosen object is a Node class, or derives from it.

You’ll have to preserve observe of the chosen node your self, so add a brand new variable above the _handles operate named node_to_edit:

var node_to_edit : Node

With this variable in place, add the _edit operate beneath the _handles operate:

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

    node_to_edit = object # 3

The _edit operate is known as by Godot proper after the _handles operate returns true. It requests the editor to edit the given object and it’s the right place to retailer a reference to the chosen object. Right here’s an outline of what’s taking place right here:

1. The _edit operate will get handed the chosen object, a Node in case of this plugin.
2. There’s a risk that the chosen object is null, so you have to examine if it’s not. If it’s null, return from the operate and don’t do something.
3. Retailer a reference to the chosen object for later use.

To examine if this code is working accurately, add a short lived print assertion on the finish of the _edit operate:

print(node_to_edit)

Now save the script and take a look at deciding on some nodes within the scene tree. It’s best to see the title of the chosen node within the console.

As you possibly can see, the plugin already works!

Observe: When you choose a root node like Major on this case, the console will name _edit twice. Fortunately, this received’t have an effect on the performance of the plugin.

Now take away or remark out the print assertion you’ve added and save the script once more. The final operate to convey all of it collectively is the _make_visible operate, add it beneath the _edit operate:

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

Just like the _edit operate, Godot calls the _make_visible operate after the _handles operate returns true. It handles the displaying and hiding of the plugin UI. It additionally will get known as when disabling the plugin. When displaying the button, you’ll create it and add it to the toolbar. When hiding the button, you’ll take away it from the toolbar and destroy it. That is a substitute for utilizing the _enter_tree and _exit_tree features for initialization and cleanup.
Right here’s the code above in additional element:

1. The _make_visible operate will get handed a boolean worth, seen to inform the UI to point out or conceal.
2. If seen is true, add the button to the toolbar by way of the _add_button operate.
3. If seen is false, take away the button from the toolbar by way of the _remove_button operate.

After including the code, you’ll get some errors as you haven’t added the _add_button and _remove_button features but. Add these empty features to eliminate the errors:

func _add_button() -> void:
    cross


func _remove_button() -> void:
    cross

These will act as placeholders for now. Within the subsequent part you’ll add the logic.