Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

类参考入门¶

本页面将介绍如何编写类参考手册。你会学到去哪里为 Godot 内置节点类型的类、方法、属性编写新的描述。

参见

要学习如何使用 Git 版本控制系统向 Godot 项目提交你的修改，请参见为类参考手册贡献。

每个类的参考文档都被包含在一个如下的 XML 文件中：

<class name="Node2D" inherits="CanvasItem" version="4.0">
    <brief_description>
        A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and Z index.
    </brief_description>
    <description>
        A 2D game object, with a transform (position, rotation, and scale). All 2D nodes, including physics objects and sprites, inherit from Node2D. Use Node2D as a parent node to move, scale and rotate children in a 2D project. Also gives control of the node's render order.
    </description>
    <tutorials>
        <link title="Custom drawing in 2D">https://docs.godotengine.org/en/latest/tutorials/2d/custom_drawing_in_2d.html</link>
        <link title="All 2D Demos">https://github.com/godotengine/godot-demo-projects/tree/master/2d</link>
    </tutorials>
    <methods>
        <method name="apply_scale">
            <return type="void">
            </return>
            <argument index="0" name="ratio" type="Vector2">
            </argument>
            <description>
                Multiplies the current scale by the [code]ratio[/code] vector.
            </description>
        </method>
        [...]
        <method name="translate">
            <return type="void">
            </return>
            <argument index="0" name="offset" type="Vector2">
            </argument>
            <description>
                Translates the node by the given [code]offset[/code] in local coordinates.
            </description>
        </method>
    </methods>
    <members>
        <member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position">
            Global position.
        </member>
        [...]
        <member name="z_index" type="int" setter="set_z_index" getter="get_z_index" default="0">
            Z index. Controls the order in which the nodes render. A node with a higher Z index will display in front of others.
        </member>
    </members>
    <constants>
    </constants>
</class>

开头是简介和详细描述。在生成的文档中，顶部总是简介，详细描述会放在方法、变量、常量列表之后。可以看到方法、成员变量、常量、信号都在各自单独的 XML 节点中。

你会想要在 Godot 的源代码中学习它们都有什么用。然后补全或者完善这些标签中的文本：

<brief_description>
<description>
<constant>
<method>（在其 <description> 标签中；返回类型和参数不带单独的文档字符串）
<member>
<signal>（在其 <description> 标签中；参数不带单独的文档字符串）
<constant>

用清晰简单的语言编写。始终遵循编写规范以使你的描述简短易读。在描述中不要留下空行：XML 文件中的每一行都将生成一个新段落，空行也是一样。

如何编辑类 XML¶

如果你想要更新某个类的类参考手册，编辑 doc/classes/ 中的对应文件即可。文件夹中包含了各个类的 XML 文件。在 XML 中，列出了类参考中的常量和方法。Godot 会自动生成并更新这些 XML。

备注

游戏引擎中某些模块的 XML 文件在 modules/<模块名称>/doc_classes/ 目录下。

用你喜欢的文本编辑器编辑它。如果你使用代码编辑器，请确保它不会改变缩进样式：XML 使用制表符，而 BBCode 风格的块内使用 4 个空格。下面有更多这方面的内容。

要检查你所做出的修改在生成后的文档中是否正确，请在 doc/ 文件夹中执行命令 make rst。这样就会将 XML 文件转换为在线文档的格式，存在错误时会有错误报告。

你也可以自行构建 Godot 然后在内置的类参考手册中打开被修改的页面。引擎的编译方法请查看 compilation guide。

我们推荐使用 Vim、Atom、Visual Studio Code、Notepad++ 等支持 XML 的代码编辑器，或者其他能够方便编辑此类文件的编辑器。你还可以使用它们的搜索功能快速查找类和属性。

小技巧

如果你使用 Visual Studio Code，则可以安装 vscode-xml 扩展 <https://marketplace.visualstudio.com/items?itemName=redhat.vscode-xml> 来纠察 XML 文件的类引用。

使用 BBCode 风格标签来改进格式¶

Godot 的 XML 类引用支持类似 BBCode 的标记，用于链接以及格式化文本和代码。在下表中，你可以找到可用的标记、用法示例以及转换为 reStructuredText 后的结果。

链接¶

每从其他类里链接一个成员，你都要在成员名前面加上该类的类名。而链接类内成员时，类名可省略。

