Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

创建脚本模板

Godot 提供了一种在创建新脚本时使用脚本模板的方法，在 脚本创建对话框 中可以看到：

../../_images/script_create_dialog_templates.webp

编辑器自带了一组内置的脚本模板，但你也可以创建新的模板，并将它们设为默认模板——这些设置既可以针对单个项目进行，也可以在整个编辑器范围内生效。

模板是与特定的节点类型绑定的。因此，当你创建脚本时，只会看到与当前节点（或其父类节点）相对应的模板。举个例子，如果你正在为一个 CharacterBody3D（3D角色身体）节点创建脚本，那么系统只会显示那些为 CharacterBody3D、Node3D 或 Node 定义的模板。

模板所在位置

有两个地方可以管理模板.

编辑器定义的模板

这些模板是全局的，所有项目中均可使用。这些模板所在的位置取决于操作系统：

Windows：%APPDATA%\Godot\script_templates\
Linux：$HOME/.config/godot/script_templates/
macOS：$HOME/Library/Application Support/Godot/script_templates/

如果你的 Godot 是从 Steam 等官方网站以外的地方获取的，那么这个文件夹可能位于其他位置。该文件夹可以使用 Godot 编辑器找到。请打开 编辑器 > 打开编辑器数据/设置文件夹，这样就会在你的文件浏览器中打开一个文件夹，script_templates 文件夹就位于该文件夹中。

项目定义的模板

搜索模板的默认路径是 res://script_templates/ 目录，可以通过代码或编辑器配置项目设置中的编辑器 > 脚本 > 模板搜索路径来修改。

如果在项目中未找到 script_templates 目录，则会将其忽略。

模板的组织和命名

编辑器和项目定义的模板使用的都是以下组织方式：

template_path/node_type/file.extension

其中：

template_path 是前文所述两个路径位置之一。
node_type 指的是该脚本将要应用到的节点类型（例如 Node 或 CharacterBody3D ）。这里需要 特别注意 ： node_type 是区分大小写的。另外，如果你的脚本没有放在正确的 node_type 文件夹里，它将无法被编辑器自动检测到。
file 是你为模板选择的自定义名称（例如：platformer_movement 和 smooth_camera）。
extension：表示应用该模板的语言（GDScript 应使用 gd、C# 应使用 cs）。

例如：

script_templates/Node/smooth_camera.gd
script_templates/CharacterBody3D/platformer_movement.gd

默认行为与覆盖

默认情况下：

模板名称与文件名一致（不含扩展名且经过美化）
描述为空
空格缩进为 4
不会将该模板设为给定节点的默认模板

你可以通过在文件开头添加元数据头（meta headers），来自定义这种行为，就像下面这样：

# meta-name: Platformer movement
# meta-description: Predefined movement for classical platformers
# meta-default: true
# meta-space-indent: 4

// meta-name: Platformer movement
// meta-description: Predefined movement for classical platformers
// meta-default: true
// meta-space-indent: 4

此处将名称设成了“Platformer movement”并给出了自定义描述，并且还将该模板设置成了所在目录对应节点的默认模板。

在编辑器和项目层面使用自定义模板的示例如下：

../../_images/script_create_dialog_custom_templates.webp

备注

脚本模板与常规脚本文件的扩展名相同。因此，脚本解析器可能将这些模板视为项目中的实际脚本，从而导致问题。为了避免这种情况，请在包含模板的目录中创建空的 .gdignore 文件，从而忽略这个目录。这样一来，该目录就不会再出现在项目的文件系统中，不过仍然可以随时使用外部文本编辑器对模板进行修改。

小技巧

默认情况下，项目目录里的每一个 C# 文件都会被包含在编译过程中。因此，你必须手动将脚本模板从 C# 项目中排除，以免引发构建错误。具体操作可以参考微软官方文档中的从生成中排除文件这一章节。

可以创建与项目特定模板级别相同的编辑器级模板，也可以创建与内置模板名称相同的编辑器级别模板，所有这些都将显示在新的脚本对话框中。

默认模板

想要覆盖默认模板，你需要在编辑器级别或项目级别，在 Node 目录（或者更具体的节点类型目录，如果你只想覆盖特定子类型的模板）中创建一个自定义模板，并在文件开头加上 meta-default: true 这个元数据头。

对于同一节点类型，同一时间只能将一个模板设置为默认模板。

默认 模板总是根据每种语言动态生成，并且不能配置也不能覆盖，但是你可以使用它们作为创建其他模板的基础：

# meta-description: Base template for Node with default Godot cycle methods

extends _BASE_


# 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) -> void:
    pass

// meta-description: Base template for Node with default Godot cycle methods

using _BINDINGS_NAMESPACE_;
using System;

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(double delta)
    {
    }
}

Godot 编辑器提供了一套非常有用的内置节点专属模板，比如针对 CharacterBody2D 和 CharacterBody3D 的 basic_movement 模板，以及针对 EditorPlugin 的 plugin 模板。

模板占位符

下面列出当前已实现的所有模板占位符.

基本占位符

占位符	描述
`_BINDINGS_NAMESPACE_`	Godot 命名空间的名称（仅在 C# 中使用）。
`_CLASS_`	新建类的名称。
`_CLASS_SNAKE_CASE_`	新类的名称，采用 `snake_case` （蛇形命名法/下划线命名法）格式（仅用于 GDScript）。
`_BASE_`	新建脚本继承的基类型。
`_TS_`	缩进占位符。用于缩进的具体空白字符类型（比如是空格还是制表符）以及数量，分别由 EditorSettings （编辑器设置）中的 `text_editor/indent/type` 和 `text_editor/indent/size` 这两个选项来决定。当然，你也可以通过在模板中添加 `meta-space-indent` nt 元数据头来强制覆盖这些默认设置。

类型占位符

在 Godot 3.x 版本中，曾经有一些专门用于 GDScript 类型提示的占位符。每当使用模板创建一个新脚本时，这些占位符就会被自动替换成实际的类型，比如：: %INT_TYPE% 、 %STRING_TYPE% 、 %FLOAT_TYPE% 或者 %VOID_RETURN% 。

这些占位符在 Godot 4.x 中已经不再起作用了。不过，如果 EditorSettings （编辑器设置）中的 text_editor/completion/add_type_hints 选项被禁用，那么对于少数几种基础类型，其参数和返回值的类型提示将会被自动移除：

int
String
Array[String]
float
void
:= 将被转换为 =