diff --git a/tutorials/scripting/creating_script_templates.rst b/tutorials/scripting/creating_script_templates.rst index cb129f78e45d..066ff4b3a08f 100644 --- a/tutorials/scripting/creating_script_templates.rst +++ b/tutorials/scripting/creating_script_templates.rst @@ -8,8 +8,15 @@ Godot provides a way to use script templates as seen in the .. image:: img/script_create_dialog_templates.png -A set of script templates is provided by default, but it's also possible -to modify existing and create new ones, both per project and editor-wide. +A set of built-in script templates are provided with the editor, but it is +also possible to create new ones and set them by default, both per project +and at editor scope. + +Templates are linked to a specific node type, so when you create a script +you will only see the templates corresponding to that particular node, or +one of its parent types. +For example, if you are creating a script for a CharacterBody3D, you will +only see templates defined for CharacterBody3Ds, Node3Ds or Nodes. Locating the templates ---------------------- @@ -41,13 +48,66 @@ the ``editor/script_templates_search_path`` setting in the If no ``script_templates`` directory is found within a project, it is simply ignored. -Language support and overriding behavior ----------------------------------------- +Template organization and naming +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Both editor and project defined templates are organized in the following way: + +:: + + template_path/node_type/file.extension + +where: + +* ``template_path`` is one of the 2 locations discussed in the previous two sections + +* ``node_type`` is the node it will apply to (for example, :ref:`Node `, or :ref:`CharacterBody3D `) + +* ``file`` is the custom name you can chose for the template (for example: ``platformer_movement`` or ``smooth_camera``) + +* ``extension``: will indicate which language the template will apply to (it should be ``gd`` for GDScript or ``cs`` for C#) + + +Default behaviour and overriding it +----------------------------------- + +By default: + +* the template's name is the same as the file name (minus the extension, prettyfied) + +* the description is empty + +* the space indent is set to 4 + +* the template will not be set as the default for the given node -Depending on whether a particular language implements a way to generate scripts -out of templates, it's possible to create a template which can be recognized by -that language according to template's file extension. For GDScript and C#, the -extensions must be ``gd`` and ``cs`` respectively. + +It is possible to customize this behaviour by adding meta headers at the start +of your file, like this: + +.. tabs:: + + .. code-tab:: gdscript GDScript + + # meta-name: Platformer movement + # meta-description: Predefined movement for clasical platformers + # meta-default: true + # meta-space-indent: 4 + + .. code-tab:: csharp + + // meta-name: Platformer movement + // meta-description: Predefined movement for clasical platformers + // meta-default: true + // meta-space-indent: 4 + + +In this case, the name will be set to "Platformer movement", with the given custom description, and +it will be set as the default template for the node in which directory it has been saved. + +This is an example of utilizing custom templates at editor and project level: + +.. image:: img/script_create_dialog_custom_templates.png .. note:: The script templates have the same extension as the regular script files. This may lead to an issue of a script parser treating those templates as @@ -56,61 +116,65 @@ extensions must be ``gd`` and ``cs`` respectively. visible throughout the project's filesystem anymore, yet the templates can be modified by an external text editor anytime. -The built-in editor templates are automatically shadowed by the project-specific -templates given both scripts have the same filename. +It is possible to create editor-level templates that have the same level as a project-specific +templates, and also that have the same name as a built-in one, all will be shown on the new script +dialog. Default template ---------------- -The ``Default`` template is always generated dynamically per language and cannot -be configured nor overridden, but you can use these as the base for creating -other templates. +To override the default template, create a custom template at editor or project level inside a +``Node`` directory (or a more specific type, if only a subtype wants to be overriden) and start +the file with the ``meta-default: true`` header. + +Only one template can be set as default at the same time for the same node type. + +The ``Default`` templates for basic Nodes, for both GDScript and C#, are shown here so you can +use these as the base for creating other templates: .. tabs:: .. code-tab:: gdscript GDScript - extends %BASE% - + # meta-description: Base template for Node with default Godot cycle methods - # Declare member variables here. Examples: - # var a%INT_TYPE% = 2 - # var b%STRING_TYPE% = "text" + extends _BASE_ - # Called when the node enters the scene tree for the first time. - func _ready()%VOID_RETURN%: - pass # Replace with function body. + # Called when the node enters the scene tree for the first time. + func _ready() -> void: + pass # Replace with function body. - # Called every frame. 'delta' is the elapsed time since the previous frame. - #func _process(delta%FLOAT_TYPE%)%VOID_RETURN%: - # pass + # Called every frame. 'delta' is the elapsed time since the previous frame. + func _process(delta: float) -> void: + pass .. code-tab:: csharp - using Godot; - using System; + // meta-description: Base template for Node with default Godot cycle methods - public class %CLASS% : %BASE% - { - // Declare member variables here. Examples: - // private int a = 2; - // private string b = "text"; + using _BINDINGS_NAMESPACE_; + using System; - // Called when the node enters the scene tree for the first time. - public override void _Ready() - { + public partial class _CLASS_ : _BASE_ + { + // Called when the node enters the scene tree for the first time. + public override void _Ready() + { + } - } + // Called every frame. 'delta' is the elapsed time since the previous frame. + public override void _Process(float delta) + { + } + } - // // Called every frame. 'delta' is the elapsed time since the previous frame. - // public override void _Process(float delta) - // { - // - // } - } +The Godot editor provides a set of useful built-in node-specific templates, such as +``basic_movement`` for both :ref:`CharacterBody2D ` and +:ref:`CharacterBody3D ` and ``plugin`` for +:ref:`EditorPlugin `. List of template placeholders ----------------------------- @@ -121,36 +185,37 @@ which are currently implemented. Base placeholders ~~~~~~~~~~~~~~~~~ -+-------------+----------------------------------------------------------------+ -| Placeholder | Description | -+=============+================================================================+ -| ``%CLASS%`` | The name of the new class (used in C# only). | -+-------------+----------------------------------------------------------------+ -| ``%BASE%`` | The base type a new script inherits from. | -+-------------+----------------------------------------------------------------+ -| ``%TS%`` | Indentation placeholder. The exact type and number of | -| | whitespace characters used for indentation is determined by | -| | the ``text_editor/indent/type`` and ``text_editor/indent/size``| -| | settings in the :ref:`EditorSettings ` | -| | respectively. | -+-------------+----------------------------------------------------------------+ ++-------------+-----------------------------------------------------------------+ +| Placeholder | Description | ++=============+=================================================================+ +| ``_CLASS_`` | The name of the new class (used in C# only). | ++-------------+-----------------------------------------------------------------+ +| ``_BASE_`` | The base type a new script inherits from. | ++-------------+-----------------------------------------------------------------+ +| ``_TS_`` | Indentation placeholder. The exact type and number of | +| | whitespace characters used for indentation is determined by | +| | the ``text_editor/indent/type`` and ``text_editor/indent/size`` | +| | settings in the :ref:`EditorSettings ` | +| | respectively. Can be overriden by the ``meta-space-indent`` | +| | header on the template. | ++-------------+-----------------------------------------------------------------+ Type placeholders ~~~~~~~~~~~~~~~~~ -These are only relevant for GDScript with static typing. Whether these -placeholders are actually replaced is determined by the -``text_editor/completion/add_type_hints`` setting in the -:ref:`EditorSettings `. - -+-------------------+--------------+ -| Placeholder | Value | -+===================+==============+ -| ``%INT_TYPE%`` | ``: int`` | -+-------------------+--------------+ -| ``%STRING_TYPE%`` | ``: String`` | -+-------------------+--------------+ -| ``%FLOAT_TYPE%`` | ``: float`` | -+-------------------+--------------+ -| ``%VOID_RETURN%`` | ``-> void`` | -+-------------------+--------------+ +There used to be, in Godot 3.x, placeholders for GDScript type hints that +would get replaced whenever a template was used to create a new script, such as: +``%INT_TYPE%``, ``%STRING_TYPE%``, ``%FLOAT_TYPE%`` or ``%VOID_RETURN%``. + +The placeholders no longer work for Godot 4.x, but if the setting +``text_editor/completion/add_type_hints`` from +:ref:`EditorSettings ` is disabled, type hints +for parameters and return types will be automatically removed for a few +base types: + +* ``int`` +* ``String`` +* ``Array[String]`` +* ``float`` +* ``void`` +* ``:=`` will be transformed into ``=`` diff --git a/tutorials/scripting/img/script_create_dialog_custom_templates.png b/tutorials/scripting/img/script_create_dialog_custom_templates.png new file mode 100644 index 000000000000..8684898c55e4 Binary files /dev/null and b/tutorials/scripting/img/script_create_dialog_custom_templates.png differ diff --git a/tutorials/scripting/img/script_create_dialog_templates.png b/tutorials/scripting/img/script_create_dialog_templates.png index 14aca3f54528..8c7240680430 100644 Binary files a/tutorials/scripting/img/script_create_dialog_templates.png and b/tutorials/scripting/img/script_create_dialog_templates.png differ