mirror of
https://github.com/godotengine/godot-docs.git
synced 2026-01-05 22:09:56 +03:00
Updated plugin tutorial w/ dialog & dep warning. (#2795)
- New note with CreatePluginDialog and images. - Warns users that CustomTypes will be deprecated in 4.0.
This commit is contained in:
committed by
Rémi Verschelde
parent
790a4b21e2
commit
3cb75877e1
Binary file not shown.
|
After Width: | Height: | Size: 21 KiB |
@@ -11,7 +11,7 @@ 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 functionality.
|
||||
make, except it is created using a script to add editor functionality.
|
||||
|
||||
This tutorial will guide you through the creation of two simple plugins so
|
||||
you can understand how they work and be able to develop your own. The first
|
||||
@@ -24,62 +24,60 @@ Creating a plugin
|
||||
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 to do is to create a new plugin the editor can
|
||||
understand as such. You need two files for that: ``plugin.cfg`` for the
|
||||
configuration and a custom GDScript with the functionality.
|
||||
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 ``addons/plugin_name`` inside
|
||||
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
|
||||
on the ``Create`` button in the top-right.
|
||||
|
||||
You will see the dialog appear, like so:
|
||||
|
||||
.. image:: img/making_plugins-create_plugin_dialog.png
|
||||
|
||||
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
|
||||
|
||||
Plugins have a standard path like ``addons/plugin_name`` inside the project
|
||||
folder. For this example, create a folder ``my_custom_node`` inside ``addons``.
|
||||
You should end up with a directory structure like this:
|
||||
|
||||
.. image:: img/making_plugins-my_custom_mode_folder.png
|
||||
|
||||
Now, open the script editor, click the **File** menu, choose **New TextFile**,
|
||||
then navigate to the plugin folder and name the file ``plugin.cfg``.
|
||||
Add the following structure to ``plugin.cfg``:
|
||||
|
||||
.. tabs::
|
||||
.. code-tab:: gdscript GDScript
|
||||
|
||||
[plugin]
|
||||
|
||||
name="My Custom Node"
|
||||
description="A custom node made to extend the Godot Engine."
|
||||
author="Your Name Here"
|
||||
version="1.0.0"
|
||||
script="custom_node.gd"
|
||||
|
||||
.. code-tab:: csharp
|
||||
|
||||
[plugin]
|
||||
|
||||
name="My Custom Node"
|
||||
description="A custom node made to extend the Godot Engine."
|
||||
author="Your Name Here"
|
||||
version="1.0.0"
|
||||
script="CustomNode.cs"
|
||||
|
||||
This is a simple INI file with metadata about your plugin. You need to set
|
||||
the name and description so people can understand what it does. Don't forget
|
||||
to add your own name so you can be properly credited. Add a version number
|
||||
so people can see if they have an outdated version; if you are unsure on
|
||||
how to come up with the version number, check out `Semantic Versioning <https://semver.org/>`_.
|
||||
Finally, set the main script file to load when your plugin is active.
|
||||
``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 <https://semver.org/>`_.
|
||||
The main script file will instruct Godot what your plugin does in the editor
|
||||
once it is active.
|
||||
|
||||
The script file
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Open the script editor (F3) and create a new GDScript file called
|
||||
``custom_node.gd`` inside the ``my_custom_node`` folder. This script is special
|
||||
and it has two requirements: it must be a ``tool`` script and it has to
|
||||
inherit from :ref:`class_EditorPlugin`.
|
||||
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 :ref:`class_EditorPlugin`.
|
||||
|
||||
It's important to deal with initialization and clean-up of resources.
|
||||
A good practice is to use the virtual function
|
||||
:ref:`_enter_tree() <class_Node_method__enter_tree>` to initialize your plugin and
|
||||
:ref:`_exit_tree() <class_Node_method__exit_tree>` to clean it up. You can delete the
|
||||
default GDScript template from your file and replace it with the following
|
||||
structure:
|
||||
:ref:`_exit_tree() <class_Node_method__exit_tree>` to clean it up. Thankfully,
|
||||
the dialog generates these callbacks for you. Your script should look something
|
||||
like this:
|
||||
|
||||
.. _doc_making_plugins_template_code:
|
||||
.. tabs::
|
||||
@@ -128,6 +126,13 @@ sometimes it can be cumbersome, especially if you're using it in many
|
||||
projects. A good solution to this is to make a plugin that adds a node with a
|
||||
custom behavior.
|
||||
|
||||
.. warning::
|
||||
|
||||
Nodes added via an EditorPlugin are "CustomType" nodes. While they work
|
||||
with any scripting language, they have fewer features than
|
||||
:ref:`the Script Class system <doc_scripting_continued_class_name>`. If you
|
||||
are writing GDScript or NativeScript, we recommend using them instead.
|
||||
|
||||
To create a new node type, you can use the function
|
||||
:ref:`add_custom_type() <class_EditorPlugin_method_add_custom_type>` from the
|
||||
:ref:`class_EditorPlugin` class. This function can add new types to the editor
|
||||
|
||||
Reference in New Issue
Block a user