描述	示例	结果
`[Class]` 链接类	`移动 [Sprite]。`	移动 Sprite2D。
`[annotation Class.name]` 链接到注解	`见 [annotation @GDScript.@export].`	见 @GDScript.@export。
`[constant Class.name]` 链接到常量	`见 [constant @GlobalScope.KEY_F1]。`	见 @GlobalScope.KEY_F1。
`[enum Class.name]` 链接到枚举	`见 [enum Mesh.ArrayType]。`	见 Mesh.ArrayType。
`[method Class.name]` 链接到方法	`调用 [method Node3D.hide].`	调用 Node3D.hide()。
`[member Class.name]` 链接到成员	`获取 [member Node2D.scale]。`	获取 Node2D.scale.
`[signal Class.name]` 链接到信号	`发送 [signal Node.renamed]。`	发送 Node.renamed。
`[theme_item Class.name]` 链接到主题项	`见 [theme_item Label.font]。`	见 Label.font。

备注

目前只有 @GDScript 有注解。

格式化文本¶

描述	示例	结果
`[param name]` 格式化参数名称（作为代码）	`用 [param size] 来表示大小。`	用 `size` 表示大小。
`[br]` 换行	`行 1。[br]` `行 2。`	行 1。行 2。
`[b]` `[/b]` 粗体	`一些[b]粗体[/b]文本。`	一些粗体文本。
`[i]` `[/i]` 斜体	`一些[i]斜体[/i]文本。`	一些斜体文本。
`[kbd]` `[/kbd]` 键盘和鼠标快捷键	`一些 [kbd]Ctrl + C[/kbd] 按键。`	一些 `Ctrl + C` 按键。

格式化代码¶

描述	示例	结果
`[code]` `[/code]` 等宽字体	`一些[code]等宽[/code]文本。`	一些`等宽`文本。
`[codeblock]` `[/codeblock]` 多行预格式化块	见下文.	见下文.
`[codeblocks]` `[/codeblocks]` 多语言代码块	见下文.	见下文.
`[gdscript]` `[/gdscript]` 代码块中的 GDScript 代码块选项卡	见下文.	见下文.
`[csharp]` `[/csharp]` 代码块中的 C# 代码块选项卡	见下文.	见下文.

备注

[code] 与 [/code] 之间的 BBCode 代码均无效。
[codeblock] 与 [/codeblock] 之间的 BBCode 代码均无效。

警告

对预格式化的代码块使用 [codeblock]。在 [codeblock] 中，请始终使用四个空格进行缩进。解析器将删除制表符。

例如：

[codeblock]
func _ready():
    var sprite = get_node("Sprite2D")
    print(sprite.get_pos())
[/codeblock]

将显示为：

func _ready():
    var sprite = get_node("Sprite2D")
    print(sprite.get_pos())

如果你有针对 GDScript 和 C# 的不同版本的代码，请换用 [codeblocks]。使用 [codeblocks]，你还需要至少一个语言标签，即 [gdscript] 和 [csharp]。

请先写 GDScript 代码示例！你可以使用这个实验性的代码翻译工具来加速工作流程。

[codeblocks]
[gdscript]
func _ready():
    var sprite = get_node("Sprite2D")
    print(sprite.get_pos())
[/gdscript]
[csharp]
public override void _Ready()
{
    var sprite = GetNode("Sprite2D");
    GD.Print(sprite.GetPos());
}
[/csharp]
[/codeblocks]

上述内容将显示为：

func _ready():
    var sprite = get_node("Sprite2D")
    print(sprite.get_pos())

public override void _Ready()
{
    var sprite = GetNode("Sprite2D");
    GD.Print(sprite.GetPos());
}

要表示重要信息，请在描述末尾添加一段以“[b]Note:[/b]”开头的内容：

[b]Note:[/b] Only available when using the Vulkan renderer.

为了表示如果不仔细遵循可能导致安全问题或数据丢失的关键信息，请在描述末尾添加一段以“[b]Warning:[/b]”开头的内容：

[b]Warning:[/b] If this property is set to [code]true[/code], it allows clients to execute arbitrary code on the server.

对于不推荐使用的属性, 请添加以 "[i]deprecated.[/i]" 开头的段落. 注意使用斜体代替粗体:

[i]Deprecated.[/i] This property has been replaced by [member other_property].

在上面描述的所有段落中, 确保标点符号是BBCode标签的一部分, 以保持一致性.