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

Class reference primer¶

本页面将介绍如何编写类参考手册。你会学到去哪里为 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 的代码编辑器，或者其他能够方便编辑此类文件的编辑器。你还可以使用它们的搜索功能快速查找类和属性。

小技巧

If you use Visual Studio Code, you can install the vscode-xml extension to get linting for class reference XML files.

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

Godot's XML class reference supports BBCode-like tags for linking as well as formatting text and code. In the tables below you can find the available tags, usage examples and the results after conversion to reStructuredText.

Linking¶

Whenever you link to a member of another class, you need to specify the class name. For links to the same class, the class name is optional and can be omitted.

Tag and Description	示例	结果
`[Class]` Link to class	`Move the [Sprite2D].`	Move the Sprite2D.
`[annotation Class.name]` Link to annotation	`See [annotation @GDScript.@export].`	See @GDScript.@export.
`[constant Class.name]` Link to constant	`See [constant @GlobalScope.KEY_F1].`	See @GlobalScope.KEY_F1.
`[enum Class.name]` Link to enum	`See [enum Mesh.ArrayType].`	See Mesh.ArrayType.
`[method Class.name]` Link to method	`Call [method Node3D.hide].`	Call Node3D.hide().
`[member Class.name]` Link to member	`Get [member Node2D.scale].`	Get Node2D.scale.
`[signal Class.name]` Link to signal	`Emit [signal Node.renamed].`	Emit Node.renamed.
`[theme_item Class.name]` Link to theme item	`See [theme_item Label.font].`	See Label.font.

备注

Currently only @GDScript has annotations.

Formatting text¶

Tag and Description	示例	结果
`[param name]` Formats a parameter name (as code)	`Takes [param size] for the size.`	Takes `size` for the size.
`[br]` Line break	`Line 1.[br]` `Line 2.`	Line 1. Line 2.
`[b]` `[/b]` 粗体	`Some [b]bold[/b] text.`	一些粗体文字.
`[i]` `[/i]` 斜体	`Some [i]italic[/i] text.`	一些斜体文字.
`[kbd]` `[/kbd]` 键盘和鼠标快捷键	`Some [kbd]Ctrl + C[/kbd] key.`	一些 `Ctrl + C` 键.

Formatting code¶

Tag and Description	示例	结果
`[code]` `[/code]` 等宽字体	`Some [code]monospace[/code] text.`	一些 `等宽字体` 文本.
`[codeblock]` `[/codeblock]` 多行预格式化块	见下文.	见下文.
`[codeblocks]` `[/codeblocks]` Codeblock for multiple languages	见下文.	见下文.
`[gdscript]` `[/gdscript]` 代码块中的 GDScript 代码块选项卡	见下文.	见下文.
`[csharp]` `[/csharp]` 代码块中的 C# 代码块选项卡	见下文.	见下文.

备注

[code] disables BBCode until the parser encounters [/code].
[codeblock] disables BBCode until the parser encounters [/codeblock].

警告

Use [codeblock] for pre-formatted code blocks. Inside [codeblock], always use four spaces for indentation. The parser will delete tabs.

例如:

[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标签的一部分, 以保持一致性.