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:
Will Nations
2019-10-29 04:09:15 -05:00
committed by Rémi Verschelde
parent 790a4b21e2
commit 3cb75877e1
2 changed files with 49 additions and 44 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

View File

@@ -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